A lightweight logging framework for Swift

Overview

Kitura

APIDoc Build Status - Master codecov macOS Linux Apache 2 Slack Status

HeliumLogger

Provides a lightweight logging implementation for Swift which logs to standard output.

Features

Usage

Add dependencies

Add the HeliumLogger package to the dependencies within your application’s Package.swift file. Substitute "x.x.x" with the latest HeliumLogger release.

.package(url: "https://github.com/Kitura/HeliumLogger.git", from: "x.x.x")

Add HeliumLogger to your target's dependencies:

.target(name: "example", dependencies: ["HeliumLogger"]),

Import packages

To use with LoggerAPI:

import HeliumLogger
import LoggerAPI

To use with swift-log:

import HeliumLogger
import Logging

Initialize HeliumLogger

To use HeliumLogger as a logging backend for LoggerAPI:

let logger = HeliumLogger()
Log.logger = logger

or, if you don't need to customize HeliumLogger:

HeliumLogger.use()

To use HeliumLogger as a logging backend for swift-log:

let logger = HeliumLogger()
LoggingSystem.bootstrap(logger.makeLogHandler)

Or, as a convenience:

HeliumLogger.bootstrapSwiftLog()

Logging levels

You can specify the level of output on initialization. You will see output of that level, and all levels below that.

The order is:

  1. entry (entering a function)
  2. exit (exiting a function)
  3. debug
  4. verbose (default)
  5. info
  6. warning
  7. error

For example, this logger will show messages of type verbose, info, warning, and error:

let logger = HeliumLogger(.verbose)
Log.logger = logger

In this example, the logger will only show messages of type warning and error:

HeliumLogger.use(.warning)

Note that when HeliumLogger is used in conjunction with swift-log, the logging level is determined by the Logger, and HeliumLogger's own logging level is unused.

Adjust logging levels at runtime (LoggerAPI)

Calling HeliumLogger.use(LoggerMessageType) will set the LoggerAPI to use this new HeliumLogger instance. If in a route you detect an error with your application, you could use this to dynamically increase the log level.

This new instance will not have any customization which you applied to other instances (see list item 7).

Logging messages (LoggerAPI)

How to use HeliumLogger to log messages in your application with LoggerAPI:

Log.verbose("This is a verbose log message.")

Log.info("This is an informational log message.")

Log.warning("This is a warning.")

Log.error("This is an error.")

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

Further customization

/// Whether, if true, or not the logger output should be colorized.
public var colored: Bool = false

/// If true, use the detailed format when a user logging format wasn't specified.
public var details: Bool = true

/// If true, use the full file path, not just the filename.
public var fullFilePath: Bool = false

/// If not nil, specifies the user specified logging format.
/// For example: "[(%date)] [(%type)] [(%file):(%line) (%func)] (%msg)"
public var format: String?

/// If not nil, specifies the format used when adding the date and the time to the logged messages.
public var dateFormat: String?

/// If not nil, specifies the timezone used in the date time format.
public var timeZone: TimeZone?

API documentation

For more information visit our API reference.

Community

We love to talk server-side Swift, and Kitura. Join our Slack to meet the team!

License

This library is licensed under Apache 2.0. Full license text is available in LICENSE.

Comments
  • The dependency graph could not be satisfied (https://github.com/IBM-Swift/HeliumLogger.git)

    The dependency graph could not be satisfied (https://github.com/IBM-Swift/HeliumLogger.git)

    I'm getting that error when trying to do swift package generate-xcodeproj The xcode project is not updating after adding a coachDB package dependency. Any idea??

    opened by penacristian 10
  • IBM-Swift/Kitura#922 Enhance features and performance of HeliumLogger

    IBM-Swift/Kitura#922 Enhance features and performance of HeliumLogger

    Description

    Enhance features and performance of HeliumLogger (IBM-Swift/Kitura#922)

    Motivation and Context

    • Currently HeliumLogger's detailed and basic default formats do not log date/time, which should be logged by default.
    • HeliumLogger formats the log message using multiple calls of string.replacingOccurrences(of). The same thing can be done much more efficiently using string interpolation or appending pre-parsed log segments.
    • The default date format is "dd.MM.YYYY, HH:mm:ss". It should be in line with standard date formatting and use "yyyy-MM-dd'T'HH:mm:ss.SSS"
    • Currently the check if we actually need to log based on the log level is done at the end. It should be the first thing we check
    • Getting the filename from the filepath is currently done by creating a NSURL object. It is more efficient to use string.substring()
    • Give users the ability to specify the time zone for the date/time

    How Has This Been Tested?

    Logging a message a million times (commenting out the final print in log()) and checking the time taken: On linux running in docker I reliably got approximately:

    current master:
    Default: 406.472931027412 seconds
    
    This PR:
    Default: 6.76490998268127 seconds
    No details: 4.81400203704834 seconds
    User specified: 8.68355000019073 seconds
    

    On mac I reliably got approximately:

    current master:
    Default: 89.0834839940071 seconds
    
    This PR:
    Default: 10.601704955101 seconds
    No details: 7.9820299744606 seconds
    User specified: 14.4082700014114 seconds
    

    Checklist:

    • [ ] I have submitted a CLA form
    • [ ] If applicable, I have updated the documentation accordingly.
    • [ ] If applicable, I have added tests to cover my changes.
    opened by na-gupta 9
  • PackageDescription API v3 deprecation warning

    PackageDescription API v3 deprecation warning

    Compilation results in a warning from the compiler:

    warning: PackageDescription API v3 is deprecated and will be removed in the future;

    Swift Version: 4.1 Platform: macOS 10.14 Mojave HeliumLogger Version: 1.7.1

    opened by KyeMaloy97 7
  • Repair all links after transition away from IBM

    Repair all links after transition away from IBM

    Description

    After all of the README links relating to IBM have been removed. We may need to remove the CLA form from the pull request template as well, thoughts?

    Motivation and Context

    Fixes broken links for proper documentation

    How Has This Been Tested?

    No testing required

    Checklist:

    Is this CLA form necessary anymore? The email address just bounces now anyways

    • [x] I have submitted a CLA form
    • [x] If applicable, I have updated the documentation accordingly.
    • [x] If applicable, I have added tests to cover my changes.
    opened by ghost 6
  • import LoggerAPI is required too

    import LoggerAPI is required too

    The usage example:

    import HeliumLogger
    Log.logger = HeliumLogger()
    Log.verbose("This is a log message.")
    

    doesn't actually compile.

    import LoggerAPI
    

    is required too. Can we remove the requirement to import LoggerAPI?

    opened by ianpartridge 5
  • Add support for using HeliumLogger as a SwiftLog backend

    Add support for using HeliumLogger as a SwiftLog backend

    This adds support for using HeliumLogger as a SwiftLog backend.

    Description

    Bootstrap SwiftLog

    This makes it possible to bootstrap the SwiftLog logging system in a few different ways.

    Convenience API There is a convenience API to bootstrap SwiftLog using HeliumLogger.

    HeliumLogger.bootstrapSwiftLog()
    

    You may optionally customize the default HeliumLogger instance used with SwiftLog using a configuration closure.

    HeliumLogger.bootstrapSwiftLog { heliumLogger in
        heliumLogger.colored = true
    }
    

    LoggingSystem API

    You can bootstrap the SwiftLog logging system directly using a static factory method on HeliumLogger.

    LoggingSystem.bootstrap(HeliumLogger.makeLogHandler)
    

    Alternatively, you can bootstrap using an existing HeliumLogger instance. This allows for customization of the HeliumLogger instance.

    let heliumLogger = HeliumLogger()
    heliumLogger.colored = true
    
    LoggingSystem.bootstrap(heliumLogger.makeLogHandler)
    

    Using SwiftLog

    Once the logging system is bootstrapped, you can use SwiftLog's Logger as usual and HeliumLogger will be used to generate the output.

    var logger = Logger(label: "MyLogger")
    logger.logLevel = .trace
    logger.trace("This is a trace")
    

    Example output:

    [2019-07-09T20:06:41.779-07:00] [MyLogger] [trace] [TestSwiftLog.swift:50 testTrace()] This is a trace
    

    Motivation and Context

    SwiftLog is primarily an API package and needs SwiftLog-compatible logging backends.

    From SwiftLog:

    As the API has just launched, not many implementations exist yet. … This API package does actually include an overly simplistic and non-configurable logging backend implementation which simply writes all log messages to stdout.

    This adds a more mature logging backend to the SwiftLog ecosystem.

    How Has This Been Tested?

    I added an XCTestCase to test the SwiftLog implementation (TestSwiftLog.swift). These tests are primarily focused on exercising the new API and follows patterns from TestLogger.swift.

    All tests are passing on macOS and Linux using Swift 4 and Swift 5 toolchains.

    Impact on Existing Code

    There are no source-breaking changes to the public API.

    However, this does expand the surface area of the HeliumLogger API and introduces potential confusion by supporting two different logging APIs with inherent differences. For example:

    • HeliumLogger instances may be initialized using a LoggerMessageType that is ignored when used with SwiftLog.

    • HeliumLogger is a class with reference semantics. SwiftLog expects a Logger to have value semantics.

    • Log segments were added to HeliumLogger that are specific to SwiftLog (label / metadata).

    Longer term, it may make sense to create a generic logger package and provide separate packages for SwiftLog and LoggerAPI support, but this pull request aims to provide a much lower touch solution.

    Overall, I'm hoping that the benefits of supporting the SwiftLog API are worth these tradeoffs.

    Feedback welcome!

    cc @ianpartridge @djones6

    opened by wlisac 4
  • fail to staging swift application with latest 1.7.0 version

    fail to staging swift application with latest 1.7.0 version

    When running with the swift application https://github.com/IBM-Bluemix/Kitura-Starter, it is fine with HeliumLogger 1.6.x version.

    But if I use majorVersion directly, .Package(url: "https://github.com/IBM-Swift/HeliumLogger.git" , majorVersion: 1), then staging failed.

       Cloning https://github.com/IBM-Swift/HeliumLogger.git
       HEAD is now at 9b310ce IBM-Swift/Kitura#1047 Swift 3.1 changes
    

    swift-build: error: The dependency graph could not be satisfied (https://github.com/IBM-Swift/LoggerAPI.git) Failed to compile droplet Exit status 223 Staging failed: Exited with status 223 Destroying container Resolved version: 1.7.0 Successfully destroyed container

    opened by cdlliuy 4
  • Added HeliumStreamLogger + minor improvements

    Added HeliumStreamLogger + minor improvements

    Description

    Motivation and Context

    How Has This Been Tested?

    Checklist:

    • [ ] I have submitted a CLA form
    • [ ] If applicable, I have updated the documentation accordingly.
    • [ ] If applicable, I have added tests to cover my changes.
    opened by vadimeisenbergibm 4
  • Disable buffering on STDOUT for CF logs to show log messages

    Disable buffering on STDOUT for CF logs to show log messages

    Description

    This PR addresses the problem that CF logs does not produce output of our Log messages.

    Motivation and Context

    Bluemix does not output the Log messages. This is because of buffering. There is a reported fix that involves disabling buffering on standard out.

    How Has This Been Tested?

    This has not been tested yet because it involves an actual Bluemix deployment.

    Checklist:

    • [x] I have submitted a CLA form
    • [x] If applicable, I have updated the documentation accordingly.
    • [x] If applicable, I have added tests to cover my changes.

    In order for STDOUT to appear in Bluemix we need

    opened by rfdickerson 3
  • Logging filter levels, tests fix

    Logging filter levels, tests fix

    Added logging levels and fixed tests performing on Linux

    Motivation and Context

    For logging - IBM-Swift/Kitura#358

    How Has This Been Tested?

    Added test testLoggingLevels with filter level usage

    Checklist:

    • [x] I have submitted a CLA form
    • [ ] If applicable, I have updated the documentation accordingly.
    • [x] If applicable, I have added tests to cover my changes.
    opened by naithar 3
  • Change in PackageDescription

    Change in PackageDescription

    PackageDescription API has been changed from v3 to v4.

    -Addition of // swift-tools-version:4.2 line in the package. -Some syntactical changes to change the version of PackageDesciprtion form v3 to v4

    • [ ] I have submitted a CLA form
    • [ ] If applicable, I have updated the documentation accordingly.
    • [ ] If applicable, I have added tests to cover my changes.
    opened by arkeo01 2
  • feature: log swift queue name

    feature: log swift queue name

    In an app using multiple dispatch queues it may be worth logging current queue with every message.

    Would you be willing to accept a PR if I consider adding this support? I am using HeliumLogger in multiple server side swift projects and would be willing to open a PR.

    thanks for great and simple component...

    opened by mman 3
  • README does not describe how to set LOG_LEVEL when using with Swift-log

    README does not describe how to set LOG_LEVEL when using with Swift-log

    I am using the HeliumStreamLogger with Swift-log Logging. I followed the README and used LoggingSystem.bootstrap(myStreamlogger.makeLogHandler). The LogHandler created from the above has a hard-coded .info level and it took me a long time to work out how to change it. Maybe there are easier ways, but the following code works and I think it should be included in the README.

    var handler = myStreamLogger.makeHandler(label: "StreamLogger")
    handler.logLevel = .debug
    LoggingSystem.bootstrap({ name in {return handler})
    
    opened by peakman 2
Releases(2.0.0)
Owner
Kitura
Kitura - Server Side framework written in Swift
Kitura
JustLog brings logging on iOS to the next level. It supports console, file and remote Logstash logging via TCP socket with no effort. Support for logz.io available.

JustLog JustLog takes logging on iOS to the next level. It supports console, file and remote Logstash logging via TCP socket with no effort. Support f

Just Eat 509 Dec 10, 2022
A lightweight logging framework for Swift

HeliumLogger Provides a lightweight logging implementation for Swift which logs to standard output. Features Logs output to stdout by default. You can

Kitura 174 Nov 30, 2022
A lightweight logging framework for Swift

HeliumLogger Provides a lightweight logging implementation for Swift which logs to standard output. Features Logs output to stdout by default. You can

Kitura 174 Nov 30, 2022
Simple, lightweight and flexible debug logging framework written in Swift

AELog Simple, lightweight and flexible debug logging minion written in Swift If you find yourself in upcoming statements, then you probably want to us

Marko Tadić 28 Jul 6, 2022
CleanroomLogger provides an extensible Swift-based logging API that is simple, lightweight and performant

CleanroomLogger CleanroomLogger provides an extensible Swift-based logging API that is simple, lightweight and performant. The API provided by Cleanro

null 1.3k Dec 8, 2022
Willow is a powerful, yet lightweight logging library written in Swift.

Willow Willow is a powerful, yet lightweight logging library written in Swift. Features Requirements Migration Guides Communication Installation Cocoa

Nike Inc. 1.3k Nov 16, 2022
Spy is a flexible, lightweight, multiplatform logging utility written in pure Swift.

Spy is a flexible, lightweight, multiplatform logging utility written in pure Swift. It allows to log with different levels and on different channels. You can define what levels and channels actually are.

AppUnite Sp. z o.o. Spk. 12 Jul 28, 2021
An extensible logging framework for Swift

Log is a powerful logging framework that provides built-in themes and formatters, and a nice API to define your owns. Get the most out of Log by insta

Damien 825 Nov 6, 2022
A powerful input-agnostic swift logging framework made to speed up development with maximum readability.

The Swift logging framework. Atlantis is an extremely powerful logging framework that I've created for everyday use, including enterprise development

Andrew Aquino 199 Jan 2, 2023
A fast & simple, yet powerful & flexible logging framework for Mac and iOS

CocoaLumberjack CocoaLumberjack is a fast & simple, yet powerful & flexible logging framework for macOS, iOS, tvOS and watchOS. How to get started Fir

null 12.9k Jan 9, 2023
Convenient & secure logging during development & release in Swift 3, 4 & 5

Colorful, flexible, lightweight logging for Swift 3, Swift 4 & Swift 5. Great for development & release with support for Console, File & cloud platfor

SwiftyBeaver 5.6k Jan 4, 2023
Swift Logging Utility for Xcode & Google Docs

QorumLogs Swift Logging Utility in Xcode & Google Docs

Goktug Yilmaz 777 Jul 15, 2022
TraceLog is a highly configurable, flexible, portable, and simple to use debug logging system for Swift and Objective-C applications running on Linux, macOS, iOS, watchOS, and tvOS.

Please star this github repository to stay up to date. TraceLog Introduction TraceLog is a highly configurable, flexible, portable, and simple to use

Tony Stone 52 Oct 28, 2022
A flexible logging library written in Swift

Puppy Puppy is a flexible logging library written in Swift ?? It supports multiple transports(console, file, syslog, and oslog) as loggers. It not onl

Koichi Yokota 92 Dec 29, 2022
Logging utility for Swift and Objective C

Swell - Swift Logging A logging utility for Swift and Objective C. ##Features Turn on logging during development, turn them off when building for the

Hubert Rabago 361 Jun 29, 2022
Most natural Swift logging

Evergreen Most natural Swift logging Evergreen is a logging framework written in Swift. It is designed to work just as you would expect, yet so versat

Nils Leif Fischer 72 Aug 12, 2022
A simple logging package for Swift

OhMyLog OhMyLog is a simple logging package for Swift. It supports the following features: Six logging levels ( ?? , ?? , ?? , ⚠️ , ?? , ?? ) Display

Junhao Wang 1 Jan 10, 2022
Simple logging for simples needs.

Simple logging for simples needs.

native.dev.br 0 May 30, 2022
Class for logging excessive blocking on the main thread

Watchdog Class for logging excessive blocking on the main thread. It watches the main thread and checks if it doesn’t get blocked for more than define

Wojtek Lukaszuk 1.8k Dec 6, 2022