Log Uploader tool

The HERE Core Log Uploader lets platform owners and application providers collect logs from end-user machines for troubleshooting. When run, it shows the user a confirmation window listing the logs to upload; after the user approves, the tool sends a zip archive to an endpoint you configure.

Requirements

• HERE Core version 40 or later. Mac requires version 42 or later.

• logUpload.method with PUT uploads requires HERE Core version 44 or later.

Configure the Log Uploader

Create a manifest for the Log Uploader with a logUpload object:

{
  "logUpload": {
    "endpoint": "UPLOAD-ENDPOINT-URL",
    "manifests": ["*://*.EXAMPLE.COM/PATH-TO-MANIFESTS/*.json"],
    "logs": ["debug", "app", "rvm"],
    "method": "POST",
    "ui": {
      "title": "WINDOW-TITLE",
      "icon": "URL-OF-ICON-FOR-UPLOADER",
      "header": "COMPANY-NAME",
      "description": "EXPLANATION-OF-WHAT-THE-TOOL-IS-DOING",
      "email": "SUPPORT-EMAIL-ADDRESS",
      "website": "WEBSITE-WITH-MORE-INFO",
      "websiteDescription": "WEBSITE-DESCRIPTION"
    }
  },
  "runtime": {
    "version": "V40-OR-LATER"
  }
}

Configuration options

• logUpload.endpoint: (Required) URL that receives the uploaded log archive.

• logUpload.manifests: (Optional) URL match patterns for program manifests whose app logs should be included. This property does not filter debug or RVM logs. Default is an empty array, which collects no app logs. Specify patterns to include app logs from matching programs.

• logUpload.logs: (Optional) Log types to upload: "debug", "app", and "rvm". Default is all three.

• logUpload.method: (Optional) HTTP method for the upload. Requires HERE Core version 44 or later. Accepts "POST" (default) or "PUT" (case-insensitive).

  Method	Request format	Typical use
  POST	multipart/form-data with a file field containing logs.zip	Standard web endpoints
  PUT	Raw zip binary with Content-Length; no Content-Type	Pre-signed upload URLs and other raw-body endpoints

• logUpload.ui: (Optional) String values that customize the confirmation window.

  • title: Window title.

  • icon: Icon URL. Default is the OpenFin logo.

  • header: Organization name shown in the window. Default is "OpenFin".

  • description: Explanation shown to the user. Default is "The following logs are being requested."

  • email: Support contact. Failure notifications are also sent to this address when upload fails.

  • website: URL for more information about log uploading.

  • websiteDescription: Label for the website link.

• runtime.version: (Recommended) HERE Core version to use. Minimum is v40. If multiple versions might be present on the user's machine, set this explicitly. See Runtime properties.

Set up an upload endpoint

Host an endpoint on your network that accepts the HTTP method configured in logUpload.method. Ensure the endpoint supports that method before distributing the Log Uploader manifest.

Install and run

Install and distribute the Log Uploader like any other HERE Core program. Set Shortcut properties in the manifest if you want a desktop shortcut.

Users can run the uploader when you need logs, or you can send a fins: link to the manifest URL so they can run it without installing it first.

Launch the manifest like any other HERE Core program. See Application launch. To suppress the confirmation window at launch, pass --no-ui to OpenFinRVM.exe. The programmatic equivalent is ui.show: false (see Run programmatically).

Run programmatically

Starting in version 42, call fin.System.launchLogUploader to upload logs from application code.

info

This method is experimental and subject to change.

Pass the same options as in the manifest (see Configuration options) in a single options argument. The ui object also accepts show (boolean) to suppress the confirmation window.

type LogUploaderOptions = {
    endpoint: string;
    manifests?: string[];
    logs?: ('debug' | 'rvm' | 'app')[];
    method?: 'POST' | 'PUT';
    ui?: {
        show?: boolean;
        title?: string;
        icon?: string;
        header?: string;
        description?: string;
        email?: string;
        website?: string;
        websiteDescription?: string;
    };
};

The method returns a Promise that rejects if upload fails. It is a Secured API and must be declared in the calling application's manifest and allowed by the desktop owner.

Examples

Collect logs for specific app manifests without showing the dialog:

await fin.System.launchLogUploader({
    endpoint: 'https://UPLOAD/ENDPOINT/url?user=USER',
    manifests: [
        'https://*app.com/manifest.json',
        'https://*.secondapp.com/manifest.json'
    ],
    ui: { show: false }
});

Collect only app logs with a customized confirmation window:

await fin.System.launchLogUploader({
    endpoint: 'https://UPLOAD/ENDPOINT/url?user=USER',
    logs: ['app'],
    ui: {
        header: 'COMPANY NAME',
        description: 'The following logs are being requested:',
        email: 'SUPPORT@EXAMPLE.COM',
        website: 'https://EXAMPLE.COM/LOG-INFO',
        websiteDescription: 'USER FRIENDLY EXPLANATION'
    }
});

Upload logs to a pre-signed URL using PUT:

await fin.System.launchLogUploader({
    endpoint: 'https://PRESIGNED-UPLOAD-URL',
    method: 'PUT',
    ui: { show: false }
});

Security considerations

The Log Uploader collects logs only from programs provided by the same organization as the uploader manifest. Some log types are encrypted before upload.

URL restrictions

The registrable domain (eTLD+1) must match across all of the following:

• The Log Uploader manifest URL

• Each pattern in logUpload.manifests

• The manifest URL of each program whose logs are collected

For example, a Log Uploader manifest at https://dev.example.com/log-uploader/manifest.json can use manifests: ["*://*.example.com/*/*.json"] to collect app logs only from manifests hosted on example.com or its subdomains.

Log encryption

• RVM logs are always encrypted.

• Debug logs are encrypted unless the program uses a security realm and only manifests your organization authorizes have used that realm. In that case, debug logs for that realm are sent unencrypted.

• App logs are not encrypted.

Troubleshoot errors

If log collection or upload fails, the Log Uploader shows an error to the user, even when the confirmation window is suppressed (--no-ui or ui.show: false). The error dialog has minimal dependencies so it can appear under degraded conditions.

When upload fails and logUpload.ui.email is set, the Log Uploader sends a failure notification to that address.