ball_record

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

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 = bdls::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;