Trace forwarding protocol

The Cardano node is able to send its metrics for an external process using TraceForwarderBK plugin, and the external process is able to receive these metrics using TraceAcceptorBK plugin. This guide describes the TraceForwarderBK/TraceAcceptorBK protocol.

Protocol

TraceForwarderBK plugin sends its metrics as a pair of ByteStrings:

HOSTNAME\nLIST_OF_LOGOBJECTS_AS_JSON

where:

1. HOSTNAME is a ByteString containing the name of host (for example, "linux") encoded in UTF-8 (source code).
2. LIST_OF_LOGOBJECTS_AS_JSON is a list of LogObjects as a ByteString conaining [LogObject a] encoded to JSON as UTF-8 (source code).

Example

This example contains the hostname linux and the list of 3 LogObjects with metrics cardano.node.release, cardano.node.version and cardano.node.commit.

linux
[{"loname":"cardano.node.release","locontent":{"kind":"LogMessage","message":"ByronProtocol"},"lometa":{"tstamp":"2020-08-11T15:04:32.354943121Z","hostname":"linux","severity":"Notice","privacy":"Public","tid":"48"}},{"loname":"cardano.node.version","locontent":{"kind":"LogMessage","message":"1.18.0"},"lometa":{"tstamp":"2020-08-11T15:04:32.354943121Z","hostname":"linux","severity":"Notice","privacy":"Public","tid":"48"}},{"loname":"cardano.node.commit","locontent":{"kind":"LogMessage","message":"a0eb636"},"lometa":{"tstamp":"2020-08-11T15:04:32.354943121Z","hostname":"linux","severity":"Notice","privacy":"Public","tid":"48"}}]

Please note that this is a complete example: it can be stored to the file and directly submitted to the named pipe using nc program.

Links

1. Data.ByteString.Char8 module.
2. LogObject a definition.
3. TraceForwarderBK plugin.
4. TraceAcceptorBK plugin.