Simple iOS managed logging library in Objective-C.

NRGLog uses standard NSLog() function so you should not redefine this macro by yourself.

Adding NRGLog to your project

Source files

Alternatively you can directly add the NRGLog.h and NRGLog.m source files to your project.

1. Download the latest code version or add the repository as a git submodule to your git-tracked project.
2. Open your project in Xcode, then drag and drop NRGLog.h and NRGLog.m onto your project (use the "Product Navigator view"). Make sure to select Copy items when asked if you extracted the code archive outside of your project.
3. Include NRGLog wherever you need it with #import "NRGLog.h".

Usage

All your code can be separated on the virtual groups, for example, network requests, UI animation cases, etc. NRGLog helps you to log these parts independently with the single NRGLog management code.

// define your tokens
#define LOG_TOKEN_NETWORK @"network"

// log
[NRGLog logToken:LOG_TOKEN_NETWORK format:@"My network request RAW: %@", yourRaw];

Tokens and Groups

There are difference between token phrases and token groups.

• Token is an exact phrase that identifies your actions logical group.
• Group of tokens is a physical group which allows you to enable or disable your several tokens at the same time.

Let's see how it works.

It's strongly recommended to define your tokens and groups in a separated header file, for example, NRGLogWrapper.h.

Let your app working with network, so it can send requests and receive responses. Also you may want to manage network connection state. It is convenient to make three separated tokens for each action (request and response) and group them into networking group.

This is how it can be implemented with my recommendations:

#ifndef NRGLOGWRAPPER_H
#define NRGLOGWRAPPER_H

#pragma mark - Groups

// networking
#define LOG_GROUP_NETWORK       @"network"
#define LOG_GROUP_NETWORK_QUERY LOG_GROUP_NETWORK ".query"

#pragma mark - Tokens

// networking
#define LOG_TOKEN_NETWORK_CONNECTION     LOG_GROUP_NETWORK ".connection"
#define LOG_TOKEN_NETWORK_QUERY_REQUEST  LOG_GROUP_NETWORK_QUERY ".request"
#define LOG_TOKEN_NETWORK_QUERY_RESPONSE LOG_GROUP_NETWORK_QUERY ".response"

#endif

Now you have two groups, one of them is a sub-group of another, and three tokens in these groups. It's simple to use this configuration:

[NRGLog logToken:LOG_TOKEN_NETWORK_CONNECTION 
          format:@"Connection established."];
[NRGLog logToken:LOG_TOKEN_NETWORK_QUERY_REQUEST 
          format:@"Request sent: %@", requestRaw];
[NRGLog logToken:LOG_TOKEN_NETWORK_QUERY_RESPONSE 
          format:@"Response received: %@ (error: %@)", responseRaw, error];

The main benefit of joining your tokens into groups is that you can disable any group at any moment, and all your token phrases which contains a specified group name in their names will not be printed in logs until you enable this group again.

For example, this code line

[[NRGLog instance] setTokenGroup:LOG_GROUP_NETWORK_QUERY enabled:NO];

will disable tokens LOG_TOKEN_NETWORK_QUERY_REQUEST and LOG_TOKEN_NETWORK_QUERY_RESPONSE, but will not disable global network group, so token LOG_TOKEN_NETWORK_CONNECTION will be accessible.

You are free to use exact token phrases without groups if this is more convenient for you, but it is strongly recommended to use groups for more flexible logging management.

Additional Abilities

You can configure NRGLog messages display mode by setting custom bitmask options for the options property. Here are all available values:

• NRGLogOptionNone - means no options enabled. NRGLog will display simple messages with your format strings and arguments, no more. It equals zero and added just for convenient naming.
• NRGLogOptionDisplayToken - if enabled, token name will be printed before each log message.
• NRGLogOptionDisplayMethod - prints a method which is currently executing.

Note that all these options are enabled by default.

The shortest configuration with no options set will print this:

// in your global configuration file, or, for example, in AppDelegate.m
[NRGLog instance].options = NRGLogOptionNone;

// then somewhere in your code
[NRGLog logToken:LOG_TOKEN_NETWORK_CONNECTION format:@"Connection established."];

Console output:

| Connection established.

Now let's compare this with all options enabled:

[NRGLog logToken:LOG_TOKEN_NETWORK_CONNECTION format:@"Connection established."];

Console output:

| network.connection | [AppDelegate application:didFinishLaunchingWithOptions:] | Connection established.

Note that you can change your logging options configuration at any time, it will affect only the future logToken:format: method calls.

Thread Safety

NRGLog is completely thread safe, you are free to use it in your asynchronous threads. Just remember that NRGLog uses standard NSLog() function, so do not forget to disable global logging by disabling loggingEnabled property on a production project scheme to avoid performance issues.

License

Apache. See LICENSE for details.