[Announcement] swift-log-oslog: OSLog integration for swift-log

Hi everyone,

We're excited to announce the initial release of swift-log-oslog, a Swift Log backend that writes to OSLog.

Swift Log is the logging API, and backends decide where logs go. With OSLogHandler, anything that logs through swift-log, including your dependencies, is delivered to OSLog, so you can view it with the Unified Logging tools, like Console and the log command-line tool.

What's in the package

  • OSLogHandler is a LogHandler for the Darwin unified logging system, available on Apple platforms.
  • SensitivityAttribute lets you mark each metadata value as .public or .sensitive. Swift Log is cross-platform and works everywhere swift-log does, including Linux, Windows, and WebAssembly.

This package is an alpha, and the API may change before 1.0. Feedback is welcome.

Using OSLogHandler

Use OSLogHandler as your swift-log backend. To control which metadata values OSLog redacts, mark them with the Sensitivity attribute, which is based on the metadata value attributes of SLG-0004.

SensitivityAttribute doesn't depend on OSLog, so code shared between macOS and Linux marks its metadata the same way. Where OSLog isn't available, OSLogHandler isn't either, so wrap any handler in RedactionLogHandler to redact the values that aren't tagged .public.

import Logging
import OSLogHandler
import SensitivityAttribute

let userId = "12345"

let logger = Logger(label: "auth") { label in
    #if canImport(os)
    OSLogHandler(subsystem: "com.example.myapp", category: label)
    #else
    RedactionLogHandler(wrapping: StreamLogHandler.standardOutput(label: label))
    #endif
}

logger.info("Login successful", metadata: [
    "user.id": "\(userId, sensitivity: .sensitive)",
    "action": "\("password", sensitivity: .public)",
])

In Console.app, this logs:

Login successful action=password <private>

If the system is configured to show private data, for example while you debug, the full message appears:

Login successful action=password user.id=12345

Building on the community's work

Over the years, several packages have connected swift-log to OSLog. They proved that the need is real, and we're grateful to those authors for showing the way.

With swift-log-oslog, Apple is providing a fully supported version of this connection. Apple maintains OSLog, and we're committed to keeping this package in step with it and with swift-log. As either one evolves, the package will follow, and problems in the integration are ours to fix.

Development happens on GitHub, where issues and pull requests are welcome. Changes to the public API go through a short proposal process modeled on the one swift-log uses.

Getting started

Add the package to your Package.swift:

.package(url: "https://github.com/apple/swift-log-oslog", exact: "0.1.0")

Then add the products you need to your target:

.product(name: "OSLogHandler", package: "swift-log-oslog")
.product(name: "SensitivityAttribute", package: "swift-log-oslog")

The documentation is available on the Swift Package Index. Please report bugs and ask questions on GitHub, and see CONTRIBUTING.md if you'd like to contribute. We look forward to your feedback.

Vladimir

16 Likes

As I understand it, the OSLog functions get some special treatment from the compiler to be more efficient and that special handling is undone by wrapping those APIs. Is this assumption correct, and if so, how does this package deal with that?

@FlorianPircher OSLog performance optimizations in the Swift compiler are only applied for const message format strings and indeed won't be applied for the LogHandler wrapping OSLog.

This packages includes a couple of benchmarks for various patterns of using Logger and OSLog. I recommend checking them while making a decision which API to use, or if it is worth having a compilation condition choosing between explicit OSLog on Darwin and Swift Log on other platforms.