Component ball_record [Package ball]

Provide a container for the fields and attributes of a log record. More...

Namespaces
namespace	ball

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Attributes
  • Usage
    • Example 1: Basic Use of ball::Record

Purpose:

Provide a container for the fields and attributes of a log record.

Classes:

ball::Record

container for a log record's fields and attributes

See also:

Component ball_recordattributes, ball_logger

Description:

This component provides a single, unconstrained (value-semantic) attribute class, ball::Record, that is used to describe the properties of a logged message.

Attributes:

  Name                Type
  ------------------  -----------------------------------
  fixedFields         ball::RecordAttributes
  userFields          ball::UserFields
  attributes          bsl::vector<ball::ManagedAttribute>

• fixedFields: mandatory log fields including timestamp, location, severity, process id, and the log message.
• userFields: user-managed fields associated with a log record. Note that use of these fields is deprecated and superseded by attributes.
• attributes: user-managed name/value pairs associated with a log record.

ball::Record aggregates a set of fixed fields and various user-defined fields and attributes into one record type, useful for transmitting a customized log record as a single instance rather than passing around individual attributes separately. Note that this class is a pure attribute class with no constraints, other than the total memory required for the class. Also note that this class is not thread-safe.

Usage:

This section illustrates intended use of this component.

Example 1: Basic Use of ball::Record:

The following example demonstrates how to create and set the properties of a ball::Record. Note that users of the ball logging subsystem are not expected to create records directly.

First we default create a ball::Record, record, and verify it has a default set of attributes:

  ball::Record record;

  assert(ball::RecordAttributes() == record.fixedFields());
  assert(0                        == record.customFields().length());

Then, we set the fixed fields of the record to contain a simple message:

  int                 processId = bdlsu::ProcessUtil::getProcessId();
  bsls::Types::Uint64 threadId  = bslmt::ThreadUtil::selfIdAsUint64();

  ball::RecordAttributes attributes(bdlt::CurrentTime::utc(), // time stamp
                                    processId,                // process id
                                    threadId,                 // thread id
                                    __FILE__,                 // filename
                                    __LINE__,                 // line number
                                    "ExampleCategory",        // category
                                    ball::Severity::e_WARN,   // severity
                                    "Simple Test Message");   // message
  record.setFixedFields(attributes);

  assert(attributes == record.fixedFields());

Next, we add an additional attribute to the log record:

  record.addAttribute(ball::Attribute("myLib.name", "John Smith"));

Finally, we write the record to a stream:

  bsl::ostringstream output;
  output << record << bsl::endl;