SOLogger Class Reference
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
-
– initWithFacility:options:
Designated initializer
ASL primitive
-
– aslclientRef
asl client handle
Logging messages
-
– debug:
Log a debug level message.
-
– info:
Log an info level message.
-
– notice:
Log a notice level message.
-
– warning:
Log a warning level message.
-
– error:
Log an error level message.
-
– alert:
Log an alert level message.
-
– critical:
Log a critical level message.
-
– panic:
Log a panic or emergency level message.
-
– logWithLevel:format:arguments:
Logs a message with the given level.
Logging to external files
-
– addDescriptor:
Add an external descriptor to the logger.
-
– removeDescriptor:
Remove an external descriptor from the logger.
Properties
-
facility
The facility identifier.
property -
options
ASL connection options.
property -
additionalDescriptors
The logger’s set of registered external logging descriptors.
property -
severityFilterMask
The logger’s severity level filtering mask.
property
Properties
additionalDescriptors
The logger’s set of registered external logging descriptors.
@property (nonatomic, readonly) NSSet *additionalDescriptors
Discussion
Each descriptor is represented as an NSNumber.
See Also
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.
See Also
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.
See Also
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