Stenographer

Stenographer is a logging framework built to be simple to get started with, efficient to execute, safe for shipping code, and extensible for flexibility. It is written in pure Swift and is suitable for macOS, iOS, tvOS, and watchOS application logging. For a developer looking for more power than print(), Stenographer takes just a moment to get started with, and comes ready to log to the console, a file, an HTTP service, or all three. Need to log to somewhere else? Defining your own Endpoint is easy too.

Stenographer is a fork of LogKit.

Contents

• Features
• Requirements
• Installation
  • CocoaPods
  • Carthage
  • Embedded
  • Source
• Usage
  • Quick Start
  • Additional Endpoints
  • Formatting
• Contributing
• License

Features

• Simple setup
• [Comprehensive documentation][docs]
• Built-in Console, File, and HTTP [Endpoints][endpoints]
• Priority-filtering per Endpoint
• Complete Log Entry [format customization][formatting] per Endpoint
• Custom Endpoints via simple protocol conformance

Requirements

• Project targeting macOS 10.10+, iOS 8+, tvOS 9+, or watchOS 2+
• Xcode 10 and Swift 4.2

Installation

There are a few ways to install Stenographer. Below are some tips, but for full details, see the [installation guide][install].

Note: For some reason, CocoaPods removes the CocoaPods and Carthage installation instructions from this readme displayed on their website. Please visit the [installation guide][install] if you do not see these installation options.

CocoaPods

Supports iOS 8+, macOS 10.9+, tvOS 9+, watchOS 2+

Include Stenographer in your Podfile:

use_frameworks!
pod 'Stenographer', '~> 1.0'

For more information on getting started with CocoaPods, read the guide.

Carthage

Supports iOS 8+, macOS 10.9+, tvOS 9+, watchOS 2+

Include Stenographer in your Cartfile:

github "stenographer/stenographer" ~> 1.0

For more information on getting started with Carthage, visit the repo.

Embedded Framework

Supports iOS 8+, macOS 10.10+, tvOS 9+, watchOS 2+

Include Stenographer.xcodeproj within your project (second level, below your project root, as a sub-project). Select your target, and add Stenographer as an Embedded Binary in the General tab. Pick the appropriate Stenographer framework for your target’s OS. Be sure to select the framework, not the tests.

Source

Supports iOS 7+, macOS 10.10+, tvOS 9+, watchOS 2+

Integrating the Stenographer source is the only way to include Stenographer in projects targeting iOS 7. When this installation method is used, skip the import Stenographer.

Add all of the .swift files found in the Sources directory to your project. No other steps are necessary for installation.

Usage

Stenographer is easy to get started with. Everything comes with convenience initializers that require the bare minimum arguments (usually no arguments) and provide sensible defaults. Get started quickly, and then customize as desired later.

Use the Quick Start below to get started now, then check out the [usage guide][usage] for details of everything Stenographer can do.

Quick Start

Near the top of your AppDelegate.swift file, add the following two lines:

import Stenographer

let log = SXLogger()

This will import the Stenographer framework and create a global Logger instance. This Logger will initialize with a standard Console Endpoint set to log all messages in the default format. Since the Logger instance is created in the global scope, you should only create it once (AppDelegate.swift is the best place).

You can now log from anywhere in your project:

log.info("Hello Internet!")

// 2015-06-25 07:36:01.638000 [INFO] applicationDidFinishLaunching <AppDelegate.swift:23> Hello Internet!

Now you’re logging! You can use the debug, info, notice, warning, error, and critical Logger methods.

Additional Endpoints

If you wanted to log to a file as well as the console, and you wanted the file to only receive notice and higher Log Entries, you could set your logger up like this:

import Stenographer

let log = SXLogger(endpoints: [

    SXConsoleEndpoint(),

    SXFileEndpoint(
        fileURL: NSURL(string: /* Path to your log file */),
        minimumPriorityLevel: .Notice
    ),

])

You can add and configure as many [Endpoints][endpoints] as desired, such as the included File and HTTP Service Endpoints. You can also completely [customize the format][formatting] in which Log Entries are written to each Endpoint.

Formatting

Each Endpoint has a property named dateFormatter that controls how an Entry’s dateTime property will be formatted. It accepts an SXDateFormatter instance and is usually set at initialization time.

let log = SXLogger(endpoints: [

    SXConsoleEndpoint(
        dateFormatter = SXDateFormatter(formatString: "HH:mm:ss.SSS")
    ),

])

Each Endpoint also has a property named entryFormatter that controls how an Entry will be converted to a string for output. It accepts an SXEntryFormatter instance and is also usually set at initialization time.

let log = SXLogger(endpoints: [

    SXConsoleEndpoint(
        entryFormatter = SXEntryFormatter({ entry in
            return "\(entry.dateTime) [\(entry.level.uppercaseString)] \(entry.message)"
        })
    ),

])

See the [Entry Formatting documentation][formatting] for more details on formatting, available Log Entry properties, and SXEntryFormatter.

Contributing

Stenographer welcomes contributions.

License

Stenographer is licensed under the permissive ISC License.