TrueNorth has a lot of functionality – it interfaces with web sites, databases, files on your hard drive, remote sensors, GPS and mobile devices. There is a lot that can go wrong. Your connection could fail, protocols and file formats change, and devices can malfunction. It’s hard to tell what’s gone wrong.
That’s why we build TrueNorth with some advanced diagnostics capabilities that you can turn on to log the inner workings of the program. While you may not be able to tell what’s wrong, you can send this log to us and it can help us identify the issue.
The Trace Log
The first step to get TrueNorth to enabling additional diagnostics is to enable the TrueNorth Trace Log.
Click on the Tools tab and then click on Trace Monitor. The following window will open, docked at the bottom of the form:
The window contains debug and diagnostic information emitted by the program and various components as things run. Some lines contain errors that the program handles internally, some report warnings, and other lines are just for information. The buttons at the top of the window have the following functions
- The first button on the top left of the window will copy all of the text to your clipboard, ready to paste into an email if you have a support questions.
- The next button will open a “Save” dialog box where you can save the text in the window to a file
- The third widow will clear all of the text in the window. This is useful if you know what action will cause an error, and want to just record the trace log for that action.
- The fourth button opens a dialog that allows you to choose which components emit diagnostic messages (see below).
If you shut down TrueNorth with this window open, the program will remember and it will open the next time you run TrueNorth.
You can configure what component of TrueNorth will emit diagnostic messages, and what kind of messages they will log. When you click on the “Configure Diagnostics” button the following dialog will open.
Each row in this dialog represents a component of TrueNorth, and in many ways is a window into the inner workings of the software. Some of the entries are libraries of code that take care of certain parts of the program, others may be plugins that add functionality. For example, TrueNorth.Core is one of the libraries that handles much of the main functions of TrueNorth, while TrueNorth.Vector is the plugin that renders vector data on a map.
Each component can be enabled or disabled using the check box in the row. Enabled means it will generate output depending on the value of the Trace Level Output value. Disabled means no output will be generated.
Trace Level Output indicates what kind of output is generated. The categories are as follows:
- Off: Output no tracing and debugging messages
- Critical: Output critical errors only.
- Error: Output error-handling messages and critical messages.
- Warning: Output warnings and error-handling and critical messages
- Information: Output informational messages, warnings, error-handling and critical messages. Often contains important and successful milestones of application execution, regardless of whether the application is working properly or not.
- Verbose: Output all debugging and tracing messages including informational messages and other messages that indicate progress and application state.
- ActivityTracing: Output information about flow events between processing activities and components.
- All: Output all diagnostics messages in all categories.
Normally, components will be set to generate no output, or only error conditions. Not all error conditions need to be addressed by the user.
If you are experiencing issues you may be directed by TrueNorth Support to enable or disable trace output on one or more components, and to set the trace level output value to Verbose or above.
The normal procedure to log a trace for an abnormal behaviour (a bug) in TrueNorth is
- Launch TrueNorth.
- Reproduce the error condition.
- Open the Trace Log (see above).
- Enable one or more components as directed.
For example, an error in the Garmin GPS Import functionality would require you to enable TrueNorth.GPS and set it to Verbose.
- Reproduce the error condition again.
- Examine the trace log – possibly saving it and sending it to TrueNorth Support staff.