ball_recordstringformatter

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Record Format Specification
  • Log Record Attributes Rendering Details
  • Usage

Purpose

Provide a record formatter that uses a printf-style format spec.

Classes

• ball::RecordStringFormatter: printf-style formatter for log records

See also

ball_record, ball_recordattributes

Description

This component provides a value-semantic function-object class, ball::RecordStringFormatter, that is used to format log records according to a printf-style format specification (see "Record Format Specification" below). A format specification and a timestamp offset (in the form of a bdlt::DatetimeInterval) are optionally supplied upon construction of a ball::RecordStringFormatter object (or simply "record formatter"). If a format specification is not supplied, a default one (defined below) is used. If a timestamp offset is not supplied, it defaults to 0. Both the format specification and timestamp offset of a record formatter can be modified following construction.

An overloaded operator() is defined for ball::RecordStringFormatter that takes a ball::Record and an bsl::ostream as arguments. This method formats the given record according to the format specification of the record formatter and outputs the result to the given stream. Additionally, each timestamp indicated in the format specification is biased by the timestamp offset of the record formatter prior to outputting it to the stream. This facilitates the logging of records in local time, if desired, in the event that the timestamp attribute of records are in UTC.

Record Format Specification

The following table lists the printf-style (%-prefixed) conversion specifications, including their expansions, that are recognized within the format specification of a record formatter:

%d - timestamp in 'DDMonYYYY_HH:MM:SS.mmm' format (27AUG2007_16:09:46.161)
%D - timestamp in 'DDMonYYYY_HH:MM:SS.mmmuuu' format
                                                (27AUG2007_16:09:46.161324)
%dtz - timestamp in 'DDMonYYYY_HH:MM:SS.mmm(+|-)HHMM' format
                                              (27AUG2007_16:09:46.161+0000)
%Dtz - timestamp in 'DDMonYYYY_HH:MM:SS.mmmuuu(+|-)HHMM' format
                                           (27AUG2007_16:09:46.161324+0000)
%i - timestamp in ISO 8601 format (without the millisecond or microsecond
                                   fields)
%I - timestamp in ISO 8601 format (*with* the millisecond field)
%O - timestamp in ISO 8601 format (*with* the millisecond and microsecond
                                   fields)
%p - process Id
%t - thread Id
%T - thread Id in hex
%s - severity
%f - filename (as provided by '__FILE__')
%F - filename abbreviated (basename of '__FILE__' only)
%l - line number (as provided by '__LINE__')
%c - category name
%m - log message
%x - log message with non-printable characters in hex
%X - log message entirely in hex
%u - user-defined fields
%% - single '%' character
%A - log all the attributes of the record
%a - log only those attributes not already logged by the %a[name] or
     %av[name] specifier(s)
%a[name] - log an attribute with the specified 'name' as "name=value",
     log nothing if the attribute with the specified 'name' is not found
%av[name] - log only the value of an attribute with the specified 'name',
     log nothing if the attribute with the specified 'name' is not found

(Note that F is used to indicate the shortened form of __FILE__ rather than f because f was given its current interpretation in an earlier version of this component.)

In addition, the following '\'-escape sequences are interpolated in the formatted output as indicated when they occur in the format specification:

\n - newline character
\t - tab character
\\ - single '\' character

Any other text included in the format specification of the record formatter is output verbatim.

When not supplied at construction, the default format specification of a record formatter is:

"\n%d %p:%t %s %f:%l %c %m %u\n"

A default-formatted record having no user-defined fields will have the following appearance:

27AUG2007_16:09:46.161 2040:1 WARN subdir/process.cpp:542 FOO.BAR.BAZ <text>

Log Record Attributes Rendering Details

Log record attributes are rendered as space-separated name="value" pairs (for example: mylibrary.username="mbloomberg"). Note that attribute names are not quoted, whereas attribute values, if they are strings, are always quoted.

Usage

The following snippets of code illustrate how to use an instance of ball::RecordStringFormatter to format log records.

First we instantiate a record formatter with an explicit format specification (but we accept the default timestamp offset since it will not be used in this example):

ball::RecordStringFormatter formatter("\n%t: %m\n");

The chosen format specification indicates that, when a record is formatted using formatter, the thread Id attribute of the record will be output followed by the message attribute of the record.

Next we create a default ball::Record and set the thread Id and message attributes of the record to dummy values:

ball::Record record;
 
record.fixedFields().setThreadID(6);
record.fixedFields().setMessage("Hello, World!");

The following "invocation" of the formatter function object formats record to bsl::cout according to the format specification supplied at construction:

formatter(bsl::cout, record);

As a result of this call, the following is printed to stdout:

6: Hello, World!