Loggers

A Logger instance is the primary way in which an application developer interacts with LogKit. This object is responsible for receiving Log Entries and distributing them to its Endpoints. Generally, a Logger instance is created once, at application load time, and used throughout the life of the application. LogKit includes the LXLogger class which fulfills this function, and is not meant to be subclassed.

Usage

Initializers

See the usage documentation for practical tips on initializing a Logger. A typical Logger instance is created at the global level so that the application developer may make logging calls from all source files within a project.

Also see the Endpoints documentation for information regarding the various Endpoints provided with LogKit, and their initialization options.

The following initializers are available for LXLogger:

init(endpoints: [LXEndpoint?])

Returns an initialized and ready Logger instance populated with each of the provided Endpoints. Any Endpoints that fail initialization are discarded immediately.

convenience init()

Returns an initialized and ready Logger instance. This Logger instance is populated with a standard Console Endpoint, configured to write Entries of all Priority Levels with the default date and Entry formatters.

Logging Methods

LXLogger instances offer the following methods for logging within an application:

func debug(_ message: String, userInfo: [String: AnyObject] = [:])

func info(_ message: String, userInfo: [String: AnyObject] = [:])

func notice(_ message: String, userInfo: [String: AnyObject] = [:])

func warning(_ message: String, userInfo: [String: AnyObject] = [:])

func error(_ message: String, userInfo: [String: AnyObject] = [:])

func critical(_ message: String, userInfo: [String: AnyObject] = [:])

In each case, the userInfo parameter may be omitted. If omitted, userInfo will default to an empty dictionary.

Note: Although the message parameter in the Logger methods above appear to accept Strings, they are actually captured as autoclosures for performance reasons. Specifically, message type is @autoclosure(escaping) message: () -> String. Developers should treat the message parameter as a String, but be aware that their message will be resolved lazily, and only if the Log Entry meets at least one Endpoint’s minimum Priority Level requirements.

Defaults

A keen observer of the method signatures for each of the above logging methods may note that there are additional parameters included in each method (as seen in Xcode or CocoaDocs). These parameters are functionName, filePath, lineNumber, and columnNumber. They are not mentioned above because they are meant to be ignored.

Each of these parameters will default to special Swift variables that automatically capture the function name, file name, line number, and column number of the code from which each of your Log Entries was created. Application developers should omit these parameters from their logging calls, allowing LogKit to correctly capture the scope of each call and save it in the Log Entry.

userInfo

Each logging method above has an optional userInfo parameter. userInfo provides the application developer with an opportunity to customize their logging calls. Any userInfo included in a logging call is captured as part of the Log Entry and made available to each of the Logger’s Endpoints, specifically during Entry formatting.

Endpoints may use userInfo in a variety of ways. In one example, a developer could provide one or more additional objects in userInfo that an Endpoint can later include in its Entry Formatter for output as part of a serialized Log Entry. In another example, additional state could be included in userInfo that affects control flow during Entry formatting.

See Customizing Entry Properties for examples of using userInfo in logging calls.