Logging

Logger

The Logger component enables logging of text messages used for error recording and debugging. These messages can be logged to several destinations, for example, the iOS console, one or more files, or custom destinations.

Note: To upload logs to SAP Mobile Services, use the SAPcpmsLogUploader component from the SAPFoundation framework. In addition to this API reference, see Logging for more information.

Basic Usage

Log levels:

• off - turns logging off
• error - indicates a serious failure
• warn - indicates a potential problem
• info - informational messages
• debug - provides tracing information

Log level recommendations:

• Use the debug and info log levels to trace the current states of your application. Log these messages extensively, for example, when your code handles different conditions of an operation, or when the state of your app changes (for example, in case the connection is lost, or a user interface is switched).

• Use the warn log level for errors that allow your app to function without having any impact on the user experience.

• Use the error log level for errors that put your app’s stability at risk or indicate a malfunction, incorrect usage, or runtime error. Typical examples include catching an error or exception, illegal user input, or situations where your app is about to terminate unexpectedly.

Set the log level of the Logger:

Logger.root.logLevel = LogLevel.error

Note: LogLevel.debug can be used for local development, use LogLevel.error in a production environment.

Using the Logger Hierarchy

Multiple logger instances can exist simultaneously. Each logger instance is part of a hierarchy and has a keyPath associated with it. The root of the hierarchy is the root logger: it is the parent of all Logger instances. Each Logger instance you create is a direct or indirect descendant of the root instance.

Loggers are created with a name, which preferably contains dots (“.”) that defines the hierarchy: each element of the name separated by a dot can be a parent of the instance.

You can use a logger instance in any class by calling:

public class MyClass {
    private let logger = Logger.shared(named: <#LoggerIdentifier#>)
}

Log messages

Warning: Avoid logging sensitive data, since logged data is readable in the log.

Set the level of messages to be logged with one of these methods:

logger.error("Message", error: errorObj) // equivalent to logger.log("Message", error: errorObj, forLevel:.error)
logger.warn("Message", error: errorObj)  // equivalent to logger.log("Message", error: errorObj, forLevel:.warn)
logger.info("Message", error: errorObj)  // equivalent to logger.log("Message", error: errorObj, forLevel:.info)
logger.debug("Message", error: errorObj) // equivalent to logger.log("Message", error: errorObj, forLevel:.debug)

If the level of messages is lower than the logger’s, it is not logged.

Advanced Usage

LogHandlers

LogHandlers are attached to Logger instances, and define the destinations where log messages are written: OSLogConsoleHandler and FileLogHandler are typical handlers. They are used to write log messages to the console or to a file respectively.

Handlers that are attached to parent Logger instances are inherited by child Logger instances (unless otherwise specified). This allows fine-grained control and makes it possible to configure the log destination for an entire subtree of the Logger hierarchy.

OSLogConsoleHandler is attached to the Logger.root by default.

Add FileLogHandler to write logs to a file, For example:

let fileHandler = try FileLogHandler(fileURL: <#your URL#>)
Logger.root.add(handler: fileHandler)

A tyical use is to write to the documents forder of the app:

let documentsPath = NSSearchPathForDirectoriesInDomains(.documentDirectory, .userDomainMask, true)[0]
let filePath = documentsPath + "/MyAppLog.txt"
let handler = try! FileLogHandler(fileURL: URL(fileURLWithPath: filePath))

These logs can be then read back with xcode by downloading or browsing the container of the app . In Xcode select your device at Window / Devices and Simulators. Clicking the cogwheel icon enables you to browse or download the container.

LogFormatters

LogFormatters are responsible for formatting the messages logged with a Logger instance before they are written to the destination LogHandlers. Such formatting can include adding a sequence number, logging date and time, or formatting the output in a special way, depending on your organization’s logging policy. Typically each logging LogHandler has an associated LogFormatter.

There are two default formatters available:

• OSLogFormatter: used by OSLogConsoleHandler
• FileLogFormatter: used by FileLogHandler