Inherits from NSObject
Declared in SOLogger.h
SOLogger.m

Overview

SOLogger implements a Cocoa API for logging messages using the Apple System Logging (ASL) service.

Features

  • methods for logging formatted messages at the various severity levels.
  • logs messages simultaneously to additional file, pipe, and socket descriptors.
  • can use a single logger from multiple threads.

SOLogger and Threads

An SOLogger interacts with the ASL service through a separate connection per thread. The connection is opened using asl_open() and configured with the logger’s current severity filtering mask and list of additional logging descriptors.

When severityFilterMask or additionalDescriptors is changed on the logger, all associated ASL connections are also updated.

Tasks

Initialization

ASL primitive

Logging messages

Logging to external files

Properties

Properties

additionalDescriptors

The logger’s set of registered external logging descriptors.

@property (nonatomic, readonly) NSSet *additionalDescriptors

Discussion

Each descriptor is represented as an NSNumber.

Declared In

SOLogger.h

facility

The facility identifier.

@property (nonatomic, readonly) NSString *facility

Discussion

Use facility to give the logger a name. If you’re using a dedicated logger for a subsystem, you might name the subsystem, using that name as the logger’s facility value.

Recommended practice is to follow a “reverse DNS notation” style for facility names to avoid namespace collection in ASL among other loggers.

Declared In

SOLogger.h

options

ASL connection options.

@property (nonatomic, readonly) uint32_t options

Discussion

The options value used when opening a connection to the ASL service via asl_open(). The value is a bitwise OR of the following:

ASL_OPT_STDERR : Also log messages to stderr (required for viewing messages in Xcode console).

ASL_OPT_NO_DELAY : Connect immediately to the ASL service.

ASL_OPT_NO_REMOTE : Ignore any remote severity level filtering settings, using only our own severityFilterMask value for filtering.

Declared In

SOLogger.h

severityFilterMask

The logger’s severity level filtering mask.

@property (nonatomic, assign) int severityFilterMask

Discussion

A mask value defining a filter of messages to be sent to the ASL database by their severity level. Use the asl(3) macro ASL_FILTER_MASK_UPTO() to obtain an appropriate filtering mask value.

Examples

To configure the logger to limit logging of messages to a range of the most severe up to the NOTICE level:

[logger setSeverityFilterMask: ASL_FILTER_MASK_UPTO (ASL_LEVEL_NOTICE)]`

To log messages with all severity levels from emergency to debug:

[logger setSeverityFilterMask: ASL_FILTER_MASK_UPTO (ASL_LEVEL_DEBUG)];

To filter messages to include only errors and more severe levels:

[logger setSeverityFilterMask: ASL_FILTER_MASK_UPTO (ASL_LEVEL_ERROR)]; 

Declared In

SOLogger.h

Instance Methods

addDescriptor:

Add an external descriptor to the logger.

- (void)addDescriptor:(int)descriptor

Parameters

descriptor

The POSIX file descriptor.

Discussion

Adds the given descriptor to the logger’s list of external descriptors that will receive copies of logged messages. The descriptor may point to a file, pipe, or socket.

ASL performs no severity level filtering on messages sent to external descriptors, including standard error. External descriptors will receive copies all messages logged.

Note: External logging descriptors are not automatically opened when added. The caller is responsible for preparing any descriptor for writing before adding to the logger.

Declared In

SOLogger.h

alert:

Log an alert level message.

- (void)alert:(NSString *)message, ...

Parameters

message

The message. Accepts all formatting specifiers available to NSString.

...

A comma-separated list of arguments to substitute into format.

Declared In

SOLogger.h

aslclientRef

asl client handle

- (aslclient)aslclientRef

Return Value

The aslclient reference for the calling thread.

Discussion

Every thread has its own connection to the ASL service. This method returns the asl client handle appropriate for use with the calling thread. This value can be passed to other ASL API where an aslclient reference is required.

Declared In

SOLogger.h

critical:

Log a critical level message.

- (void)critical:(NSString *)message, ...

Parameters

message

The message. Accepts all formatting specifiers available to NSString.

...

A comma-separated list of arguments to substitute into format.

Declared In

SOLogger.h

debug:

Log a debug level message.

- (void)debug:(NSString *)message, ...

Parameters

message

The message text. Accepts all formatting specifiers available to NSString.

...

A comma-separated list of arguments to substitute into format. This is the least severe message level.

Discussion

In the default syslog configuration, debug- and info-level messages are filtered out the ASL database. They will be logged to stderr and also to any additional file descriptors attached to the logger.

Declared In

SOLogger.h

error:

Log an error level message.

- (void)error:(NSString *)message, ...

Parameters

message

The message. Accepts all formatting specifiers available to NSString.

...

A comma-separated list of arguments to substitute into format.

Declared In

SOLogger.h

info:

Log an info level message.

- (void)info:(NSString *)message, ...

Parameters

message

The message text. Accepts all formatting specifiers available to NSString.

...

A comma-separated list of arguments to substitute into format.

Discussion

In the default syslog configuration, debug- and info-level messages are filtered out the ASL database. They will be logged to stderr and also to any additional file descriptors attached to the logger.

Declared In

SOLogger.h

initWithFacility:options:

Designated initializer

- (id)initWithFacility:(NSString *)facility options:(uint32_t)options

Parameters

facility

The facility for which this logger will be logging. Pass nil to use ASL defaults.

options

Bitflag specifying ASL connection options. Of most utility is the ASL_OPT_STDERR flag.

Discussion

The facility can be used to identify the application or a particular subsystem within the application. Messages are tagged with this facility identifier when added to the ASL database. The value should be unique to your application to avoid name collisions with other loggers. Apple suggests using a reverse-DNS style naming scheme.

The option ASL_OPT_STDERR configures the logger to echo all messages to stderr.

NOTE: this required to see log messages in the Xcode console.

Use the constant SOLoggerDefaultASLOptions for a reasonable combination of Apple System Logging options. Currently defined as:

ASL_OPT_NO_DELAY | ASL_OPT_STDERR | ASL_OPT_NO_REMOTE

See asl_open() in asl(3) for documentation on the available option flags.

Declared In

SOLogger.h

logWithLevel:format:arguments:

Logs a message with the given level.

- (void)logWithLevel:(int)aslLevel format:(NSString *)format arguments:(va_list)arguments

Parameters

aslLevel

The asl(3) severity level of the message.

format

The text of the message. Accepts all formatting specifiers available to NSString.

arguments

A list of arguments to substitute into format.

Discussion

ASL severity levels, from least to most severe:

  • ASL_LEVEL_DEBUG
  • ASL_LEVEL_INFO
  • ASL_LEVEL_NOTICE
  • ASL_LEVEL_WARNING
  • ASL_LEVEL_ERR
  • ASL_LEVEL_CRIT
  • ASL_LEVEL_ALERT
  • ASL_LEVEL_EMERG

Declared In

SOLogger.h

notice:

Log a notice level message.

- (void)notice:(NSString *)message, ...

Parameters

message

The message. Accepts all formatting specifiers available to NSString.

...

A comma-separated list of arguments to substitute into format.

Discussion

In the default syslog configuration, this is the lowest severity level to be logged in the ASL database.

Declared In

SOLogger.h

panic:

Log a panic or emergency level message.

- (void)panic:(NSString *)message, ...

Parameters

message

The message. Accepts all formatting specifiers available to NSString.

...

A comma-separated list of arguments to substitute into format.

Discussion

This is the highest severity level message.

Declared In

SOLogger.h

removeDescriptor:

Remove an external descriptor from the logger.

- (void)removeDescriptor:(int)descriptor

Parameters

descriptor

The POSIX file descriptor.

Discussion

Removes the given file descriptor from the logger’s list of external descriptors receiving messages.

When the logger is deallocated, all external descriptor are automatically removed. You only need to call this method when removing an external descriptor adhoc.

Note: External logging descriptors are not automatically closed when removed. The caller is responsible for closing all external file descriptors.

Declared In

SOLogger.h

warning:

Log a warning level message.

- (void)warning:(NSString *)message, ...

Parameters

message

The message. Accepts all formatting specifiers available to NSString.

...

A comma-separated list of arguments to substitute into format.

Discussion

NSLog() messages are written to the system log at the ASL warning level.

Declared In

SOLogger.h