Welcome to OpenFin Docs

Explore our guides, resources and references for building with OpenFin

Get Started

Testing and debugging

OpenFin provides application providers with the tools needed to support their application development. These features range from the Chrome DevTools 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 Chrome browser

  1. Launch Chrome browser
  2. Enter the following URL: http://localhost:9090
  3. You’ll see a list of the running web pages. Select the page you’d like to debug

Launch via your app

Set the contextMenu to true in your app config JSON file as followings:

"startup_app": {
    
    "contextMenu": true
}

With this enabled, you’ll be able to 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/Browser crash

Although rare, Renderer or Browser crashes may occur within your OpenFin environment. If it does, OpenFin has tools to provide application providers to collect the necessary information / logs to diagnose the cause. In our experience, the leading contributors to a renderer crash are application memory leaks or AntiVirus software killing a process.

Sample Renderer Crash Message

Sample Renderer Crash Message

NOTE

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

Diagnostics mode

Diagnostics mode provides application providers (and end-users) an opportunity to recreate a Runtime Renderer or Browser Crash within your application and generate crash logs. The feature is opt-in, can be configured in your application config or triggered from a command line.

Add --diagnostics argument to your application config

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

When enabled, end-users can re-launch your application in this mode 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 / Debug logs 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 machine in %temp%/OpenFin Crashes/FILENAME.dmp. The OpenFin Runtime will deliver this .dmp file and the debug.log file to OpenFin's CDN.

NOTE

Crash logs can be extremely large, require keys to read the .dmp file and can only be delivered to OpenFin. OpenFin will receive the files, if the end-user's machine is behind a firewall that can reach OpenFin's CDN.

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://YOURAPPSERVER.COM/app.json" --runtime-arguments="--diagnostics"

DO NOT LEAVE ENABLED IN PRODUCTION ENVIRONMENT

If left enabled for an extending period of time, the files in the end-user's temp folder will become extremely large and may impact performance over time. OpenFin recommends immediately removing diagnostics flag post recreation of the crash.

Crash Reporting tool

An alternative approach to diagnostics mode is to enable the Crash Reporting Tool. The benefit to this approach is that an application provider has multiple approaches to enable the Crash Reporting Tool, including programmatically. The feature is opt-in, and can be configured in your application config or passed in via the System.startCrashReporter API.

Add --enable-crash-reporting --no-sandbox arguments to your application config.

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

As with the diagnostics mode, if a Renderer or Browser process crashes with diagnostics enabled, a .dmp file is generated and stored on the end-user's machine in %temp%/OpenFin Crashes/FILENAME.dmp. The OpenFin Runtime will deliver this .dmp file and the debug.log file to OpenFin's CDN.

If choosing to leverage the System.startCrashReporter API in your application, its important to note 2 points

  1. OpenFin recommends coupling Verbose logging (v=1) programmatically via the System.setMinLogLevel. This ensures the debug.log will also capture useful logging in the event a true crash does not occur.
  2. This approach will have less success in automatically delivering the files to OpenFin because the --no-sandbox flag will not be set. Files are stored on the end-user's machine in %temp%/OpenFin Crashes/FILENAME.dmp.

DO NOT LEAVE ENABLED IN PRODUCTION ENVIRONMENT

As with diagnostics mode, OpenFin recommends immediately removing diagnostics flag post recreation of the crash. When programmatically enabling this option, you'll want to remind end-users to restart the application to exit this mode.

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 main cause of renderer crash.

Verbose logging

OpenFin provides two levels of logging:

  1. Basic - default is always on. Recommended for Production environments.
  2. Verbose - (--v=1) which needs to be turned on via an argument in your app config or programmatically with System.setMinLogLevel. Recommended for development purposes or isolated Production issues.
"runtime": {
    "arguments": "--v=1"
    },

Verbose Logging in Production Environments

Please note that 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 in a Production environment, this setting can result in excessive log sizes on the local system.

OpenFin recommends ONLY using this setting in a Production environment for isolated situations where debugging a production issue is required. Remember to turn verbosity off when debugging is completed.

Best Practice

In an effort to limit the log file sizes, Application Providers can enable verbose logging through the System.setMinLogLevel API call to facilitate debugging from their application code:

fin.System.setMinLogLevel("verbose");

This programatic approach is perfect 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() - (https://developer.openfin.co/docs/javascript/stable/tutorial-Application.scheduleRestart.html); System.exit() - (https://developer.openfin.co/docs/javascript/stabl/System.html#exit);

APIs

OpenFin offers several API calls that can be used directly by application providers for their 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/db, as well as active metric gathering when an error or other issue occurs in your application.

Some critical APIs in System are:

Testing Examples

Have questions? Get in touch with us at support@openfin.co.

Updated 12 days ago


Testing and debugging


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.