Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sushichop/Puppy
A flexible logging library written in Swift
https://github.com/sushichop/Puppy
cross-platform darwin ios linux logging macos server-side-swift swift swift-log windows
Last synced: about 1 month ago
JSON representation
A flexible logging library written in Swift
- Host: GitHub
- URL: https://github.com/sushichop/Puppy
- Owner: sushichop
- License: mit
- Created: 2020-10-18T09:14:17.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-04-20T04:45:25.000Z (8 months ago)
- Last Synced: 2024-05-30T00:04:18.967Z (7 months ago)
- Topics: cross-platform, darwin, ios, linux, logging, macos, server-side-swift, swift, swift-log, windows
- Language: Swift
- Homepage:
- Size: 194 KB
- Stars: 148
- Watchers: 5
- Forks: 28
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- fucking-awesome-swift - Puppy - A flexible logging library that supports multiple transports and platforms. (Libs / Logging)
- awesome-swift - Puppy - A flexible logging library written in Swift ` 📝 6 days ago ` (Logging [🔝](#readme))
- awesome-swift - Puppy - A flexible logging library that supports multiple transports and platforms. (Libs / Logging)
README
# Puppy
![Swift5.6+](https://img.shields.io/badge/Swift-5.6%2B-orange.svg?style=flat)
[![release](https://img.shields.io/github/v/release/sushichop/Puppy.svg?color=blue)](https://github.com/sushichop/Puppy/releases)
[![CocoaPods](https://img.shields.io/cocoapods/v/Puppy.svg?color=blue)](https://cocoapods.org/pods/Puppy)
![CI](https://github.com/sushichop/Puppy/workflows/CI/badge.svg)
[![codecov](https://codecov.io/gh/sushichop/Puppy/branch/main/graph/badge.svg)](https://codecov.io/gh/sushichop/Puppy)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/sushichop/Puppy/blob/master/LICENSE)![platforms](https://img.shields.io/badge/Platforms-macOS%20%7C%20iOS%20%7C%20tvOS%20%7C%20watchOS%20%7C%20Linux%20%7C%20Windows-orange.svg?style=flat)
![SwiftPM|CMake|Bazel|Carthage](https://img.shields.io/badge/SwiftPM%20%7C%20CMake%20%7C%20Bazel%20%7C%20Carthage-compatible-4BC51D.svg?style=flat)### **Puppy is a flexible logging library written in Swift** 🐶
It supports multiple transports(console, file, syslog, and oslog) as loggers. It not only works alone, but also as a backend for [apple/swift-log](https://github.com/apple/swift-log/).
Furthermore, it has file log rotation feature and you can also customize the log format as you like. And it supports **cross-platform(Darwin, Linux, and Windows)**.
## Features
- Written in Swift.
- Supports cross-platform(Darwin, Linux, and Windows).
- Supports console, file, syslog, and oslog as loggers.
- Supports automatic log rotation about file logger.
- Also Works as a backend for `apple/swift-log`.## Examples
### Basic Usage
Logging to mutliple transports(e.g. console and file). It is recommended that the first argument of each logger be a unique reverse-order FQDN since it is also used internally for a `DispatchQueue`'s label.
```Swift
import Puppylet console = ConsoleLogger("com.example.yourapp.console", logLevel: .info)
let fileURL = URL(fileURLWithPath: "./foo.log").absoluteURL
let file = FileLogger("com.example.yourapp.file",
logLevel: .info,
fileURL: fileURL,
filePermission: "600") // Default permission is "640".var log = Puppy()
log.add(console)
log.add(file)log.debug("DEBUG message") // Will NOT be logged.
log.info("INFO message") // Will be logged.
log.error("ERROR message") // Will be logged.
```### Use file log rotation
Logging to file and use log rotation feature.
```swift
import Puppyclass ViewController: UIViewController {
let fileURL = URL(fileURLWithPath: "./logs/foo.log").absoluteURL
let rotationConfig = RotationConfig(suffixExtension: .date_uuid,
maxFileSize: 10 * 1024 * 1024,
maxArchivedFilesCount: 3)
let delegate = SampleFileRotationDelegate()
let fileRotation = try! FileRotationLogger("com.example.yourapp.filerotation",
fileURL: fileURL,
rotationConfig: rotationConfig,
delegate: delegate)override func viewDidLoad() {
super.viewDidLoad()
var log = Puppy()
log.add(fileRotation)
log.info("INFO message")
log.warning("WARNING message")
}
}class SampleFileRotationDelegate: FileRotationLoggerDelegate {
func fileRotationLogger(_ fileRotationLogger: FileRotationLogger,
didArchiveFileURL: URL, toFileURL: URL) {
print("didArchiveFileURL: \(didArchiveFileURL), toFileURL: \(toFileURL)")
}
func fileRotationLogger(_ fileRotationLogger: FileRotationLogger,
didRemoveArchivedFileURL: URL) {
print("didRemoveArchivedFileURL: \(didRemoveArchivedFileURL)")
}
}
```### Use with [apple/swift-log](https://github.com/apple/swift-log/)
Logging to multiple transports(e.g. console and syslog) as a backend for `apple/swift-log`.
```swift
import Puppylet console = ConsoleLogger("com.example.yourapp.console")
let syslog = SystemLogger("com.example.yourapp.syslog")var puppy = Puppy()
puppy.add(console)
puppy.add(syslog)LoggingSystem.bootstrap {
var handler = PuppyLogHandler(label: $0, puppy: puppy)
// Set the logging level.
handler.logLevel = .trace
return handler
}var log = Logger(label: "com.example.yourapp.swiftlog")
log.trace("TRACE message") // Will be logged.
log.debug("DEBUG message") // Will be logged.
```Here is a practical example of using `Puppy` with [Vapor](https://vapor.codes), which uses `apple/swift-log` internally.
```swift
import App
import Vapor // Vapor 4.67.4
import Puppylet fileURL = URL(fileURLWithPath: "./server-logs/bar.log").absoluteURL
let rotationConfig = RotationConfig(suffixExtension: .numbering,
maxFileSize: 30 * 1024 * 1024,
maxArchivedFilesCount: 5)
let fileRotation = try FileRotationLogger("com.example.yourapp.server",
fileURL: fileURL,
rotationConfig: rotationConfig)
var puppy = Puppy()
puppy.add(fileRotation)// https://docs.vapor.codes/basics/logging/
var env = try Environment.detect()
try LoggingSystem.bootstrap(from: &env) { (logLevel) -> (String) -> LogHandler in
return { label -> LogHandler in
var handler = PuppyLogHandler(label: label, puppy: puppy)
handler.logLevel = .info
return handler
}
}
let app = Application(env)
defer { app.shutdown() }
try configure(app)
try app.run()
```### Customize the logging format
Customize the log format using `Formattable` protocol. Logging to oslog for example.
```swift
import Puppyclass ViewController: UIViewController {
let logFormat = LogFormatter()
let oslog = OSLogger("com.yourapp.oslog", logFormat: logFormat)override func viewDidLoad() {
super.viewDidLoad()
var log = Puppy()
log.add(oslog)
log.info("INFO message")
log.warning("WARNING message")
}
}struct LogFormatter: LogFormattable {
private let dateFormat = DateFormatter()init() {
dateFormat.dateFormat = "yyyy-MM-dd'T'HH:mm:ss.SSSZZZZZ"
}func formatMessage(_ level: LogLevel, message: String, tag: String, function: String,
file: String, line: UInt, swiftLogInfo: [String : String],
label: String, date: Date, threadID: UInt64) -> String {
let date = dateFormatter(date, withFormatter: dateFormat)
let fileName = fileName(file)
let moduleName = moduleName(file)
return "\(date) \(threadID) [\(level.emoji) \(level)] \(swiftLogInfo) \(moduleName)/\(fileName)#L.\(line) \(function) \(message)".colorize(level.color)
}
}
```### Create a custom logger
You can also create your own custom logger. The custom logger needs to conform to `Loggerable` protocol.
```swift
@preconcurrency import Dispatch
import Puppypublic struct CustomLogger: Loggerable {
public let label: String
public let queue: DispatchQueue
public let logLevel: LogLevel
public let logFormat: LogFormattable?public init(_ label: String, logLevel: LogLevel = .trace, logFormat: LogFormattable? = nil) {
self.label = label
self.queue = DispatchQueue(label: label)
self.logLevel = logLevel
self.logFormat = logFormat
}public func log(_ level: LogLevel, string: String) {
// Implements the logging feature here.
}
}
```## License
Puppy is available under the [MIT license](http://www.opensource.org/licenses/mit-license). See the LICENSE file for details.