ObsessiO / Mirth-MetaAppender

Eliminates the logging limitations of the Mirth enterprise application integration system by replacing the logging mechanism

Context

• This repository enhances the Mirth enterprise service bus, an application integration middleware that enables the information exchange between arbitrary applications in the healthcare sector.
• The source code of the open source version of this dual-licenced product can be found in this repository.
• The quite active community around Mirth mainly exchanges via this forum
• The company providing a ready to go download version as well as commercial support for this product is NextGen Healthcare

Functionality
This library eliminates Mirth logging limitations by replacing the logging mechanism.

• All log messages created by a channel will be placed in a separate log file named like the channel itself.
• Messages that are not caused by a channel (e.g. global deploy script) are logged to the standard log file [I]mirth.log[/I].
• All messages on log level ERROR are accumulated in a specific log file called [I]mirthErrors.log[/I].
• All messages that are logged to the console or administrator dashboard are enriched with the name of the channel causing the message.

How to use:

1. Create a jar file from the code or download the latest release
2. Copy the jar to the custom-lib subfolder of your mirth installation
3. Add the following code to the global deploy script:
   Packages.lu.hrs.mirth.MetaAppender.activate();
   (just needs to be called once after the service is started but multiple calls do not do harm)
4. ❗If you are using the function activateChannelLogging(), remove it or remove it's content if already referenced in many places❗
5. Restart the mirth service

Customization:
By default the logging configuration of log4j.properties in the subfolder .\config of the mirth installation is used. It is however possible to overwrite certain parameters by providing them to the activate() call:

Packages.lu.hrs.mirth.MetaAppender.activate(<customLogPath>, <customMaxFileSize>, <customMaxBackupIndex>, <customLogPattern>, <logAllToMainLog>);

customLogPath - Defines a custom location for the log files
customMaxFileSize - Defines a custom maximal size per log file
customMaxBackupIndex - Defines a maximum number of log files that will be created per channel till the oldest is overwritten (round-robin)
customLogPattern - Defines a custom structure for the log file entries
logAllToMainLog - If this flag is set, all log entries (also channel-specific ones) will also be logged to the main log. (off by default)

• All parameter are optional and can be expressed by null.
• Tailing parameters can be omitted.

Examples:
Writes the channel-specific log entries in a custom structure:
Packages.lu.hrs.mirth.MetaAppender.activate(null, null, null, "%d %-5p %c: %m%n");

Extends the size of all log files to 5MB and logs all channel data also to the main log file (mirth.log):
Packages.lu.hrs.mirth.MetaAppender.activate(null, '5MB', null, null, true);

Further features:
Focus on specific channel log
If many channels are logging to the dashboard, you might want to focus on the log output of one specific channel if e.g. an issue occurs.
This can be done via:
Packages.lu.hrs.mirth.MetaAppender.setFocus(<Channel name or id>);
Focus can be removed by:
Packages.lu.hrs.mirth.MetaAppender.removeFocus();

• Setting a focus does not influence the logging to the channel log-files but only the dashboard.
• If a focus is set, this is indicated by a "FOCUSED: "-prefix before the channel name of each log entry.

Suppress specific channel log
In case of an issue with a specific channel, you might want to log additional information for tracking down the bug (even in prod env 😎). However, while having additional information in the channel log, you probably do not want to have your dashboard log spammed.
This can be done via:
Packages.lu.hrs.mirth.MetaAppender.setFilter(<Channel name or id>);
Focus can be removed by:
Packages.lu.hrs.mirth.MetaAppender.removeFilter();

• Setting a filter does not influence the logging to the channel log-files but only the dashboard.
• If a filter is set, this is indicated by a "FILTERED: "-prefix before the channel name of each log entry.

Additional Information:

• The meta appender "hijacks" the mirth logging mechanism and gains that way full control over all logging activities.
• It thus substitutes the approach posted some time ago in the Mirth support forum. It overcomes all weaknesses of this initial approach (no exception logging to channel logs, no automated integration for transformers).
• It solves all issues mentioned here in Mirth Jira