[#BloombergLP-ball-FileObserver2]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/ball.adoc[ball]::FileObserver2
:relfileprefix: ../../
:mrdocs:

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

== Synopsis

Declared in `&lt;ball&lowbar;fileobserver2&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class FileObserver2
    : public xref:BloombergLP/ball/Observer.adoc[Observer]
----

== Base Classes

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/ball/Observer.adoc[Observer]`
| This class provides a protocol for receiving and processing log record output&period;
|===

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/FileObserver2/LogRecordFunctor.adoc[`LogRecordFunctor`] 
| `LogRecordFunctor` is an alias for the type of the functor used for formatting log records to a stream&period;
| xref:BloombergLP/ball/FileObserver2/OnFileRotationCallback.adoc[`OnFileRotationCallback`] 
| `OnFileRotationCallback` is an alias for a user&hyphen;supplied callback function that is invoked after the file observer attempts to rotate its log file&period; The callback takes two arguments&colon; (1) an integer status value where 0 indicates a new log file was successfully created and a non&hyphen;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&period; E&period;g&period;&colon; &grave; void onLogFileRotation(int rotationStatus, const bsl&colon;&colon;string&amp; rotatedLogFileName)&semi; &grave;
| xref:BloombergLP/ball/FileObserver2/RecordFormatter.adoc[`RecordFormatter`] 
| `RecordFormatter` is an alias for the type of the functor used for formatting log records to a stream&period;
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/ball/FileObserver2/2constructor.adoc[`FileObserver2`]         [.small]#[constructor]#
| Create a file observer with file logging initially disabled&period; Optionally specify a `basicAllocator` used to supply memory&period; If `basicAllocator` is 0, the currently installed default allocator is used&period; Note that `isPublishInLocalTimeEnabled` returns `false` following construction indicating that the timestamp attribute of published records will be written in UTC time (see `enablePublishInLocalTime`)&period; Also note that a default record format is in effect for file logging (see `setLogFileFunctor`)&period;
| xref:BloombergLP/ball/FileObserver2/2destructor.adoc[`&#126;FileObserver2`] [.small]#[destructor]# [.small]#[virtual]#
| Close the log file of this file observer if file logging is enabled, and destroy this file observer&period;
| xref:BloombergLP/ball/FileObserver2/disableFileLogging.adoc[`disableFileLogging`] 
| Disable file logging for this file observer&period; This method has no effect if file logging is not enabled&period; Note that records subsequently received through the `publish` method will be dropped until file logging is re&hyphen;enabled&period;
| xref:BloombergLP/ball/FileObserver2/disableLifetimeRotation.adoc[`disableLifetimeRotation`] 
| Disable log file rotation based on a periodic time interval for this file observer&period; This method has no effect if rotation&hyphen;on&hyphen;time&hyphen;interval is not enabled&period;
| xref:BloombergLP/ball/FileObserver2/disablePublishInLocalTime.adoc[`disablePublishInLocalTime`] 
| Disable publishing of the timestamp attribute of records in local time by this file observer&semi; henceforth, timestamps will be in UTC time&period; This method has no effect if publishing in local time is not enabled&period; Note that this method also affects log filenames (see &lcub;Log Filename Patterns&rcub;)&period;
| xref:BloombergLP/ball/FileObserver2/disableSizeRotation.adoc[`disableSizeRotation`] 
| Disable log file rotation based on log file size for this file observer&period; This method has no effect if rotation&hyphen;on&hyphen;size is not enabled&period;
| xref:BloombergLP/ball/FileObserver2/disableTimeIntervalRotation.adoc[`disableTimeIntervalRotation`] 
| Disable log file rotation based on a periodic time interval for this file observer&period; This method has no effect if rotation&hyphen;on&hyphen;time&hyphen;interval is not enabled&period;
| xref:BloombergLP/ball/FileObserver2/enableFileLogging-0b.adoc[`enableFileLogging`] 
| `enableFileLogging` overloads
| xref:BloombergLP/ball/FileObserver2/enablePublishInLocalTime.adoc[`enablePublishInLocalTime`] 
| Enable publishing of the timestamp attribute of records in local time by this file observer&period; This method has no effect if publishing in local time is already enabled&period; Note that this method also affects log filenames (see &lcub;Log Filename Patterns&rcub;)&period;
| xref:BloombergLP/ball/FileObserver2/forceRotation.adoc[`forceRotation`] 
| Forcefully perform a log file rotation by this file observer&period; Close the current log file, rename the log file if necessary, and open a new log file&period; This method has no effect if file logging is not enabled&period; See &lcub;Rotated File Naming&rcub; for details on filenames of rotated log files&period;
| xref:BloombergLP/ball/FileObserver2/getFormat.adoc[`getFormat`] 
| Return the format config of the last successful `setFormat` call&period;
| xref:BloombergLP/ball/FileObserver2/isFileLoggingEnabled-00.adoc[`isFileLoggingEnabled`] 
| `isFileLoggingEnabled` overloads
| xref:BloombergLP/ball/FileObserver2/isPublishInLocalTimeEnabled.adoc[`isPublishInLocalTimeEnabled`] 
| Return `true` if this file observer writes the timestamp attribute of records that it publishes in local time, and `false` otherwise (in which case timestamps are written in UTC time)&period; Note that the value returned by this method also affects log filenames (see &lcub;Log Filename Patterns&rcub;)&period;
| xref:BloombergLP/ball/FileObserver2/isSuppressUniqueFileNameOnRotation.adoc[`isSuppressUniqueFileNameOnRotation`] 
| Return `true` if the log filename uniqueness check on rotation is suppressed, and false otherwise&period;
| xref:BloombergLP/ball/FileObserver2/localTimeOffset.adoc[`localTimeOffset`] 
| Return the difference between the local time and UTC time in effect when this file observer was constructed&period; 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&period;g&period;, when transitioning into or out of daylight savings time)&period;
| xref:BloombergLP/ball/FileObserver2/publish-09.adoc[`publish`] 
| `publish` overloads
| xref:BloombergLP/ball/FileObserver2/releaseRecords.adoc[`releaseRecords`]  [.small]#[virtual]#
| Discard any shared references to `Record` objects that were supplied to the `publish` method, and are held by this observer&period; Note that this operation should be called if resources underlying the previously provided shared pointers must be released&period;
| xref:BloombergLP/ball/FileObserver2/rotateOnLifetime.adoc[`rotateOnLifetime`] 
| Set this file observer to perform a periodic log file rotation at multiples of the specified `timeInterval`&period; This rule replaces any rotation&hyphen;on&hyphen;time&hyphen;interval rule currently in effect&period; The behavior is undefined unless `0 &lt; timeInterval&period;totalMilliseconds()`&period;
| xref:BloombergLP/ball/FileObserver2/rotateOnSize.adoc[`rotateOnSize`] 
| Set this file observer to perform log file rotation when the size of the file exceeds the specified `size` (in kilobytes)&period; This rule replaces any rotation&hyphen;on&hyphen;size rule currently in effect&period; The behavior is undefined unless `size &gt; 0`&period;
| xref:BloombergLP/ball/FileObserver2/rotateOnTimeInterval-0b.adoc[`rotateOnTimeInterval`] 
| `rotateOnTimeInterval` overloads
| xref:BloombergLP/ball/FileObserver2/rotationLifetime.adoc[`rotationLifetime`] 
| Return the lifetime of the log file that will trigger a file rotation by this file observer if rotation&hyphen;on&hyphen;lifetime is in effect, and a 0 time interval otherwise&period;
| xref:BloombergLP/ball/FileObserver2/rotationSize.adoc[`rotationSize`] 
| Return the size (in kilobytes) of the log file that will trigger a file rotation by this file observer if rotation&hyphen;on&hyphen;size is in effect, and 0 otherwise&period;
| xref:BloombergLP/ball/FileObserver2/setFormat.adoc[`setFormat`] 
| Set the formatting functor used when writing records to the log file of this file observer to a log file functor created according to the specified, possibly URI&hyphen;like scheme tagged, `format`&period; Return zero if the setup with the specified arguments was successful and also save the `format` to be later retrievable using `getFormat`&period; Otherwise (if no matching scheme could be found or the configuration is invalid) return a non&hyphen;zero value and do not change the log record formatter used by this object&period; Note that a default format (&quot;n%d %p&colon;%t %s %f&colon;%l %c %m %un&quot;) is in effect until this method or `setLogFileFunctor` is called&period; Also, notice that the observer 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&period;
| xref:BloombergLP/ball/FileObserver2/setLogFileFunctor.adoc[`setLogFileFunctor`] 
| Set the formatting functor used when writing records to the log file of this file observer to the specified `logFileFunctor`&period; Note that a default format (&quot;n%d %p&colon;%t %s %f&colon;%l %c %m %un&quot;) is in effect until this method or `setFormat` is called&period; Also, notice that the observer 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&period; Note that this method exists for backwards compatibility and new code is highly encouraged to make use of `setFormat` with the URI&hyphen;scheme&hyphen;like tags to create different formatters&period; (Currently string and JSON output format is supported&period;)
| xref:BloombergLP/ball/FileObserver2/setOnFileRotationCallback.adoc[`setOnFileRotationCallback`] 
| Set the specified `onRotationCallback` to be invoked after each time this file observer attempts to perform a log file rotation&period; The behavior is undefined if the supplied function calls either `setOnFileRotationCallback`, `forceRotation`, or `publish` on this file observer (i&period;e&period;, the supplied callback should _not_ attempt to write to the `ball` log)&period;
| xref:BloombergLP/ball/FileObserver2/suppressUniqueFileNameOnRotation.adoc[`suppressUniqueFileNameOnRotation`] 
| Suppress generating a unique log file name upon rotation if the specified `suppress` is `true`, and generate a unique filename otherwise&period; See &lcub;Rotated File Naming&rcub; for details&period;
| xref:BloombergLP/ball/FileObserver2/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration&lt;FileObserver2, UsesBslmaAllocator&gt;`] 
| Declare that this type uses a `bslma` allocator&period;
|===



[.small]#Created with https://www.mrdocs.com[MrDocs]#
