Swiftpack.co - Package - tonystone/tracelog

⚡️ Stay tuned for updates: upcoming version 5.0.0 (currently in beta)

Please star this github repository to stay up to date.

TraceLog license: Apache 2.0

Platforms: iOS | macOS | watchOS | tvOS | Linux Swift 5.0 Version Build Status   Codecov

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

  • [x] Quick and easy to get started.
  • [x] Fully configurable.
  • [x] Message filtering.
  • [x] Logging Levels (error, warning, info, trace1, trace2, trace3, trace4).
  • [x] Custom tag support for message grouping and filtering.
  • [x] Dynamically configurable levels via the OS environment at run time or inline code compiled into the application.
  • [x] Installable log writers (multiple writers at a time)
  • [x] Create custom log writers for any use-case.
  • [x] 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
  • [x] 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.
  • [x] Create custom output formatters for any use case.
  • [x] 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.
  • [x] Multi-language: Swift and Objective-C support.
  • [x] 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

| Platform | Version | Swift | Swift Build | Xcode | |:--------:|:--------------------------:|:-----:|:-----------:|:----------:| | Linux | Ubuntu 14.04, 16.04, 16.10 | 5.0 | ✔ | ✘ | | OSX | 10.13 | 5.0 | ✔ | Xcode 10.x |

Minimum Runtime Version

| iOS | OS X | tvOS | watchOS | Linux | |:---:|:-----:|:----:|:-------:|:--------------------------:| | 9.0 | 10.13 | 9.0 | 2.0 | Ubuntu 14.04, 16.04, 16.10 |

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

Github

link
Stars: 33
Help us keep the lights on

Dependencies

Releases

5.0.0-beta.2 - Mar 4, 2019

Added

  • Added extensive HTML documentation including user guides and a complete API reference.

Changed

  • Renamed AsyncOption to AsyncConcurrencyModeOption.
  • Changed OutputStreamFormatter, it now requires var encoding: String.Encoding { get }.
  • Renamed FileWriter.FileStrategy to FileWriter.Strategy.
  • Renamed FileWriter.Strategy.RotateOption to FileWriter.Strategy.RotationOption.

Updated

  • TextFormat to add var encoding: String.Encoding { get } requirement.
  • JSONFormat to add var encoding: String.Encoding { get } requirement.

5.0.0-beta.1 - Feb 25, 2019

Added

  • Added OutputStreamFormatter protocol to define formatters for use with byte output stream type Writers.
  • Added TextFormat, an implementation of a OutputStreamFormatter that formats its output based on a supplied template (this is the default formatter for Console and File output).
  • Added JSONFormat, an implementation of a OutputStreamFormatter that formats its output in standard JSON format.
  • Added OutputStreamWriter protocol to define types that write byte streams to their output and accept OutputStreamFormatter types to format the output.
  • Added LogEntry tuple type to Writer defining the formal types that a Writer writes.
  • Added .buffer option for .async concurrency modes to allow for buffering when the writer is not available to write to its endpoint.

Changed

  • Requires Swift 5 for compilation.
  • Changed parameters to .async to include options for configuration of the mode (.async(options: Set<AsyncOption>) and .async(Writer, options: Set<AsyncOption>)).
  • Changed Writer protocol log() method to write(_ entry: Writer.LogEntry) to make it easier to process messages by writers and formatters.
  • Changed Writer return to Swift.Result<Int, FailedReason> to return instructions for TraceLog for buffering and error recovery.
  • Changed ConsoleWriter to accept new OutputStreamFormatter instances allowing you to customize the output log format (default is TextFormat.)
  • Changed FileWriter public interface
    • FileWriter now requires the log directory be passed in, removing default value of ./.
    • Removed the fileConfiguration parameter replacing with new strategy enum.
    • It now accepts the new OutputStreamFormatter instances allowing you to customize the output log format (default is TextFormat.)
  • Changed FileWriter archive file name date format to "yyyyMMdd-HHmm-ss-SSS" (This was done for maximum compatibility between platforms and can be overridden in the FileConfiguration object passed at init.)

Removed

  • Removed TraceLogTestHarness module.

Fixed

  • Fixed logTrace when no trace level is passed. It's now the correct default value of 1 instead of 4 (issue #58).

4.0.1 - Sep 10, 2018

Fixed

  • Adding missing newline to ConsoleWriter output (issue #55).

4.0.0 - Sep 6, 2018

Added

  • Added mode to TraceLog.configuration to allow direct, async, or sync mode of operation. Sync & direct mode are useful for use cases that have short-lived processes (scripts) or require real-time logging.
  • Added ability to set the concurrency mode individually for each Writer.
  • Added FileWriter class for writing to local log files.
  • Added TestHarness to assist developers in testing their own Writer types.
  • Added shell utility to assist in testing Writer types.
  • Added TraceLogTestTools module/library to allow use of new TestHarness and other Utilities.

Removed

  • Removed all Xcode projects, Xcode projects are now generated using Swift Package Manager.
  • Dropped iOS 8 support.

4.0.0-beta.3 - Jul 6, 2018

Added

  • Added FileWriter class for writing to local log files.