Component ball_streamobserver [Package ball]

Provide an observer that emits log records to a stream. More...

Namespaces
namespace	ball

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Log Record Formatting
  • 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:

Component ball_record, Component ball_context, Component ball_loggermanager

Description:

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

                 ,--------------------.
                ( ball::StreamObserver )
                 `--------------------'
                           |              ctor
                           |              setRecordFormatFunctor
                           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, 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_streamobserver2.t.cpp 404 TEST hi!

The default format can be overridden by supplying a suitable formatting functor to setRecordFormatFunctor. For example, an instance of ball::RecordStringFormatter conveniently provides such a functor:

  streamObserver.setRecordFormatFunctor(
              ball::RecordStringFormatter("\n%I %p:%t %s %f:%l %c %m %u\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. See ball_recordstringformatter for information on how format specifications are defined and interpreted.

Note that the observer emits newline characters at the beginning and at the end of a log record by default, so the user needs to add them explicitly to the format string to preserve this behavior.

Also note that in the sample message above the timestamp has millisecond precision (18MAY2005_18:58:12.076). If microsecond precision is desired instead, consider using either the D or O format specification supported by 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