ClinSpark Agent Log File

Summary

The ClinSpark Agent writes most of its interactions with local devices and interfaces to a local ‘log’ file for troubleshooting purposes.

When encountering an error within a given workflow, the ClinSparkAgent.log file can lend valuable insight into the processes which may be at fault. The support team will frequently request this file be retrieved from local site PCs when troubleshooting issues.

The default location is this path:

Note

Screenshots provided below shows user specific file names, directories, etc. as relative examples to locate the log file.

Instructions

1. Navigate to home (root) directory. This is typically the C: drive, and should be preceded by an “OS” as shown.

   Open

   

2. Open up the “Users” folder

   Open

   

3. Open up the current active user folder (in this example, haeuserww)

4. Open the AppData folder. By default, this is a hidden directory in Windows. If this folder is not displaying, click “View” on the top of the window, and check the box that says “Hidden Items.” The AppData folder should then display.

5. Open the Roaming folder. In the Roaming folder should be a file called ClinSparkAgent.log. The file extension may or may not display depending on configured Windows settings.  Windows may default to treat this file as a text document, as represented in the screenshot.

Multiple Log Files

The Agent will write out statements to the log file up until a certain amount (usually when exceeding 100,000 lines). At some point, the current log file is ‘archived’ and a new file is started. This ensures that the log files on local PCs are of reasonable size and allow the logs to be reviewed and shared with relative ease over time.

When this process occurs, the archived log file will append with a numbered sequence at the end of the file name. For example:

When support team members ask to review log files, it would be ideal to include all of the logs present. Otherwise, the most current log file (without and number appended in the file name) is often the most relevant file.

Log File Review Tips

Realtime Log Monitoring

Often it’s useful to reference the log file for constant review while testing certain workflows. This can give insight into what statements are being written to the log file immediately as actions are performed. Depending on the operating environment of the Agent, and the user who is accessing the log file for this kind of review, it may be helpful to consider real-time monitoring capabilities through the use of a terminal command similar to ‘tail’.

Within a Windows operating environment, ‘tail’ style commands can be easily be called through a number of tools. Built directly into most Windows installations is a command prompt tool called PowerShell. Within PowerShell, the Get-Content cmdlet supports a ‘tail’ parameter that can print out the most recently written lines in a given file. Specifically, this command can monitor a log file and print out a console line each time something is written:

Get-Content C:\Users<user>\AppData\Roaming\ClinSparkAgent.log –Wait

Another way to monitor files is by using 3rd party applications such as Notepad++ or Visual Studio Code, which are free lightweight code editors.

Notepad++ supports ‘tail’ style commands in a feature called Document Monitoring. This feature out of the box is used by simply by opening the log file, and then selecting the ‘Monitor’ options in the View menu.

Windows PowerShell is integrated into editors like Visual Studio. From there, you can open the Agent Log file, and then typically, enter the following commands when starting PowerShell from the home directory:

cd .\AppData\Roaming\ Get-Content .\ClinSparkAgent.log -Wait -Tail 30

This will result in PowerShell keeping open the log file in your terminal:

Short video demonstrating this functionality in Visual Studio Code can be found here:

‘Core Dump’ log files

A core dump or a crash dump is a memory snapshot of a running process. A core dump can be created when a fatal or unhandled error (for example, signal or system exception) occurs.

When a fatal or unhandled error occurs in the Agent, it may terminate open processes and create a corresponding core dump log file. This rarely occurs, but their presence often indicates a rare condition that needs to be promptly investigated and addressed.

Core dump log files will be located in the same directory as the ClinSpark Agent executable file:

For Versions prior to ClinSpark Agent 23.3:

For Versions ClinSpark Agent 23.3 and beyond:

If present, they will have a generated filename something like this: hs_err_pid5160.log

The exact filename will vary, but would start with prefix: hs_err_pid####

These should be provided to Foundry Health via service desk ticket upon request.