Entry Formatting

In LogKit, Log Entries go from LXLogEntry to string by using each target Endpoint’s formatters. Every Endpoint has its own formatters, so different Endpoints can output Entries in different formats. For example, an application using both a Console Endpoint and a File Endpoint could choose concise formatters for the console, and more detailed formatters for the file.

An Endpoint requires two formatters to convert each Log Entry to a string. The Endpoint’s dateFormatter describes how an Entry’s dateTime property will be converted. Its entryFormatter describes how the Entry itself will be converted. Using the Endpoint’s formatters, each LXLogEntry is converted to a string before the Endpoint writes it to its final destination.

Although the formatters of each Endpoint may be customized, all Endpoints include sensible defaults that will suit most developer’s needs. If desired, however, a developer can choose to use another of the variety of date and Entry formatters included with LogKit, or even create and use their own.

Date Formatters

Date formatting is handled by the LXDateFormatter object.

Built-in Date Formatters

LXDateFormatter comes with the following built-in presets:

Default Date Formatter

Unless otherwise specified by a specific Endpoint’s documentation, when the dateFormatter initialization parameter is omitted, the Endpoint will be initialized with the .standardFormatter() date formatter.

Custom Date Formatters

LogKit makes creating custom date formatters easy. The LXDateFormatter object comes with the following initializer:

init(formatString: timeZone: )

Parameters

The formatString parameter requires a string in the same format as Apple’s NSDateFormatter.dateFormat parameter. If omitted, the formatter will use the UTC timezone for its timeZone parameter. UTC is recommended for most applications, as it makes it easy to compare datetimes from different systems in different locations.

Returns an initialized LXDateFormatter instance.

Example: The following creates a date formatter that outputs only the hour and minute of a Log Entry’s dateTime in the user’s local time zone:

LXDateFormatter(formatString: "HH:mm", timeZone: NSTimeZone.localTimeZone())

A note about precision:

Although LogKit captures timestamps with microsecond precision, LXDateFormatter always rounds to the nearest millisecond. If your application requires microsecond precision, you should customize your Endpoint’s entryFormatter to display each Entry’s timestamp property, which retains microsecond precision.

Using a Date Formatter

To use a date formatter, simply supply it to the Endpoint you are initializing using the dateFormatter parameter. Some examples:

// Using a built-in date formatter:
LXConsoleEndpoint(dateFormatter: LXDateFormatter.timeOnlyFormatter())

// Using a custom date formatter:
LXConsoleEndpoint(dateFormatter: LXDateFormatter(formatString: "HH:mm:ss.SSS"))

// Omit the dateFormatter parameter to use an Endpoint's default date formatter:
LXConsoleEndpoint()

Entry Formatters

Log Entry formatting is handled by the LXEntryFormatter object.

Built-in Entry Formatters

LXEntryFormatter includes the following built-in presets:

.standardFormatter()        // Converts LXLogEntry objects into strings in a standard format that contains basic debugging information
"dateTime [LEVEL] functionName <fileName:lineNumber> message"

.longFormatter()            // Converts LXLogEntry objects into strings in a long format that contains detailed debugging information
"dateTime (timestamp) [LEVEL] {thread: id name isMain} functionName <fileName:lineNumber.columnNumber> message"

.shortFormatter()           // Converts LXLogEntry objects into strings in a short format that contains minimal information
"dateTime [LEVEL] message"

.messageOnlyFormatter()     // Converts LXLogEntry objects into strings in a short format that contains only the logged message
"message"

Default Entry Formatter

Unless otherwise specified by a specific Endpoint’s documentation, when the entryFormatter initialization parameter is omitted, the Endpoint will be initialized with the .standardFormatter() Entry formatter.

Custom Entry Formatters

LogKit makes creating custom Entry formatters easy. The LXEntryFormatter object comes with the following initializer:

init(_: )

The initializer takes only one parameter - a closure of type (LXLogEntry) -> String. This closure must accept an LXLogEntry and return a String. The closure is free to use as many or as few of a Log Entry’s properties as the developer wishes.

Returns an initialized LXEntryFormatter instance.

Example: The following creates a concise Entry formatter that outputs only a Log Entry’s dateTime and message:

LXEntryFormatter({ entry in return "\(entry.dateTime) \(entry.message)" })

Example: The following creates a detailed Entry formatter that outputs an Entry’s timestamp, level, and detailed information regarding location of the function that generated the message, as well as the message itself:

LXEntryFormatter({ entry in return "\(entry.timestamp) [\(entry.level.uppercaseString)] \(entry.functionName) <\(entry.fileName):\(entry.lineNumber).\(entry.columnNumber)> \(entry.message)" })

Using an Entry Formatter

To use an Entry formatter, simply provide it to the Endpoint you are initializing using the entryFormatter parameter. Some examples:

// Using a built-in Entry formatter:
LXConsoleEndpoint(entryFormatter: LXEntryFormatter.shortFormatter())

// Using a custom Entry formatter:
LXConsoleEndpoint(entryFormatter: LXEntryFormatter({ entry in return "\(entry.dateTime) \(entry.message)" }))

// Omit the entryFormatter parameter to use an Endpoint's default Entry formatter:
LXConsoleEndpoint()

Customizing Entry Properties

Each Log Entry instance contains a userInfo dictionary property. This dictionary’s contents are set by the application developer during each Logger method call. For example:

log.debug("Hello Internet!", ["year": "2015"])

Including data in userData can be useful in a few ways.

• The developer can supply additional properties to be included in an Entry formatter’s string output.

let myFormatter = LXEntryFormatter({ entry in
    let year = entry.userInfo["year"] as? String ?? "unknown"
    return "\(entry.message) The year is \(year)."
})

// Hello Internet! The year is 2015.

• The developer can supply parameters intended to control an Entry formatter’s string output.

let myFormatter = LXEntryFormatter({ entry in
    guard let year = entry.userInfo["year"] as? String where year == "2015" else {
        return "" // No bugs to log in 2016 and beyond!
    }
    return "\(entry.message)"
})

Note: Some Endpoints (such as the included HTTP JSON Endpoint) may automatically attempt to include any userInfo provided as a part of their entryFormatter output string.