Getting Started

Installation

Add BedrockLog to Package.swift dependencies list.

dependencies: [
    .Package(url: "https://github.com/bedrock-project/bedrock-log.git", majorVersion: 1),
]

If you are developing a library, that is enough. But to develop an application, you have to install a logging library conforming to the BedrockLog API as well.

Logging

Let’s see how to write a log:

// Import BedrockLog:
import BedrockLog

// Import some logging library that conforms to BedrockLog API:
import ExampleLogger

// Instantiate `Log` with some implementation of `Logger`:
let log = Log(logger: ExampleLogger())

// Write to the log!
log.info("Everything is going good!")

Log provides eight method, one for each severity according to RFC 5424:

Method Description
emergency(_:) System is unusable
alert(_:) Action must be taken immediately
critical(_:) Critical conditions
error(_:) Error conditions
warning(_:) Warning conditions
notice(_:) Normal but significant condition
info(_:) Informational messages
debug(_:) Debug-level messages

Note

Each of these methods contains three additional parameters (function, file, line), which describe origin of the message in the code.

But you SHOULD NOT provide explicit values for them; these parameters have actual defaults.

Filtering Messages by Severity

When you run an application in production you hardly want to log debug messages. To cut off messages with too low severity use SeverityFilteringLogger.

This is a proxy implementation of Logger which calls real logger only for messages with severity equal to or greater than minimum required:

// Import BedrockLog:
import BedrockLog

// Import some logging library that conforms to BedrockLog API:
import ExampleLogger

// Instantiate `Log` with some implementation of `Logger`
// wrapped inside a `SeverityFilteringLogger`:
let log = Log(
    logger: SeverityFilteringLogger(minSeverity: .notice, logger: ExampleLogger())
)

log.notice("This notice will be written to the log.")
log.warning("This warning will be written to the log.")

log.info("Will NOT be written!")
log.debug("Will NOT be written!")

NilLogger

When you are developing a component which uses a log, it is better make a dependecncy on Log optional. It is a right of user to decide if he wants to catch logs from your component or not.

class MyAwesomeComponent {

    private let log: Log?

    init(log: Log?) {
        self.log = log
    }

    func doSomethingAwesome() {
        log?.info("All fine!")
    }
}

But sometimes you can meet a third-party component which requires non-optional Log. What to do with it? Use NilLogger to instantiate a Log for that kind of components.

let log = Log(logger: NilLogger())

What’s Next?

If you are going to write log from your components, that is it! But if your are implementing your own logging library, read Specification for more details.