The LXRotatingFileEndpoint writes Log Entries to a rotating group of files. Developers can specify the number of files to use, and the maximum size a file can reach.

At initialization time, the specified URL will be used to create a group of files, each prepended with an index number. Before writing each Entry, the Endpoint will check if the current file has reached its maximum size, and if so, will rotate to the next file before writing. Each time the Endpoint rotates, it clears the newly selected file and starts from its beginning.

The Rotating File Endpoint is safe to be used in environments featuring concurrency. This Endpoint does some of its work asynchronously to allow better logging performance. Because the Rotating File Endpoint takes advantage of asynchronous technologies, Log Entries written to this Endpoint may not appear until slightly after execution has moved on. In other words, if your application attempts to create a Log Entry directly before it crashes, it may not be delivered before the crash occurs. While debugging your application, if the asynchronous nature of this Endpoint is problematic, consider using a synchronous Console Endpoint in addition.

Usage

Initializers

The following initializers are available for LXRotatingFileEndpoint:

init?(baseURL: numberOfFiles: maxFileSizeKiB: minimumPriorityLevel: dateFormatter: entryFormatter: )

Parameters

baseURL Type: NSURL?
Default: see below		 The URL used to build the rotating file set’s file URLs; see description below
numberOfFiles Type: UInt
Default: 5		 The number of files to be used in the rotation
maxFileSizeKiB Type: UInt?
Default: 1024		 The maximum file size of each file in the rotation, specified in kilobytes
minimumPriorityLevel Type: LXPriorityLevel
Default: .All		 The minimum Priority Level a Log Entry must meet to be accepted by this Endpoint
dateFormatter Type: LXDateFormatter
Default: .standardFormatter()		 The formatter used by this Endpoint to serialize a Log Entry’s dateTime property to a string
entryFormatter Type: LXEntryFormatter
Default: .standardFormatter()		 The formatter used by this Endpoint to serialize each Log Entry to a string

This Endpoint writes Log Entries to a set of files specified by baseURL, with each file’s name automatically prepended with an index number indicating its place in the rotation. If the specified file cannot be opened, or if the index-prepended URL evaluates to nil, the initializer may fail.

If omitted, the URL defaults to {AppSupport}/{bundleID}/logs/{number}_log.txt, where {AppSupport} is the system-determined Application Support directory, {bundleID} is the host application’s bundleIdentifier string, and {number} is the index of the currently selected file.

As an example, if an LXRotatingFileEndpoint is initialized with its default parameter values, it will create a set of files in Application Support/{bundleID}/logs/ named 1_log.txt, 2_log.txt, 3_log.txt, 4_log.txt, and 5_log.txt.

If maxFileSizeKiB is nil, the Endpoint will not automatically rotate log files. See Manual Rotation below for information on manually prompting the Endpoint to rotate files.

Returns an initialized Rotating File Endpoint instance if successful, or nil if the file cannot be accessed.

Manual Rotation

New in 2.3

LXRotatingFileEndpoint instances include a rotate() method that will cause the Endpoint to attempt to rotate to its next log file. If, for whatever reason, the Endpoint cannot open the next file in its rotation, it will continue to use the current log file.

Manual log file rotation will trigger the expected rotation notifications, identical to automatic rotation.

Notifications

LXRotatingFileEndpoint instances will post notifications before and after they rotate log files.

Before rotating files, the instance will post a LXFileEndpointWillRotateFilesNotification notification. The notification’s object is the actual Endpoint instance that is rotating files. The userInfo dictionary contains the current and next URLs, at the LXFileEndpointRotationCurrentURLKey and LXFileEndpointRotationNextURLKey keys, respectively.

After rotating files, the instance will post a LXFileEndpointDidRotateFilesNotification notification. The notification’s object is the actual Endpoint instance that is rotating files. The userInfo dictionary contains the current and previous URLs, at the LXFileEndpointRotationCurrentURLKey and LXFileEndpointRotationPreviousURLKey keys, respectively.

All notifications are posted to the default notification center.

Note: Developers should not modify the log file currently in use by the Endpoint.