mudox/jac-kit

A scope based logger on top of CocoaLumberjack

JacKit

JacKit is a scope based logger inspired from Python logging module. It is based on the CocoaLumberjack framework.

Features

• Modern Swifty interface.
• Scope based logging control.
• Flexible & eye-saving console output formatting.
  • Common layout options
  • Merge contiguous logging with the same scope and level.
  • Significant interval separator.
• HTTP logger to make logging available outside Xcode.
• Common automatic logging
  • Launching reports
  • Application states change report
• Tmux integration

Installation

JacKit is currently not published.

pod 'JacKit' :git => 'https://github.com/mudox/jac-kit.git'

Usage

// NetworkService.swift

import JacKit

private let jack = Jack("MyApp.NetworkService")
  .set(level: .warning)      // Set severity level at a higher scope
  .set(format: .short)       // Set formatting optoins at a higher scope

class NetworkService {

  func request() {
    jack
      .descendant("request") // Lower scope "MyApp.NetworkService.request"
      .info("request ...")   // Message with severity level `.info`
  }

}

Scopes Explained

A scope is a string using reverse-DNS notation you use to represent arbitrary components in your project. For example:

// A method named `request` of class `NetworkService`.
MyApp.NetworkService.request

// A class `MainViewController` in your App project.
MyApp.MainViewController

// A method under from your framework project.
MyFramework.Component1.Class2.method3

Here

• MyFramework.Component1 is an ancestor of MyFramework.Component1.Class2.method3
• MyApp.NetworkService.request is a descendant of MyApp.

Descendants inherit scoped based behaviors from its nearest ancestor who have corresponding behavior set. You can explicitly set behaviors on a given descendant to override those inherited behaviors from upstream.

Each Jack instance is associated to a given scope when initialized.

Each Jack instance expose 2 important properties associated with its scope:

• Severity level.
• Formatting options.

They are computed properties, values assigned to are stored in a private shared place indexed by the scope string.

Behavior inheriting & overriding

Every time the property value is read, it is resolved under 3 cases:

• Explicitly set on current scope.

  // Scope have its severity level explicitly set to `.info`
  let jack = Jack("A.B.C")
  jack.set(level: .info)

• Inherit from parent scope.

  // Explicitly set severity level at higher scope.
  Jack("A").set(level: .warning)
  
  // This scope have its severity level inherited from ancetor "A".
  let jack = Jack("A.B.C")
  jack.debug("...") // This message will not be logged out.

• Use fallback value if no parent scope have this property set.

  // This scope and all its ancestor have not set the severity level.
  // Hence use the fallback value - `.verbose`
  let jack = Jack("A.B.C")
  jack.debug("...") // `.debug` is higher than the fallback level `.verbose`, messge get logged out.

Usage snippets

Use custom icon for one time.

jack.info("🌻 only use this icon for thismessage, format: .bare")

Use custom icon for multiple logging messages under same severity level.

let log = Jack("⛑ ").set(format: .noIcon).

jack.debug("some logging")

Author

Mudox

License

JacKit is available under the MIT license. See the LICENSE file for more info.