The Diagnostic codec connectivity plug-in
The Diagnostic codec can be used to diagnose issues with connectivity plug-ins. It logs the events that go through a connectivity chain in either direction.
To reference the Diagnostic codec, an entry such as the following is required in the
connectivityPlugins section of the configuration file (see also
Configuration file for connectivity plug-ins):
diagnosticCodec:
libraryName: DiagnosticCodec
class: DiagnosticCodec
You can then add the diagnosticCodec at any point in a connectivity chain. With no further configuration, the codec logs to the correlator log file at INFO level.
An example configuration may look as follows:
startChains:
myChain:
- apama.eventMap
- diagnosticCodec:
tag: host
output: logger
logLevel: DEBUG
- myCodec # the codec being inspected
- diagnosticCodec:
tag: transport
output: logger
logLevel: DEBUG
- myTransport
The following configuration options are available:
Configuration option | Description |
tag: string | If a chain has multiple diagnosticCodec instances, you can specify a tag for each instance to distinguish it from other instances. string is the tag that is used to prefix the messages from the current instance. Default: empty. |
output: mode | Defines the file to which the codec logs its output. mode can be one of the following:  logger - Default. The codec logs to the correlator log file at the log level that is defined with logLevel. file - The codec logs to the file that is defined with fileName. |
logLevel: level | Applies when the logger mode is defined. level can be any correlator log level. Default: INFO. |
fileName: file | Applies when the file mode is defined. file is either the path to a file or one of the special strings stdout or stderr. Default: stdout. |
When writing to the correlator log file, the Diagnostic codec replaces any non-printable ASCII characters (those with ASCII values less than 0x20, which includes tab and newline) with an underscore (_) character.
Output to files
If the mode of the output configuration option is set to file, the Diagnostic codec formats the output messages as follows:
[tag] direction: metadata / payload
where:
tag is optional. This is the tag that is defined in the configuration (or omitted completely if no tag is configured). If a tag is present, it is enclosed in square brackets.
direction is either
Towards Host or
Towards Transport.
metadata is the content of the metadata at the point in the chain where the Diagnostic codec has been placed.
payload is the content of the payload at the point in the chain where the Diagnostic codec has been placed.
The following is an example of an output message that is written to a file:
[host] Towards Transport: {sag.type:test.EventType, sag.channel:myChain} / {t:Isabelle,isB:true}
Output to loggers
If the mode of the output configuration option is set to logger, the Diagnostic codec formats the output messages with an additional prefix:
timestamp loglevel [threadID] - <connectivity.codecname.chainname>
where:
timestamp is the date and time that the output was logged.
loglevel is configured in the Diagnostic codec configuration.
threadID is the unique integer identifier of the thread that logged the message.
codecname is the name of the Diagnostic codec listed in the configuration (usually
diagnosticCodec).
chainname is the name of the codec chain listed in the configuration.
The following is an example of an output message that is written to a log file:
2020-03-16 17:45:14.472 DEBUG [18744] - <connectivity.diagnosticCodec.myChain> [host] Towards Transport: {sag.type:test.EventType,sag.channel:myChain} / {t:Isabelle,isB:true}