Logging in Custom Devices
- Nick Judson
Connexion has two primary log types:
Message Context Logging
A message context object wraps each message as it passes through your channel. It holds the message currently being processed as well as related metadata, methods, and properties. If you are writing log information which pertains to the message currently being processed (for example, the message fails validation), then use the IMessageContext.WriteEvent method. This will write information into the Processing History log for the current message. If you write an error log entry, your message will be moved to the error queue.System-level Logging
Using the Logger.Write method within your custom device will write to the Connexion system logger. This logger typically writes to textual log files in the %programdata%\ConnexionV14\Logs folder, the Windows event log, and to the event log in the Connexion database. Log information here if it doesn't relate to a specific message being processed. For example, your device cannot start because it has missing or invalid configuration.
Don't Write PHI!
Make sure you do not write PHI in your log statements. Connexion routes log statements from your custom device to the Connexion.User.txt file instead of the Connexion.txt file to attempt to minimize any chance of PHI being accidentally released (the user log file is not included in any reports). Please be cognizant of what is being written in your log statements.
The following shows the difference between the two logging types (Visual Studio project: LoggingExample.zip):
In version 15 onward, Debug and Info level log events are no longer written to the Events table in the database
To minimize database bloat, only Warning and Error events are written to the event table. All other events written via Logger.Write(...) are sent to the Connexion.User.txt log file. Log file content can be viewed directly from the Connexion and Gateway UIs.
In this ProcessMessage method, the user is logging to the system log:
Notice how we end up with a line in the event log table for every message processed:
This dilutes the event log table and makes it difficult to find important information (in addition to reduced query performance). Instead, any logging which relates to the message currently being processed should use the IMessageContext.WriteEvent method:
Now the log information is displayed when the message is active in the queue device:
Write to the system log file when you are writing infrequently, or in conditions which don't relate to a specific message. For example, if you detect that configuration settings are missing or invalid in your Start() method, use Logger.Write:
Event IDs under 10,000 are reserved for Connexion. If you are supplying your own event ID, please use a number between 10,001 and 65,000
Conditional Logging
In some cases you may need to enable verbose logging to diagnose errors for a specific device. This is easy to achieve by creating a configuration property to enable/disable verbosity:
Then create some wrapper methods for your debug/trace log statements:
Instead of calling Logger.Write(EventSeverity.Debug...) or context.WriteEvent(EventSeverity.Debug...) directly, call the appropriate Debug method. Only if the user has enabled debug-level logging will the information be written.