- Generated by
1.9.8
|
BDE 4.39.x Production Release
|
Provide a thread-safe observer that logs to a file and to stdout.
Provide a thread-safe observer that logs to a file and to stdout.
stdoutThis component provides a concrete implementation of the ball::Observer protocol, ball::FileObserver, for publishing log records to stdout and, optionally, to a user-specified file. The following inheritance hierarchy diagram shows the classes involved and their methods:
A ball::FileObserver object processes the log records received through its publish method by writing them to stdout and, if so configured, to a user-specified file. The format of published log records is user-configurable for both destinations, stdout and file (see {Log Record Formatting} below). Although logging to a file is initially disabled following construction, the most common use-case for ball::FileObserver is to also log to a file, enabled by calling the enableFileLogging method. In addition, a file observer may be configured to perform automatic log file rotation (see {Log File Rotation} below).
ball::FileObserver offers several constructor arguments and manipulators that may be used to configure various aspects of a file observer object. These are summarized in the following tables along with the accessors that can be used to query the current state of the configuration. Further details are provided in the following sections and the function-level documentation.
In general, a ball::FileObserver object can be dynamically configured throughout its lifetime (in particular, before or after being registered with a logger manager). However, note that for ball::FileObserver, configuration changes that affect how records are logged (e.g., enablePublishInLocalTime and disablePublishInLocalTime) impact only those records that are published subsequent to making the configuration change.
By default, the output format of published log records, whether written to stdout or to a user-specified file, is:
where DATE and TIME are of the form DDMonYYYY and HH:MM:SS.mmm, respectively (Mon being the 3-letter abbreviation for the month). For example, a log record will have the following appearance when the default format is in effect (assuming that no user-defined fields are present):
The default format for records published to stdout (only) can be shortened by calling disableStdoutLoggingPrefix. This method has the effect of reducing the above example message to the following when output to stdout:
For additional flexibility, the setFileLogFormat and setStdoutLogFormat methods can be called to independently configure the format of published records to a file and to stdout, respectively. The format specifications can be either scheme-tagged (recommended) or legacy printf-style format strings that results in a RecordStringFormatter being used.
The recommended way to specify log record formats is using URI-like scheme-tagged format configuration strings. A scheme-tagged format string begins with a scheme identifier followed by :// and then a scheme-specific format specification:
The scheme determines which formatter will be used and the syntax of the format specification. The following schemes are currently supported: text, json, qjson. See Scheme-Based Formatters for more details of the supported schemes and their accompanying format specification syntaxes.
For example, to log records to a file in JSON format with printf-style format specification, and to stdout using text format with ISO 8601 timestamps:
Note that both text:// and qjson:// schemes support printf-style % specifications in their format strings, though with different output structures (plain text vs. JSON).
For backward compatibility, format specifications that do not begin with a scheme tag are treated as legacy printf-style format strings. Such specifications are implicitly treated as if they had a text:// prefix and use ball::RecordStringFormatter. For example, the following two calls are equivalent:
These %-prefixed conversion specifications are defined in ball_recordstringformatter .
The setLogFormat method sets both file and stdout formats at once. Using setFileLogFormat and setStdoutLogFormat is preferred to set formats independently for file and stdout output:
When a format is set using setLogFormat, calling disableStdoutLoggingPrefix will change the stdout format to the default short format (i.e., "\n%s %f:%l %c %m %u\n"), regardless of whether the original format was specified as a printf-style format string or a scheme-based formatter. If enableStdoutLoggingPrefix is subsequently called, the format specified in the most recent call to setLogFormat will be reinstated, preserving the original formatter type (string-based or scheme-based).
By default, the timestamp attributes of published records are written in UTC time (unless true is supplied for the optional publishInLocalTime constructor flag). To write timestamps in local time instead, call the enablePublishInLocalTime method. Note that the local time offset is calculated using the UTC timestamp of each record. To revert to UTC time, call the disablePublishInLocalTime method. Whether UTC time or local time is in effect can be queried via isPublishInLocalTimeEnabled.
The calculation of the local time offset adds some overhead to the publication of each log record. If this overhead is an issue, it can be mitigated by installing a high-performance local-time offset callback for bdlt::CurrentTime in main. See bsls_systemtime for the details of installing such a callback and see baltzo_localtimeoffsetutil for an example facility. Note that such callbacks can improve performance for all users of bdlt::CurrentTime, not just the ball logger.
The enableFileLogging method supports the use of %-escape sequences to specify log filenames. The recognized sequences are as follows:
The date and time elements of the derived filename are based on the time when the log file is created. Furthermore, these elements are based on either UTC time or local time depending on the value returned by isPublishInLocalTimeEnabled. (See {Log Record Timestamps} for the similarity with the treatment of record timestamps.)
For example, a log filename pattern of "task.log.%Y%M%D_%h%m%s" will yield the filename task.log.20110501_123000 if the file is created on 01-May-2011 at 12:30:00 local time (assuming enablePublishInLocalTime was called).
A ball::FileObserver may be configured to perform automatic rotation of log files based on simple file rotation conditions (or rules).
Rotation rules may be established based on the size of the log file (i.e., a "rotation-on-size" rule), and a periodic time interval (i.e., a "rotation-on-time-interval" rule). These rules are independently enabled by the rotateOnSize and rotateOnTimeInterval methods, respectively. If both rules are in effect, log file rotation is performed whenever either rule applies.
When a log file is rotated, a new filename is generated using the pattern supplied to enableFileLogging. If the file having the new name does not exist, the current log file is closed, and the logging continues to the new file.
If the file having the new name already exists, then the behavior of the file rotation is further controlled by the flag set with suppressUniqueFileNameOnRotation:
suppressUniqueFileNameOnRotation(false) (default behavior) The current log filename is renamed by appending a timestamp in the form ".%Y%M%D_%h%m%s" where the timestamp indicates when the file being rotated was last opened (the time of either the last file rotation or the last call to enableFileLogging, whichever is most recent). As with the timestamps of logged records, the timestamps appended to log filenames upon rotation will be in UTC time or local time depending on the value returned by isPublishInLocalTimeEnabled.suppressUniqueFileNameOnRotation(true) The logging continues to the current log file, effectively suppressing log filename rotation. This may happen when the log file pattern does not contain %-escape sequences indicating a time period, or the rotation interval is less than the time period encoded by %-escape sequences. In order to rotate log files in this mode, the log file pattern MUST contain %-escape sequences that specify date and (optionally) time. For example, the log filename pattern "app_%Y%M%D.log" will produce a single log file per calendar day (assuming, the rotation on time is enabled and the rotation happens at least once a day).The two tables below illustrate the names of old and new log files when a file rotation occurs. We assume that the log file is rotated on 2011-May-21 at 12:29:59 local time and that the last rotation occurred at 12:30:00 on the previous day. We further assume that enablePublishInLocalTime was called, so that all date and time elements are rendered in local time.
The first table shows the name change (if any) of the (old) log file being rotated when the flag controlled by suppressUniqueFileNameOnRotation is set to false:
Note that upon rotation a timestamp was appended to the name of the rotated file when the log pattern does not contain %-escape sequences indicating a time period ("a.log"), or the rotation period (in our case, one day) is less than the time period encoded in the pattern (in case of "a.log.%Y%M" the period is one month).
The next table shows the rotated name when the flag controlled by suppressUniqueFileNameOnRotation is set to true, and (possibly new) name of the (new) log file following rotation:
Note that the original filename is reused when the log pattern does not contain %-escape sequences indicating a time period ("a.log"), or the rotation period (in our case, one day) is less than the time period encoded in the pattern (in case of "a.log.%Y%M" the period is one month).
Also note, that in any cases, when the log pattern includes "%T", or encodes a time period that coincides the rotation period (in case of "a.log.%Y%M%D" the period is one day), then a unique name on each rotation is produced with the (local) time at which file rotation occurred embedded in the filename.
All methods of ball::FileObserver are thread-safe, and can be called concurrently by multiple threads.
This section illustrates intended use of this component.
First, we create a ball::LoggerManagerConfiguration object, lmConfig, and set the logging "pass-through" level – the level at which log records are published to registered observers – to DEBUG:
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:
Next, we create a ball::FileObserver object and register it with the ball logging system;
The default format for outputting log records can be changed by calling the setFileLogFormat and setStdoutLogFormat methods. The statements below output record timestamps in ISO 8601 format to the log file and in bdlt-style (default) format to stdout, where timestamps are output with millisecond precision in both cases:
Note that both of the above format specifications omit user fields ("%u") in the output. Also note that, unlike the default, this format does not emit a blank line between consecutive log messages.
Henceforth, all messages that are published by the logging system will be transmitted to the publish method of observer. By default, only the messages with a e_WARN, e_ERROR, or e_FATAL severity will be logged to stdout:
This default can be changed by specifying an optional argument to the ball::FileObserver constructor or by calling the setStdoutThreshold method:
The user can log all messages to a specified file and specify rotation rules based on the size of the log file or its lifetime:
Note that in this configuration the user may end up with multiple log files for any given day (because of the rotation-on-size rule). This feature can be disabled dynamically later:
1.9.8