fpillet/NSLogger

NSLogger

NSLogger is a high performance logging utility which displays traces emitted by client applications running on macOS, iOS and Android. It replaces traditional console logging traces (NSLog(), Java Log).

The NSLogger Viewer runs on macOS and replaces Xcode, Android Studio or Eclipse consoles. It provides powerful additions like display filtering, defining log domain and level, image and binary logging, message coloring, traces buffering, timing information, link with source code, etc.

NSLogger feature summary:

• View logs using the desktop application
• Logs can be sent from device or simulator
• Accept connections from local network clients (using Bonjour) or remote clients connecting directly over the internet
• Online (application running and connected to NSLogger) and offline (saved logs) log viewing
• Buffer all traces in memory or in a file, send them over to viewer when a connection is acquired
• Define a log domain (app, view, model, controller, network…) and an importance level (error, warning, debug, noise…)
• Color the log messages using regexp
• Log images or raw binary data
• Secure logging (connections use SSL by default)
• Advanced log filtering options
• Save viewer logs to share them and/or review them later
• Export logs to text files
• Open raw buffered traces files that you brought back from client applications not directly connected to the log viewer

Here is what it looks like in action:

And with macOS Mojave and later's dark mode:

Basic Usage

Without any change to your code, all the NSLog() logs from your application are redirected to the NSLogger desktop viewer. The viewer is found automatically on your network, using Bonjour.

A rich API lets you log messages, binary data or images with a lot of detail. Simple wrappers are available for your convenience:

Swift wrapper API:

import NSLogger

[…]

// logging some messages
Logger.shared.log(.network, .info, "Checking paper level…")

// logging image
Logger.shared.log(.view, .noise, myPrettyImage)

// logging data
Logger.shared.log(.custom("My Domain"), .noise, someDataObject)

Objective-C wrapper API:

#import <NSLogger/NSLogger.h>

[…]

LoggerApp(1, @"Hello world! Today is: %@", [self myDate]);
LoggerNetwork(1, @"Hello world! Today is: %@", [self myDate]);

Installation

• Step 1. Download the NSLogger desktop app on your Mac.
• Step 2. Add the NSLogger framework to your project.
• Step 3. There is no step 3…

Desktop Viewer Download

Download the pre-built, signed version of the NSLogger desktop viewer for macOS. Don't forget to launch the application on your Mac. It won't show a window until a client connects to it and starts logging.

Client Framework Install

CocoaPods Install

If your project is configured to use CocoaPods, just add this line to your Podfile:

pod "NSLogger"

The above only includes C and Obj-C APIs and is suitable for use in applications without any Swift code. Swift syntactic sugar APIs are added with the Swift subspec. If you're developing code in Swift or a mixed Swift / Obj-C environment, use:

pod "NSLogger/Swift"

Note that you don't strictly need to include the /Swift variant for your Swift applications. You can perfectly develop your own extensions that call into NSLogger's C APIs without using the basic provided ones.

Finally if you are using frameworks or libraries that may use NSLogger, then you can use the NoStrip variant which forces the linker to keep all NSLogger functions in the final build, even those that your code doesn't use. Since linked in frameworks may dynamically check for the presence of NSLogger functions, this is required as the linker wouldn't see this use.

pod "NSLogger/NoStrip"

Carthage Install

NSLogger is Carthage-compatible. It builds two frameworks: NSLogger and NSLoggerSwift. You'll need to pick either one (but not both) to use in your application. Both can be used with Swift, the NSLoggerSwift variant adds a simple Swift layer to make NSLogger easier to use from Swift code. You can perfectly develop your own extensions that call into NSLogger's C APIs without using the basic provided ones, and just use the NSLogger framework.

Depending on the framework you choose, your code will need to import NSLogger or import NSLoggerSwift. This is a difference with Cocoapods support where you always import NSLogger.

github "fpillet/NSLogger"

Then run:

$ carthage update

Again, the NSLogger.xcodeproj top-level project offers two targets (NSLogger and NSLoggerSwift). Add the built framework that suits your needs.

Network Support for iOS 14+

Since iOS 14, apps have to request permission to access your local network. To enable NSLogger for iOS 14, you have to update your Info.plist for development builds to include the following:

<key>NSBonjourServices</key>
<array>
  <string>_nslogger._tcp</string>
  <string>_nslogger-ssl._tcp</string>
</array>
<key>NSLocalNetworkUsageDescription</key>
<string>Access to the local network for development builds</string>

Advanced Usage

Using NSLogger on a Shared Network

The first log sent by NSLogger will start the logger, by default on the first Bonjour service encountered. But when multiple NSLogger users share the same network, logger connections can get mixed.

To avoid confusion between users, just add this when you app starts (for example, in the applicationDidFinishLaunching method:

LoggerSetupBonjourForBuildUser();

Then, in the Preferences pane of the NSLogger.app desktop viewer, go to the Network tab. Type your user name (i.e. $USER) in the "Bonjour service name" text field.

This will allow the traces to be received only by the computer of the user who compiled the app.

This only work when NSLogger has been added to your project using CocoaPods.

Set up logger options

For example if you don't want to disable OS_ACTIVITY_MODE for your scheme because you need that logs. And you wanna have only your logs in NSLogger in Swift call init function:

func LoggerInit() {
    let pointer = LoggerGetDefaultLogger()
    var options = LoggerGetOptions(pointer)
    
    options ^= UInt32(kLoggerOption_CaptureSystemConsole) // disable that option
    
    LoggerSetOptions(pointer, options)
}

Manual Framework Install

When using NSLogger without CocoaPods, add LoggerClient.h, LoggerClient.m and LoggerCommon.h (as well as add the CFNetwork.framework and SystemConfiguration.framework frameworks) to your iOS or Mac OS X application, then replace your NSLog() calls with LogMessageCompat() calls. We recommend using a macro, so you can turn off logs when building the distribution version of your application.

How Does the Connection Work?

For automatic discovery of the desktop viewer, your application must run on a device that is on the same network as your Mac. When your app starts logging, the NSLogger framework automatically (by default) looks for the desktop viewer using Bonjour. As soon as traces start coming, a new window will open on your Mac.

Advanced users can setup a Remote Host / Port to log from a client to a specific host), or specify a Bonjour name in case there are multiple viewers on the network.

Advanced Desktop Viewer Features

The desktop viewer application provides tools like:

• Filters (with regular expression matching) that let your perform data mining in your logs
• Timing information: each message displays the time elapsed since the previous message in the filtered display, so you can get a sense of time between events in your application.
• Image and binary data display directly in the log window
• Markers (when a client is connected, place a marker at the end of a log to clearly see what happens afterwards, for example place a marker before pressing a button in your application)
• Fast navigation in your logs
• Display and export all your logs as text
• Optional display of file, line and function for uncluttered display

Your logs can be saved to a .nsloggerdata file, and reloaded later. When logging to a file, name your log file with extension .rawnsloggerdata so NSLogger can reopen and process it. You can have clients remotely generating raw logger data files, then send them to you so you can investigate post-mortem.

Note that the NSLogger Mac OS X viewer requires Mac OS X 10.6 or later.

Advanced Colors Configuration

Apply colors to tags and messages using regular expressions.

To define the color, you can use:

• A standard NSColor name, for example: blue
• Hex colors, for example: #DEAD88
• You can add the prefix bold, for example: bold red

High Performance, Low Overhead

The NSLogger framework runs in its own thread in your application. It tries hard to consume as few CPU and memory as possible. If the desktop viewer has not been found yet, your traces can be buffered in memory until a connection is acquired. This allows for tracing in difficult situations, for example device wakeup times when the network connection is not up and running.

Credits

NSLogger is Copyright (c) 2010-2018 Florent Pillet, All Rights Reserved, All Wrongs Revenged. Released under the New BSD Licence. The NSLogger icon is Copyright (c) Louis Harboe