AboutSupport
Docs

Testing and debugging

Suggest Edits

OpenFin provides application providers with the tools needed to support their application development. These features range from the Chrome Developer Tools to API calls for collecting raw data about an end-user’s machine.

Debugging your app

The Chrome DevTools is available for easy and efficient debugging. There are two ways to access these tools via your OpenFin app:

Launch via Google Chrome browser

  1. Launch the Google Chrome browser.

  2. Enter the following URL: http://localhost:9090
    You’ll see a list of the running web pages.

  3. Select the page you’d like to debug.

Launch via your app

Set the contextMenu option to true in your app manifest file as follows:

"startup_app": {
    …
    "contextMenu": true
}

You can then right-click on your app and select Inspect Element to open the Chrome DevTools.

🚧

REMINDER

Remember to set contextMenu: false or remove the setting before deploying to your production environment.

Debugging a render or browser crash

Although rare, renderer or browser crashes may occur within your OpenFin environment. In case this happens, OpenFin has tools to provide application providers to collect the necessary information or logs to diagnose the cause. In our experience, the leading contributors to a renderer crash are application memory leaks or anti-virus software killing a process.

In the OpenFin environment, the renderer process is where application code runs.

Diagnostics mode

Diagnostics mode can recreate a runtime renderer or browser crash within your application and generate crash logs. The feature is opt-in. It can be configured in your application manifest or triggered from a command line.

Add --diagnostics as the value of the argument option in your application manifest, under the runtime object:

"runtime": {
    "arguments": "--diagnostics"
    },

When this setting is enabled, end-users can re-launch your application and attempt to recreate the crash. When your application runs in diagnostics mode, the OpenFin Runtime supports the following:

  • Verbose logging defaults to enabled ( --v=1).

  • Crash Reporting Tool is enabled.

  • --no-sandbox is enabled (required for Crash Reporter to properly work).

  • Crash and debug logs are delivered on Runtime crash or application close.

If a renderer or browser process crashes with diagnostics enabled, a .dmp file is generated and stored on the end-user's file system. The OpenFin Runtime delivers this .dmp file and the debug.log file to OpenFin's CDN.

  • In Runtime versions 15.80.50.34 and earlier, the .dmp file is created in %temp%/OpenFin Crashes/FILENAME.dmp.

  • In Runtime versions 16.83.50.9 and later, it is created in C:\Users\USERNAME\AppData\Local\OpenFin\cache\RUNTIME_VERSION\Crashpad\reports, or, if a security realm is used, in C:\Users\USERNAME\AppData\Local\OpenFin\cache\SECURITY_REALM\RUNTIME_VERSION\Crashpad\reports.

Diagnostics can also be manually triggered by adding --diagnostics to the command line for the application's shortcut target.

C:\Users\USERNAME\AppData\Local\OpenFin\OpenFinRVM.exe --config="https://APP_SERVER.com/APP_MANIFEST.json" --runtime-arguments="--diagnostics"

❗️

DO NOT LEAVE ENABLED IN PRODUCTION ENVIRONMENT

If diagnostics mode is left enabled for an extending period of time, the files in the end-user's temp or cache folder will become extremely large and may affect performance. OpenFin recommends immediately removing the diagnostics flag after recreating the crash.

Crash Reporting tool

An alternative approach to diagnostics mode is to enable the Crash Reporting tool. The benefit of this approach is that there are multiple ways to enable the Crash Reporting tool, including programmatically. The feature is opt-in, and can be configured in your application manifest or triggered by the System.startCrashReporter method.

📘

NOTE

Crash logs can be extremely large and require keys to read the .dmp file.

Add --enable-crash-reporting --no-sandbox arguments to your application manifest:

"runtime": {
    "arguments": "--enable-crash-reporting --no-sandbox"
    },

As with the diagnostics mode, if a renderer or browser process crashes with crash reporting enabled, a .dmp file is generated and stored on the end-user's machine in a subfolder of the temp or cache folder, depending on the version. By default, the OpenFin Runtime delivers this file and the debug.log file to OpenFin's CDN.

If you choose to leverage the System.startCrashReporter method in your application, it is important to note two points:

  • OpenFin recommends coupling Verbose logging (v=1) programmatically via the System.setMinLogLevel method. This ensures the debug.log file captures useful log entries in the event a true crash does not occur.

  • In contrast to the other approaches, this approach does not set the --no-sandbox argument, so the Runtime might have less success in automatically delivering the files to OpenFin. Files are stored on the end-user's file system in a .dmp file in a subfolder of the temp or cache folder, depending on the version.

❗️

DO NOT LEAVE ENABLED IN PRODUCTION ENVIRONMENT

As with diagnostics mode, OpenFin recommends immediately removing the --enable-crash-reporting flag after recreating the crash. When programmatically enabling this option, remind end-users to restart the application to exit this mode.

Configure a custom crash reporter server

If you do not want crash report files to be delivered to OpenFin's server, you can set up your own crash reporter server and direct the files there.

OpenFin leverages the crashReporter module of Electron. The Electron documentation about crashReporter suggests using available open source projects or a third-party hosted solution. Refer to that documentation for details.

To define a custom location for the crash reporter files, you can modify one of the following:

Memory profiling

Through Chrome DevTools, Chromium offers a comprehensive set of tools to profile your application. This tutorial is a good resource for application developers.

🚧

Renderer Crashes

Memory leaks are a primary cause of renderer crashes.

Verbose logging

OpenFin provides two levels of logging:

  • Basic: By default, this mode is always on. It is recommended for production environments.

  • Verbose: This mode must be turned on via an argument (--v=1) in the app manifest or programmatically with System.setMinLogLevel. It is recommended for development purposes or isolated production issues.

"runtime": {
    "arguments": "--v=1"
    },

❗️

Verbose logging in production environments

The Verbose logging setting --v=1 is a runtime switch, which enables Chromium verbosity logging and subsequently increases the volume of messages written to the log. When used in a production environment, this setting can result in excessive log sizes on the local system.\n\nOpenFin recommends using this setting in a production environment only for isolated situations where debugging a production issue is required. Remember to turn verbosity off when debugging is completed.

To limit the log file sizes, you can enable verbose logging through the System.setMinLogLevel method.
fin.System.setMinLogLevel("verbose");

This programmatic approach is well-suited for diagnosing issues in a production environment. Applications can provide this setting embedded in their applications preferences where an end-user can enable the logging while trying to replicate the issue. This same setting can then be switched off by the user in the same location it was enabled, restarting the application or programmatically 'Schedule a Restart', and close the running Runtime:

Application.scheduleRestart();
System.exit();

Log-related APIs

OpenFin offers several methods that you can use directly for your support needs. More details on these calls can be found in fin.System.

OpenFin recommends logging information on a regular basis from the client back to your server or database, as well as active metric gathering when an error or other issue occurs in your application.

Some critical methods in System include the following:

Still have questions?

Get in touch with us at [email protected].

Updated 11 months ago