Logger

public class Logger : Hashable, Equatable, CustomStringConvertible

A class for writing log messages to a variety of different sinks, so called handlers.

In your code, you can log messages with one of the following methods:

logger.error("Message", error: errorObj)
logger.warn("Message", error: errorObj)
logger.info("Message", error: errorObj)
logger.debug("Message", error: errorObj)

All calls to shared(named: String) always returns an instance of Logger and the instance always has a parent of type Logger. The only exception is the root logger which has no direct parent.

There can be multiple logger instances at the same time, which are all descendants of the root logger. Each logger instance is part of a hierarchy and has a keyPath associated with it. Each instance is used to create log messages using methods like Logger.error("Message").

Log messages are handled by the handlers associated with each logger. All attached LogHandlers are passed to the loggers ancestors in the log hierarchy. This behaviour can be controlled through the useParentHandlers parameter.

Each handler must conform to the LogHandler protocol. Each handler can have its own LogFormatter, which is responsible for the output format of the log messages. Loggers as well as LogHandlers objects can include an optional LogLevel. Consequently, log messages with a lower level are not processed by the logger or handler object respectively. If a specific level is not set, the level is obtained from the ancestor logger instances in the hierarchy.

IMPORTANT: Avoid logging sensitive data. All logged data will be readable in the log.

Private Members

  • The serial synchronization queue for synchronizing Logger methods

    Declaration

    Swift

    public static let synchronizationQueue: DispatchQueue

Public Members

  • Property to control whether the handlers of the parents are supposed to be used for logging with this Logger instance, too. Set to true to publish each log message also to the parents’ handlers.

    Declaration

    Swift

    public var useParentHandlers: Bool

  • Returns the root logger instance. This instance is initialized with a meaningful default handler for logging to the console. The default log level of the root logger is .error. You need to set this to .debug, if you want to see all possible log output.

    Declaration

    Swift

    public static let root: Logger

  • The nearest parent of this Logger instance. May be nil, if there is no parent, i.e. this instance is the root. Access to the parent is synchronized.

    Declaration

    Swift

    public private(set) var parent: Logger? { get set }

  • The log level of this logger instance. This property will always return a log level (unless the root logger has it’s level set to nil). If this Logger instance has a non-nil level set, that level will be returned. If the logLevel of this instance is nil the effective log level of this instance is calculated by checking the logLevel of its parent, which in turn may ask its parent up the logger hierarchy, etc.

    Declaration

    Swift

    public var logLevel: LogLevel? { get set }

Getting Loggers

  • Returns a logger instance by keyPath. The logger may already exist or may be newly created.

    Declaration

    Swift

    public class func shared(named name: String) -> Logger

    Parameters

    name

    the keyPath of the Logger. The keyPath contains the name and the position of the logger in the hierarchy. The different hierarchy levels are separated by dots. Therefore, the full name is unique and only one instance can be created for a specific logger name. Every logger will be part of a hierarchy that starts with the root logger instance. Here is an example for an unique logger name: “MyProject.MyFolder.MyType”. This will result in the generation of 3 logger instances, one for each hierachy level (MyProject, MyFolder, MyType). All in all, there will be one root logger and every logger inherits from it. Call Logger.root or use the parent property to get to the root logger.

    Return Value

    the logger instance.

Adding and removing Handlers

  • Adds a handler to this logger.

    Declaration

    Swift

    public func add(handler: LogHandler)

    Parameters

    handler

    the handler object to add

  • Removes a handler from this logger. If the specified handler does not exist then this method has no effect.

    Declaration

    Swift

    public func remove(handler: LogHandler)

    Parameters

    handler

    the handler to be removed.

  • Removes all handlers from the Logger instance. Note: a Logger does not log anything without handlers. Make sure to add handlers again, after removing them all.

    Declaration

    Swift

    public func removeHandlers()

Log methods

  • Logs a message of the specified level. The message is transmitted to all subscribed handlers.

    Convenience method to allow calls like

    Logger.log { return "Message" }

    Declaration

    Swift

    public func log(_ message: String, error: Error? = nil, level: LogLevel = .debug, fileName: String = #file, functionName: String = #function, lineNumber: Int = #line, correlationId: String? = nil)

    Parameters

    message

    a block that returns the message to log. Strings are automatically wrapped in a message. Is executed only if the loglevel of the logger is greater or equal.
    error

    the optional error to log.
    forLevel

    the level of the specified message. The default LogLevel is error.

  • Logs a message with error log level on the root logger.

    Convenience method to allow calls like

    Logger.error { return "Message" }

    Declaration

    Swift

    public func error(_ message: String, error: Error? = nil, fileName: String = #file, functionName: String = #function, lineNumber: Int = #line, correlationId: String? = nil)

    Parameters

    message

    a block that returns the message to log. Strings are automatically wrapped in a message. Is executed only if the loglevel of the logger is greater or equal.
    error

    the optional error to log.

  • Logs a message with warning log level on the root logger.

    Convenience method to allow calls like

    Logger.warn { return "Message" }

    Declaration

    Swift

    public func warn(_ message: String, error: Error? = nil, fileName: String = #file, functionName: String = #function, lineNumber: Int = #line, correlationId: String? = nil)

    Parameters

    message

    a block that returns the message to log. Strings are automatically wrapped in a message. Is executed only if the loglevel of the logger is greater or equal.
    error

    the optional error to log.

  • Logs a message with info log level on the root logger.

    Convenience method to allow calls like

    Logger.info { return "Message" }

    Declaration

    Swift

    public func info(_ message: String, error: Error? = nil, fileName: String = #file, functionName: String = #function, lineNumber: Int = #line, correlationId: String? = nil)

    Parameters

    message

    a block that returns the message to log. Strings are automatically wrapped in a message. Is executed only if the loglevel of the logger is greater or equal.
    error

    the optional error to log.

  • Logs a message with debug log level on the root logger.

    Convenience method to allow calls like

    Logger.debug { return "Message" }

    Declaration

    Swift

    public func debug(_ message: String, error: Error? = nil, fileName: String = #file, functionName: String = #function, lineNumber: Int = #line, correlationId: String? = nil)

    Parameters

    message

    a block that returns the message to log. Strings are automatically wrapped in a message. Is executed only if the loglevel of the logger is greater or equal.
    error

    the optional error to log.

Checking if logging at level would succeed

  • Returns true if this logger instance would currently log error messages. False otherwise.

    Declaration

    Swift

    public var isErrorEnabled: Bool { get }

  • Returns true if this logger instance would currently log warning messages. False otherwise.

    Declaration

    Swift

    public var isWarnEnabled: Bool { get }

  • Returns true if this logger instance would currently log info messages. False otherwise.

    Declaration

    Swift

    public var isInfoEnabled: Bool { get }

  • Returns true if this logger instance would currently log debug messages. False otherwise.

    Declaration

    Swift

    public var isDebugEnabled: Bool { get }

  • Dumps the current loggers sub hierarchy.

    Declaration

    Swift

    public func dumpHierarchy()

Hashable & Equatable Implementation

  • Declaration

    Swift

    public static func == (lhs: Logger, rhs: Logger) -> Bool

  • Declaration

    Swift

    public var hashValue: Int { get }

Custom String Convertible

  • Declaration

    Swift

    public var description: String { get }