ball.h

Go to the documentation of this file.

/// @file ball.h
///
///
/// @defgroup ball Package ball
/// @brief  Basic Application Library Logging (ball)
/// @addtogroup bal
/// @{
/// @addtogroup ball
/// [ball]: group__ball.html
/// @{
///
/// # Purpose {#ball-purpose}
/// Provide thread-safe logging toolkit suitable for all platforms.
///
/// # Mnemonic {#ball-mnemonic}
/// Basic Application Library Logging (ball)
///
/// # Description {#ball-description}
/// The 'ball' package provides a toolkit for logging messages in
/// applications and library code.  The logger toolkit has an administration layer
/// that allows configuration both at start-up and during program execution, a
/// basic logger API for the most general possible use, and two sets of macros for
/// somewhat less flexible but simpler, more convenient use.  In particular,
/// messages may be logged via these macros in either a C++ stream-style syntax
/// (i.e., with the '<<' operator) or a 'printf'-style syntax.  Users are
/// encouraged to use the macros exclusively, because they provide uniformity, and
/// because they are less error-prone.  See the {Appendix: Macro Reference}
/// section below.
///
/// This document contains a number of code examples, explained below:
///
///  * {Usage: Key Features} - short examples demonstrating key features of the
///    logging system.
/// 
///  * {Usage: Tutorial} - A series of related examples, building on each other,
///    to illustrate fundamental logging concepts.
/// 
///  * {Usage: Advanced Features} - Examples for advanced users aiming to
///    customize either the behavior or performance of the logger in more complex
///    ways.
///
/// ## Usage: Key Features
///
/// The following section provides short examples highlighting some important
/// features of logging.
///
/// ### Key Example 1: Writing to a Log
///
/// The following trivial example shows how to use the logging macros to log
/// messages at various levels of severity.
///
/// First, we include 'ball_log.h', then create an example function where we
/// initialize the log category within the context of this function.
/// The logging macros such as 'BALL_LOG_ERROR' will not compile unless a
/// category has been specified in the current lexical scope:
/// @code
///  #include <ball_log.h>
///
///  int processData() {
///      BALL_LOG_SET_CATEGORY("MYLIBRARY.MYSUBSYSTEM");
/// @endcode
/// Then, we record messages at various levels of severity.  These messages will
/// be conditionally written to the log depending on the current logging
/// threshold of the category (configured using the 'ball::LoggerManager'
/// singleton):
/// @code
///      BALL_LOG_FATAL << "Write this message to the log if the log threshold "
///                     << "is above 'ball::Severity::e_FATAL' (i.e., 32).";
///
///      BALL_LOG_TRACE << "Write this message to the log if the log threshold "
///                     << "is above 'ball::Severity::e_TRACE' (i.e., 192).";
/// @endcode
/// Next, we demonstrate how to use proprietary code within logging macros.
/// Suppose you want to add the content of a vector to the log trace:
/// @code
///      bsl::vector<int> myVector(4, 328);
///      BALL_LOG_TRACE_BLOCK {
///          BALL_LOG_OUTPUT_STREAM << "myVector = [ ";
///          unsigned int position = 0;
///          for (bsl::vector<int>::const_iterator it  = myVector.begin(),
///                                                end = myVector.end();
///               it != end;
///               ++it, ++position) {
///              BALL_LOG_OUTPUT_STREAM << position << ':' << *it << ' ';
///          }
///          BALL_LOG_OUTPUT_STREAM << ']';
///      }
///  }
/// @endcode
/// Notice that the code block will be conditionally executed depending on the
/// current logging threshold of the category.  The code within the block must
/// not produce any side effects, because its execution depends on the current
/// logging configuration.  The special macro 'BALL_LOG_OUTPUT_STREAM' provides
/// access to the log stream within the block.
///
/// Then we show a simple class that declares a log category for the class (log
/// categories can also be configured at namespace scope in a '.cpp' file):
/// @code
///  class AccountInformation {
///      BALL_LOG_SET_CLASS_CATEGORY("MYLIBRARY.AccountInformation");
///
///      void privateRetrieveData();
///    public:
///      void addSecurity(const bsl::string_view& security);
///      void removeSecurity(const bsl::string_view& security);
///  };
///
///  void AccountInformation::addSecurity(const bsl::string_view& security)
///  {
///      BALL_LOG_INFO << "addSecurity";
///  }
/// @endcode
/// Finally we can use a 'ball::ScopedAttribute' to associate an attribute with
/// the current thread's logging context.
/// @code
///  void AccountInformation::privateRetrieveData()
///  {
///      BALL_LOG_INFO << "retrieveData";
///  }
///
///  void AccountInformation::removeSecurity(const bsl::string_view& security)
///  {
///      ball::ScopedAttribute securityAttribute("mylibrary.security", security);
///      BALL_LOG_INFO << "removeSecurity";
///
///      privateRetrieveData();
///  }
/// @endcode
/// Notice that the attribute "mylibrary.security" will be associated with each
/// log message generated by the current thread until the destruction of the
/// 'securityAttribute' object (including the log message created by
/// 'privateRetrieveData').  To publish the attribute to the log the
/// 'ball::Observer' must be configured correctly (e.g., using the "%a" format
/// specification with 'ball::FileObserver' or 'ball::RecordStringFormatter'), as
/// we do in the subsequent example.
///
/// ### Key Example 2: Initialization
///
/// Clients that perform logging must first instantiate the singleton logger
/// manager using the 'ball::LoggerManagerScopedGuard' class.  This example
/// shows how to create a logger manager with basic "default behavior".
/// Subsequent examples will show more customized behavior.
///
/// The following snippets of code illustrate the initialization sequence
/// (typically performed near the top of 'main').
///
/// First, we create a 'ball::LoggerManagerConfiguration' object,
/// 'configuration', and set the logging "pass-through" level -- the level at
/// which log records are published to registered observers -- to 'WARN' (see
/// {'Categories, Severities, and Threshold Levels'}):
/// @code
///  // myApp.cpp
///
///  int main()
///  {
///      ball::LoggerManagerConfiguration configuration;
///      configuration.setDefaultThresholdLevelsIfValid(ball::Severity::e_WARN);
/// @endcode
/// Next, create a 'ball::LoggerManagerScopedGuard' object whose constructor
/// takes the configuration object just created.  The guard will initialize the
/// logger manager singleton on creation and destroy the singleton upon
/// destruction.  This guarantees that any resources used by the logger manager
/// will be properly released when they are not needed:
/// @code
///      ball::LoggerManagerScopedGuard guard(configuration);
/// @endcode
/// Note that the application is now prepared to log messages using the 'ball'
/// logging subsystem, but until the application registers an observer, all log
/// messages will be discarded.
///
/// Finally, we create a 'ball::FileObserver' object 'observer' that will
/// publish records to a file, and exceptional records to 'stdout'.  We
/// configure the log format to publish log attributes (see
/// {Key Example 1: Write to a Log}, enable the logger to write to a log file,
/// and then register 'observer' with the logger manager.  Note that observers
/// must be registered by name; this example simply uses "default" for a name:
/// @code
///      bslma::Allocator *alloc = bslma::Default::globalAllocator(0);
///
///      bsl::shared_ptr<ball::FileObserver> observer =
///          bsl::allocate_shared<ball::FileObserver>(alloc);
///
///      observer->setLogFormat(
///                      ball::RecordStringFormatter::k_BASIC_ATTRIBUTE_FORMAT,
///                      ball::RecordStringFormatter::k_BASIC_ATTRIBUTE_FORMAT);
///
///      if (0 != observer->enableFileLogging("myapplication.log.%T")) {
///          bsl::cout << "Failed to enable logging" << bsl::endl;
///          return -1;
///      }
///      ball::LoggerManager::singleton().registerObserver(observer, "default");
/// @endcode
/// The application is now prepared to log messages using the 'ball' logging
/// subsystem:
/// @code
///      // ...
///
///      BALL_LOG_SET_CATEGORY("MYLIBRARY.MYSUBSYSTEM");
///      BALL_LOG_ERROR << "Exiting the application (0)";
///
///      return 0;
///  }
/// @endcode
///
/// ## Hierarchical Synopsis
///
/// The 'ball' package currently has 51 components having 17 levels of physical
/// dependency.  The list below shows the hierarchical ordering of the components.
/// The order of components within each level is not architecturally significant,
/// just alphabetical.
/// @code
///  17. ball_asyncfileobserver
///
///  16. ball_fileobserver
///      ball_logfilecleanerutil
///
///  15. ball_fileobserver2
///      ball_logthrottle
///
///  14. ball_log
///
///  13. ball_administration
///
///  12. ball_loggercategoryutil
///      ball_loggerfunctorpayloads
///
///  11. ball_loggermanager
///      ball_scopedattribute
///      ball_scopedattributes
///
///  10. ball_attributecontext
///
///   9. ball_categorymanager
///
///   8. ball_category
///
///   7. ball_broadcastobserver
///      ball_filteringobserver
///      ball_multiplexobserver                             !DEPRECATED!
///      ball_ruleset
///
///   6. ball_observeradapter
///      ball_rule
///      ball_streamobserver
///      ball_testobserver
///
///   5. ball_fixedsizerecordbuffer
///      ball_observer
///      ball_predicateset                                  !DEPRECATED!
///      ball_recordjsonformatter
///      ball_recordstringformatter
///
///   4. ball_managedattributeset
///      ball_record
///
///   3. ball_attributecontainerlist
///      ball_defaultattributecontainer
///      ball_predicate                                     !DEPRECATED!
///      ball_userfields
///
///   2. ball_attributecollectorregistry
///      ball_attributecontainer
///      ball_context
///      ball_loggermanagerconfiguration
///      ball_managedattribute
///      ball_recordbuffer
///      ball_severityutil
///      ball_userfieldvalue
///
///   1. ball_attribute
///      ball_countingallocator
///      ball_loggermanagerdefaults
///      ball_patternutil
///      ball_recordattributes
///      ball_severity
///      ball_thresholdaggregate
///      ball_transmission
///      ball_userfieldtype
/// @endcode
///
/// ## Component Synopsis
///
///  @ref ball_administration :
///       Provide a suite of utility functions for logging administration.
/// 
///  @ref ball_asyncfileobserver :
///       Provide an asynchronous observer that logs to a file and `stdout`.
/// 
///  @ref ball_attribute :
///       Provide a representation of (literal) name/value pairs.
/// 
///  @ref ball_attributecollectorregistry :
///       Provide a registry for attribute collector functors.
/// 
///  @ref ball_attributecontainer :
///       Provide a protocol for containers holding logging attributes.
/// 
///  @ref ball_attributecontainerlist :
///       Provide a list of attribute container addresses.
/// 
///  @ref ball_attributecontext :
///       Provide a container for storing attributes and caching results.
/// 
///  @ref ball_broadcastobserver :
///       Provide a broadcast observer that forwards to other observers.
/// 
///  @ref ball_category :
///       Provide a container for a name and associated thresholds.
/// 
///  @ref ball_categorymanager :
///       Provide a manager of named categories each having "thresholds".
/// 
///  @ref ball_context :
///       Provide a container for the context of a transmitted log record.
/// 
///  @ref ball_countingallocator :
///       Provide a concrete allocator that keeps count of allocated bytes.
/// 
///  @ref ball_defaultattributecontainer :
///       Provide a default container for storing attribute name/value pairs.
/// 
///  @ref ball_fileobserver :
///       Provide a thread-safe observer that logs to a file and to `stdout`.
/// 
///  @ref ball_fileobserver2 :
///       Provide a thread-safe observer that emits log records to a file.
/// 
///  @ref ball_filteringobserver :
///       Provide an observer that filters log records.
/// 
///  @ref ball_fixedsizerecordbuffer :
///       Provide a thread-safe fixed-size buffer of record handles.
/// 
///  'ball_log':
///       Provide macros and utility functions to facilitate logging.
/// 
///  @ref ball_logfilecleanerutil :
///       Provide a utility class for removing log files.
/// 
///  @ref ball_loggercategoryutil :
///       Provide a suite of utility functions for category management.
/// 
///  @ref ball_loggerfunctorpayloads :
///       Provide a suite of logger manager singleton functor payloads.
/// 
///  @ref ball_loggermanager :
///       Provide a manager of core logging functionality.
/// 
///  @ref ball_loggermanagerconfiguration :
///       Provide a constrained-attribute class for the logger manager.
/// 
///  @ref ball_loggermanagerdefaults :
///       Provide constrained default attributes for the logger manager.
/// 
///  @ref ball_logthrottle :
///       Provide throttling equivalents of some of the `ball_log` macros.
/// 
///  @ref ball_managedattribute :
///       Provide a wrapper for `ball::Attribute` with managed name storage.
/// 
///  @ref ball_managedattributeset :
///       Provide a container for managed attributes.
/// 
///  @ref ball_multiplexobserver :                              !DEPRECATED!
///       Provide a multiplexing observer that forwards to other observers.
/// 
///  @ref ball_observer :
///       Define a protocol for receiving and processing log records.
/// 
///  @ref ball_observeradapter :
///       Provide a helper for implementing the `ball::Observer` protocol.
/// 
///  @ref ball_patternutil :
///       Provide a utility class for string pattern matching.
/// 
///  @ref ball_predicate :                                      !DEPRECATED!
///       Provide a predicate object that consists of a name/value pair.
/// 
///  @ref ball_predicateset :                                   !DEPRECATED!
///       Provide a container for managed attributes.
/// 
///  @ref ball_record :
///       Provide a container for the fields and attributes of a log record.
/// 
///  @ref ball_recordattributes :
///       Provide a container for a fixed set of fields suitable for logging.
/// 
///  @ref ball_recordbuffer :
///       Provide a protocol for managing log record handles.
/// 
///  @ref ball_recordjsonformatter :
///       Provide a formatter for log records that renders output in JSON.
/// 
///  @ref ball_recordstringformatter :
///       Provide a record formatter that uses a `printf`-style format spec.
/// 
///  @ref ball_rule :
///       Provide an object having a pattern, thresholds, and attributes.
/// 
///  @ref ball_ruleset :
///       Provide a set of unique rules.
/// 
///  @ref ball_scopedattribute :
///       Provide a scoped guard for a single BALL attribute.
/// 
///  @ref ball_scopedattributes :
///       Provide a class to add and remove attributes automatically.
/// 
///  @ref ball_severity :
///       Enumerate a set of logging severity levels.
/// 
///  @ref ball_severityutil :
///       Provide a suite of utility functions on `ball::Severity` levels.
/// 
///  @ref ball_streamobserver :
///       Provide an observer that emits log records to a stream.
/// 
///  @ref ball_testobserver :
///       Provide an instrumented observer for testing.
/// 
///  @ref ball_thresholdaggregate :
///       Provide an aggregate of the four logging threshold levels.
/// 
///  @ref ball_transmission :
///       Enumerate the set of states for log record transmission.
/// 
///  @ref ball_userfields :
///       Provide a container of user supplied field values.
/// 
///  @ref ball_userfieldtype :
///       Enumerate the set of data types for a user supplied attribute.
/// 
///  @ref ball_userfieldvalue :
///       Provide a type for the value of a user supplied field.
///
/// ## Multi-Threaded Logging
///
/// The 'ball' logging toolkit is thread-enabled and suitable for multi-threaded
/// applications.  At the user's option, the multi-threaded toolkit permits each
/// thread to install a distinct instance of 'ball::Logger'; the process-wide
/// "default" logger is available to any thread that does not install its own
/// logger.
///
/// ## Logging Features Overview
///
/// This section provides a brief overview of the features of the 'ball' logging
/// toolkit, and introduces (without formal definition) some of the terminology
/// used in 'ball'.  Refer to the hierarchical and alphabetical Synopsis sections
/// above to associate these features with the overall 'ball' design, and see the
/// various sections below for more detailed descriptions.
///
///  * User-assigned Severity Level associated with each log message
/// 
///  * User-defined Category associated with each log message
/// 
///  * Four Severity Threshold Levels associated with each Category
/// 
///  * Category threshold levels are configurable both at start-up and during
///    program execution
/// 
///  * Severity Level plus (administrable) per-category Threshold Levels allow:
///    * efficient suppression of message-logging operation (one 'if' statement)
///    * efficient logging-to-memory (subsequent publication is user-controlled)
///    * immediate publication of log message (to user-defined "observer")
///    * immediate publication of all messages currently held in (finite) buffer
/// 
///  * Logging to memory permits efficient logging of large quantities of "trace"
///    information that will not be published *unless* a specific user-defined
///    logging event occurs ("trace-back" feature)
/// 
///  * User can always configure logger to publish every message, if desired
/// 
///  * User defines and registers one or more "observers", each of which in turn
///    defines the behavior of the "publish" operation (e.g., write to file, write
///    to console, process message and take specific action, etc.)
/// 
///  * Convenient logging macros simplify usage for the most common operations
/// 
///  * Optional functors and other parameters allow customized logging behavior
///    (e.g., default threshold levels, category name filtering)
/// 
///  * The ability to configure thread-context dependent rules for logging (e.g.,
///    configuring more verbose logging for threads processing a request for
///    a particular user id).  See {'Rule-Based Logging'} below.
///
///
/// The 'ball' package provides a flexible logging toolkit that supports several
/// standard and non-standard features.  Perhaps most notable among the
/// non-standard features is the ability to write messages to an in-memory
/// "circular" (finite) buffer with the expectation that those messages will be
/// overwritten and never actually "logged" to any permanent medium.  With this
/// feature, during normal production operation a large quantity of "trace-back"
/// information can be "logged" to memory, and typically be discarded, without
/// having clogged production resources.  If, however, some "error" occurs, the
/// information just prior to that error will be available for fast diagnosis and
/// debugging.  It is easy to re-configure logger operation so that every message
/// is archived, if that is the preferred behavior, but the efficient trace-back
/// feature is an explicit design goal.  See the "Hello world!" examples under
/// {Usage} below for illustrations of how to configure the logger behavior.
///
/// Another key design feature is the "observer" object.  'ball' defines the
/// 'ball::Observer' protocol (abstract interface), and provides a few concrete
/// observers.  It is expected that most users will find the concrete observers
/// that are provided in 'ball' to be sufficient for their needs.  However, users
/// are free to define their own observers tailored to meet their specific
/// requirements.  In the current release, exactly one observer is registered with
/// the 'ball' logger on initialization; we anticipate that multiple observers,
/// e.g., one per thread or perhaps one per logger, may be available in future
/// releases.  An observer makes its 'publish' method available to the logger;
/// since the 'publish' method is free to do almost anything that the user wants,
/// the limitation of one observer per process is not very restrictive.  The
/// observer may: write the message to a simple file, write the message to a set
/// of managed files, write the message to the console (perhaps with some
/// information removed and/or added), process the message (complete with Category
/// and Severity information) and take specific responsive actions, or any
/// combination of these or other behaviors.  In particular, 'ball' provides a
/// "broadcast observer", 'ball::BroadcastObserver', that forwards log records to
/// any number of observers registered with the broadcast observer.  Note that
/// 'ball::LoggerManager' contains an integrated broadcast observer and all
/// observers registered with the logger manager will receive log records.
///
/// ## Severity Levels and Categories: a Brief Overview
///
/// The logger supports the notions of severity levels and categories.  Every
/// message is logged at some severity level and to some category.  Categories are
/// user-defined (except for the "default category"), and can be separately
/// managed; in particular, the behavior of any given message-logging operation
/// depends upon specific severity level threshold settings for the category to
/// which the message is being logged.  See the @ref ball_loggermanager  component for
/// more details about categories and category administration.
///
/// Severity levels are, from the perspective of the basic logger API,
/// user-settable in the range '[0 .. 255]'.  Much more commonly, however, (and
/// necessarily when using the 'ball' convenience macros defined in the 'ball_log'
/// component), the user will choose to use the fixed set of enumerated severity
/// levels as defined in the @ref ball_severity  component.  The enumerator names
/// suggest a meaning that is consistent with common practice, but no policy is
/// enforced by the basic logger API or the macros.
///
/// For convenient reference only, the 'ball::Severity::Level' 'enum'
/// implementation is presented below.  Note that this implementation and the
/// specific numerical values may not be relied upon.  Also note that the
/// enumerator 'NONE' is deprecated, since its name has proven to be confusing.
/// As an argument to 'logMessage', it would satisfy "none" of the thresholds, but
/// when provided as a threshold value itself, it would enable "all" of the
/// enumerated 'logMessage' requests (and all of the macros).  Use 'e_OFF' as a
/// threshold level to disable all logging events for a particular logging
/// behavior (see the "Log Record Storage and Publication" section below).
/// @code
///  enum Level {
///      e_OFF   =   0,  // disable generation of corresponding message
///      e_FATAL =  32,  // a condition that will (likely) cause a *crash*
///      e_ERROR =  64,  // a condition that *will* cause incorrect behavior
///      e_WARN  =  96,  // a *potentially* problematic condition
///      e_INFO  = 128,  // data about the running process
///      e_DEBUG = 160,  // information useful while debugging
///      e_TRACE = 192,  // execution trace data
///  };
/// @endcode
/// Note that numerically lower 'Level' values correspond to conditions having
/// greater severity.
///
/// ## Messages, Records, and other ball Terminology
///
/// The entity that the logger logs is called a "log record" in 'ball'.  A log
/// record consists of a number of fixed and user-defined fields; one of the fixed
/// fields is called a "log message" (or "message" for short).  In casual usage,
/// we use "record" and "message" interchangeably, but note that they are distinct
/// concepts.  The set of fixed fields that constitute a log record are defined in
/// the @ref ball_recordattributes  component.  A brief description of the fixed
/// fields (or "record attributes") is given in the following table.
/// @code
///   Attribute        Type               Description               Default
///   ----------   --------------  ------------------------------   -------
///   timestamp    bdlt::Datetime  creation date and time           (*Note*)
///   processID    int             process id of creator              0
///   threadID     Uint64          thread id of creator               0
///   fileName     bsl::string     file where created  (__FILE__)     ""
///   lineNumber   int             line number in file (__LINE__)     0
///   category     bsl::string     category of logged record          ""
///   severity     int             severity of logged record          0
///   message      bsl::string     log message text                   ""
///
///   Note: The default value given to the timestamp attribute is implementation
///         defined.  (See the @ref bdlt_datetime  component-level documentation for
///         more information.)
/// @endcode
/// The user may wish to specify a set of user-defined fields to be included
/// within every log record for a given program.  Such user-defined fields are
/// represented in each log record by an instance of 'ball::UserFields'.  A
/// 'ball::LoggerManagerConfiguration::UserFieldsPopulatorCallback' functor may
/// be provided to the logger manager on construction (via a
/// 'ball::LoggerManagerConfiguration' object) that, when invoked, "populates"
/// (i.e., provides the values for) all elements of the 'ball::UserFields' object
/// containing the user-defined fields.  See the @ref ball_record  component for more
/// information about the use of 'ball::UserFields' in logging, and see the
/// @ref ball_loggermanager  component for more information about installing a user
/// populator callback.
///
/// ### Constraints on Message Encodings
///
/// The 'ball' infrastructure has no provisions for specifying or enforcing
/// constraints on the encoding used for logged messages (in general, logged
/// messages are published to registered observers in the encoding in which they
/// were originally supplied).  However, particular applications, frameworks, and
/// consumers of log records (e.g., readers of log files) may place their own
/// constraints on log records with respect to encoding.  Clients generating log
/// records should be aware of the encoding requirements for logged messages
/// generated by their application (e.g., many applications at Bloomberg require
/// UTF-8 encoded messages).
///
/// ## Log Record Storage and Publication
///
/// The logger achieves good run-time performance while capturing critical log
/// messages by *selectively* storing log records and *selectively* publishing a
/// subset of those stored records.  The determination of whether a log record
/// should be stored or published is based on the "category" and "severity" level
/// that are associated with each record.  The severity of a record is intended to
/// indicate that record's relative urgency.  A category is comprised of a name
/// (an arbitrary string) and four severity threshold levels (see the
/// component-level documentation of @ref ball_severity  for more information on
/// typical severity levels).  A message's text, its associated severity, and the
/// name of its associated category are each among the fixed fields in the logged
/// record (see the "Messages, Records, and other 'ball' Terminology" section
/// above).
///
/// The following four settings define the log record severity levels at which the
/// logger takes certain actions.  The logger determines the disposition of a
/// record based on its severity level in relation to the four *severity*
/// *threshold* *levels* of the category associated with the message:
///
///  Record:
///    If the severity level of the record is at least as severe as the Record
///    threshold level of the associated category, then the record will be stored
///    by the logger in its log record buffer (i.e., it will be recorded).
/// 
///  Pass:
///    If the severity level of the record is at least as severe as the Pass
///    threshold level of the associated category, then the record will be
///    immediately published by the logger (i.e., it will be transmitted to the
///    logger's downstream recipient -- the observer).
/// 
///  Trigger:
///    If the severity level of the record is at least as severe as the Trigger
///    threshold level of the associated category, then the record will cause
///    immediate publication of that record and any records in the logger's log
///    record buffer (i.e., this record will trigger a general log record dump).
/// 
///  Trigger-All:
///    If the severity level of the record is at least as severe as the
///    Trigger-All threshold level of the associated category, then the record
///    will cause immediate publication of that record and all other log records
///    stored by *all* active loggers.
///
/// Note that more than one of the above actions can apply to a given log record
/// since the four threshold levels are independent of one another.  Also note
/// that the determination of whether a log record should cause a Trigger or
/// Trigger-All event is based on the trigger and trigger-all threshold levels,
/// respectively, of the category associated with the record being logged.  The
/// categories and severities associated with log records stored earlier are not
/// taken into account.
///
/// ## The Basic Tools in the ball Logging Toolkit
///
/// This section will be expanded upon in the future.  For now, we provide a brief
/// introduction to the objects that are most central to understanding basic
/// logger operation, so that we may use their names elsewhere in this
/// documentation.
///
/// ### ball::LoggerManager
///
/// 'ball::LoggerManager' is a singleton that must be constructed with a
/// configuration object (see below) and an optional 'bslma' allocator before any
/// true logging operations can be performed.  The logger manager's main tasks are
/// to administer categories and to "allocate" loggers.  If the user has *not*
/// allocated and installed any logger instances, then the 'getLogger' method will
/// return the "default logger" that is a specific instance of 'ball::Logger'
/// owned and managed by the logger manager.  This default logger is suitable for
/// single-threaded and multi-threaded use, and is used "transparently" by users
/// willing to accept default-logger behavior.  See {Usage} below.
///
/// The logger manager maintains an internal broadcast observer (see below) and
/// provides the 'registerObserver', 'deregisterObserver', and 'findObserver'
/// methods that register, deregister, and find observers, respectively.  The
/// internal broadcast observer forwards all log records that it receives to all
/// registered observers.
///
/// The logger manager provides the 'allocateLogger' and 'setLogger' methods that
/// allocate arbitrarily many loggers and install (at most) one logger per thread,
/// respectively.  Any thread in which the 'setLogger' method was not called will
/// use the default logger.  See {Example 6} and {Example 7} below for a
/// discussion of how and why to allocate multiple loggers.
///
/// ### ball::Logger
///
/// 'ball::Logger' provides the most central logging functionality, namely the
/// 'logMessage' method.  However, most users will never call 'logMessage'
/// directly, but rather will use the sets of macros defined in the 'ball_log'
/// component.  See the {Appendix: Macro Reference} section below.
///
/// The "default" 'ball::Logger' instance managed by the logger manager is
/// suitable for many purposes, so typical users need never interact with logger
/// instances explicitly at all.  However, in multi-threaded applications (and
/// perhaps also in certain special-purpose single-threaded programs), the user
/// may want to instantiate one or more logger instances and install at most one
/// logger instance per thread.  See {Example 6} and {Example 7} below.
///
/// ### ball::LoggerManagerConfiguration
///
/// 'ball::LoggerManagerConfiguration' is a "configuration" object that must be
/// supplied to the logger manager at construction.  The default object configures
/// the "default" logging behavior; the user can change the logger behavior by
/// changing attributes in the configuration object.  The name, type, and
/// description of the configuration attributes are presented in the two tables
/// below; the awkward repetition of 'NAME' is due to the long type names of the
/// functor types.
/// @code
///  NAME                   TYPE
///  -------------------    -----------------------------------------------------
///  defaults               ball::LoggerManagerDefaults
///
///  userFieldsPopulatorCallback
///                         bsl::function<void(ball::UserFields *)>
///
///  categoryNameFilterCallback
///                         bsl::function<void(bsl::string *, const char *)>
///
///  defaultThresholdLevelsCallback
///                         bsl::function<void(int *, int *, int *, int *,
///                                            const char *)>
///
///  logOrder               ball::LoggerManagerConfiguration::LogOrder
/// @endcode
///
/// @code
///  NAME                  DESCRIPTION
///  -------------------   -----------------------------------------------------
///  defaults              constrained defaults for buffer size and thresholds
///
///  userFieldsPopulatorCallback
///                        populates optional user fields in a log record
///                        [!DEPRECATED!]
///
///  categoryNameFilterCallback
///                        invoked on category names, e.g., to re-map characters
///
///  defaultThresholdLevelsCallback
///                        sets category severity threshold levels (by default)
///
///  logOrder              log message publication order on "trigger" events
/// @endcode
/// Note that the configuration object is not value-semantic because its three
/// functor attributes are not value-semantic.  For this reason, the single
/// "defaults" attribute, a value-semantic simply-constrained attribute type, was
/// factored out from the configuration type.  The defaults object holds six
/// numerical attributes and is described next.
///
/// ### ball::LoggerManagerDefaults
///
/// 'ball::LoggerManagerDefaults' is a value-semantic simply-constrained
/// attribute type that is itself an attribute of the above "configuration"
/// object.  The "defaults" object contains the following six constrained
/// attributes.
/// @code
///  TYPE          NAME                DESCRIPTION
///  -----------   ----------------    -------------------------------------
///  int           recordBufferSize    size in bytes of *default* logger's
///                                    record buffer
///
///  int           loggerBufferSize    default size in bytes of *each*
///                                    logger's "scratch" buffer (for macros)
///
///  char          recordLevel         default record severity level
///
///  char          passLevel           default pass-through severity level
///
///  char          triggerLevel        default trigger severity level
///
///  char          triggerAllLevel     default trigger-all severity level
/// @endcode
/// The constraints are as follows:
/// @code
///   NAME                 CONSTRAINT
///  +--------------------+---------------------------------------------+
///  | recordBufferSize   | 1 <= recordBufferSize                       |
///  +--------------------+---------------------------------------------+
///  | loggerBufferSize   | 1 <= loggerBufferSize                       |
///  +--------------------+---------------------------------------------+
///  | recordLevel        | 0 <= recordLevel     <= 255                 |
///  | passLevel          | 0 <= passLevel       <= 255                 |
///  | triggerLevel       | 0 <= triggerLevel    <= 255                 |
///  | triggerAllLevel    | 0 <= triggerAllLevel <= 255                 |
///  +--------------------+---------------------------------------------+
/// @endcode
/// 'ball::LoggerManagerDefaults' was factored out of the configuration object
/// because the former is purely value-semantic, and can be generated from, e.g.,
/// a configuration file.  From this perspective, it is very convenient to set
/// this one attribute in the configuration object.  It is quite possible to
/// ignore the independent existence of 'ball::LoggerManagerDefaults' and set the
/// above constrained attributes directly in the
/// 'ball::LoggerManagerConfiguration' object.  The latter is more convenient in
/// "simple" usage, and is illustrated in {Usage} below.
///
/// ### ball::Observer
///
/// 'ball::Observer' is the object that receives "published" log messages.
/// Specifically, 'ball::Observer' is a protocol (abstract interface), and the
/// user must supply a concrete implementation (separately written or chosen from
/// existing 'ball' observers).  The observer provides a 'publish' method that
/// defines the behavior of the logical concept of "publication" of a message used
/// throughout this document.  Note that multiple observers may be registered with
/// the logger manager and each registered observer will receive "published" log
/// messages.
///
/// ### Logging Macros
///
/// For both convenience and uniformity of programming, 'ball' provides a suite of
/// logging macros (defined in the 'ball_log' component).  All but the most
/// demanding and customized applications will use the logging macros for basic
/// logging operations (e.g., setting categories and logging messages).  The
/// logger manager interface is used primarily to administer global and
/// category-specific severity threshold levels, and to allocate loggers.  See the
/// {Usage} and {Appendix: Macro Reference} sections below for examples and
/// reference documentation, respectively.
///
/// The user should note the following two facts about macro usage:
///
///  1. The 'BALL_LOG_SET_CATEGORY' macro is not only convenient, it is most often
///    *required* for macro use, since it defines symbols that the other macros
///    expect to see.  (Alternatively, either the 'BALL_LOG_SET_DYNAMIC_CATEGORY'
///    or 'BALL_LOG_SET_CLASS_CATEGORY' macro may be used instead; see the
///    'ball_log' component for details.)
/// 
///  2. There are two styles of logging macros, C++ stream style and 'printf'
///    style.  The 'printf'-style logging macros write to an intermediate
///    fixed-size buffer managed by the active logger instance.  For any one macro
///    invocation, data larger than the buffer size is (silently) truncated.  The
///    buffer size is 8k bytes by default; the buffer size can be queried by the
///    logger 'messageBufferSize' instance method, and can be set at logger
///    manager construction via the 'ball::LoggerManagerConfiguration' object.
///    (This is not the case with the C++ stream-style macros, which are more
///    efficient.)
///
/// ## More About Categories
///
/// When the logger manager singleton is created, a distinguished category known
/// as the *Default* *Category* is created.  At initialization, the *Default*
/// *Category* is given "factory-supplied" default threshold levels.  These
/// threshold levels, values distributed in the range '[0 .. 255]', are not
/// published and are subject to change over time.  Explicit settings for these
/// factory values may be specified when the singleton is constructed.  This is
/// done by constructing a 'ball::LoggerManagerConfiguration' object (needed for
/// logger manager construction in any event) and then calling the
/// 'setDefaultThresholdLevelsIfValid' method with the desired values for its four
/// arguments before supplying the configuration object to the logger manager
/// configuration.
///
/// The *Default* *Category* may arise during logging whenever the
/// 'setCategory(const char *categoryName)' method is called.  That method returns
/// the address of the category having 'categoryName', if it exists; if no such
/// category exists, and a category having 'categoryName' cannot be created due to
/// a capacity limitation on the category registry maintained by the logger
/// manager singleton, then the *Default* *Category* is returned.
///
/// Categories that are added to the registry during logging through calls to the
/// 'setCategory(const char *)' method are given threshold levels by one of two
/// means.  One alternative is to use the
/// 'ball::LoggerManagerConfiguration::DefaultThresholdLevelsCallback' functor
/// that is optionally supplied by the client when the logger manager singleton is
/// initialized.  If such a functor *is* provided by the client, then it is used
/// to supply threshold levels to categories added by 'setCategory(const char *)'.
/// Otherwise, default threshold levels maintained by the logger manager for that
/// purpose are used.  At initialization, these default threshold levels are given
/// the same "factory-supplied" settings as those for the *Default* *Category*
/// that, again, may be explicitly overridden at construction.
///
/// The default threshold levels can be adjusted ('setDefaultThresholdLevels') and
/// reset to their original values ('resetDefaultThresholdLevels').  Note that if
/// factory values are overridden at initialization, a reset will restore
/// thresholds to the user-specified default values.  In addition, there is a
/// method to set the threshold levels of a given category to the current default
/// threshold levels ('setCategoryThresholdsToCurrentDefaults') or to the
/// factory-supplied (or client-overridden) default values
/// ('setCategoryThresholdsToFactoryDefaults').
///
/// One final note regarding categories is that the client can optionally supply a
/// 'ball::LoggerManagerConfiguration::CategoryNameFilterCallback' functor to
/// translate category names from an external to an internal representation.  For
/// example, a project may allow programmers to refer to categories using
/// mixed-case within an application, but provide a 'toLower'
/// 'CategoryNameFilterCallback' to map all external upper-case letters to
/// lower-case internally.  Such a name-filtering functor is set in the
/// 'ball::LoggerManagerConfiguration' object before that configuration object is
/// passed to the logger manager scoped guard constructor.  In this scenario, the
/// (hypothetical) external category names "EQUITY.MARKET.NYSE" and
/// "equity.market.nyse" would be mapped to the same category internally by the
/// presumed 'toLower' functor.
///
/// ## Log Attributes
///
///The 'ball' logging framework provides the ability to associatiate "attributes"
///(name-value pairs) with the current logging context, which can be both be
///written to the log as part of a log record, as well as used in logging rules
///(see {Rule-Based Logging} below).  This is typically done using the
///@ref ball_scopedattribute  component.
///
///Below is a simple example using log attributes:
///
/// @code
///  int processData(const bsl::string&        security,
///                  const bsl::vector<char>&  data)
///  {
///       ball::ScopedAttribute securityAttribute("mylibrary.security", security);
///
///       // ...
///
///       int rc = reticulateSplines(data);
///
///       return rc;
///  }
///
///  int reticulateSplines(data)
///  {
///      // ...
///
///      if (0 != rc) {
///          BALL_LOG_ERROR << "Error computing splines (" << rc << ")";
///      }
///      return rc;
///  }
/// @endcode
///
///In the above example a logging attribute, "mylibrary.security", is associated
///with the current thread's logging context for the lifetime of the
///'securityAttribute' object.  As a result, if attributes have been
///enabled in the log format, the error log message generated by this example
///might look like:
///
/// @code
///  ERROR example.cpp:105 EXAMPLE.CATEGORY mylibrary.security="IBM US Equity" Error computing splines (-1)
/// @endcode
///
///Notice the attribute rendered does not appear in the logging message itself ("Error
///computing splines (-1)"), and is rendered as a name-value pair, meaning it can be
///easily parsed by log management systems like Humio or Splunk.
///
///Attributes will not appear in your log unless your ball::Observer format
///specification is configured to render attributes (see below).
///
/// ### Configuring an Observer to Output Attributes
///
///Log attributes are not rendered by default as part of the log message (for
///backward compatibility).  Clients can enable log attributes to be rendered for
///observers that support log record formatting:
///
///  * 'ball::FileObserver'
///  * 'ball::AsyncFileObserver'
///  * 'ball::StreamObserver'
///  * 'ball::FileObserver2'
///
///Log message formatting is implemented by the @ref ball_recordstringformatter 
///component, which supports the following (new) format specifiers to render log
///attributes:
///
/// @code
///  +------------------+--------------------------------------------------------------------------+
///  | Format Specifier | Description                                                              |
///  +==================+==========================================================================+
///  | %A               | Log all the attributes of the record                                     |
///  +------------------+--------------------------------------------------------------------------+
///  | %a               | Log only those attributes not already logged by the "%a[name]" or        |
///  |                  | "%av[name]" specifiers                                                   |
///  +------------------+--------------------------------------------------------------------------+
///  | %a[name]         | Log an attribute with the specified 'name' as "name=value",              |
///  |                  | log nothing if the attribute with the specified 'name' is not found      |
///  +------------------+--------------------------------------------------------------------------+
///  | %av[name]        | Log only the *value* of the attribute with the specified 'name',         |
///  |                  | log nothing if the attribute with the specified 'name' is not found      |
///  +------------------+--------------------------------------------------------------------------+
/// @endcode
///
///The following code snippet illustrates the creation and configuration commonly used
///by observers:
///
/// @code
///  int initFileObserver() {
///     // 'ball::FileObserver' uses an internal record string formatter and
///     // is configured by supplying a format string via 'setLogFormat().
///
///     bslma::Allocator *alloc = bslma::Default::globalAllocator(0);
///
///     bsl::shared_ptr<ball::FileObserver> observer =
///         bsl::allocate_shared<ball::FileObserver>(alloc);
///
///
///     // Set the log format for file and console logs to "\n%d %p:%t %s %f:%l %c %a %m\n"
///     observer->setLogFormat(ball::RecordStringFormatter::k_BASIC_ATTRIBUTE_FORMAT,
///                            ball::RecordStringFormatter::k_BASIC_ATTRIBUTE_FORMAT);
///
///     if (0 != observer->enableFileLogging("myapplication.log.%T")) {
///         bsl::cout << "Failed to enable logging" << bsl::endl;
///         return -1;
///     }
///     ball::LoggerManager::singleton().registerObserver(observer, "default");
///     return 0;
///  }
/// @endcode
///
/// ### Suggested Log Record Format
///
///The logger now provides a new constant,
///'ball::RecordStringFormatter::k_BASIC_ATTRIBUTE_FORMAT', which is the
///recommended log format specification for most users (see the example above).
///The default log format specification remains the same to avoid changing
///behavior for existing applications.  Note that the default format
///specification might be changed in a subsequent release of BDE.
///
///
/// ### Details on Using Attributes
///
///
///The 'ball' library provides the following classes that implement ready-to-use
///application solutions for log attributes:
///
///  * @ref ball_attribute : This class represents an attribute that consists of a
///    (literal) name (held but not owned), and an associated value (owned).  The
///    value might be a number or string (see @ref ball_attribute  for more detail).
/// 
///  * @ref ball_scopedattribute : Scoped guard that creates an attribute container
///    with a single attribute supplied at construction and adds this container to
///    the current thread's context.  The container is removed from the thread
///    context when the guard leaves the scope.
/// 
///  * @ref ball_recordformatter : Implements a log record formatting functor.
///    Formats log records into human-readable log messages according to the
///    specified format specs.
///
///Note that 'ball::ScopedAttribute' is recommended for most applications.
///However, some low-level performance-critical systems (e.g., BAS) may implement
///custom attribute-collection mechanisms.  This adds considerable complexity, but
///can deliver a small benefit in performance by taking advantage of compile time
///knowledge of the attributes being collected.  See
///@ref ball_attributecollectorregistry  for more details on attribute collection
///mechanism.
///
/// ### Attribute Naming Recommendations
///
///Use the following naming conventions for attribute names:
///
///  * An attribute name should start with an alphabetic character; no other
///    special characters or digits should be allowed as the first character of an
///    attribute name.
///  * An attribute name should not contain whitespaces.
///  * An attribute name should contain only alphanumeric characters,
///    underscores('_'), and dots('.').  Do not use any other special characters.
///
///It is highly recommended to use "namespaces" when naming attributes to avoid
///attribute name collisions.  For example, consider these attribute names:
///
/// @code
///  +--------------------------+----------------------------+
///  | "context id"             | BAD (contains whitespace)  |
///  +--------------------------+----------------------------+
///  | "contextid"              | BAD (no namespace)         |
///  +--------------------------+----------------------------+
///  | "bde.contextid"          | GOOD                       |
///  +--------------------------+----------------------------+
///  | "bde.logger.context_id"  | GOOD                       |
///  +--------------------------+----------------------------+
/// @endcode
///
///Handling of attributes with identical names is dictated by the underlying
///container(s) that store the attributes and the 'ball' library cannot guarantee any
///deterministic behavior in this case.  It is the responsibility of the users to
///guarantee uniqueness of attribute names.
///
///Log record attributes are rendered as space-separated 'name="value"' pairs
///(for example: 'mylibrary.requestType="POST"').  Note that attribute names are
///*not* quoted, whereas attribute values, if they are strings, are
///*always* quoted.
///
/// ## Rule-Based Logging
///
///The 'ball' logging toolkit provides a set of components that collectively
///allow clients to define rules to modify logging severity levels depending
///on attributes associated with the current thread.  The canonical example of
///rule-based logging is to enable verbose logging when processing requests
///for a particular user in a service.
///
///A usage example can be found in
///{'Advanced Features Example 1: Rule-Based Logging'}.
///
///To enable rule-based logging clients must do two things:
///  1. Configure a set of (process-wide) rules to set logging thresholds based on
///     'ball::Attribute' values.
/// 
///  2. Associate (on a per-thread basis) 'ball::Attribute' values with the
///     current thread.
///
///The configuration of process-wide rules is accomplished by creating rules
///(see {@ref ball_rule }) that set a logging category's thresholds if a set of
///attributes associated with the current thread matches those of the rule (see
///{@ref ball_managedattribute }).  For example, a 'ball::Rule' might express: set
///the logging threshold for any logging category starting with the prefix
///"DATABASE" to 'e_TRACE' if the "myLib.userid" is 123456 and the
///"myLib.requesttype" is "trade" (where "myLib.userid" and "myLib.requesttype"
///are names of attributes that will be associated with a processing thread).
///Clients can then call 'ball::LoggerManager::addRule' to add this rule to the
///logger manager.
///
///To associate an attribute (like "myLib.userid" and "myLib.requesttype") with a
///particular thread, clients must add a 'ball::AttributeContainer' holding the
///attribute to the 'ball::AttributeContext' (note that an attribute context is a
///thread-local object).  The simplest means for doing this is to create a
///'ball::ScopedAttribute' object as a local variable, which adds an attribute
///container (holding a single attribute) that exists for the lifetime of the
///scoped-attribute object.  A 'ball::ScopedAttribute' appends a container having
///a single attribute to a list of containers, which is easy and efficient if
///there are only a small number of attributes.  Clients with a large number of
///attributes could use a 'ball::DefaultAttributeContainer', which provides an
///efficient container for a large number of attributes.  However, clients *must*
///take care to remove the container from the 'ball::AttributeContext' before the
///object goes out of scope and is destroyed.  See @ref ball_scopedattributes 
///(plural) for an example.  Finally, clients may also provide their own
///implementations of 'ball::AttributeContainer' customized for their needs (e.g.,
///by creating a simple, efficient 'ball::AttributeContainer' specifically for the
///"myLib.userid" and "myLib.requesttype" attributes); see
///@ref ball_attributecontainer  for an example.
///
///{'Advanced Features Example 1: Rule-Based Logging'} below demonstrates creating
///a simple logging rule, and associating attributes with a processing thread.
///
/// ## A Note on Multi-Threaded Logging Usage
///
/// The 'ball' logging toolkit may be used in single-threaded and multi-threaded
/// library code and applications with equal ease, and with virtually no
/// difference in coding.  In particular, the same call to the logger manager
/// scoped guard constructor is required in 'main' in both cases, and individual
/// calls to the 'ball::Logger' instance method 'logMessage' (and logging calls
/// via the logging macros -- see 'ball_log' and the {Appendix: Macro Reference}
/// below) are identical from the user's perspective.  Category threshold
/// administration is also identical in both cases, since that is done by the
/// singleton logger manager.
///
/// Differences in logger usage, or, more precisely, additional options for the
/// multi-threaded user, arise when the user wishes to allocate one or more
/// loggers beyond the default logger that is owned by the singleton logger
/// manager.  If a user does *not* explicitly allocate a logger (via the logger
/// manager instance method 'allocateLogger') and install that logger for a given
/// thread (via the manager instance method 'setLogger'), then all records from
/// all threads in a program will be logged to the one default logger.  However,
/// since each thread of execution may have its own logger instance,
/// multi-threaded users may choose to allocate and install multiple loggers.
/// Note that each thread may have at most one logger, but a single logger may be
/// used by any number of threads.
///
/// Multi-threaded users of logging may prefer to allocate and install one logger
/// per thread in order to take advantage of the "trace-back" feature described
/// above on a per-thread basis.  In the event of an "error condition" (as defined
/// by the *user*), such a logging configuration can provide a trace-back through
/// the record buffer of the thread that caused the error, without any dilution
/// from records logged from other threads.  Conversely, if several threads are
/// known to interact closely, it may be advantageous to have them share a common
/// logger so that the trace-back log *does* include relevant records from all
/// designated threads, in reverse chronological order.
///
/// ## Managing the ball::LoggerManager Singleton
///
/// The recommended way to initialize the logger manager singleton is to create a
/// 'ball::LoggerManagerScopedGuard' object in 'main' (*before* creating any
/// threads).  The logger manager scoped guard constructor takes a configuration
/// object (an instance of 'ball::LoggerManagerConfiguration') and an optional
/// allocator.  The logger manager singleton is created as a side-effect of
/// creating the scoped guard object.  When the guard object goes out of scope
/// (i.e., on program exit), the logger manager singleton is automatically
/// destroyed.
///
/// As an alternative to using the logger manager scoped guard, the 'static'
/// 'ball::LoggerManager::initSingleton' method that takes the same arguments as
/// the scoped guard constructor may be used to initialize the singleton.
/// However, in this case the 'ball::LoggerManager::shutDownSingleton' method must
/// be explicitly called to destroy the logger manager singleton on program exit.
/// Unless 'shutDownSingleton' is called, the singleton will not be destroyed and
/// resources used by the singleton will leak.
///
/// Direct use of the 'public' logger manager constructor to initialize the logger
/// manager singleton is *deprecated*.  The constructor will be declared 'private'
/// in a future release.
///
/// Direct use of any of the 16 'ball::LoggerManager::initSingleton' methods that
/// do *not* take an instance of 'ball::LoggerManagerConfiguration' to initialize
/// the logger manager singleton is *deprecated*.  These methods will be
/// eliminated in a future release.
///
/// ## Usage: Tutorial
///
/// This section provides a set of logging examples designed to introduce and
/// illustrate basic concepts, features, and resulting operation.  The first four
/// examples are very simple "Hello world!" programs that show single-threaded
/// usage.  The next three examples illustrate multi-threaded usage.  As simple as
/// these examples are, they show sufficient functionality to use the 'ball'
/// logger in a fair number of production applications.  In particular, all of
/// these examples use the macros from the 'ball_log' component to perform the
/// actual logging.  Methods from @ref ball_loggermanager  are used for initialization
/// and administration, but for most applications, anything that *can* be done
/// using the logging macros *should* be done with the macros.
///
/// ### Tutorial Example 1: Hello World!
///
/// This "Hello world!" example illustrates the most basic use of logging within a
/// single translation unit containing a 'main' function and essentially nothing
/// else.  Among the points of usage that we illustrate are:
///
///  * Instantiating a 'ball::LoggerManagerConfiguration' and passing it to the
///    logger manager scoped guard constructor.
/// 
///  * Instantiating a 'ball::StreamObserver' and registering it with the logger
///    manager singleton.
/// 
///  * Invoking the 'BALL_LOG_SET_CATEGORY' macro to set a category (named "main
///    category" in this example); records logged from a scope where the effects
///    of the macro are visible (and not superseded by a macro invocation in a
///    nested scope) will be logged to this category.
/// 
///  * Using the 'BALL_LOG_INFO' macro to log a "Hello world!" message at 'e_INFO'
///    severity; messages at 'e_INFO' severity are ignored by default.
/// 
///  * Depending upon a command-line argument, a message is logged at 'e_ERROR'
///    severity that will be published as a "pass-through".  If the command-line
///    argument is absent, the program will succeed with no messages published.
///    This is the intended behavior.
///
/// Note that, when logging using the macros, the 'BALL_LOG_SET_CATEGORY' macro is
/// not only extremely convenient, it is typically required, since it in turn
/// defines symbols that the logging macros expect to see.  Also note that
/// 'BALL_LOG_SET_CATEGORY' must be used at function scope, and can be used only
/// once within a scope, although it can be nested in inner scopes.
///
/// The entire program file is as follows.
/// @code
///  // logging.m.cpp                                                    -*-C++-*-
///
///  #include <ball_log.h>
///  #include <ball_loggermanager.h>
///  #include <ball_loggermanagerconfiguration.h>
///  #include <ball_streamobserver.h>
///
///  #include <bslma_allocator.h>
///  #include <bslma_default.h>
///
///  #include <bsl_iostream.h>
///  #include <bsl_memory.h>
///
///  using namespace BloombergLP;
///
///  int main(int argc, char *argv[])
///  {
///      int verbose = argc > 1;
///          // Enable command-line control of program behavior.
///
///      bslma::Allocator *alloc_p = bslma::Default::globalAllocator();
///          // Get global allocator.
///
///      ball::LoggerManagerConfiguration configuration;
///      configuration.setDefaultThresholdLevelsIfValid(ball::Severity::e_WARN);
///          // Configure the minimum threshold at which records are published to
///          // the observer to 'e_WARN'.
///
///      ball::LoggerManagerScopedGuard scopedGuard(configuration);
///          // Instantiate the logger manager singleton.
///
///      ball::LoggerManager& manager = ball::LoggerManager::singleton();
///
///      bsl::shared_ptr<ball::StreamObserver> observer(
///                                new(*alloc_p) ball::StreamObserver(&bsl::cout),
///                                alloc_p);
///          // Create simple observer; writes to 'stdout'.
///
///      manager.registerObserver(observer, "default");
///          // Register the observer under (arbitrary) name "default".
///
///      BALL_LOG_SET_CATEGORY("main category");
///          // Set a category -- an arbitrary name.
///
///      BALL_LOG_INFO << "Hello world!";
///          // With default settings, this line has no effect.
///
///      if (verbose) {  // 'if' to allow command-line activation
///          BALL_LOG_ERROR << "Good-bye world!";
///              // Log 'message' at 'ball::Severity::e_ERROR' severity level.
///      }
///      else {
///          bsl::cout << "This program should produce no other output.\n";
///              // By default, 'e_INFO' is ignored; only 'e_ERROR' and above are
///              // published.
///      }
///
///      return 0;
///  }
/// @endcode
/// If the above program is run with no command-line arguments, the output will
/// appear on 'stdout' as:
/// @code
///  This program should produce no other output.
/// @endcode
/// This case illustrates the default behavior, namely that "extraordinary"
/// severity events (i.e., 'e_ERROR' and 'e_FATAL') are published immediately, but
/// other events (such as 'e_INFO', 'e_DEBUG', and 'e_TRACE') are ignored.  The
/// user can easily modify this default behavior; subsequent examples will address
/// these alternate usage modes.
///
/// If, however, any argument at all is provided to the executable on the command
/// line, the output to 'stdout' will appear something like the following.  (The
/// spacing is changed to aid readability.)
/// @code
///  27SEP2007_13:26:46.322 6152 1 ERROR logging.m.cpp 33 main category
///  Good-bye world!
/// @endcode
/// Note that any number of observers can be registered with a logger manager.
/// Also note that concrete observers that can be configured after their creation
/// (e.g., as to whether log records are published in UTC or local time)
/// generally can have their configuration adjusted at any time, either before
/// or after being registered.  For an example of such an observer, see
/// @ref ball_asyncfileobserver .
///
/// ### Tutorial Example 2: Hello World! With Modified Defaults
///
/// This "Hello world!" example illustrates how to enable "recording" log records
/// to the in-memory record buffer, and also how to change the severity level at
/// which records are published as "pass-through".  The code is identical to
/// {Example 1}, except that attributes of 'ball::LoggerManagerConfiguration' are
/// changed from their defaults (in a single line, in this case).
///
/// The 'setDefaultThresholdLevelsIfValid' method of
/// 'ball::LoggerManagerConfiguration' that we will use to change the default
/// configuration takes four arguments, each in the range '[0 .. 255]'.  The
/// method returns a status, and will fail (with no effect) if any argument is not
/// a valid threshold level.  Note that any 'ball::Severity::Level' enumerator
/// value is valid, and it is good practice to limit arguments to one of those
/// enumerators.  The one line that effects our change is:
/// @code
///  configuration.setDefaultThresholdLevelsIfValid(
///                               ball::Severity::e_TRACE,   // record level
///                               ball::Severity::e_WARN,    // pass-through level
///                               ball::Severity::e_ERROR,   // trigger level
///                               ball::Severity::e_FATAL);  // trigger-all level
/// @endcode
/// This method call sets the four severity threshold levels as indicated and has
/// the following effect on logging behavior.
///
///  1. Any record logged with a severity that is at least that of 'e_TRACE' is
///    written to the record buffer, but not necessarily published.
/// 
///  2. Any record logged with a severity that is at least that of 'e_WARN' is
///    published immediately as a pass-through record *and* is recorded in the
///    record buffer.  Note that, should the record buffer be published before
///    such a record is overwritten, the record will be published a second time,
///    avoiding "holes" in the trace-back if and when the buffer is published.
/// 
///  3. Any record logged with a severity that is at least that of 'e_ERROR' is
///    published immediately as a pass-through record *and* is recorded in the
///    record buffer, and *then* triggers the publication of the record buffer.
///    This behavior, among other things, guarantees that the 'e_ERROR' record
///    will be published twice.  Although this might seem like a bug, it is the
///    intended behavior.  Each published record is sent to the observer with a
///    publication cause (a 'ball::Transmission::Cause' value) that the observer
///    is free to use in filtering and re-routing published records.  Future
///    examples will illustrate various filtering techniques.
/// 
///  4. Any record logged with a severity that is at least that of 'e_FATAL' will
///    behave as for 'e_ERROR' above, except that the record buffer from *every*
///    active logger registered with the logger manager will be published.  See
///    the multi-threaded examples below for more information about multiple
///    loggers.
///
/// With the one extra line of code as described above, plus the explicit
/// '#include' directive of 'ball_severity.h' (since we use symbols from that
/// header explicitly), the code is otherwise exactly as in {Example 1} above.
/// @code
///  // logging.m.cpp                                                    -*-C++-*-
///
///  #include <ball_log.h>
///  #include <ball_loggermanager.h>
///  #include <ball_loggermanagerconfiguration.h>
///  #include <ball_severity.h>
///  #include <ball_streamobserver.h>
///
///  #include <bslma_allocator.h>
///  #include <bslma_default.h>
///
///  #include <bsl_iostream.h>
///  #include <bsl_memory.h>
///
///  using namespace BloombergLP;
///
///  int main(int argc, char *argv[])
///  {
///      int verbose = argc > 1;
///          // Enable command-line control of program behavior.
///
///      bslma::Allocator *alloc_p = bslma::Default::globalAllocator();
///          // Get global allocator.
///
///      ball::LoggerManagerConfiguration configuration;
///          // Instantiate the default configuration.
///
///      configuration.setDefaultThresholdLevelsIfValid(
///                               ball::Severity::e_TRACE,   // record level
///                               ball::Severity::e_WARN,    // pass-through level
///                               ball::Severity::e_ERROR,   // trigger level
///                               ball::Severity::e_FATAL);  // trigger-all level
///          // Set the four severity threshold levels; note that this method can
///          // fail, and therefore returns a status.
///
///      ball::LoggerManagerScopedGuard scopedGuard(configuration);
///          // Instantiate the logger manager singleton.
///
///      ball::LoggerManager& manager = ball::LoggerManager::singleton();
///
///      bsl::shared_ptr<ball::StreamObserver> observer(
///                                new(*alloc_p) ball::StreamObserver(&bsl::cout),
///                                alloc_p);
///          // Create simple observer; writes to 'stdout'.
///
///      manager.registerObserver(observer, "default");
///          // Register the observer under (arbitrary) name "default".
///
///      BALL_LOG_SET_CATEGORY("main category");
///          // Set a category -- an arbitrary name.
///
///      BALL_LOG_INFO << "Hello world!";
///          // With default settings, this line has no effect.
///
///      if (verbose) {  // 'if' to allow command-line activation
///          BALL_LOG_ERROR << "Good-bye world!";
///              // Log 'message' at 'ball::Severity::e_ERROR' severity level
///              // *and* trigger the publication of the record buffer
///              // "trace-back".
///      }
///      else {
///          bsl::cout << "This program should produce no other output.\n";
///              // 'e_INFO' messages are recorded but *not* automatically
///              // published; an 'e_ERROR' or 'e_FATAL' message is needed to
///              // trigger the publication of the record buffer.
///      }
///
///      return 0;
///  }
/// @endcode
/// Once again, if the program is run with no command-line arguments, the output
/// will appear on 'stdout' as:
/// @code
///   This program should produce no other output.
/// @endcode
/// Now, however, if a command-line argument is provided, the output is a little
/// more extensive.  (The spacing is changed to aid readability, and the
/// timestamps are altered for illustrative purposes to show the temporal sequence
/// more clearly).
/// @code
///  27SEP2007_13:29:18.147 105 1 ERROR logging.m.cpp 42 main category
///  Good-bye world!
///
///  27SEP2007_13:29:18.147 105 1 ERROR logging.m.cpp 42 main category
///  Good-bye world!
///
///  27SEP2007_13:29:18.147 105 1 INFO logging.m.cpp 38 main category
///  Hello world!
/// @endcode
/// Notice that the 'e_ERROR' message appears twice.  This is not a bug but, as
/// mentioned above, an intended consequence of the settings.  As described above,
/// the sequence of events is as follows: (1) The 'e_INFO' message is written to
/// an in-memory buffer but *not* published (because 'e_INFO' is above the
/// "Record" threshold but below the "Pass-Through", "Trigger", and "Trigger-All"
/// thresholds).  (2) The (one) 'e_ERROR' message is *first* published (a
/// relatively quick operation insuring that the error indication is seen) because
/// 'e_ERROR' is above the "Pass-Through" threshold, and *then* is written to the
/// in-memory buffer, because 'e_ERROR' is above the "Record" threshold.  Then,
/// the entire contents of the in-memory buffer is published, in "Last In, First
/// Out" (LIFO) order, because 'e_ERROR' is at the "Trigger" threshold.
///
/// ### Tutorial Example 3: Hello World! With Manual publish
///
/// This "Hello world!" example alters {Example 2} in one aspect.  The conditional
/// 'e_ERROR' message is removed, as is the use of command-line arguments, since
/// they are not needed to illustrate our point.  Instead, the user calls the
/// 'publish' method of the logger instance "manually" before exiting, to force
/// the publication of all unpublished messages in the logger's buffer.  Note that
/// this is not "default" behavior, but is accomplished simply enough.  The line:
/// @code
///  manager.getLogger().publish();
/// @endcode
/// uses the singleton logger manager instance to obtain the default logger
/// instance, and with that logger instance invokes the 'publish' method.  Note
/// that the logger's "manual" 'publish' method should not be confused with the
/// 'ball::Observer' 'publish' method that is invoked by all "manual" and
/// "automatic" logger "publishing" operations.  Also note that should the
/// 'manager' instance for some reason not be visible, the class method
/// 'ball::LoggerManager::singleton()' can be used to obtain a reference to that
/// instance.  The full program file appears as follows.
/// @code
///  // logging.m.cpp                                                    -*-C++-*-
///
///  #include <ball_log.h>
///  #include <ball_loggermanager.h>
///  #include <ball_loggermanagerconfiguration.h>
///  #include <ball_severity.h>
///  #include <ball_streamobserver.h>
///
///  #include <bslma_allocator.h>
///  #include <bslma_default.h>
///
///  #include <bsl_iostream.h>
///  #include <bsl_memory.h>
///
///  using namespace BloombergLP;
///
///  int main()
///  {
///      bslma::Allocator *alloc_p = bslma::Default::globalAllocator();
///          // Get global allocator.
///
///      ball::LoggerManagerConfiguration configuration;
///          // Create default configuration.
///
///      configuration.setDefaultThresholdLevelsIfValid(
///                               ball::Severity::e_TRACE,   // record level
///                               ball::Severity::e_WARN,    // pass-through level
///                               ball::Severity::e_ERROR,   // trigger level
///                               ball::Severity::e_FATAL);  // trigger-all level
///          // Set the four severity threshold levels; note that this method can
///          // fail, and therefore returns a status.
///
///      ball::LoggerManagerScopedGuard scopedGuard(configuration);
///          // Instantiate the logger manager singleton.
///
///      ball::LoggerManager& manager = ball::LoggerManager::singleton();
///
///      bsl::shared_ptr<ball::StreamObserver> observer(
///                                new(*alloc_p) ball::StreamObserver(&bsl::cout),
///                                alloc_p);
///          // Create simple observer; writes to 'stdout'.
///
///      manager.registerObserver(observer, "default");
///          // Register the observer under (arbitrary) name "default".
///
///      BALL_LOG_SET_CATEGORY("main category");
///          // Set a category -- an arbitrary name.
///
///      BALL_LOG_INFO << "Hello world!";
///
///      BALL_LOG_INFO << "Hello again, world!";
///
///      bsl::cout << "We're almost ready to exit."     " "
///                   "Let's publish the buffer first:" "\n";
///
///      manager.getLogger().publish();
///          // This chain of calls insures that all messages that are still held
///          // in the logger's in-memory buffer are published before the program
///          // terminates.
///
///      return 0;
///  }
/// @endcode
/// This program produces the following output on 'stdout', altered here again in
/// spacing format and timestamp value for ease of reading.
/// @code
///  We're almost ready to exit.  Let's publish the buffer first:
///
///  27SEP2007_13:32:17.778 13702 1 INFO logging.m.cpp 37 main category
///  Hello again, world!
///
///  27SEP2007_13:32:17.778 13702 1 INFO logging.m.cpp 35 main category
///  Hello world!
/// @endcode
/// Note again that the output is published in LIFO order.
///
/// ### Tutorial Example 4: Hello World! in Three Files
///
/// This example adds a few new aspects to the scenario of {Example 1} and
/// {Example 2}.  First of all, in addition to the file defining 'main', we
/// introduce a separate translation unit 'f_log.cpp' that defines a function
/// 'logThisInfoMsg'.  The 'f_log.cpp' file defines its own category, "function
/// category", that is distinct from the "main category" defined in 'main'.  When
/// 'logThisInfoMsg' is invoked, the resulting message is logged to "function
/// category".  Note, however, that when the now-familiar logging macros are used
/// from 'main' directly, those messages are logged to "main category".
///
/// In addition to the above, we also show another way to alter the default
/// thresholds.  In this case, we choose values so that all messages logged with a
/// severity at least that of 'e_INFO' are passed through immediately to the
/// observer (in this case, to 'stdout').  In this example, we make the change by
/// calling the 'setDefaultThresholdLevels' method of the logger manager:
/// @code
///  manager.setDefaultThresholdLevels(
///                   ball::Severity::e_TRACE,   // sets "Record" threshold
///                   ball::Severity::e_INFO,    // sets "Pass-Through"  threshold
///                   ball::Severity::e_ERROR,   // sets "Trigger" threshold
///                   ball::Severity::e_FATAL);  // sets "Trigger-All" threshold
/// @endcode
/// The above call has an effect that differs subtly from the configuration
/// object's 'setDefaultThresholdLevelsIfValid' method.  The latter sets the
/// permanent "factory defaults", as well as the "instantaneous defaults" that may
/// be altered as often as desired using the above call.  If, after the above call
/// is made, the 'setCategoryThresholdsToFactoryDefaults' method is called, the
/// effects of 'setDefaultThresholdLevels' are erased.  This distinction is
/// important for more advanced administration, but is not central to this
/// example; we offer the alternative to illustrate logger functionality.
///
/// Note that it is both unnecessary and a *fatal* *error* for 'f_log' (or *any*
/// library code) to instantiate a logger manager.  The logger manager is a
/// singleton, and should be constructed using the logger manager scoped guard
/// ('ball::LoggerManagerScopedGuard').  In any sound design, this should be done
/// in 'main' before any other threads have been created.
///
/// The main 'logging.m.cpp' file, plus 'f_log.cpp' and its associated 'f_log.h'
/// file, are shown below.  First the 'f_log.h' header file:
/// @code
///  // f_log.h                                                          -*-C++-*-
///  #ifndef INCLUDED_F_LOG
///  #define INCLUDED_F_LOG
///
///  namespace BloombergLP {
///
///  void logThisInfoMsg(const char *message);
///      // Log the specified 'message' at the 'ball::Severity::e_INFO' severity
///      // level.  The category to which 'message' is logged is defined in
///      // the implementation.  Note that this function may affect the
///      // operation of other logging operations that do not explicitly set
///      // their own categories.
///
///  }  // close enterprise namespace
///
///  #endif
/// @endcode
/// Then the 'f_log.cpp' implementation file:
/// @code
///  // f_log.cpp                                                        -*-C++-*-
///
///  #include <ball_log.h>
///
///  namespace BloombergLP {
///
///  void logThisInfoMsg(const char *message)
///  {
///      // Note that the uppercase symbols are macros defined in 'ball_log'.
///
///      BALL_LOG_SET_CATEGORY("function category");
///          // Set a category -- arbitrary and may be changed.
///
///      BALL_LOG_INFO << message;
///          // Log 'message' at 'ball::Severity::e_INFO' severity level.
///  }
///
///  }  // close enterprise namespace
/// @endcode
/// Finally, the 'logging.m.cpp' file that defines 'main':
/// @code
///  // logging.m.cpp                                                    -*-C++-*-
///
///  #include <ball_log.h>
///  #include <ball_loggermanager.h>
///  #include <ball_loggermanagerconfiguration.h>
///  #include <ball_severity.h>
///  #include <ball_streamobserver.h>
///
///  #include <bslma_allocator.h>
///  #include <bslma_default.h>
///
///  #include <bsl_iostream.h>
///  #include <bsl_memory.h>
///
///  #include <f_log.h>
///
///  using namespace BloombergLP;
///
///  int main(int argc, char *argv[])
///  {
///      int verbose = argc > 1;
///          // Enable command-line control of program behavior.
///
///      bslma::Allocator *alloc_p = bslma::Default::globalAllocator();
///          // Get global allocator.
///
///      ball::LoggerManagerConfiguration configuration;
///          // Instantiate the default configuration.
///
///      ball::LoggerManagerScopedGuard scopedGuard(configuration);
///          // Instantiate the logger manager singleton.
///
///      ball::LoggerManager& manager = ball::LoggerManager::singleton();
///
///      manager.setDefaultThresholdLevels(
///                    ball::Severity::e_TRACE,   // sets "Record" threshold
///                    ball::Severity::e_INFO,    // sets "Pass-Through" threshold
///                    ball::Severity::e_ERROR,   // sets "Trigger" threshold
///                    ball::Severity::e_FATAL);  // sets "Trigger-All" threshold
///
///      bsl::shared_ptr<ball::StreamObserver> observer(
///                                new(*alloc_p) ball::StreamObserver(&bsl::cout),
///                                alloc_p);
///          // Create simple observer; writes to 'stdout'.
///
///      manager.registerObserver(observer, "default");
///          // Register the observer under (arbitrary) name "default".
///
///      BALL_LOG_SET_CATEGORY("main category");
///          // Set a category -- note that this will *not* affect the category
///          // set in 'logThisInfoMsg'.
///
///      BALL_LOG_INFO << "Called directly from 'main'";
///          // Logged to "main category".
///
///      if (verbose) {  // 'if' to allow command-line activation
///          for (int i = 0; i < 3; ++i) {
///              logThisInfoMsg("Hello world!");
///              bsl::cout << "Watch the loop execute:  i = " << i << bsl::endl;
///                  // proves Msg is published as "pass-through"
///          }
///      }
///
///      BALL_LOG_INFO << "Called again directly from 'main'";
///          // Logged to "main category".
///
///      return 0;
///  }
/// @endcode
/// Building these two files and running the executable with no additional
/// command-line arguments produces output from the two direct logging calls only.
/// Once again, the format and timestamps are altered for readability.
/// @code
///  27SEP2007_13:35:33.356 9427 1 INFO logging.m.cpp 40 main category
///  Called directly from 'main'
///
///  27SEP2007_13:35:33.357 9427 1 INFO logging.m.cpp 51 main category
///  Called again directly from 'main'
/// @endcode
/// Note that this sequence is not in LIFO order since this output is not from the
/// message buffer, but rather is direct "Pass-Through" output.
///
/// If we provide a command-line argument that will cause the 'for' loop to
/// execute, we then get the following output (with formats and timestamps altered
/// as is now familiar in these examples).
/// @code
///  27SEP2007_13:39:07.150 8249 1 INFO logging.m.cpp 40 main category
///  Called directly from 'main'
///
///  27SEP2007_13:39:07.151 8249 1 INFO f_log.cpp 16 function category
///  Hello world!
///  Watch the loop execute:  i = 0
///
///  27SEP2007_13:39:07.151 8249 1 INFO f_log.cpp 16 function category
///  Hello world!
///  Watch the loop execute:  i = 1
///
///  27SEP2007_13:39:07.152 8249 1 INFO f_log.cpp 16 function category
///  Hello world!
///  Watch the loop execute:  i = 2
///
///  27SEP2007_13:39:07.152 8249 1 INFO logging.m.cpp 51 main category
///  Called again directly from 'main'
/// @endcode
///
/// ### Tutorial Example 5: Logging in Two Threads
///
/// This example illustrates how to use logging in a multi-threaded application.
/// Since we have already shown how logging works seamlessly across multiple
/// translation units, we will implement everything that we need for this example
/// in a single file named 'mtlogging1.cpp'.
///
/// We define two functions, 'f1' and 'f2', that log their 'message' text argument
/// to function-defined categories, at 'e_INFO' and 'e_WARN' severities,
/// respectively.  We also define two 'extern' "C" thread functions,
/// 'threadFunction1' and 'threadFunction2', that call 'f1' and 'f2',
/// respectively, in a loop of three iterations.  The thread functions also differ
/// slightly in their calls to 'bslmt::ThreadUtil::sleep' within the loop.  These
/// 'sleep' calls, in conjunction with the logged timestamps, show the interleaved
/// operation of the threads.  Note that although the thread functions define
/// their own categories, the logging macros in 'f1' and 'f2' use only the
/// category defined within the scope of 'f1' and 'f2', respectively.
///
/// 'main' creates an observer that will write to 'stdout', initializes the logger
/// manager singleton, sets a category, and sets the default threshold values,
/// just as in the single-threaded examples above.  Then 'main' uses 'bslmt' to
/// spawn two threads running the above two thread functions.  Each thread logs
/// its messages, but only the second thread's log messages having 'e_WARN'
/// severity will be published immediately as "Pass-Through" records.  Finally,
/// using the same 'verbose' mechanism (set by the presence or absence of a
/// command-line argument) as the above examples, we conditionally log a message
/// in 'main' at 'e_ERROR' severity.  If this block of code executes, then the
/// entire record buffer for the example (i.e., for both threads and 'main') will
/// be published, in reverse chronological order.
///
/// The full code as described above is presented without interruption for ease of
/// reading.
/// @code
///  // logging.m.cpp                                                    -*-C++-*-
///
///  #include <ball_log.h>
///  #include <ball_loggermanager.h>
///  #include <ball_loggermanagerconfiguration.h>
///  #include <ball_severity.h>
///  #include <ball_streamobserver.h>
///
///  #include <bslma_allocator.h>
///  #include <bslma_default.h>
///
///  #include <bslmt_threadutil.h>
///
///  #include <bsls_timeinterval.h>
///
///  #include <bsl_iostream.h>
///  #include <bsl_memory.h>
///
///  using namespace BloombergLP;
///
///  void f1(const char *message)
///      // Log the specified 'message' to the "Function 1" category at 'e_INFO'
///      // severity.
///  {
///      BALL_LOG_SET_CATEGORY("Function 1");
///      BALL_LOG_INFO << message;
///  }
///
///  void f2(const char *message)
///      // Log the specified 'message' to the "Function 2" category at 'e_WARN'
///      // severity.
///  {
///      BALL_LOG_SET_CATEGORY("Function 2");
///      BALL_LOG_WARN << message;
///  }
///
///  extern "C" void *threadFunction1(void *)
///      // Log to the default logger a sequence of messages to the "Function 1"
///      // category at 'e_INFO' severity.
///  {
///      char               buf[10] = "Message n";
///      bsls::TimeInterval waitTime(4.0);
///
///      for (int i = 0; i < 3; ++i) {
///          buf[8] = '0' + i;
///          f1(buf);
///          bslmt::ThreadUtil::sleep(waitTime);
///      }
///      return 0;
///  }
///
///  extern "C" void *threadFunction2(void *)
///      // Log to the default logger a sequence of messages to the "Function 2"
///      // category at 'e_WARN' severity.
///  {
///      char               buf[10] = "Message n";
///      bsls::TimeInterval waitTime(2.0);
///
///      for (int i = 0; i < 3; ++i) {
///          buf[8] = '0' + i;
///          bslmt::ThreadUtil::sleep(waitTime);
///          f2(buf);
///      }
///      return 0;
///  }
///
///  int main(int argc, char *argv[])
///  {
///      int verbose = argc > 1;  // allows user to control output from command
///                               // line
///
///      bslma::Allocator *alloc_p = bslma::Default::globalAllocator();
///          // Get global allocator.
///
///      ball::LoggerManagerConfiguration configuration;
///      configuration.setDefaultThresholdLevelsIfValid(
///                                    ball::Severity::e_TRACE,  // "Record"
///                                    ball::Severity::e_WARN,   // "Pass-Through"
///                                    ball::Severity::e_ERROR,  // "Trigger"
///                                    ball::Severity::e_FATAL); // "Trigger-All"
///
///      ball::LoggerManagerScopedGuard scopedGuard(configuration);
///          // Instantiate the logger manager singleton.
///
///      ball::LoggerManager& manager = ball::LoggerManager::singleton();
///
///      bsl::shared_ptr<ball::StreamObserver> observer(
///                                new(*alloc_p) ball::StreamObserver(&bsl::cout),
///                                alloc_p);
///          // Create simple observer; writes to 'stdout'.
///
///      manager.registerObserver(observer, "default");
///          // Register the observer under (arbitrary) name "default".
///
///      BALL_LOG_SET_CATEGORY("main");
///
///      bslmt::ThreadAttributes   attributes;
///      bslmt::ThreadUtil::Handle handle1;
///      bslmt::ThreadUtil::Handle handle2;
///
///      bslmt::ThreadUtil::create(&handle1, attributes, threadFunction1, 0);
///      bslmt::ThreadUtil::create(&handle2, attributes, threadFunction2, 0);
///
///      bslmt::ThreadUtil::join(handle1);
///      bslmt::ThreadUtil::join(handle2);
///
///      if (verbose) {  // 'if' to allow command-line activation
///          BALL_LOG_ERROR << "Force publication.";
///      }
///      return 0;
///  }
/// @endcode
/// Running the above program with no extra command-line argument produces the
/// output shown below.  Note that only the 'e_WARN' records (from thread 3) are
/// published, and that they are in chronological order.
/// @code
///  27SEP2007_13:50:20.023 6625 3 WARN logging.m.cpp 28 Function 2 Message 0
///
///  27SEP2007_13:50:22.033 6625 3 WARN logging.m.cpp 28 Function 2 Message 1
///
///  27SEP2007_13:50:24.042 6625 3 WARN logging.m.cpp 28 Function 2 Message 2
/// @endcode
/// However, if we supply an additional command-line argument, the 'if' statement
/// containing the 'BALL_LOG_ERROR' macro will execute.  This causes the 'e_ERROR'
/// record itself to be published (from thread 1, the 'main' thread, as a
/// "pass-through"), and it also triggers the publication of the entire record
/// buffer.  Note how the records from threads 1, 2, and 3 are published in
/// inverse chronological order.  Note in particular how the 'e_INFO' and 'e_WARN
/// records interleave irregularly because of the different 'sleep' statements in
/// the above code.
/// @code
///  27SEP2007_13:52:20.435 13809 3 WARN logging.m.cpp 28 Function 2 Message 0
///
///  27SEP2007_13:52:22.445 13809 3 WARN logging.m.cpp 28 Function 2 Message 1
///
///  27SEP2007_13:52:24.455 13809 3 WARN logging.m.cpp 28 Function 2 Message 2
///
///  27SEP2007_13:52:30.456 13809 1 ERROR logging.m.cpp 89 main Force publication.
///
///  27SEP2007_13:52:30.456 13809 1 ERROR logging.m.cpp 89 main Force publication.
///
///  27SEP2007_13:52:26.446 13809 2 INFO logging.m.cpp 20 Function 1 Message 2
///
///  27SEP2007_13:52:24.455 13809 3 WARN logging.m.cpp 28 Function 2 Message 2
///
///  27SEP2007_13:52:22.445 13809 3 WARN logging.m.cpp 28 Function 2 Message 1
///
///  27SEP2007_13:52:22.435 13809 2 INFO logging.m.cpp 20 Function 1 Message 1
///
///  27SEP2007_13:52:20.435 13809 3 WARN logging.m.cpp 28 Function 2 Message 0
///
///  27SEP2007_13:52:18.433 13809 2 INFO logging.m.cpp 20 Function 1 Message 0
/// @endcode
///
/// ### Tutorial Example 6: Logging in Two Threads Using Two Loggers
///
/// This example is similar to {Example 5} above, with only a few "minor" changes.
/// Nevertheless, as we use more of the logger's features, we need to become more
/// familiar with the details of logger operation.  In this example, we install a
/// distinct logger instance (i.e., not the default logger) for one of the
/// threads.  (The other thread continues to use the default logger that is shared
/// with 'main', to make clear that the "one-logger-per-thread" usage pattern
/// applies on a thread-by-thread basis, and is not "all-or-nothing".)  By
/// choosing this more sophisticated usage, however, we need to address the
/// question of logger resource management and lifetime -- a question that is
/// completely avoided by using the default logger.  As is often the case in
/// programming, there is no one "right" answer to this resource question, and so
/// we will discuss our choices and the alternatives in this example.
///
/// Installing a distinct logger instance in 'threadFunction1' is simple enough to
/// do, but a question arises immediately: who should own the logger resources?
/// Before we discuss this question, let's look at the specific solution that we
/// have chosen to clarify the question of what resources a logger needs.
///
/// We've modified 'threadFunction1' to take a logger as an argument (passed as a
/// 'void *') and to use the logger manager's 'setLogger' function to install the
/// logger as the active logger for that thread.  The code to do this in
/// 'threadFunction1' is straightforward:
/// @code
///  extern "C" void *threadFunction1(void *logger)
///      // ...
///  {
///      // ...
///      ball::LoggerManager::singleton().setLogger((ball::Logger*)logger);
///          // Install a local 'logger' for this thread.
///      // ...
///  }
/// @endcode
/// Clearly, in this solution, 'threadFunction1' does *not* own 'logger' or any of
/// its resources.  This *must* be the case, because the function has no way of
/// knowing in how many other threads the passed-in 'logger' might be installed.
/// Recall that any one logger may be installed in any number of threads.
///
/// This one-line addition to call the 'setLogger' method is, from the thread
/// function's perspective, the only change needed if the thread is *not* to
/// manage its own logger resources.  But if 'threadFunction1' does not manage the
/// logger resources, then 'main' must do so.  Let's look at what 'main' needs to
/// do so that we can be concrete about what resources are needed in the first
/// place.
///
/// Several steps are needed to instantiate a 'ball::Logger' instance.  The logger
/// needs a (concrete) 'ball::RecordBuffer', and the preferred record buffer,
/// 'ball::FixedSizeRecordBuffer', in turn needs a size for the record buffer
/// ('LOGBUF_SIZE').  We also provide an explicit 'bslma::Allocator' to supply
/// memory; the global allocator returned by 'bslma::Default::globalAllocator()'
/// is sufficient here.  Assuming that 32k bytes is a good size for the buffer,
/// the following eight lines will appear in 'main'.
/// @code
///  enum { LOGBUF_SIZE = 32 * 1024 };
///  bslma::Allocator            *alloc_p = bslma::Default::globalAllocator();
///  ball::FixedSizeRecordBuffer  rb(LOGBUF_SIZE, alloc_p);
///  ball::LoggerManager&         manager = ball::LoggerManager::singleton();
///  ball::Logger                *logger  = manager.allocateLogger(&rb);
///  // ...
///  manager.deallocateLogger(logger);  // free resources
/// @endcode
/// The last line frees resources and is executed just before 'main' returns.
///
/// With this implementation choice, 'main' clearly owns 'logger's resources.  We
/// now have enough information to address the question of what the consequences
/// of this decision are, and whether or not 'main' actually *should* own these
/// resources.
///
/// At first glance, it might seem that the thread itself should own and manage
/// everything it needs for its own logger.  This is certainly a reasonable
/// choice, and {Example 6} below shows what 'threadFunction1' would look like in
/// that case, but there are two separate reasons why the owner of 'main' might
/// prefer *not* to delegate those responsibilities to the thread function.
///
/// The first reason -- not relevant in this particular example -- is that 'main'
/// may wish to install the *same* logger in several threads.  In this case, no
/// one thread can manage "its own" logger, because the logger is (or at least
/// might be) shared.  Sharing loggers among groups of threads is at least a
/// reasonable design choice, and so it is useful to see how 'main' takes
/// ownership of logger resources.
///
/// The second reason for wanting 'main' and not the thread function to own the
/// logger's resources is illustrated -- albeit trivially -- in this example:
/// 'main' can *potentially* log a 'e_FATAL' record (here the "Trigger-All"
/// threshold) after all other threads have terminated.  If the user wants the
/// (now-terminated) thread's trace-back log to be published by the "Trigger-All",
/// then 'main' must preserve the logger resources.  Otherwise, if a thread were
/// to own its own logger resources, then any "trace-back" records generated by
/// that thread would necessarily be discarded (or, at best, unconditionally
/// published) when the thread function returned.
///
/// In this example we also made a trivial change that has nothing to do with
/// threading, but illustrates a useful feature of 'ball::StreamObserver', namely
/// that an instance can write to a file as easily as to 'stdout'.  The three
/// lines in 'main':
/// @code
///  ball::LoggerManagerScopedGuard scopedGuard(configuration);
///      // Instantiate the logger manager singleton.
///
///  bsl::ofstream outFile("outFile");
///  bsl::shared_ptr<ball::StreamObserver> observer(
///                                  new(*alloc_p) ball::StreamObserver(&outFile),
///                                  alloc_p);
///      // Create simple observer; writes to 'outFile".
///
///  ball::LoggerManager& manager = ball::LoggerManager::singleton();
///
///  manager.registerObserver(observer, "default");
///      // Register the observer under (arbitrary) name "default".
/// @endcode
/// install a "file observer" that will write to "outFile", creating the file if
/// it doesn't exist and overwriting it if it does.  Clearly, this is just taking
/// advantage of the standard C++ 'ofstream' class, but it is useful all the same.
///
/// The full code as described above is presented without interruption for ease of
/// reading.
/// @code
///  // logging.m.cpp                                                    -*-C++-*-
///
///  #include <ball_fixedsizerecordbuffer.h>
///  #include <ball_log.h>
///  #include <ball_loggermanager.h>
///  #include <ball_loggermanagerconfiguration.h>
///  #include <ball_severity.h>
///  #include <ball_streamobserver.h>
///
///  #include <bslma_allocator.h>
///  #include <bslma_default.h>
///
///  #include <bslmt_threadutil.h>
///
///  #include <bsls_timeinterval.h>
///
///  #include <bsl_fstream.h>
///  #include <bsl_memory.h>
///
///  using namespace BloombergLP;
///
///  void f1(const char *message)
///      // Log the specified 'message' to the "Function 1" category at 'e_INFO'
///      // severity.
///  {
///      BALL_LOG_SET_CATEGORY("Function 1");
///      BALL_LOG_INFO << message;
///  }
///
///  void f2(const char *message)
///      // Log the specified 'message' to the "Function 2" category at 'e_WARN'
///      // severity.
///  {
///      BALL_LOG_SET_CATEGORY("Function 2");
///      BALL_LOG_WARN << message;
///  }
///
///  extern "C" void *threadFunction1(void *logger)
///      // Log to the specified 'logger' a sequence of messages to the "Function
///      // 1" category at 'e_INFO' severity.
///  {
///      ball::LoggerManager::singleton().setLogger((ball::Logger *)logger);
///          // Install a local logger for this thread.
///
///      char               buf[10] = "Message n";
///      bsls::TimeInterval waitTime(4.0);
///
///      for (int i = 0; i < 3; ++i) {
///          buf[8] = '0' + i;
///          f1(buf);
///          bslmt::ThreadUtil::sleep(waitTime);
///      }
///      return 0;
///  }
///
///  extern "C" void *threadFunction2(void *)
///      // Log to the default logger a sequence of messages to the "Function 2"
///      // category at 'e_WARN' severity.
///  {
///      char               buf[10] = "Message n";
///      bsls::TimeInterval waitTime(2.0);
///
///      for (int i = 0; i < 3; ++i) {
///          buf[8] = '0' + i;
///          bslmt::ThreadUtil::sleep(waitTime);
///          f2(buf);
///      }
///      return 0;
///  }
///
///  int main(int argc, char *argv[])
///  {
///      int verbose = argc > 1; // allows user to control output from command
///                              // line
///
///      bslma::Allocator *alloc_p = bslma::Default::globalAllocator();
///          // Get global allocator.
///
///      ball::LoggerManagerConfiguration configuration;
///      configuration.setDefaultThresholdLevelsIfValid(
///                                   ball::Severity::e_TRACE,   // "Record"
///                                   ball::Severity::e_WARN,    // "Pass-Through"
///                                   ball::Severity::e_ERROR,   // "Trigger"
///                                   ball::Severity::e_FATAL);  // "Trigger-All"
///
///      ball::LoggerManagerScopedGuard scopedGuard(configuration);
///          // Instantiate the logger manager singleton.
///
///      ball::LoggerManager& manager = ball::LoggerManager::singleton();
///
///      bsl::ofstream outFile("outFile");
///      bsl::shared_ptr<ball::StreamObserver> observer(
///                                  new(*alloc_p) ball::StreamObserver(&outFile),
///                                  alloc_p);
///          // Create simple observer; writes to 'outFile".
///
///      manager.registerObserver(observer, "default");
///          // Register the observer under (arbitrary) name "default".
///
///      BALL_LOG_SET_CATEGORY("main");
///
///      // The following lines prepare resources to allocate a 'logger' from the
///      // logger manager.  'main' is responsible for managing resource
///      // lifetimes.
///
///      enum { LOGBUF_SIZE = 32 * 1024 };
///      ball::FixedSizeRecordBuffer  rb(LOGBUF_SIZE, alloc_p);
///      ball::Logger                *logger  = manager.allocateLogger(&rb);
///
///      bslmt::ThreadAttributes   attributes;
///      bslmt::ThreadUtil::Handle handle1;
///      bslmt::ThreadUtil::Handle handle2;
///
///      // first thread gets 'logger'; second thread uses default logger
///      bslmt::ThreadUtil::create(&handle1, attributes, threadFunction1, logger);
///      bslmt::ThreadUtil::create(&handle2, attributes, threadFunction2, 0);
///
///      bslmt::ThreadUtil::join(handle1);
///      bslmt::ThreadUtil::join(handle2);
///
///      if (verbose) {  // 'if' to allow command-line activation
///          BALL_LOG_FATAL << "Force publication.";
///      }
///
///      manager.deallocateLogger(logger);  // free resources
///      return 0;
///  }
/// @endcode
/// Running the above program with no extra command-line argument produces the
/// output shown below that in this example is written to 'outFile'.  Note that,
/// except for the timestamps, process id, and filename, the output is the same
/// as for {Example 5} above: only the 'e_WARN' records (from thread 3) are
/// published and they are in chronological order.
/// @code
///   27SEP2007_13:57:52.012 3648 3 WARN logging.m.cpp 29 Function 2 Message 0
///
///   27SEP2007_13:57:54.022 3648 3 WARN logging.m.cpp 29 Function 2 Message 1
///
///   27SEP2007_13:57:56.032 3648 3 WARN logging.m.cpp 29 Function 2 Message 2
/// @endcode
/// When we supply an additional command-line argument, causing the logging macro
/// in 'main' (now 'BALL_LOG_FATAL') to execute, the *initial* output is similar
/// to {Example 5}.  Specifically, the three 'e_WARN' records are published in
/// chronological order as "Pass-Through" records, as is the 'e_FATAL' record
/// (that now replaces the 'e_ERROR' record).  From here on, however, the sequence
/// of events is a bit different.
///
/// Recall that in this example 'e_FATAL' is the "Trigger-All" threshold level.
/// For a "Trigger-All", each record buffer is published in turn.  *Within* a
/// record buffer, records are published in reverse chronological order, but, as
/// can clearly be seen from the timestamps, the sequence of records as a whole is
/// not well ordered in time at all.  Note, rather, that the 'e_FATAL' and
/// 'e_WARN' records from the default logger are published in reverse
/// chronological order, and *then* the 'e_INFO' records from the installed
/// 'logger' are published in reverse chronological order.
/// @code
///  27SEP2007_13:59:23.504 8707 3 WARN logging.m.cpp 29 Function 2 Message 0
///
///  27SEP2007_13:59:25.514 8707 3 WARN logging.m.cpp 29 Function 2 Message 1
///
///  27SEP2007_13:59:27.524 8707 3 WARN logging.m.cpp 29 Function 2 Message 2
///
///  27SEP2007_13:59:33.524 8707 1 FATAL logging.m.cpp 103 main Force publication.
///
///  27SEP2007_13:59:33.524 8707 1 FATAL logging.m.cpp 103 main Force publication.
///
///  27SEP2007_13:59:27.524 8707 3 WARN logging.m.cpp 29 Function 2 Message 2
///
///  27SEP2007_13:59:25.514 8707 3 WARN logging.m.cpp 29 Function 2 Message 1
///
///  27SEP2007_13:59:23.504 8707 3 WARN logging.m.cpp 29 Function 2 Message 0
///
///  27SEP2007_13:59:29.514 8707 2 INFO logging.m.cpp 21 Function 1 Message 2
///
///  27SEP2007_13:59:25.504 8707 2 INFO logging.m.cpp 21 Function 1 Message 1
///
///  27SEP2007_13:59:21.498 8707 2 INFO logging.m.cpp 21 Function 1 Message 0
/// @endcode
///
/// ### Tutorial Example 7: A Thread that Owns its Own Logger Resources
///
/// This example is almost identical to {Example 6} above, except that the eight
/// lines (as highlighted above) needed to manage resources are moved from 'main'
/// to 'threadFunction1', so that the latter function no longer needs an argument.
/// Therefore, we show only 'threadFunction1' and 'main' explicitly in this
/// example.  Refer to the discussion of {Example 6} for details.
/// @code
///  // ...
///
///  extern "C" void *threadFunction1(void *)
///      // Log to an internally managed logger a sequence of messages to the
///      // "Function 1" category at 'e_INFO' severity.
///  {
///      // The following lines prepare resources to allocate a 'logger' from the
///      // logger manager.  This thread is responsible for managing resource
///      // lifetimes.
///
///      enum { LOGBUF_SIZE = 32 * 1024 };
///      bslma::Allocator            *alloc_p = bslma::Default::globalAllocator();
///      ball::FixedSizeRecordBuffer  rb(LOGBUF_SIZE, alloc_p);
///      ball::LoggerManager&         manager = ball::LoggerManager::singleton();
///      ball::Logger                *logger  = manager.allocateLogger(&rb);
///
///      manager.setLogger((ball::Logger*)logger);
///          // Install a local logger for this thread.
///
///      char               buf[10] = "Message n";
///      bsls::TimeInterval waitTime(4.0);
///
///      for (int i = 0; i < 3; ++i) {
///          buf[8] = '0' + i;
///          f1(buf);
///          bslmt::ThreadUtil::sleep(waitTime);
///      }
///
///      manager.deallocateLogger(logger);  // free resources
///      return 0;
///  }
///
///  // ...
///
///  int main(int argc, char *argv[])
///  {
///      int verbose = argc > 1; // allows user to control output from command
///                              // line
///
///      bslma::Allocator *alloc_p = bslma::Default::globalAllocator();
///          // Get global allocator.
///
///      ball::LoggerManagerConfiguration configuration;  // default configuration
///      configuration.setDefaultThresholdLevelsIfValid(
///                                   ball::Severity::e_TRACE,   // "Record"
///                                   ball::Severity::e_WARN,    // "Pass-Through"
///                                   ball::Severity::e_ERROR,   // "Trigger"
///                                   ball::Severity::e_FATAL);  // "Trigger-All"
///
///      ball::LoggerManagerScopedGuard scopedGuard(configuration);
///          // Instantiate the logger manager singleton.
///
///      ball::LoggerManager& manager = ball::LoggerManager::singleton();
///
///      bsl::ofstream outFile("outFile");
///      bsl::shared_ptr<ball::StreamObserver> observer(
///                                  new(*alloc_p) ball::StreamObserver(&outFile),
///                                  alloc_p);
///          // Create simple observer; writes to 'outFile".
///
///      manager.registerObserver(observer, "default");
///          // Register the observer under (arbitrary) name "default".
///
///      BALL_LOG_SET_CATEGORY("main");
///
///      bslmt::ThreadAttributes   attributes;
///      bslmt::ThreadUtil::Handle handle1;
///      bslmt::ThreadUtil::Handle handle2;
///
///      // first thread manages its own logger; second thread uses default logger
///      bslmt::ThreadUtil::create(&handle1, attributes, threadFunction1, 0);
///      bslmt::ThreadUtil::create(&handle2, attributes, threadFunction2, 0);
///
///      bslmt::ThreadUtil::join(handle1);
///      bslmt::ThreadUtil::join(handle2);
///
///      if (verbose) {  // 'if' to allow command-line activation
///          BALL_LOG_FATAL << "Force publication.";
///      }
///      return 0;
///  }
/// @endcode
/// When the above program is run with a command-line argument, causing the
/// 'e_FATAL' record to be logged and thus a "Trigger-All", the records from
/// thread 2 are not available to be published.  This is of course not an error
/// but desired behavior chosen by the programmer.  The output is as follows.
/// @code
///  27SEP2007_14:09:31.197 1615 3 WARN logging.m.cpp 29 Function 2 Message 0
///
///  27SEP2007_14:09:33.207 1615 3 WARN logging.m.cpp 29 Function 2 Message 1
///
///  27SEP2007_14:09:35.217 1615 3 WARN logging.m.cpp 29 Function 2 Message 2
///
///  27SEP2007_14:09:41.217 1615 1 FATAL logging.m.cpp 107 main Force publication.
///
///  27SEP2007_14:09:41.217 1615 1 FATAL logging.m.cpp 107 main Force publication.
///
///  27SEP2007_14:09:35.217 1615 3 WARN logging.m.cpp 29 Function 2 Message 2
///
///  27SEP2007_14:09:33.207 1615 3 WARN logging.m.cpp 29 Function 2 Message 1
///
///  27SEP2007_14:09:31.197 1615 3 WARN logging.m.cpp 29 Function 2 Message 0
/// @endcode
///
/// ## Usage: Advanced Features
///
///The following section shows examples of features used to customize the behavior
///and performance of the 'ball' logging system.  They might be used, for example,
///by a low-level infrastructure library where the trade-off of greater complexity
///would be justified.
///
/// ### Advanced Features Example 1: Rule-Based Logging
///
/// The following example demonstrates the use of attributes and rules to
/// conditionally enable logging.
///
/// We start by defining a function, 'processData', that is passed data in a
/// 'vector<char>' and information about the user who sent the data.  This
/// example function performs no actual processing, but does log a single
/// message at the 'ball::Severity::e_DEBUG' threshold level.  The 'processData'
/// function also adds the user information passed to this function to the
/// thread's attribute context.  We will use these attributes later, to create a
/// logging rule that enables verbose logging only for a particular user.
/// @code
///  void processData(int                      uuid,
///                   int                      luw,
///                   int                      terminalNumber,
///                   const bsl::vector<char>& data)
///      // Process the specified 'data' associated with the specified Bloomberg
///      // 'uuid', 'luw', and 'terminalNumber'.
///  {
///      (void)data;  // suppress "unused" warning
/// @endcode
/// We add our attributes using 'ball::ScopedAttribute', which adds an attribute
/// container with one attribute to a list of containers.  This is easy and
/// efficient if the number of attributes is small, but should not be used if
/// there are a large number of attributes.  If motivated, we could use
/// 'ball::DefaultAttributeContainer', which provides an efficient container for
/// a large number of attributes, or even create a more efficient attribute
/// container implementation specifically for these three attributes (uuid, luw,
/// and terminalNumber).  See {@ref ball_scopedattributes } (plural) for an example
/// of using a different attribute container, and {@ref ball_attributecontainer }
/// for an example of creating a custom attribute container.
/// @code
///      // We use 'ball::ScopedAttribute' here because the number of
///      // attributes is relatively small.
///
///      ball::ScopedAttribute uuidAttribute("mylibrary.uuid", uuid);
///      ball::ScopedAttribute luwAttribute("mylibrary.luw", luw);
///      ball::ScopedAttribute termNumAttribute("mylibrary.terminalNumber",
///                                             terminalNumber);
/// @endcode
/// In this simplified example we perform no actual processing, and simply log
/// a message at the 'ball::Severity::e_DEBUG' level.
/// @code
///      BALL_LOG_SET_CATEGORY("EXAMPLE.CATEGORY");
///
///      BALL_LOG_DEBUG << "An example message";
/// @endcode
/// Notice that if we were not using a "scoped" attribute container like that
/// provided automatically by 'ball::ScopedAttribute' (e.g., if we were using a
/// local 'ball::DefaultAttributeContainer' instead), then the container
/// **must** be removed from the 'ball::AttributeContext' before it is
/// destroyed!  See @ref ball_scopedattributes  (plural) for an example.
/// @code
///  }
/// @endcode
/// Next we demonstrate how to create a logging rule that sets the pass-through
/// logging threshold to 'ball::Severity::e_TRACE' (i.e., enables verbose logging)
/// for a particular user when calling the 'processData' function defined
/// above.
///
/// We start by creating the singleton logger manager that we configure with
/// the stream observer and a default configuration.  We then call the
/// 'processData' function: This first call to 'processData' will not result in
/// any logged messages because 'processData' logs its message at the
/// 'ball::Severity::e_DEBUG' level, which is below the default configured logging
/// threshold.
/// @code
///  int main(int argc, const char *argv[])
///  {
///      ball::LoggerManagerConfiguration configuration;
///      ball::LoggerManagerScopedGuard lmg(configuration);
///      ball::LoggerManager& manager = ball::LoggerManager::singleton();
///
///      bsl::shared_ptr<ball::StreamObserver> observer =
///          bsl::make_shared<ball::StreamObserver>(&bsl::cout);
///      manager.registerObserver(observer, "default");
///
///      BALL_LOG_SET_CATEGORY("EXAMPLE.CATEGORY");
///
///      bsl::vector<char> message;
///
///      BALL_LOG_ERROR << "Processing the first message.";
///      processData(3938908, 2, 9001, message);
///
/// @endcode
/// Now we add a logging rule, setting the pass-through threshold to be
/// 'ball::Severity::e_TRACE' (i.e., enabling verbose logging) if the thread's
/// context contains a "uuid" of 3938908.  Note that we use the wild-card
/// value '*' for the category so that the 'ball::Rule' rule will apply to all
/// categories.
/// @code
///      ball::Rule rule("*", 0, ball::Severity::e_TRACE, 0, 0);
///      rule.addAttribute(ball::ManagedAttribute("mylibrary.uuid", 3938908));
///      ball::LoggerManager::singleton().addRule(rule);
///
///      BALL_LOG_ERROR << "Processing the second message.";
///      processData(3938908, 2, 9001, message);
/// @endcode
/// The final call to the 'processData' function below, passes a "uuid" of
/// 2171395 (not 3938908) so the logging rule we defined will *not* apply and
/// no message will be logged.
/// @code
///      BALL_LOG_ERROR << "Processing the third message.";
///      processData(2171395, 2, 9001, message);
///  }
/// @endcode
/// The resulting logged output for this example looks like the following:
/// @code
/// ERROR example.cpp:105 EXAMPLE.CATEGORY Processing the first message.
/// ERROR example.cpp:117 EXAMPLE.CATEGORY Processing the second message.
/// DEBUG example.cpp:35 EXAMPLE.CATEGORY An example message
/// ERROR example.cpp:129 EXAMPLE.CATEGORY Processing the third message.
/// @endcode
/// Please see {Key Example 2: Initialization} to learn how scoped attributes can
/// be added to log messages to provide additional log context.
///
/// ### Advanced Features Example 2: Customizing Attribute Collection
///
/// This example demonstrates how to customize the collection of log attributes.
/// Attributes are typically associated with a log record using a
/// 'ball::ScopedAttribute' object (see {Key Example 1: Write to a Log} and
/// {Key Example 2: Initialization}).  However, advanced users can customize
/// the collection of attributes, either by registering an attribute-collector
/// callback with the 'ball::LoggerManager', or by creating their own
/// 'ball::AttributeCollector' implementation, or both.  These customizations
/// can be used to implement alternative behavior, or provide faster
/// implementation (e.g., by taking advantage of compile-time knowledge of the
/// attributes being recorded).
///
/// Suppose we are writing a performance critical infrastructure system
/// that processes requests.  We want to:
///
///  * Obtain a (very small) performance benefit by implementing our own
///    'ball::AttributeContainer (rather than using 'ball::ScopedAttribute').
/// 
///  * Install a separate attribute collector callback function, in this
///    instance one that will report information about global process state.
///
/// First we create a 'ball::AttributeContainer' implementation.  Although the
/// performance gains from doing so are typically insignificant, the use of a
/// context-specific attribute container object allows us to take advantage of
/// compile-time knowledge of the attributes being collected and make small
/// improvements in the overhead required, which may be important for
/// performance critical systems.
/// @code
///  // serviceattributes.h
///
///  class ServiceAttributes : public ball::AttributeContainer {
///      // Provide a concrete implementation of the 'ball::AttributeContainer'
///      // protocol that holds the 'uuid', 'luw', and 'firmId' associated with a
///      // request to the example service.
///
///      int d_uuid;
///      int d_luw;
///      int d_firmId;
///
///      // ...
///
///    public:
///      // CREATORS
///      ServiceAttributes(int uuid, int luw, int firmId);
///          // Create a service-attributes object with the specified 'uuid',
///          // 'luw', and 'firmId'.
///
///      virtual ~ServiceAttributes();
///
///      // ACCESSORS
///      virtual bool hasValue(const ball::Attribute& value) const;
///
///      virtual void visitAttributes(
///           const bsl::function<void(const ball::Attribute&)>& visitor) const;
///
///      virtual bsl::ostream& print(bsl::ostream& stream,
///                                  int           level = 0,
///                                  int           spacesPerLevel = 4) const;
///          // Format this object to the specified output 'stream'.
///  };
///
///  // CREATORS
///  inline
///  ServiceAttributes::ServiceAttributes(int uuid, int luw, int firmId)
///  : d_uuid(uuid)
///  , d_luw(luw)
///  , d_firmId(firmId)
///  {
///  }
///
///    // serviceattributes.cpp
///
///  // CREATORS
///  ServiceAttributes::~ServiceAttributes()
///  {
///  }
///
///  // ACCESSORS
///  bool ServiceAttributes::hasValue(const ball::Attribute& value) const
///  {
///      return ball::Attribute("mylibrary.uuid",    d_uuid)   == value
///          || ball::Attribute("mylibrary.luw",     d_luw)    == value
///          || ball::Attribute("mylibrary.firmId",  d_firmId) == value;
///  }
///
///  void ServiceAttributes::visitAttributes(
///      const bsl::function<void(const ball::Attribute&)>& visitor) const
///  {
///      visitor(ball::Attribute("mylibrary.uuid",   d_uuid));
///      visitor(ball::Attribute("mylibrary.luw",    d_luw));
///      visitor(ball::Attribute("mylibrary.firmId", d_firmId));
///  }
///
///  bsl::ostream& ServiceAttributes::print(bsl::ostream& stream,
///                                         int           level,
///                                         int           spacesPerLevel) const
///  {
///      bslim::Printer printer(&stream, level, spacesPerLevel);
///      printer.start();
///      printer.printAttribute("uuid", d_uuid);
///      printer.printAttribute("luw", d_luw);
///      printer.printAttribute("firmId", d_firmId);
///      printer.end();
///      return stream;
///  }
/// @endcode
/// Then we create a guard to add and remove a 'ServiceAttributes' container
/// from the current logging attribute context:
/// @code
///  class ServiceAttributesGuard {
///      // DATA
///      ServiceAttributes                      d_attributes;
///          // attributes
///
///      const ball::AttributeContext::iterator d_it;
///          // reference to attribute container
///
///    public:
///      ServiceAttributesGuard(int uuid, int luw, int firmId)
///      : d_attributes(uuid, luw, firmId)
///      , d_it(
///          ball::AttributeContext::getContext()->addAttributes(&d_attributes))
///      {
///      }
///
///      ~ServiceAttributesGuard()
///      {
///          ball::AttributeContext::getContext()->removeAttributes(d_it);
///      }
///  };
/// @endcode
/// Now we use a 'ServiceAttributesGuard' in a critical infrastructure
/// function:
/// @code
///  int processData(int  uuid, int luw, int firmId, const char *data)
///  {
///      BALL_LOG_SET_CATEGORY("MYLIBRARY.MYSUBSYSTEM");
///      ServiceAttributesGuard attributes(uuid, luw, firmId);
///
///      BALL_LOG_TRACE << "Processing data: " << data;
///
///      int rc = 0;
///
///      // ...
///
///      if (0 != rc) {
///          BALL_LOG_WARN << "Error processing data: " << data;
///      }
///      return rc;
///  }
/// @endcode
/// Notice that when 'processData' is called, attributes for 'uuid', 'luw', and
/// 'firmId' will be associated with each log message emitted during that
/// function call.
///
/// Next, we create a callback function that will be used to associate
/// a hostname attribute to each log record for the lifetime of the process:
/// @code
///  void loadHostnameAttribute(
///      const ball::LoggerManager::AttributeVisitor& visitor)
///  {
///      char hostname[256];
///      if (0!= gethostname(hostname, 256)) {
///          bsl::strcpy(hostname, "failed.to.get.hostname");
///      }
///      visitor(ball::Attribute("mylibrary.hostname", hostname));
///  }
/// @endcode
/// Finally we demonstrate a function that registers the
/// 'loadHostnameAttribute' with the logger manager:
/// @code
///  int configureLibrary()
///  {
///      ball::LoggerManager::singleton().registerAttributeCollector(
///            &loadHostnameAttribute, "mylibrary.hostnamecollector");
///
///      // ...
///  }
/// @endcode
/// Notice that the attribute "mylibrary.hostname" will now be associated with
/// every log message created (until "mylibrary.hostnamecollector" is unregistered
/// or the logger manager is destroyed).
///
/// ## Appendix: Macro Reference
///
/// This section documents the preprocessor macros defined in 'ball_log' that are
/// most commonly used.
///
/// The following two macros establish the logging context required by the other
/// macros.  A use of one of these two macros must be visible from within the
/// lexical scope where the C++ stream-based and 'printf'-style macros are used:
///
///  'BALL_LOG_SET_CATEGORY(CATEGORY)':
///    Set the category for logging to the specified 'CATEGORY' (assumed to be of
///    type convertible to 'const char *').  Note that this macro must be used at
///    block scope and can be used at most once in any given block (or else a
///    compiler diagnostic will result).  Also note that this macro invokes the
///    'ball::Log::setCategory' method to retrieve the address of an appropriate
///    category structure for its scope.  (See the function- level documentation
///    of 'ball::Log::setCategory' for more information.)  Also note that the
///    category is set only on the *first* invocation of this macro in a code
///    block; subsequent invocations will use a cached address of the category.
/// 
///  'BALL_LOG_SET_DYNAMIC_CATEGORY(CATEGORY)':
///    Set, *on each invocation*, the category for logging to the specified
///    'CATEGORY'.  This macro is identical to 'BALL_LOG_SET_CATEGORY' in scoping,
///    parameter, and use of the 'ball::Log::setCategory' method.  However, the
///    address returned from 'ball::Log::setCategory' is not cached for subsequent
///    calls.  Use this macro to create categories that depend on run-time values
///    (e.g., UUID).
///
/// The seven macros based on C++ streams, 'BALL_LOG_TRACE', 'BALL_LOG_DEBUG',
/// 'BALL_LOG_INFO', 'BALL_LOG_WARN', 'BALL_LOG_ERROR', and 'BALL_LOG_FATAL',
/// have the following usage pattern:
/// @code
///  BALL_LOG_TRACE << X << Y ...;
///  BALL_LOG_DEBUG << X << Y ...;
///  BALL_LOG_INFO  << X << Y ...;
///  BALL_LOG_WARN  << X << Y ...;
///  BALL_LOG_ERROR << X << Y ...;
///  BALL_LOG_FATAL << X << Y ...;
///      where X, Y, ... represents any sequence of values for which 'operator<<'
///      is defined.  The resulting formatted message string is logged with the
///      severity indicated by the name of the initial macro (e.g.,
///      'BALL_LOG_TRACE' logs with severity 'ball::Severity::e_TRACE').  Note
///      that the formatted string includes the category and filename as
///      established by the 'BALL_LOG_SET_CATEGORY' (or
///      'BALL_LOG_SET_DYNAMIC_CATEGORY') and '__FILE__' macros, respectively.
/// @endcode
/// The remaining macros are based on 'printf'-style format specifications:
/// @code
///  BALL_LOGVA_TRACE(MSG, ...);
///  BALL_LOGVA_DEBUG(MSG, ...);
///  BALL_LOGVA_INFO( MSG, ...);
///  BALL_LOGVA_WARN( MSG, ...);
///  BALL_LOGVA_ERROR(MSG, ...);
///  BALL_LOGVA_FATAL(MSG, ...);
///      Format the specified '...' optional arguments, if any, according to the
///      'printf'-style format specification in the specified 'MSG' (assumed to be
///      of type convertible to 'const char *') and log the resulting formatted
///      message string with the severity indicated by the name of the macro
///      (e.g., 'BALL_LOGVA_INFO' logs with severity 'ball::Severity::e_INFO').
///      The behavior is undefined unless the number and types of optional
///      arguments are compatible with the format specification in 'MSG'.  Note
///      that each use of these macros must be terminated by a ';'.
/// @endcode
///
/// @}
/** @} */