Log

public struct Log

Log is the primary public API for CleanroomLogger.

If you wish to send a message to the log, you do so by calling the appropriae function provided by the appropriate LogChannel given the importance of your message.

There are five levels of severity at which log messages can be recorded. Each level is represented by a read-only static variable maintained by the Log:

Log.error — The highest severity; something has gone wrong and a fatal error may be imminent
Log.warning — Something appears amiss and might bear looking into before a larger problem arises
Log.info — Something notable happened, but it isn’t anything to worry about
Log.debug — Used for debugging and diagnostic information
Log.verbose - The lowest severity; used for detailed or frequently occurring debugging and diagnostic information

Each LogChannel can be used in one of three ways:

The trace() function records a short log message detailing the source file, source line, and function name of the caller. It is intended to be called with no arguments, as follows:

Log.debug?.trace()

The message() function records a message specified by the caller:

Log.info?.message("The application has finished launching.")

message() is intended to be called with a single parameter, the message string, as shown above. Unlike NSLog(), no printf-like functionality is provided; instead, use Swift string interpolation to construct parameterized messages.

Finally, the value() function records a string representation of an arbitrary Any value:

Log.verbose?.value(delegate)

The value() function is intended to be called with a single parameter, of type Any?.

The underlying logging implementation is responsible for converting this value into a string representation.

Note that some implementations may not be able to convert certain values into strings; in those cases, log requests may be silently ignored.

Enabling logging

By default, logging is disabled, meaning that none of the Log‘s log channels have been populated. As a result, attempts to perform any logging will silently fail.

It is the responsibility of the application developer to enable logging, which is done by calling the appropriate Log.enable() function.

error
The LogChannel that can be used to perform logging at the .error log severity level. Will be nil if logging hasn’t yet been enabled, or if logging for the .error severity has not been configured.
Declaration
Swift

public private(set) static var error: LogChannel?
warning
The LogChannel that can be used to perform logging at the .warning log severity level. Will be nil if logging hasn’t yet been enabled, or if logging for the .warning severity has not been configured.
Declaration
Swift

public private(set) static var warning: LogChannel?
info
The LogChannel that can be used to perform logging at the .info log severity level. Will be nil if logging hasn’t yet been enabled, or if logging for the .info severity has not been configured.
Declaration
Swift

public private(set) static var info: LogChannel?
debug
The LogChannel that can be used to perform logging at the .debug log severity level. Will be nil if logging hasn’t yet been enabled, or if logging for the .debug severity has not been configured.
Declaration
Swift

public private(set) static var debug: LogChannel?
verbose
The LogChannel that can be used to perform logging at the .verbose log severity level. Will be nil if logging hasn’t yet been enabled, or if logging for the .verbose severity has not been configured.
Declaration
Swift

public private(set) static var verbose: LogChannel?


                    
                    
                    enable(minimumSeverity:debugMode:verboseDebugMode:stdStreamsMode:mimicOSLogOutput:showCallSite:filters:)

Enables logging using an XcodeLogConfiguration.

Log entries are recorded by being written to the Apple System Log and to the stderr output stream of the running process. In Xcode, log entries will appear in the console.

Warning

Setting either debugMode or verboseDebugMode to true will result in synchronousMode being used when recording log entries. Synchronous mode is helpful while debugging, as it ensures that logs are always up-to-date when debug breakpoints are hit. However, synchronous mode can have a negative influence on performance and is therefore not recommended for use in production code.

Declaration

Swift

public static func enable(minimumSeverity: LogSeverity = .info, debugMode: Bool = false, verboseDebugMode: Bool = false, stdStreamsMode: ConsoleLogConfiguration.StandardStreamsMode = .useAsFallback, mimicOSLogOutput: Bool = true, showCallSite: Bool = true, filters: [LogFilter] = [])

Parameters

`minimumSeverity`	The minimum supported `LogSeverity`. Any `LogEntry` having a `severity` less than `minimumSeverity` will be silently ignored.
`debugMode`	If `true`, the value of `minimumSeverity` will be lowered (if necessary) to `.debug` and `synchronousMode` will be used when recording log entries.
`verboseDebugMode`	If `true`, the value of `minimumSeverity` will be lowered (if necessary) to `.verbose` and `synchronousMode` will be used when recording log entries.
`stdStreamsMode`	A `StandardStreamsMode` value that governs when standard console streams (i.e., `stdout` and `stderr`) should be used for recording log output.
`mimicOSLogOutput`	If `true`, any output sent to `stdout` will be formatted in such a way as to mimic the output seen when `os_log()` is used.
`showCallSite`	If `true`, the source file and line indicating the call site of the log request will be added to formatted log messages.
`filters`	The `LogFilter`s to use when deciding whether a given `LogEntry` should be passed along for recording.


                    
                    
                    enable(configuration:)

Enables logging using the specified LogConfiguration.

Declaration

Swift

public static func enable(configuration: LogConfiguration)

Parameters


                                configuration

The LogConfiguration to use for controlling the behavior of logging.


                    
                    
                    enable(configuration:)

Enables logging using the specified LogConfigurations.

Declaration

Swift

public static func enable(configuration: [LogConfiguration])

Parameters


                                configuration

An array of LogConfigurations specifying the behavior of logging.


                    
                    
                    enable(receptacle:)

Enables logging using the specified LogReceptacle.

Individual LogChannels for error, warning, info, debug, and verbose may or may not be constructed depending on the receptacle’s minimumSeverity.

Declaration

Swift

public static func enable(receptacle: LogReceptacle)

Parameters


                                receptacle

The LogReceptacle to use when creating the LogChannels for the five severity levels.


                    
                    
                    enable(errorChannel:warningChannel:infoChannel:debugChannel:verboseChannel:)

Enables logging using the specified LogChannels.

The static error, warning, info, debug, and verbose properties of Log will be set using the specified values.

If you know that the configuration of a given LogChannel guarantees that it will never perform logging, it is best to pass nil instead. Otherwise, needless overhead will be added to the application.

Declaration

Swift

public static func enable(errorChannel: LogChannel?, warningChannel: LogChannel?, infoChannel: LogChannel?, debugChannel: LogChannel?, verboseChannel: LogChannel?)

Parameters

`errorChannel`	The `LogChannel` to use for logging messages with a `severity` of `.error`.
`warningChannel`	The `LogChannel` to use for logging messages with a `severity` of `.warning`.
`infoChannel`	The `LogChannel` to use for logging messages with a `severity` of `.info`.
`debugChannel`	The `LogChannel` to use for logging messages with a `severity` of `.debug`.
`verboseChannel`	The `LogChannel` to use for logging messages with a `severity` of `.verbose`.

neverEnable()
Assuming CleanroomLogger has not yet been enabled, calling this function prevents any other caller from enabling CleanroomLogger for the remainder of the lifetime of the running executable.

The ability to prevent CleanroomLogger from being enabled may be useful in applications that link against libraries requiring CleanroomLogger. Application developers who did not choose to use CleanroomLogger can ensure that embedded third-party libraries don’t use it, either.

Important
If Log.enable() has already been called, calling Log.neverEnable() will have no effect.
Declaration
Swift

public static func neverEnable()


                    
                    
                    channel(severity:)

Returns the LogChannel responsible for logging at the given severity.

Declaration

Swift

public static func channel(severity: LogSeverity)
        -> LogChannel?

Parameters


                                severity

The LogSeverity level of the LogChannel to return.

Return Value

The LogChannel used by Log to perform logging at the given severity; will be nil if Log is not configured to perform logging at that severity.


                    
                    
                    trace(_:function:filePath:fileLine:)

Sends program execution trace information to the log using the specified severity. This information includes source-level call site information as well as the stack frame signature of the caller.

Declaration

Swift

public static func trace(_ severity: LogSeverity, function: String = #function, filePath: String = #file, fileLine: Int = #line)

Parameters

`severity`	The `LogSeverity` for the message being recorded.
`function`	The default value provided for this parameter captures the signature of the calling function. You should not provide a value for this parameter.
`filePath`	The default value provided for this parameter captures the file path of the code issuing the call to this function. You should not provide a value for this parameter.
`fileLine`	The default value provided for this parameter captures the line number issuing the call to this function. You should not provide a value for this parameter.


                    
                    
                    message(_:message:function:filePath:fileLine:)

Sends a message string to the log using the specified severity.

Declaration

Swift

public static func message(_ severity: LogSeverity, message: String, function: String = #function, filePath: String = #file, fileLine: Int = #line)

Parameters

`severity`	The `LogSeverity` for the log entry.
`msg`	The message to log.
`function`	The default value provided for this parameter captures the signature of the calling function. You should not provide a value for this parameter.
`filePath`	The default value provided for this parameter captures the file path of the code issuing the call to this function. You should not provide a value for this parameter.
`fileLine`	The default value provided for this parameter captures the line number issuing the call to this function. You should not provide a value for this parameter.


                    
                    
                    value(_:value:function:filePath:fileLine:)

Sends an arbitrary value to the log using the specified severity.

Declaration

Swift

public static func value(_ severity: LogSeverity, value: Any?, function: String = #function, filePath: String = #file, fileLine: Int = #line)

Parameters

`severity`	The `LogSeverity` for the log entry.
`value`	The value to send to the log. Determining how (and whether) arbitrary values are captured and represented will be handled by the `LogRecorder` implementation(s) that are ultimately called upon to record the log entry.
`function`	The default value provided for this parameter captures the signature of the calling function. You should not provide a value for this parameter.
`filePath`	The default value provided for this parameter captures the file path of the code issuing the call to this function. You should not provide a value for this parameter.
`fileLine`	The default value provided for this parameter captures the line number issuing the call to this function. You should not provide a value for this parameter.