It might be a good idea to read Advanced Logging before continuing here. For a general overview of the concepts of NXLogging, read Architecture.
Unless you manually created a NXLogger instance, any of the standard loggers use the shared instances of NXSystemLogTarget and NXConsoleLogTarget for log output, which themselves employ the shared instances of NXSystemLogFormatter and NXDebugLogFormatter respectively.
The following examples will show the configuration of these shared instances of log targets and log formatters, but of course the configuration can as well be applied to any other compatible log target or formatter.
This chapter tells you all about
- Setting the log level threshold
- Configuring log information
- Managing log targets
- Logging to files
- Managing log formatters
- Logging in colors
You change the log level threshold of any log target with the maxLogLevel property. To e.g. change the log level threshold for the shared NXConsoleLogTarget to Warning, you would write in Objective C:
[NXConsoleLogTarget sharedInstance].maxLogLevel = NXLogLevelWarning;
and in Swift:
NXConsoleLogTarget.sharedInstance().maxLogLevel = .Warning
As an effect, log messages with the log levels Debug, Info and Notice will not be logged to this target.
If you want to silence a log target completely, assign None (NXLogLevelNone in Objective C, NXLogLevel.None in Swift). If, however, you want any log message to be logged to the target, you can assign Any (NXLogLevelAny in Objective C, NXLogLevel.Any in Swift).
Removing (or adding) information to the log is a task of the log formatter. All standard log formatters which come with NXLogging are sub classes of NXBasicLogFormatter and inherit its property NXLogInfo hiddenInfo
. This property is a bit mask representing the information that you wish not to be displayed in the log. The NXLogInfo enum is defined in the public header file NXLogTypes.h, where you will also find additional documentation. In Objective C, NXLogInfo is presented as a bitmask, in Swift as an OptionSetType.
If, e.g. you want all available information on your debug console (note, that this will lead to very long lines), you can achieve this in Objective C with:
[NXDebugLogFormatter sharedInstance].hiddenInfo = NXLogInfoNone;
and in Swift:
NXDebugLogFormatter.sharedInstance().hiddenInfo = .None
In the highly unlikely case, that you wish to log empty lines, you can assign NXLogLevelAll to the hiddenInfo property. More likely however is, that you will use the value All to hide everything but certain info. Let's say, e.g. that you want to hide everything but the Date, the log Level, and the actual Content (which is messages, errors and exceptions); then you would write in Objective C:
NXLogInfo visibleInfo = NXLogInfoDate | NXLogInfoLevel | NXLogInfoContent;
[NXDebugLogFormatter sharedInstance].hiddenInfo = NXLogInfoAll ^ visibleInfo;
and in Swift:
let visibleInfo : NXLogInfo = [ .Date, .Level, .Content ]
NXDebugLogFormatter.sharedInstance().hiddenInfo = NXLogInfo.All.exclusiveOr(visibleInfo)
Note, that in Objective C, you could also assign the bitwise complement ~visibleInfo
instead of the exclusive or NXLogInfoAll ^ visibleInfo
.
Instead of silencing a log target by setting its maxLogLevel property to None (see above), you can also remove it from the logger. Let's assume, you want to remove the console log target (NXConsoleLogTarget) from the standard logger (applicationLogger). In Objective C you would code:
[[NXLogger applicationLogger] removeLogTarget:[NXConsoleLogTarget sharedInstance]];
and in Swift:
NXLogger.applicationLogger().removeLogTarget(NXConsoleLogTarget.sharedInstance());
Of course, it's just as simple to add a log target. Just use addLogTarget instead of removeLogTarget. See also Logging to files.
Logging to files ----------------To log to a file, simply add a NXFileLogTarget to an existing logger, or create a new logger with such a target. In Objective C:
NXFileLogTarget *fileLogTarget = [NXFileLogTarget sharedInstance];
fileLogTarget.maxAge = 24 * 60 * 60;
fileLogTarget.maxSize = 1024 * 1024;
fileLogTarget.maxNumberOfFiles = 10;
[[NXLogger applicationLogger] addLogTarget:fileLogTarget];
and in Swift:
let fileLogTarget = NXFileLogTarget.sharedInstance()
fileLogTarget.maxAge = 24 * 60 * 60
fileLogTarget.maxSize = 1024 * 1024
fileLogTarget.maxNumberOfFiles = 10
NXLogger.applicationLogger().addLogTarget(fileLogTarget)
The sharedInstance of the NXFileLogTarget will log to the documents directory into a file with the same names as your application and the extension log. If you want to change the file, the target is logging to, use the filePath property. Note, that data protection (encryption) is not turned on for the log file. With the above configuration, the log file will be rolled over after a day or after it reaches a size of 1 MB, while a maximum of ten log files will be kept (the current log file plus nine historic files). A value of 0 (the default value) for maxAge, maxSize, and maxNumberOfFiles means unlimited file age, size and number respectively. When a log file is being rolled over, the log target will add a minus sign, followed by a timestamp to the old file's name and keep the extension log. Please note, that the sharedInstance of the NXFileLogTarget uses the sharedInstance of the NXDebugLogFormatter for formatting log output.
Warning: You can not use several log target instances with the same file (filePath property). You may however, use one log target instance in several loggers.
You can replace a log formatter simply by assigning it to the logFormatter property of a log target. This is how you format your log to JSON in Objective C:
NXJSONLogFormatter *jsonLogFormatter = [NXJSONLogFormatter sharedInstance];
jsonLogFormatter.prettyPrint = YES;
[NXConsoleLogTarget sharedInstance].logFormatter = jsonLogFormatter;
and in Swift:
let jsonLogFormatter = NXJSONLogFormatter.sharedInstance()
jsonLogFormatter.prettyPrint = true
NXConsoleLogTarget.sharedInstance().logFormatter = jsonLogFormatter
You can log to your Xcode debug console in colors. Since Xcode doesn't support colors in the console natively, we need the help of a Plug-in. Install XcodeColors. It's simple: Just pull it from GitHub, build the XcodeColors target, and restart Xcode. You can then enable a colorful log output in Objective C like this:
[NXConsoleLogTarget sharedInstance].colorsEnabled = YES;
and in Swift:
NXConsoleLogTarget.sharedInstance().colorsEnabled = true
You can also adjust the color used for every log level individually. To set the color for messages at level Notice to magenta, write the following in Objective C:
NXTextColor *magenta = [NXTextColor colorWithRed:255 green:0 blue:255];
[[NXConsoleLogTarget sharedInstance] setColor:magenta forLoglevel:NXLogLevelNotice];
and in Swift:
let magenta = NXTextColor(red: 255, green: 0, blue: 255)
NXConsoleLogTarget.sharedInstance().setColor(magenta, forLoglevel: .Notice)