TraceLog

Introduction

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.

TraceLog Design Philosophy

1. Universal: With TraceLog you are not locked into one type of logging system, as a matter of fact, you can choose to use a combination of log writers to write to various endpoints and systems.
2. Flexible: With TraceLog you can filter messages dynamically at run time or statically at compile time. Choose whatever combination of Writers and filters that work for your particular use case. Write your own custom Writers to plug into TraceLog for customized use-cases.
3. Portable: At this writing, TraceLog is one of the few logging systems that was designed to run on all swift supported platforms (Linux, macOs, iOS, tvOS, and watchOS) and be used in multiple languages (Swift and Objective-C).
4. Lightweight: TraceLog's footprint is small and efficient. It's designed and meant to be as efficient on resources as can be and also optimize itself out if required by the use case.
5. Easy to use: TraceLog can be used right out of the box with No setup or special dependencies. That was designed in, and we've worked hard to maintain that over the years. You can literally link to it and start adding log statements to your app and get useful output on any platform.

Features

• Quick and easy to get started.
• Fully configurable.
• Message filtering.
• Logging Levels (error, warning, info, trace1, trace2, trace3, trace4).
• Custom tag support for message grouping and filtering.
• Dynamically configurable levels via the OS environment at run time or inline code compiled into the application.
• Installable log writers (multiple writers at a time)
• Create custom log writers for any use-case.
• Predefined log writers to write to various endpoints.
  • Built-in (OutputStreamWriters)
    • Stdout (ConsoleWriter) - A simple standard out (stdout) writer for logging to the console or terminal.
    • File (FileWriter) - A file writer which writes log output to files on local disk managing rotation and archive of files as needed.
  • External
    • Apple Unified Logging (AdaptiveWriter) - On Apple platforms the AdaptiveWriter writes to the Unified Logging System (see https://github.com/tonystone/tracelog-adaptive-writer).
    • Linux systemd Journal (AdaptiveWriter) - On Linux platforms the AdaptiveWriter writes to the systemd journal (see https://github.com/tonystone/tracelog-adaptive-writer)
• Output formatters for formatting the log entries in any format required.
  • TextFormat a customizable human readable text formatter useable with any OutputStreamWriter.
  • JSONFormat a customizable JSON string formatter usable with any OutputStreamWriter.
• Create custom output formatters for any use case.
• An output buffering mode to buffer output when a writer is unavailable (e.g. on iOS when protected data is not available).
• Multiple concurrency modes for writing to Writers. Settable globally or per Writer installed.
  • direct - straight through real-time logging.
  • sync - blocking queued logging.
  • async - background thread logging.
• Multi-language: Swift and Objective-C support.
• Portable: Linux, macOS, iOS, tvOS, WatchOS

Documentation

• User Guides & Reference - Extensive user guides and reference documentation! 100% documented API, full examples and many hidden details.

Quick Start Guide

Using TraceLog is incredibly simple out of the box. Although TraceLog is highly configurable, to get started all you have to do is add the pod to your project, import TraceLog to the files that require logging and start adding log statements where you need them. TraceLog initializes itself and does everything else for you.

Add TraceLog to your project

In your Podfile add TraceLog.

    target 'MyApp'

    pod "TraceLog", '~>5.0'

If you have mixed Swift and Objective-C code, you must specify the subspec to enable Objective-C as follows:

    target 'MyApp'

    pod "TraceLog", '~>5.0'
    pod "TraceLog/ObjC", '~>5.0'

Import TraceLog and Start logging

Import TraceLog into you files and start logging.

    import TraceLog

    struct MyStruct {

        func doSomething() {

            logInfo { "A simple TraceLog Test message" }
        }
    }

Log Functions

TraceLog has the following primary logging functions to log various levels of information. The output of these can be controlled via the environment variables at runtime or programmatically at application startup via the TraceLog.configure() func.

    logError  (tag: String?, message: @escaping () -> String)
    logWarning(tag: String?, message: @escaping () -> String)
    logInfo   (tag: String?, message: @escaping () -> String)
    logTrace  (tag: String?, level: UInt, message: @escaping () -> String)
    logTrace  (level: UInt, @escaping message: () -> String)

Note: hidden parameters and defaults were omitted for simplicity.

Basic Configuration

Although not strictly require, calling the TraceLog.configure() command at startup will allow TraceLog to read the environment for configuration information.

Simply call configure with no parameters as early as possible in your startup code (preferably before ay log statements get called.)

    TraceLog.configure()

For a complete documentation set including user guides, a 100% documented API reference and many more examples, please see https://tonystone.io/tracelog.

Runtime Overhead

The Swift implementation was designed to take advantage of swift compiler optimizations and will incur no overhead when compiled with optimization on (-O) and TRACELOG_DISABLED is defined.

The Objective-C implementation was designed to take advantage of the preprocessor and when compiled with TRACELOG_DISABLED defined, will incur no overhead in the application.

For XCode TRACELOG_DISABLED can be set in the project target. For Swift Package Manager pass a swiftc directive to swift build as in the following example.

swift build -Xswiftc -DTRACELOG_DISABLED

Minimum Requirements

Build Environment

Minimum Runtime Version

Note:

To build and run on Linux we have a a pre-configured Vagrant file located at https://github.com/tonystone/vagrant-swift

See the README for instructions.

Installation (Swift Package Manager)

TraceLog now supports dependency management via Swift Package Manager on All Apple OS variants as well as Linux.

Please see Swift Package Manager for further information.

Installation (CocoaPods)

TraceLog is available through CocoaPods. See the Quick Start Guide for installing through CocoaPods.

See the "Using CocoaPods" guide for more information on CocoaPods itself.

Author

Tony Stone (https://github.com/tonystone)

License

TraceLog is released under the Apache License, Version 2.0