ball_streamobserver

Detailed Description

Provide an observer that emits log records to a stream.

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 stream.

Classes

• ball::StreamObserver: observer that emits log records to a stream

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::StreamObserver )
               `--------------------'
                         |              ctor
                         |              disablePublishInLocalTime
                         |              enablePublishInLocalTime
                         |              setFormat
                         |              setRecordFormatFunctor
                         |              getFormat
                         |              isPublishInLocalTimeEnabled
                         V
                  ,--------------.
                 ( ball::Observer )
                  `--------------'
                                        publish
                                        releaseRecords
                                        dtor

ball::StreamObserver is a concrete class derived from ball::Observer that processes the log records it receives through its publish method by writing them to an output stream. Given its minimal functionality, ball::StreamObserver 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.

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, a log record will have the following appearance when the default format is in effect (assuming that no user-defined fields are present):

18MAY2005_18:58:12.076 7959:1 WARN ball_streamobserver.t.cpp:404 TEST hello!

For additional flexibility, the setFormat method can be called to configure the format of published records to the stream. The format specifications can be either scheme-tagged (recommended) or legacy printf-style format strings that results in a RecordStringFormatter being used.

Scheme-Based Format Specifications (Recommended)

The recommended way to specify log record formats is using URI-like scheme-tagged format configuration strings. A scheme-tagged format string begins with a scheme identifier followed by :// and then a scheme-specific format specification:

<scheme>://<format-specification>

The scheme determines which formatter will be used and the syntax of the format specification. The following schemes are currently supported: text, json, qjson. See Scheme-Based Formatters for more details of the supported schemes and their accompanying format specification syntaxes.

For example, to log records to a file in JSON format with printf-style format specification:

asyncFileObserver.setFormat("qjson://%d %p:%t %s %f:%l %c %m");

Legacy Format Specifications

For backward compatibility, format specifications that do not begin with a scheme tag are treated as legacy printf-style format strings. Such specifications are implicitly treated as if they had a text:// prefix and use ball::RecordStringFormatter. For example, the following two calls are equivalent:

streamObserver.setFormat("%d %p:%t %s %f:%l %c %m %a\n");
streamObserver.setFormat("text://%d %p:%t %s %f:%l %c %m %a\n");

These %-prefixed conversion specifications are defined in ball_recordstringformatter .

Thread Safety

All methods of ball::StreamObserver 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::StreamObserver.

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 stream observer observer with the bsl::cout as the output stream.

ball::StreamObserver observer(&bsl::cout);

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