Skip to main content

Debugging Finsemble

This tutorial provides an overview of techniques that you can use to quickly iterate with Finsemble. If you need targeted support, check out Troubleshooting.

Updating the Finsemble framework​

If you encounter any bugs, first make certain that you're using the latest version of Finsemble. You can verify this through the version field in ../node_modules/@finsemble/finsemble-core/package.json.

Updating the framework​

To update the underlying Finsemble framework, run this commands from your local repository directory:

npm update @finsemble/finsemble-core

See also Upgrading Finsemble.

Using the Chromium Debugger​

Finsemble runs on top of Chromium, which contains the same debugging tools that you are used to in Chrome. Press Control+Shift+I on Windows or Command+Option+I on Mac to pop up Chromium's developer tools for any window.

Follow these steps if the developer tools don't appear:

  1. From the Google Chrome browser, enter "chrome://inspect" in the location bar.
  2. Click "Open Dedicated Devtools for Node."
  3. Click the "Connection" tab and add "localhost:9090" as a connection.
  4. A link to debug each Electron window will appear.

An alternative debugging method is to open a browser and navigate to http://localhost:9090. Each window in your application is listed on that page. Click the window you want to debug and the developer console will be launched for that window. There are some limitations here. For example you can't evaluate code in the console in a remote session, but it largely acts as you would expect.

You can also force an app to spawn its developer console when launched by setting manifest.component.showDevConsoleOnVisible to true in an app's AppD entry.

note

Only logger errors and warnings are written to both the Central Logger and Chromium developer console. All the other logger functions (log, info, debug, verbose) are not captured by the console.

Finsemble's Electron Adapter log files​

Most issues you'll encounter are more easily debugged in the Central Logger or in the Chromium developer console, but for some low level problems, such as startup or window launching, the Finsemble Electron Adapter's log file ("FEA log") can be useful. The FEA log can be found in AppData\Roaming\Electron\logs.

Debugging a service​

Debugging a service can sometimes be difficult if its initialization occurs before the Central Logger comes online (such as with Finsemble's core services). This issue can be eliminated by configuring Finsemble to open the service’s Chromium developer console when the service is launched.

In the service’s configuration, add a property visible and set it to true. The services’ configuration can be temporarily modified in ../node_modules/@finsemble/finsemble-core/configs/core/services.json.

Here's an example of this configuration for the Storage Service:

{
    "services": {
        "storageService": {
            "spawnAs": "window",
            "name": "storageService",
            "html": "$servicesRoot/storage/storage.html",
            "file": "$servicesRoot/storage/storageService.js",
            "category": "system",
            "visible": true
        }
    }
}

FSBL.debug - menus and the toolbar​

FSBL.debug is a flag that when set to true prevents menus from hiding on blurring. This can be useful for debugging issues inside of a menu that normally closes when you click in or outside of it. FSBL.debug also allows you to reload the toolbar without causing Finsemble to shutdown. You can set this value anywhere inside of the menu or toolbar code.

note

To allow toolbar reloading, you must set FSBL.debug before the <ToolbarShell> initializes. Therefore it must be temporarily placed in source code. You cannot set this field dynamically in the developer console if you want to avoid Finsemble shutting down during a reload.

Debugging the storage adapter​

To debug the storage adapter, configure the storage service's visible property to true. When the service is visible, search for the storage adapter’s file name (for example localStorageAdapter.js). Put breakpoints in the storage adapter where you need them. To debug initialization, you might need to set breakpoints and restart Finsemble.

If breakpoints are not hit in the storage adapter, set them for storage adapter methods (get, save, delete,keys, clearCache and empty) in the storage service; it has corresponding methods.

Debugging start-up and the system log​

The System Manager controls Finsemble's start-up processes. The System Manager also provides a basic system log for diagnostics. The system log automatically displays whenever there is a startup problem.

note

The System Manager displays as "Finsemble" in the Central Logger.

The system log provides:

  • The state of the start-up sequence
  • Catastrophic error messages
  • A copy of all user notifications since last start-up

You can access the system log in one of three ways:

  • The log will always be displayed when the manifest’s startup_app.autoShow value is set to true.
  • The log will be displayed only on startup error when the manifest config has finsemble.bootConfig.onErrorMakeSystemManagerVisible set to true.
  • The log can be manually displayed by selecting "System Log" in the Finsemble menu.

You can find detailed diagnostic info in the System Manager's developer console.

Iterate quickly​

Reload​

When running your build process in watch mode, it often isn't necessary to completely quit apps after making changes to them. After you make a change and save your code, reload the app by right-clicking inside it and choosing "Reload." You can also press CTRL+R on Windows or CMD-R on Mac to reload the window that you're focused on and in the window's developer console.

note

You can disabe or override key combos. More information on Hotkeys.

Resetting your application​

As you work on your smart desktop, Finsemble saves state to the activeWorkspace. If you need to start from scratch, you can delete this workspace by clearing storage. To programmatically clear your storage:

FSBL.Clients.StorageClient.clearCache(console.log);

You can also reset your app by using the "reset" icon in the SystemTrayComponent. To see this component, click on the Finsemble icon in your operating system's tray.

Deleting your cache​

You can clear the browser cache for Finsemble.

note

This will also delete the storage for all of your Finsemble applications!

  1. Navigate to: C:\Users<your user>\AppData\Roaming\Electron for local development or C:\Users<your user>\AppData\Roaming\<your desktop name> for an installed copy of a Finsemble desktop. On a Mac, use /Users/<your user>/Library/Application Support/Electron (or name from installer.txt).
  2. Delete the Cache folder.
note

AppData\Roaming\Electron\localStorage is "localStorage", while AppData\Roaming\Electron\cache is cached web pages and their assets. AppData\Roaming\<your desktop name>/e2o/cache/remote_modules is a cache of preload files.

Killing Finsemble​

You can kill Finsemble after running yarn launch or yarn start by pressing CTRL+C in your terminal. If you do this, Finsemble will not save changes to a named workspace. If you quit through the Finsemble toolbar, you will see the option to save changes.

Common failure points (and their solutions)​

npm run dev does nothing​

If npm run dev does nothing and the runtime is hung, it may be because you have zombie processes. This can occur, for instance, if you kill off the dev runner before the application has properly started.

To get back to a good state, open your Windows Task Manager and kill any AssimilationMain.exe, node.exe, or electron.exe processes that are running. You should then be able to start the dev runner again. You might also need to delete your cache (see earlier) to solve this issue.

How can I inspect configuration settings if Finsemble doesn't come up?​

- Case 1: The toolbar is up​

If the toolbar is up, you launch the Central Logger to view the complete manifest containing Finsemble's configuration. First, bring up the Central Logger and ensure all service and component logging is visible by clicking on "Toggle All." Next, enter "processed manifest" into the "Filter Log" box (as opposed to the "Filter Client List" input box). The filtered log entry includes the complete run-time manifest with Finsemble's complete configuration under the FSBL object.

For this case, the data shown is after configuration has been fully processed on startup (that is, macros expanded, configuration files imported) but before dynamic configuration changes have taken place. To see configuration after dynamic configuration changes, filter logs using "revised manifest" to get the revised configuration object.

- Case 2: The toolbar isn't fully up, but the Central Logger is up​

In this scenario, Case 1 instructions might be useful; however that data may or may not exist depending on where start-up failed. Therefore, a third log filter, "initial manifest," is available to show the bootstrap configuration, which is the minimal initial configuration pulled from the manifest and Finsemble's core configuration in order to start the essential Finsemble services.

  • - Case 3: The toolbar isn't up and the Central Logger isn't up​

If neither the toolbar nor the Central Logger are available, you can still see configuration using the Chromium developer console through http://localhost:9090. If the Config Service exists, you can filter its console's output by using "processed manifest." However, that data might not exist, depending on where start-up failed. A more reliable option is to go into the "Finsemble" (Service Manager) window using http://localhost:9090. Click on the Central Logger entry and enter the command showConsole(). Filter on "initial manifest" to see the bootstrap configuration.

You should also inspect the Central Logger's log for configuration-related error messages. You can do this by turning off filtering and enabling only error messages.

How to debug Finsemble and Electron main locally​

You might sometimes want to add breakpoints to your code as you’re debugging it, so that you can collect more details at a specific point. You can do this in VS Code by adding this launch.json to your .vscode file.

Here is the code:

{  
    "version": "0.2.0",
    "configurations": [
        { 
            "name": "Node Server",
            "type": "node",
            "request": "launch",
            "program": "${workspaceFolder}/server/server.js" 
        },
        { 
            "name": "Electron Main", 
            "type": "node",  
            "request": "launch", 
            "program": "${workspaceFolder}/node_modules/@chartiq/finsemble-electron-adapter/startup/devIndex.js", 
            "stopOnEntry": false,
            "args": ["ELECTRON_DEV=true"],
            "cwd": "${workspaceRoot}/node_modules/@chartiq/finsemble-electron-adapter", 
            "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/electron", 
            "runtimeArgs": [  
                "--remote-debugging-port=9090 --inspect=5858", 
                "--manifest http://localhost:3375/configs/openfin/manifest-local.json" 
            ], 
            "env": {} 
        }, 
    ],  "compounds": [
        {     
            "name": "Node Server + Electron Main",   
            "configurations": ["Node Server", "Electron Main"]  
        } 
    ]
}

Launch.json

Here are the steps:

  1. Add launch.json to your .vscode folder in your finsemble-seed project OR Update the launch.json if you already have a launch.json with debug configuration. (Do this by merging your 'configurations' objects and adding the 'compounds' property from the attached launch.json).
  2. Add a breakpoint to \node_modules@chartiq\finsemble-electron-adapter\startup\devIndex.js.
  3. Run the 'Node Server + Electron Main' debug task.
  4. The debugger should halt at the relative break points.

See also​

To zero in on a specific problem, see the Troubleshooting tutorial.

Check out the Central Logger, a great tool for diagnosing problems across multiple windows.