Debug Log

There is a basic debug logger that you can use. It is built around the fmt library, so all of the normal fmt formatting rules apply.

There are two “axis” that you can log messages with: the severity, and the verbosity level.

All “severity” levels (info, warn, error) are active at all times. There is a separate “verbosity” level (a number, from zero to a maximum integer) which indicates if the text should be displayed or not. A verbosity of zero (the default) is always displayed.

This allows you to write ‘debugging’ messages at different levels, and able to express the severity at that level independently.

Here is an example:

#include "ark/debuglog/log.hh"

// Standard levels, always visible.
LWARN("This is a warning message.");
LINFO("Here is a string value: {}.", string_value);
LERROR("This is an error.");
LDEBUG("This is an debug statement, {}!.", name);

// Verbosity (filtered) levels.
LINFO_VERBOSE(2, "This is a filtered message.");
LWARN_VERBOSE(5, "This is a filtered warning.");
LERROR_VERBOSE(0, "This is an unfiltered error, equivalent to LERROR().");

All of these messages are dumped to stderr, synchronously, so excessive debug messages can slow your program down.

Throttled Variants

If you are emitting too many debug log statements in one area of code, or simply wish to limit the amount of output to one-output-per-n-seconds, you can use the throttled variants of the debuglog statements:

#include "ark/debuglog/log.hh"

LDEBUG_THROTTLED(0.5, "Prints a debug statement at most every 0.5 seconds.");
LDEBUG_VERBOSE_THROTTLED(1, 0.5, "Prints a debug statement at most every 0.5 seconds, filtered.");

There is some cost to doing this – the ‘steady clock’ will be retrieved each time a log statement is executed, along with an additional mutex request.

Logging Exactly Once

If you want your statement to print once for the lifetime of your program (and only once), then you can use the ‘once’ variants of the debuglog statements:

#include "ark/debuglog/log.hh"

auto lambda = []() { LDEBUG_ONCE("Only prints once."); };

lambda();
lambda();

This will only print the ‘Only prints once.’ text exactly once. Each statement will only trigger a single time.

Environment Variables

You can set the ARK_DEBUGLOG_VERBOSITY environment variable to adjust the verbosity level of any application using the Ark debug logger. This can be handy when they have not exposed a command line flag for this explicitly (and useful for unit test debugging as well).

Extracting Debug Statements from Logs

If you have added the DebugLoggerStage to your pipeline, and then specified that the /debuglog channel is logged, your data log will contain all debug log statements that occurred during the logging run.

You can then use the ark-debuglog-tool to dump all of the debug log statements out of a log to easily view them. Additionally, all debug log statements will be automatically extracted and displayed in the catalog.

Kernel Debug Log

The kernel regularly outputs its own debug log statements (typically viewed through the command line tool dmesg). All of these can be logged by adding the KmsgReaderStage to your pipeline. This will cause all kernel messages (or all messages received over /dev/kmsg) to be written out to the debug log.

See above for how to log the debug log statements or extract them again for viewing.

Google Log Bridge

If you link against the glog_bridge library, and then invoke the following API, we will initiailize glog for you, and redirect all glog output into the Ark debug logger.

This can be helpful for getting third party (or legacy) messages from the Google logger and sent over comms or into your logging stack.

#include "ark/debuglog/glog_bridge.hh"

ark::debuglog::GoogleDebugLogSink::instance();