ball_cstdioobserver

Detailed Description

Provide an observer that emits log records to a FILE *.

Outline

• Purpose
• Classes
• Description
  • Log Record Formatting
    • Scheme-Based Format Specifications (Recommended)
    • Legacy Format Specifications
  • Thread Safety
  • Usage
    • Example 1: Basic Usage

Purpose

Provide an observer that emits log records to a FILE *.

Classes

• ball::CstdioObserver: observer that emits log records to a FILE *

See also

ball_record, ball_context, ball_loggermanager

Description

This component provides a concrete implementation of the ball::Observer protocol for receiving and processing log records:

               ,--------------------.
              ( ball::CstdioObserver )
               `--------------------'
                         |              ctor
                         |              disablePublishInLocalTime
                         |              enablePublishInLocalTime
                         |              setFormat
                         |              setFormatFunctor
                         |              getFormat
                         |              isPublishInLocalTimeEnabled
                         V
                  ,--------------.
                 ( ball::Observer )
                  `--------------'
                                        publish
                                        releaseRecords
                                        dtor

ball::CstdioObserver is a concrete class derived from ball::Observer that processes the log records it receives through its publish method by writing them to a C stdio output file (FILE *). Given its minimal functionality, ball::CstdioObserver should be used with care in a production environment. It is not recommended to construct this observer with file-based streams due to lack of any file rotation functionality, however it is ideal for writing to stdout or stderr.

Log Record Formatting

By default, the output format of published log records is:

DATE_TIME PID THREAD-ID SEVERITY FILE LINE CATEGORY MESSAGE USER-FIELDS

where DATE and TIME are of the form DDMonYYYY and HH:MM:SS.mmm, respectively (Mon being the 3-letter abbreviation for the month). For example, assuming that no user-defined fields are present, a log record will have the following appearance when the default format is in effect:

18MAY2005_18:58:12.076 7959 1 WARN ball_cstdioobserver.t.cpp 404 TEST hi!

The default format and the formatter used can be changed by calling the setFormat method. The format specifications can be either scheme-tagged (recommended) or legacy format strings that results in a RecordStringFormatter being used. See {Scheme-Based Format Specifications (Recommended)} and {Legacy Format Specifications}.

streamObserver.setFormat("qjson://%d %s %m");

The above statement will cause subsequent records to be logged as JSON objects that contain a timestamp in 'DDMonYYYY_HH:MM:SS.mmm' format, the severity, and the log message.

Scheme-Based Format Specifications (Recommended)

The log record format can be specified using a URI-like scheme-tagged format configuration string passed to the setFormat method. The scheme determines which formatter will be used:

• text://<format-specification>

  ‍Uses ball::RecordStringFormatter with the provided format specification. For example: "text://\n%d %p:%t %s %f:%l %c %m %a\n"

• qjson://<format-specification>

  ‍Uses ball::RecordJsonFormatter to output log records in JSON format using a simplified printf-style format specification. The format specification uses %-prefixed fields (e.g., "%d" for timestamp, "%s" for severity, "%m" for message). For example: "qjson://%d %s %m". See ball_recordjsonformatter for the complete list of supported % fields.

• json://<format-specification>

  ‍Uses ball::RecordJsonFormatter to output log records in JSON format. The format specification must be a JSON array (using [] brackets) listing the field names to include in the output. For example: json://["timestamp","severity","message"]. See ball_recordjsonformatter for details on supported field names and format specifications.

  Examples:

  // Use JSON formatter with simplified printf-style format specification
  streamObserver.setFormat("qjson://%d %s %m");
   
  // Use text formatter with custom format
  streamObserver.setFormat("text://%d %p %t %s %f %l %c %m %a\n");
   
  // Use JSON formatter with selected fields
  streamObserver.setFormat("json://[\"timestamp\",\"severity\",\"message\"]");

Legacy Format Specifications

If no scheme is specified (i.e., the configuration doesn't contain ://), the configuration is treated as a format specification for ball::RecordStringFormatter (equivalent to text://). The %-prefixed conversion specifications for the "text://" format are defined in ball_recordstringformatter .

Note that the observer's default text format emits newline characters at the beginning and at the end of a log record, so the user needs to add them explicitly to (text) format strings to preserve that behavior.

There is also a legacy way to override the default format by supplying a suitable formatting functor using setFormatFunctor. For example, an instance of ball::RecordStringFormatter is such a functor:

ball::CstdioObserver streamObserver(stdout);
streamObserver.setFormatFunctor(
            ball::RecordStringFormatter("%I %p:%t %s %f:%l %c %m %a\n"));

The above statement will cause subsequent records to be logged in a format that is almost identical to the default format except that the timestamp attribute will be written in ISO 8601 format, and the user fields will be replaced by the more modern attributes.

Example using format specification directly (no scheme):

// Backward compatible: no scheme means text format
streamObserver.setFormat("%d %p %t %s %f %l %c %m %a\n");

Thread Safety

All methods of ball::CstdioObserver are thread-safe, and can be called concurrently by multiple threads.

Usage

This section illustrates intended use of this component.

Example 1: Basic Usage

The following snippets of code illustrate the basic usage of ball::CstdioObserver.

First create a ball::Record object record and a ball::Context object context. Note that the default values for these objects (or their contained objects) are perfectly suitable for logging purposes.

ball::RecordAttributes attributes;
ball::UserFields       fieldValues;
ball::Context          context;
 
bslma::Allocator *ga = bslma::Default::globalAllocator(0);
const bsl::shared_ptr<const ball::Record>
           record(new (*ga) ball::Record(attributes, fieldValues, ga), ga);

Next, create a cstdio observer observer with the stdout as the output stream.

ball::CstdioObserver observer(stdout);

Finally, publish record and context to observer.

observer.publish(record, context);

This will produce the following output on stdout:

01JAN0001_24:00:00.000 0 0 OFF  0