Skip to content

Poco::Util::Application Logging Configuration

Jump to bottom
Günter Obiltschnig edited this page Nov 3, 2022 · 1 revision

Poco::Util::Application supports a very flexible logging configuration, allowing fine-grained control over the amount of logging data produced. Logging information can be written to the console, to a log file, or to the syslog daemon.

Logging is based on the concept of loggers, channels and formatters. A logger creates a log message, which is then formatted using a formatter, and then sent to a channel. The kind of channel decides whether the message is written to the console, to a file, or to the syslog daemon. Loggers form a hierarchy, with a special logger, the root logger, at the base. A logger inherits its configuration from the logger(s) above in the hierarchy. If only the root logger is configured, all loggers will inherit the configuration of the root logger. In the following, we will only configure the root logger, as this is sufficient for most production purposes. A logger’s configuration consists of the channel the logger is connected to, as well as its log level. Every log message is tagged with a priority, or log level. A logger will only forward messages with a priority higher than the configured log level. The following priorities or log levels are available:

  • none (turns off logging)
  • fatal (highest priority)
  • critical
  • error
  • warning
  • notice
  • information
  • debug
  • trace (lowest priority)

logging.loggers.root.channel

This setting specifies which channel is connected to the root logger. A channel with the name specified here must be defined in the configuration file, otherwise the application won’t start up. The default configuration file specifies two channels, one named console and one named file. Additional channels can be added if necessary.

logging.loggers.root.level

This setting specifies the log level of the root logger. Specify one of the log levels none, fatal, critical, error, warning, notice, information, debug or trace. The lower the level, the more information will be logged. For production purposes, the log level notice or warning is recommended.

logging.channels.file.class

This setting creates a channel named file for writing to a log file (FileChannel).

logging.channels.file.pattern

This setting specifies the format of the log messages for the file channel. See Logging Format Placeholders for a list of supported format placeholders.

logging.channels.file.path

The path of the log file.

logging.channels.file.rotation

The log file rotation strategy. Log files can be rotated based on size or time interval. Rotating a log file means closing the current log file, renaming ("archiving") it, and creating a new log file. The following values can be given:

  • never: No log rotation. The log file will grow indefinitely. Default.
  • [day,][hh]:mm: The log file is rotated on specified day/time.
    • day is specified as long or short day name (Monday/Mon, Tuesday/Tue, ... ) and can be omitted, in which case log is rotated daily.
    • hh: hour – valid hour range is 00-23; can be omitted, in which case log is rotated every hour.
    • mm: minute – valid minute range is 00-59 and must be given.
  • daily: the file is rotated daily.
  • weekly: The file is rotated every seven days.
  • monthly: The file is rotated every 30 days.
  • <n> minutes: The file is rotated every <n> minutes, where <n> is an integer greater than zero.
  • <n> hours: The file is rotated every <n> hours, where <n> is an integer greater than zero.
  • <n> days: The file is rotated every <n> days, where <n> is an integer greater than zero.
  • <n> weeks: The file is rotated every <n> weeks, where <n> is an integer greater than zero.
  • <n> months: The file is rotated every <n> months, where <n> is an integer greater than zero and a month has 30 days.
  • <n>: The file is rotated when its size exceeds <n> bytes.
  • <n> K: The file is rotated when its size exceeds <n> Kilobytes.
  • <n> M: The file is rotated when its size exceeds <n> Megabytes.

NOTE: For periodic log file rotation (daily, weekly, monthly, etc.), the date and time of log file creation or last rotation is written into the first line of the log file. This is because there is no reliable way to find out the real creation date of a file on many platforms (e.g., most Unix platforms do not provide the creation date, and Windows has its own issues with its "File System Tunneling Capabilities").

logging.channels.file.time

Using this setting it is possible to specify whether the times used for rotation are in UTC or local time. The following values are supported:

  • utc: Rotation is based on UTC time (default).
  • local: Rotation is based on local time.

logging.channels.file.archive

Using the this setting it is possible to specify how archived log files are named. The following values are supported:

  • number: A number, starting with 0, is appended to the name of archived log files. The newest archived log file always has the number 0. For example, if the log file is named myapplication.log, and it fulfils the criteria for rotation, the file is renamed to myapplication.log.0. If a file named myapplication.log.0 already exists, it is renamed to myapplication.log.1, and so on.
  • timestamp: A timestamp is appended to the log file name. For example, if the log file is named myapplication.log , and it fulfils the criteria for rotation, the file is renamed to myapplication.log.20190510113000.

logging.channels.file.purgeAge

Archived log files can be automatically purged, either if they reach a certain age, or if the number of archived log files reaches a given maximum number. This is controlled by the purgeAge and purgeCount settings.

The purgeAge property can have the following values:

  • <n> [seconds]: The maximum age is <n> seconds.
  • <n> minutes: The maximum age is <n> minutes.
  • <n> hours: The maximum age is <n> hours.
  • <n> days: The maximum age is <n> days.
  • <n> weeks: The maximum age is <n> weeks.
  • <n> months: The maximum age is <n> months, where a month has 30 days.

logging.channels.file.purgeCount

This setting specifies the maximum number of archived log files. If the number is exceeded, archived log files deleted, starting with the oldest.

logging.channels.file.compress

Archived log files can be compressed using the gzip compression method. The following values are supported:

  • true: Compress archived log files.
  • false: Do not compress archived log files.

logging.channels.console.class

This setting creates a channel named console for writing to standard output (ColorConsoleChannel).

logging.channels.console.pattern

This setting specifies the format of the log messages for the console channel. See Logging Format Placeholders for a list of supported format placeholders.

Logging Format Placeholders

  • %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)
  • %L: use local time zone for dates and times (must be specified before any of the date/time placeholders)
  • %%: percent sign
Clone this wiki locally