https://github.com/l1men9yu/senna

a logging engine backend of Apple's swift-log
https://github.com/l1men9yu/senna

logger logging logging-library swift swift-log

Last synced: 4 months ago
JSON representation

a logging engine backend of Apple's swift-log

Host: GitHub
URL: https://github.com/l1men9yu/senna
Owner: L1MeN9Yu
License: mit
Created: 2019-09-29T10:41:12.000Z (over 6 years ago)
Default Branch: main
Last Pushed: 2023-10-13T08:27:04.000Z (over 2 years ago)
Last Synced: 2025-12-28T19:27:59.355Z (6 months ago)
Topics: logger, logging, logging-library, swift, swift-log
Language: Swift
Homepage:
Size: 1.12 MB
Stars: 11
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

README

          # Senna

**a logging engine backend of Apple's** [swift-log](https://github.com/apple/swift-log)

## Status

![Swift5.0+](https://img.shields.io/badge/Swift-5.0%2B-orange.svg?style=flat)

[![release](https://img.shields.io/github/v/release/L1MeN9Yu/Senna.svg?color=blue)](https://github.com/L1MeN9Yu/Senna/releases)

[![Build](https://github.com/L1MeN9Yu/Senna/actions/workflows/Build.yml/badge.svg)](https://github.com/L1MeN9Yu/Senna/actions/workflows/Build.yml)

[![codecov](https://codecov.io/gh/L1MeN9Yu/Senna/branch/main/graph/badge.svg?token=0ZQSVH4ERX)](https://codecov.io/gh/L1MeN9Yu/Senna)

[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/L1MeN9Yu/Senna/blob/main/LICENSE)

[![platforms](https://img.shields.io/badge/Platforms-macOS%20%7C%20iOS%20%7C%20tvOS%20%7C%20watchOS%20%7C%20Linux-orange.svg?style=flat)](https://github.com/L1MeN9Yu/Senna/blob/main/Package.swift)

## Features

* Pure Swift

* Backend of `apple/swift-log`

* Both Darwin(iOS macOS watchOS tvOS) and Linux compatibility

* Builtin output target : `[stdout/stderr,file,oslog,syslog]`

* ANSI escape code

* Complete customizable for text out

* Support string interpolation the same as [Apple's Unified Logging System](https://developer.apple.com/documentation/os/logging/generating_log_messages_from_your_code)

* 100% Code Coverage

## Examples

### Use Builtin Sinks

#### Simple stdout

```swift

//create sink

let sink = StandardSink.out()

//create formation

let formation = Formation.standard

//create log

var logger = Logger(label: "LogName") {

    Handler(name: $0, sink: sink, formation: formation, logLevel: .trace)

}

// do some logs

logger.trace("This is a trace message")

logger.debug("This is a debug message")

logger.info("This is a info message")

logger.notice("This is a notice message")

logger.warning("This is a warning message")

logger.error("This is a error message")

logger.critical("This is a critical message")

 ```

Terminal out :

![](Documentations/README/Resources/stdout.png)

#### Change LogLevel

```swift

logger.logLevel = .info

logger.debug("will not log")

logger.info("will log")

```

#### Add MetaData

```swift

logger[metadataKey: "UserID"] = .stringConvertible(9527)

logger.info("message with logger meta data")

logger.info("message with both logger and message meta data", metadata: ["UserName": .string("L1MeN9Yu")])

```

Terminal out :

![](Documentations/README/Resources/stdout_message_with_metadata.png)

### Builtin Sinks

#### FileSink

```swift

let fileSink = FileSink("path/of/log")

```

Log message will write to file.

See [Tests](Tests/FileSinkTests.swift) for more.

#### OSLogSink (Apple platform only)

```swift

let osLogSink = OSLogSink(subsystem: "subsystem", category: "category")

```

Log message will write to OS log (Apple's syslog). Use `Connsole.app` in your macOS to watch oslog messages.

See [Tests](Tests/OSLogSinkTests.swift) for more.

#### SystemLogSink (Linux)

```swift

let systemLogSink = SystemLogSink()

```

Log message will write to syslog.

See [Tests](Tests/SystemLogSinkTests.swift) for more.

### Formation

`Formation` generate the log message.

There are some builtin `Formation`:

1. `Formation.standard`. This is default for `stdout/stderr`.

2. `Formation.standardXcode`. This is default for `stdout/stderr` display in Xcode due Xcode's console is not support ANSI escape code.

![](Documentations/README/Resources/stdout_xcode.png)

3. `Formation.file`. This is default for `File`.

4. `Formation.os`. This is default for `OSLog`.

5. `Formation.system`. This is default for `syslog`.

### Advanced Customize Formation

Create `Formation` is simple : `Formation(components: <#T##[Component]##[Senna.Component]#>, printer: <#T##Printable?##Senna.Printable?#>, separator: <#T##String?##Swift.String?#>)`

The Formation contains `components: [Component]`, `printer: Printable?` and `separator: String?`.

#### Component

Component is your log message's element. See [Component](Sources/Types/Component.swift) file.

#### Printable

The `Printable` enhanced your log messages, It can add color or style to the component.

The builtin `Printer` has two default instance.

`Printer.standard` for `stdout/stderr`.

`Printer.xcode` for `stdout/stderr` in Xcode.

You can create new `Printer` instance or Use `YourPrinter` which implements `Printable` protocol.

See [Printer](Sources/Implements/Printer.swift) and [Printable](Sources/Protocols/Printable.swift) for more.

#### Separator

The `Separator` string is used for split log message's component.

The `Formation.standard`'s separator is `" ▶ "`.

### Apple's Unified Logging System

Senna reimplement the string interpolation behavior of [Apple's Unified Logging System](https://developer.apple.com/documentation/os/logging/generating_log_messages_from_your_code)

```swift

let sink = StandardSink.out()

let formation = Formation.standard

var logger = Logger(label: "LogName") {

    Handler(name: $0, sink: sink, formation: formation, logLevel: .trace)

}

logger[metadataKey: "UserID"] = .stringConvertible(9527)

#if DEBUG

let privacy = Privacy.public

#else

let privacy = Privacy.private

#endif

// default is private

logger.senna.notice("the user name is \("L1MeN9Yu")")

logger.senna.notice("the user name is \("L1MeN9Yu", privacy: privacy)")

```

Terminal out :

![](Documentations/README/Resources/stdout.string.interpolation.png)

see [LoggerSennaTests.swift](Tests/LoggerSennaTests.swift) for more usages.

## Installation

### Swift Package Manager

Add the following to your `Package.swift` file:

```swift

dependencies: [

    .package(url: "https://github.com/L1MeN9Yu/Senna.git", from: "3.0.0")

]

```

## Credit

* [swift-log](https://github.com/apple/swift-log)

* [swift-log-format-and-pipe](https://github.com/Adorkable/swift-log-format-and-pipe)

* [spdlog](https://github.com/gabime/spdlog)

* [Rainbow](https://github.com/onevcat/Rainbow)

* [Logging](https://github.com/shaps80/Logging)

## License

Senna is available under the [MIT license](http://www.opensource.org/licenses/mit-license). See the LICENSE file for details.

## Thanks | 鸣谢

Thanks to [JetBrains][JetBrains] for "Licenses for Open Source Development". [JetBrains][JetBrains] supports non-commercial open source projects by providing core project contributors with a set of best-in-class

developer tools free of charge.

感谢 [JetBrains][JetBrains] 提供的开源开发许可证。[JetBrains][JetBrains] 通过为项目核心开发者免费提供开发工具来支持非商业开源项目。

[JetBrains]: https://www.jetbrains.com/?from=Senna

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/l1men9yu/senna

Awesome Lists containing this project

README