This class implements the Observer protocol. The publish method of this class outputs the log records that it receives to stdout and optionally to a user‐specified file. This class is thread‐safe; different threads can operate on an object concurrently. This class is exception‐neutral with no guarantee of rollback. In no event is memory leaked.

Synopsis

Declared in <ball_fileobserver.h>

class FileObserver
    : public Observer

Base Classes

Name

Description

Observer

This class provides a protocol for receiving and processing log record output.

Type Aliases

Name

Description

OnFileRotationCallback

OnFileRotationCallback is an alias for a user‐supplied callback function that is invoked after the file observer attempts to rotate its log file. The callback takes two arguments: (1) an integer status value where 0 indicates a new log file was successfully created and a non‐zero value indicates an error occurred during rotation, and (2) a string that provides the name of the rotated log file if the rotation was successful. E.g.: ` void onLogFileRotation(int rotationStatus, const bsl::string& rotatedLogFileName); `

Member Functions

Name

Description

FileObserver [constructor]

Constructors

~FileObserver [destructor] [virtual]

Close the log file of this file observer if file logging is enabled, and destroy this file observer.

allocator

Return the memory allocator used by this object.

disableFileLogging

Disable file logging for this file observer. This method has no effect if file logging is not enabled. Note that records subsequently received through the publish method of this file observer may still be logged to stdout after calling this method.

disableLifetimeRotation

Disable log file rotation based on a periodic time interval for this file observer. This method has no effect if rotation‐on‐time‐interval is not enabled.

disablePublishInLocalTime

Disable publishing of the timestamp attribute of records in local time by this file observer; henceforth, timestamps will be in UTC time. This method has no effect if publishing in local time is not enabled. Note that this method also affects log filenames (see {Log Filename Patterns}).

disableSizeRotation

Disable log file rotation based on log file size for this file observer. This method has no effect if rotation‐on‐size is not enabled.

disableStdoutLoggingPrefix

Disable this file observer from using the long output format when logging to stdout. Henceforth, this file observer will use the default short output format ("n%s %f:%l %c %m %un") when logging to stdout. This method has no effect if the long output format for stdout logging is not enabled. Note that this method omits the "%d %p:%t " prefix from the default long output format.

disableTimeIntervalRotation

Disable log file rotation based on a periodic time interval for this file observer. This method has no effect if rotation‐on‐time‐interval is not enabled.

disableUserFieldsLogging [deprecated]

Disable the logging of user‐defined fields by this file observer. This method has no effect if logging of user‐defined fields is not enabled, or if a format string other than the default one is in effect.

enableFileLogging

enableFileLogging overloads

enablePublishInLocalTime

Enable publishing of the timestamp attribute of records in local time by this file observer. This method has no effect if publishing in local time is already enabled. Note that this method also affects log filenames (see {Log Filename Patterns}).

enableStdoutLoggingPrefix

Enable this file observer to use the long output format when logging to stdout. Henceforth, this file observer will use the output format for stdout logging that was set by the most recent call to setLogFormat, or the default long output format ("n%d %p:%t %s %f:%l %c %m %un") if setLogFormat has not yet been called. This method has no effect if the long output format for stdout logging is already enabled.

enableUserFieldsLogging [deprecated]

Enable the logging of user‐defined fields by this file observer. This method has no effect if logging of user‐defined fields is already enabled, or if a format string other than the default one is in effect.

forceRotation

Forcefully perform a log file rotation by this file observer. Close the current log file, rename the log file if necessary, and open a new log file. This method has no effect if file logging is not enabled. See {Rotated File Naming} for details on filenames of rotated log files.

getFileLogFormat

Return the format specification for log records written to the log file by this file observer. See {Log Record Formatting} for details on the syntax of format specifications.

getLogFormat

Load the format specification for log records written by this file observer to the log file into the specified *logFileFormat address and the format specification for log records written to stdout into the specified *stdoutFormat address. See {Log Record Formatting} for details on the syntax of format specifications.

getStdoutLogFormat

Return the format specification for log records written to stdout by this file observer. See {Log Record Formatting} for details on the syntax of format specifications.

isFileLoggingEnabled

isFileLoggingEnabled overloads

isPublishInLocalTimeEnabled

Return true if this file observer writes the timestamp attribute of records by default in local time, and false otherwise (in which case timestamps are written in UTC time by default). Note that the value returned by this method also affects log filenames (see {Log Filename Patterns}).

isStdoutLoggingPrefixEnabled

Return true if this file observer uses the long output format when writing to stdout, and false otherwise (in which case the default short output format is used). See enableStdoutLoggingPrefix and disableStdoutLoggingPrefix.

isSuppressUniqueFileNameOnRotation

Return true if the log filename uniqueness check on rotation is suppressed, and false otherwise.

isUserFieldsLoggingEnabled [deprecated]

Return true if the logging of user‐defined fields is enabled for this file observer, and false otherwise.

localTimeOffset

Return the difference between the local time and UTC time in effect when this file observer was constructed. Note that this value remains unchanged during the lifetime of this object and therefore may become incorrect when the difference between the local time and UTC time changes (e.g., when transitioning into or out of daylight savings time).

publish

publish overloads

releaseRecords [virtual]

Discard any shared references to Record objects that were supplied to the publish method, and are held by this observer. Note that this operation should be called if resources underlying the previously provided shared pointers must be released.

rotateOnLifetime

Set this file observer to perform a periodic log file rotation at multiples of the specified timeInterval. The behavior is undefined unless 0 < timeInterval.totalMilliseconds(). This rule replaces any rotation‐on‐time‐interval rule currently in effect.

rotateOnSize

Set this file observer to perform log file rotation when the size of the file exceeds the specified size (in kilobytes). This rule replaces any rotation‐on‐size rule currently in effect. The behavior is undefined unless size > 0.

rotateOnTimeInterval

rotateOnTimeInterval overloads

rotationLifetime

Return the lifetime of the log file that will trigger a file rotation by this file observer if rotation‐on‐lifetime is in effect, and a 0 time interval otherwise.

rotationSize

Return the size (in kilobytes) of the log file that will trigger a file rotation by this file observer if rotation‐on‐size is in effect, and 0 otherwise.

setFileLogFormat

Set the format specifications for log records written to the log file to logFileFormat. See {Log Record Formatting} for details on the syntax of format specifications. Return zero if the format is valid and the corresponding formatter has been set. Otherwise, if the format is invalid, return a non‐zero value and do not change the formatter. Note that default format is in effect following construction until a format‐setting method is called ("n%d %p:%t %s %f:%l %c %m %un" for both file and stdout logging).

setLogFormat

Same as setLogFormats.

setLogFormats

Set the format specifications for log records written to the log file and to stdout to the specified logFileFormat and stdoutFormat, respectively. If the default short output format is currently in effect for logging to stdout, this method has the effect of calling enableStdoutLoggingPrefix (see that method and disableStdoutLoggingPrefix) and setting the format corresponding to enabled stdout logging prefix to stdoutFormat. See {Log Record Formatting} for details on the syntax of format specifications. Return zero if both formats are valid and have been set. Otherwise, if either format is invalid, return a non‐zero value. If one of the formats is invalid, it will not be set, but the valid format will be set. Note that default formats are in effect following construction until a format‐setting method is called ("n%d %p:%t %s %f:%l %c %m %un" for both file and stdout logging). Also note that the default format emits newline characters at the beginning and at the end of a log record by default, so the user needs to add them explicitly to (text) format strings to preserve that behavior.

setOnFileRotationCallback

Set the specified onRotationCallback to be invoked after each time this file observer attempts to perform a log file rotation. The behavior is undefined if the supplied function calls either setOnFileRotationCallback, forceRotation, or publish on this file observer (i.e., the supplied callback should not attempt to write to the ball log).

setStdoutLogFormat

Set the format specifications for log records written to stdout to stdoutFormat. If the default short output format is currently in effect (for logging to stdout) this method has the effect of calling enableStdoutLoggingPrefix (see that method and disableStdoutLoggingPrefix) and setting the format corresponding to enabled stdout logging prefix to stdoutFormat. See {Log Record Formatting} for details on the syntax of format specifications. Return zero if the format is valid and the corresponding formatter has been set. Otherwise, if the format is invalid, return a non‐zero value and do not change the formatter. Note that default format is in effect following construction until a format‐setting method is called ("n%d %p:%t %s %f:%l %c %m %un" for both file and stdout logging).

setStdoutThreshold

Set the minimum severity of records logged to stdout by this file observer to the specified stdoutThreshold level. Note that if the value of stdoutThreshold is Severity::e_OFF, logging to stdout is disabled.

stdoutThreshold

Return the minimum severity of records that will be logged to stdout by this file observer. Note that records with a threshold less severe than stdoutThreshold() may still be output to the log file if file logging is enabled.

suppressUniqueFileNameOnRotation

Suppress generating a unique log file name upon rotation if the specified suppress is true, and generate a unique filename otherwise. See {Rotated File Naming} for details.

operator BloombergLP::bslmf::NestedTraitDeclaration<FileObserver, UsesBslmaAllocator>

Declare that this type uses a bslma allocator.

Created with MrDocs