Logging

RoadRunner has extensive logging system. Many internal methods will log extensive details (in full color) to either the clog (typically stderr) or a user specified file path. Internally, the RoadRunner logging system is currently implemented by the Poco (http://pocoproject) logging system.

Future versions will include a Logging Listener, so that the RoadRunner log will log messages to a user specified function.

The logging system is highly configurable, users have complete control over the color and format of the logging messages.

All methods of the Logger are static, they are available immediately upon loading the RoadRunner package.

If one wants to display logging at the lowest level (LOG_TRACE), where every logging message is displayed, one would run:

roadrunner.Logging.setLevel(roadrunner.Logging.LOG_TRACE)

Logging the following messages:

roadrunner.Logger.log(roadrunner.Logger.LOG_FATAL, "A fatal message")
roadrunner.Logger.log(roadrunner.Logger.LOG_CRITICAL, "A critical message")
roadrunner.Logger.log(roadrunner.Logger.LOG_ERROR, "An error message")
roadrunner.Logger.log(roadrunner.Logger.LOG_WARNING, "A warning message")
roadrunner.Logger.log(roadrunner.Logger.LOG_NOTICE, "A notice message")
roadrunner.Logger.log(roadrunner.Logger.LOG_INFORMATION, "An informational message")
roadrunner.Logger.log(roadrunner.Logger.LOG_DEBUG, "A debugging message.")
roadrunner.Logger.log(roadrunner.Logger.LOG_TRACE,  "A tracing message. This is the lowest priority.")

will produce the following output:

../_images/logging.png

If one wants different colors on the log, these can be set via:

rr.Logger.setProperty("traceColor", "red")
rr.Logger.setProperty("debugColor", "green")

The available color property names and values are listed below at the Logger.setProperty method.

Logging Levels

The Logger has the following logging levels:

Logger.LOG_CURRENT

Use the current level – don’t change the level from what it is.

Logger.LOG_FATAL

A fatal error. The application will most likely terminate. This is the highest priority.

Logger.LOG_CRITICAL

A critical error. The application might not be able to continue running successfully.

Logger.LOG_ERROR

An error. An operation did not complete successfully, but the application as a whole is not affected.

Logger.LOG_WARNING

A warning. An operation completed with an unexpected result.

Logger.LOG_NOTICE

A notice, which is an information with just a higher priority.

Logger.LOG_INFORMATION

An informational message, usually denoting the successful completion of an operation.

Logger.LOG_DEBUG

A debugging message.

Logger.LOG_TRACE

A tracing message. This is the lowest priority.

Logging Methods

static Logger.setLevel([level])

sets the logging level to one a value from Logger::Level

Parameters:

level (int) – the level to set, defaults to LOG_CURRENT if none is specified.

static Logger.getLevel()

get the current logging level.

static Logger.disableLogging()

Suppresses all logging output

static Logger.disableConsoleLogging()

stops logging to the console, but file logging may continue.

static Logger.enableConsoleLogging(level)

turns on console logging (stderr) at the given level.

Parameters:

level – A logging level, one of the above listed LOG_* levels.

static Logger.enableFileLogging(fileName[, level])

turns on file logging to the given file as the given level.

Parameters:
  • fileName (str) – the path of a file to log to.

  • level – (optional) the logging level, defaults to LOG_CURRENT.

static Logger.disableFileLogging()

turns off file logging, but has no effect on console logging.

static Logger.getCurrentLevelAsString()

get the textural form of the current logging level.

static Logger.getFileName()

get the name of the currently used log file.

static Logger.setFormattingPattern(format)

Internally, RoadRunner uses the Poco logging framework, so we can custom format logging output based on a formatting pattern string.

The format pattern is used as a template to format the message and is copied character by character except for the following special characters, which are replaced by the corresponding value.

An example pattern of “%Y-%m-%d %H:%M:%S %p: %t” set via:

roadrunner.Logger.setFormattingPattern("%Y-%m-%d %H:%M:%S %p: %t")

would produce the following output:

../_images/logging2.png

RoadRunner supports the following format specifiers. These were copied from the Poco documentation:

  • %s - message source

  • %t - message text

  • %l - message priority level (1 .. 7)

  • %p - message priority (Fatal, Critical, Error, Warning, Notice, Information, Debug, Trace)

  • %q - abbreviated message priority (F, C, E, W, N, I, D, T)

  • %P - message process identifier

  • %T - message thread name

  • %I - message thread identifier (numeric)

  • %N - node or host name

  • %U - message source file path (empty string if not set)

  • %u - message source line number (0 if not set)

  • %w - message date/time abbreviated weekday (Mon, Tue, …)

  • %W - message date/time full weekday (Monday, Tuesday, …)

  • %b - message date/time abbreviated month (Jan, Feb, …)

  • %B - message date/time full month (January, February, …)

  • %d - message date/time zero-padded day of month (01 .. 31)

  • %e - message date/time day of month (1 .. 31)

  • %f - message date/time space-padded day of month ( 1 .. 31)

  • %m - message date/time zero-padded month (01 .. 12)

  • %n - message date/time month (1 .. 12)

  • %o - message date/time space-padded month ( 1 .. 12)

  • %y - message date/time year without century (70)

  • %Y - message date/time year with century (1970)

  • %H - message date/time hour (00 .. 23)

  • %h - message date/time hour (00 .. 12)

  • %a - message date/time am/pm

  • %A - message date/time AM/PM

  • %M - message date/time minute (00 .. 59)

  • %S - message date/time second (00 .. 59)

  • %i - message date/time millisecond (000 .. 999)

  • %c - message date/time centisecond (0 .. 9)

  • %F - message date/time fractional seconds/microseconds (000000 - 999999)

  • %z - time zone differential in ISO 8601 format (Z or +NN.NN)

  • %Z - time zone differential in RFC format (GMT or +NNNN)

  • %E - epoch time (UTC, seconds since midnight, January 1, 1970)

  • %[name] - the value of the message parameter with the given name

  • %% - percent sign

Parameters:

format (str) – the logging format string. Must be formatted using the above specifiers.

static Logger.getFormattingPattern()

get the currently set formatting pattern.

static Logger.levelToString(level)

gets the textual form of a logging level Enum for a given value.

Parameters:

level (int) – One of the above listed logging levels.

static Logger.stringToLevel(s)

parses a string and returns a Logger::Level

Parameters:

s (str) – the string to parse.

static Logger.getColoredOutput()

check if we have colored logging enabled.

static Logger.setColoredOutput(b)

enable / disable colored output

Parameters:

b (boolean) – turn colored logging on or off

static Logger.setProperty(name, value)

Set the color of the output logging messages.

In the future, we may add additional properties here.

The following properties are supported:

  • enableColors: Enable or disable colors.

  • traceColor: Specify color for trace messages.

  • debugColor: Specify color for debug messages.

  • informationColor: Specify color for information messages.

  • noticeColor: Specify color for notice messages.

  • warningColor: Specify color for warning messages.

  • errorColor: Specify color for error messages.

  • criticalColor: Specify color for critical messages.

  • fatalColor: Specify color for fatal messages.

The following color values are supported:

  • default

  • black

  • red

  • green

  • brown

  • blue

  • magenta

  • cyan

  • gray

  • darkgray

  • lightRed

  • lightGreen

  • yellow

  • lightBlue

  • lightMagenta

  • lightCyan

  • white

Parameters:
  • name (str) – the name of the value to set.

  • value (str) – the value to set.

static Logger.log(level, msg)

logs a message to the log.

Parameters:
  • level (int) – the level to log at.

  • msg (str) – the message to log.