e18692fd4d
Use a single unicode right arrow instead of the two char ASCII right arrow to separate the metadata from the actual log message. This is just a preference decision and has no functional background.
104 lines
3.2 KiB
Markdown
104 lines
3.2 KiB
Markdown
# ``LoggingOSLog``
|
|
|
|
An unified logging backend implementation for SwiftLog.
|
|
|
|
## Overview
|
|
|
|
LoggingOSLog is a logging backend implementation for [SwiftLog][swift-log], that
|
|
routes log messages to [OSLog][oslog], the
|
|
[unified logging system][unified-logging] on Apple platforms. On macOS you can
|
|
view the log messages using the Console app or the `log` cli tool.
|
|
|
|
While SwiftLog is available on all Swift platforms though, the
|
|
unified logging system of OSLog is only available on Apple platforms.
|
|
Use this library to combine both worlds. Use SwiftLog in your codebase and use
|
|
this library as the backend implementation when compiling for an Apple platform,
|
|
i.e. using `#if canImport(Darwin)`.
|
|
|
|
[unified-logging]: https://developer.apple.com/documentation/os/logging
|
|
[oslog]: https://developer.apple.com/documentation/oslog
|
|
[backend]: https://swiftpackageindex.com/apple/swift-log/1.10.1/documentation/logging
|
|
[swift-log]: https://github.com/apple/swift-log
|
|
|
|
## Getting started
|
|
|
|
Use this package if you're writing a cross-platform (for example, Linux and
|
|
macOS) application or library and still want to take full advantage of the
|
|
unified logging system on Apple platforms.
|
|
|
|
### Adding the Dependency
|
|
|
|
Add the dependency to your Package.swift:
|
|
|
|
```swift
|
|
.package(url: "https://github.com/astzweig/swift-log-oslog", from: "1.0.0")
|
|
```
|
|
|
|
And to your target:
|
|
|
|
```swift
|
|
.target(
|
|
name: "YourTarget",
|
|
dependencies: [
|
|
.product(name: "LoggingOSLog", package: "swift-log-oslog")
|
|
]
|
|
)
|
|
```
|
|
|
|
### Basic Usage
|
|
|
|
```swift
|
|
// Import the logging API and this backend implementation
|
|
import Logging
|
|
#if canImport(Darwin)
|
|
import LoggingOSLog
|
|
#endif
|
|
|
|
// Later, in your application initialization code
|
|
func init() {
|
|
// ...
|
|
#if canImport(Darwin)
|
|
LoggingSystem.bootstrap(LoggingOSLog.init)
|
|
#endif
|
|
|
|
// Start creating loggers
|
|
let loggers: [String: Logger] = [
|
|
"main": Logger(label: "com.example.yourapp.Main"),
|
|
"mail": Logger(label: "com.example.yourapp.Mail System"),
|
|
]
|
|
|
|
// And using loggers
|
|
logger["main"]!.debug("Starting build",
|
|
metadata: [
|
|
"input.output_directory": "\(output)",
|
|
"input.data": "\(data ?? "-")"
|
|
])
|
|
}
|
|
```
|
|
|
|
## Relation to the unified logging system
|
|
|
|
The [unified logging system][unified-logging] uses two parameters to allow for
|
|
better filtering of log messages: [subsystem][subsystem] and
|
|
[category][category]. [SwiftLog][swift-log] has only a label parameter, so this
|
|
library maps a reverse domain style label to the subsystem and category
|
|
parameters of the unified logging system. See
|
|
``/LoggingOSLog/LoggingOSLog/init(label:)`` for more information.
|
|
|
|
Metadata is appended as JSON to the logged message after a simple unicode right
|
|
arrow ("→").
|
|
|
|
### What this library does not supply
|
|
This library does not implement any of the interpolation privacy features of
|
|
the unified logging system, i.e. there is no way to redact or align a meta
|
|
information, like the `Logging` API would allow.
|
|
|
|
[subsystem]: https://developer.apple.com/documentation/os/generating-log-messages-from-your-code#:~:text=The%20subsystem%20string,for%20each%20subsystem%20string.
|
|
[category]: https://developer.apple.com/documentation/os/generating-log-messages-from-your-code#:~:text=The%20category%20string,for%20these%20strings.
|
|
|
|
## Topics
|
|
|
|
### API
|
|
|
|
- ``LoggingOSLog``
|