asl
— ASL library¶
The Apple System Log facility is a logging API with a simular goal to the classic unix syslog API, but with a richer interface and with an API for querying the logging system.
There is more information on the ASL library in Apple’s manual page for ASL
Note
All APIs accept unicode strings, and require them for Python 3.
The strings will be converted to the C strings expected by the C API using the UTF-8 encoding.
Note
Functions and methods raise OSError
when the C API
fails.
ASL connection¶
-
class
asl.
aslclient
(ident, facility, options)¶ Parameters: - ident – Name of the sender
- facility – A facility name
- optons – Option flags, see Open options
Connection to the ASL backend. These objects implement the context protocol and can be used with the “with” statement.
-
add_log_file
(fd)¶ Parameters: fd – A file descriptor Log messages will be written to the file descriptor as well as to the logging subsystem.
-
remove_log_file
(fd)¶ Parameters: fd – A file descriptor No longer write log messages to the file descriptor. The file descriptor should be one that’s added earlier with
add_log_file()
.
-
set_filter
(filter)¶ Parameters: filter – an integer with the levels that should be sent to the server filter is an bitwise or of values from Message priority levels, and only messages whose log level is set in filter will be sent to the logging subsystem.
Returns the previous value of the filter.
-
log
(msg, level, text)¶ Parameters: - msg – an
aslmsg
object orNone
- level – a lot level from Message priority levels
- text – a message string for the log message
Note
The C API uses a printf-style format string instead of a message. In Python you can use string formatting to format the string.
- msg – an
-
search
(msg)¶ Parameters: msg – an aslmsg
objectReturns: an iterator that yields the result messages. Send a query message to the logging subsystem.
-
log_descriptor
(msg, level, fd, fd_type)¶ Parameters: - msg – an
aslmsg
object orNone
- level – a log level from Message priority levels
- fd – a file descriptor
- fd_type – type of file descriptor, from File descriptor types
If fd_type is
ASL_LOG_DESCRIPTOR_READ
ASL will read lines from the file descriptor and forward those lines to the logging subsystem as log messages.If fd_type is
ASL_LOG_DESCRIPTOR_WRITE
the file descriptor is closed and reopened as a pipe where the application can write lines that will be converted to log messages.The msg is a template for the log messages created by this API.
This method is available on OSX 10.8 or later.
- msg – an
-
close
()¶ Explicitly close the client.
Note
The connection will also de closed when the object is garbage collected.
-
asl.
asl_open
(ident, facility, options)¶ Parameters: - ident – A program identifier string, or
None
. - facility – A facility name
- options – Option flags, see Open options
This is an alias for
asclient
.- ident – A program identifier string, or
-
asl.
open_from_file
(fd, ident, facility)¶ Parameters: - fd – A file descriptor, open for writing and reading
- ident – A program identifier string, or
None
. - facility – A facility name
Opens an ASL log file for writing using an existing file descriptor, for example one returned by
create_auxiliary_file()
. The file descriptor must be open for reading and writing.Avaliable on Mac OS X 10.7 or later.
ASL messages¶
-
class
asl.
aslmsg
(type)¶ -
__getitem__
(key)¶ Parameters: key – An attribute name Return the attribute value for key. The key is a unicode string.
See Standard message attributes for a list of standard attributes.
-
__setitem__
(key, value)¶ Parameters: - key – An attribute name
- value – Value for the attribute, must be a string
Set the value for attribute key to value. Both arguments are unicode strings.
See Standard message attributes for a list of standard attributes.
-
__delitem__
(key)¶ Parameters: key – An attribute name Remove an attribute from the message.
-
set_query
(key, value, operation)¶ Parameters: - key – An attribute name
- value – Value to compare the attribute name with
- operation – The comparison method
Add a query element to the message. The operation is … .
A second call to
set_query()
for the same key will replace that query. Calls toset_query()
for different values of key are combined into an AND query (that is, all query elements must match).Note
It is not possible to perform OR queries, to do those you’ll have to fetch and merge the various subsets yourself.
Note
For basic equality tests (
ASL_QUERY_OP_EQUAL
) you can also set the key and value using the mapping interface. That is,m[key] = value
is equivalent to:
m.set_query(key, value, ASL_QUERY_OP_EQUAL)
-
keys
()¶ Returns the set of attribute names for this message.
-
asdict
()¶ Return a dict with all attributes of this message. Equivalent to:
{ k: msg[k] for k in msg.keys() }
Note
It is not possible to retrieve the “operation” for query messages, the C API doesn’t provide this information.
-
Utility functions¶
-
asl.
ASL_FILTER_MASK
(level)¶ Parameters: level – A message priority level Converts one of the values from Message priority levels into a bit mask that can be used with
aslclient.set_filter()
.
-
asl.
ASL_FILTER_MASK_UPTO
(level)¶ Parameters: level – A message priority level Returns a mask where all bits from
ASL_LEVEL_DEBUG
upto level are set.
-
asl.
create_auxiliary_file
(msg, title, uti)¶ Parameters: Creates an auxiliary file that may be used to store arbitrary data associated with the mssage. Returns a file descriptor for the file. This file descriptor must be closed with
close_auxiliary_file()
.When uti is
None
the system will use “public.data” instead.The Console.app application will show auxiliary file as an file icon that can be opened.
This function is available on Mac OS X 10.7 or later.
-
asl.
log_auxiliary_location
(msg, title, uti, url)¶ Parameters: Write a log message to the logging system with a URL in the message.
When uti is
None
the system will use “public.data” instead.The Console.app application will show the URL as a clickable link.
This method is available on Mac OS X 10.7 or later.
-
asl.
close_auxiliary_file
(fd)¶ Parameters: fd – File descriptor returned by create_auxiliary_file()
.Close the file descriptor for an auxiliary file that was created earlier with
aslmsg.create_auxiliary_file()
. A side effect of this is that the message is logged with the logging system.
Constants¶
Message priority levels¶
The levels are listed from highest to lowest priority.
-
asl.
ASL_LEVEL_EMERG
¶
-
asl.
ASL_LEVEL_ALERT
¶
-
asl.
ASL_LEVEL_CRIT
¶
-
asl.
ASL_LEVEL_ERR
¶
-
asl.
ASL_LEVEL_WARNING
¶
-
asl.
ASL_LEVEL_NOTICE
¶
-
asl.
ASL_LEVEL_INFO
¶
-
asl.
ASL_LEVEL_DEBUG
¶
Message priority level strings¶
These are the string representation of the constants in
the previous section, and are
used as the value for the ASL_KEY_LEVEL
key in
aslmsg
objects.
-
asl.
ASL_STRING_EMERG
¶
-
asl.
ASL_STRING_ALERT
¶
-
asl.
ASL_STRING_CRIT
¶
-
asl.
ASL_STRING_ERR
¶
-
asl.
ASL_STRING_WARNING
¶
-
asl.
ASL_STRING_NOTICE
¶
-
asl.
ASL_STRING_INFO
¶
-
asl.
ASL_STRING_DEBUG
¶
Priority translations¶
-
asl.
LEVEL2STRING
¶ A directionary mapping numeric levels to the equivalent string value
-
asl.
STRING2LEVEL
¶ A directionary mapping string levels to the equivalent integer value
Attribute matching operations¶
Modifiers¶
-
asl.
ASL_QUERY_OP_CASEFOLD
¶ String comparisons are case folded
-
asl.
ASL_QUERY_OP_PREFIX
¶ The match is done on a leading substring
-
asl.
ASL_QUERY_OP_SUFFIX
¶ The match is done on a trailing substring
-
asl.
ASL_QUERY_OP_SUBSTRING
¶ Match any substring
-
asl.
ASL_QUERY_OP_NUMERIC
¶ Perform the comparison after converting the value to an integer using the C function
atoi
.
Operators¶
-
asl.
ASL_QUERY_OP_REGEX
¶ Perform a regular expression match using the regex library. When the
ALS_QUERY_OP_CASEFOLD
modifier is specified the regular expression is compiled case insensitive (REG_ICASE). All other modifiers are ignored.
-
asl.
ASL_QUERY_OP_EQUAL
¶ Value equality
-
asl.
ASL_QUERY_OP_GREATER
¶ Value greater than
-
asl.
ASL_QUERY_OP_GREATER_EQUAL
¶ Value greater than or equal to
-
asl.
ASL_QUERY_OP_LESS
¶ Value less than
-
asl.
ASL_QUERY_OP_LESS_EQUAL
¶ Value less than or equal to
-
asl.
ASL_QUERY_OP_NOT_EQUAL
¶ Value not equal
-
asl.
ASL_QUERY_OP_TRUE
¶ Always true. Use this to test if an attribute is present.
Standard message attributes¶
These are the names of well-known attributes of ASL messages, you can add other attributes as well but those won’t be used by the ASL backend.
-
asl.
ASL_KEY_TIME
¶ Timestamp. Set automatically
-
asl.
ASL_KEY_TIME_NSEC
¶ Nanosecond time.
-
asl.
ASL_KEY_HOST
¶ Sender’s address (set by the server).
-
asl.
ASL_KEY_SENDER
¶ Sender’s identification string. Default is process name.
-
asl.
ASL_KEY_FACILITY
¶ Sender’s facility. Default is “user”.
-
asl.
ASL_KEY_PID
¶ Sending process ID encoded as a string. Set automatically.
-
asl.
ASL_KEY_UID
¶ UID that sent the log message (set by the server).
-
asl.
ASL_KEY_GID
¶ GID that sent the log message (set by the server).
-
asl.
ASL_KEY_LEVEL
¶ Log level number encoded as a string. See levels above.
-
asl.
ASL_KEY_MSG
¶ Message text.
-
asl.
ASL_KEY_READ_UID
¶ User read access (-1 is any user).
-
asl.
ASL_KEY_READ_GID
¶ Group read access (-1 is any group).
-
asl.
ASL_KEY_EXPIRE_TIME
¶ Expiration time for messages with long TTL.
-
asl.
ASL_KEY_MSG_ID
¶ 64-bit message ID number (set by the server).
-
asl.
ASL_KEY_SESSION
¶ Session (set by the launchd).
-
asl.
ASL_KEY_REF_PID
¶ Reference PID for messages proxied by launchd
-
asl.
ASL_KEY_REF_PROC
¶ Reference process for messages proxied by launchd
-
asl.
ASL_KEY_AUX_TITLE
¶ Auxiliary title string
-
asl.
ASL_KEY_AUX_UTI
¶ Auxiliary Uniform Type ID
-
asl.
ASL_KEY_AUX_URL
¶ Auxiliary Uniform Resource Locator
-
asl.
ASL_KEY_AUX_DATA
¶ Auxiliary in-line data
-
asl.
ASL_KEY_OPTION
¶ Internal
-
asl.
ASL_KEY_SENDER_INSTANCE
¶ Sender instance UUID.
-
asl.
ASL_KEY_SENDER_MACH_UUID
¶ Sender Mach-O UUID
-
asl.
ASL_KEY_FINAL_NOTIFICATION
¶ Syslogd posts value as a notification when message has been processed.
-
asl.
ASL_KEY_OS_ACTIVITY_ID
¶ Current OS Activity for the logging thread.
Match directions¶
-
asl.
ASL_MATCH_DIRECTION_FORWARD
¶ Match in forward direction.
-
asl.
ASL_MATCH_DIRECTION_REVERSE
¶ Match in reverse direction.
Message types¶
-
asl.
ASL_TYPE_UNDEF
¶ Undefined type
-
asl.
ASL_TYPE_MSG
¶ A regular log message.
-
asl.
ASL_TYPE_QUERY
¶ A query message.
-
asl.
ASL_TYPE_LIST
¶ A list of messages or queries
-
asl.
ASL_TYPE_FILE
¶ Abstraction for a ASL data file.
-
asl.
ASL_TYPE_STORE
¶ Abstraction for an ASL data store (directory containing data files)
-
asl.
ASL_TYPE_CLIENT
¶ High-level objet that abstracts ASL interactions.
Message encoding¶
-
asl.
ASL_ENCODE_NONE
¶ Don’t escape characters
-
asl.
ASL_ENCODE_SAFE
¶ Escapes backspace as “^H”, replaces carriage returns by newlines, add tabs after newlines to indent continued message text.
-
asl.
ASL_ENCODE_ASL
¶ Use C style encoding for a subset of non-printable characters, like the vis(1) command with the “-c” option.
-
asl.
ASL_ENCODE_XML
¶ Encode message as XML text.
File message formats¶
-
asl.
ASL_MSG_FMT_RAW
¶ Complete message structure with key-value pairs in square brackets.
-
asl.
ASL_MSG_FMT_STD
¶ Simular to
ASL_MSG_FMT_BSD
, but with message priority.
-
asl.
ASL_MSG_FMT_BSD
¶ Format used by the syslog daemon for system log files.
-
asl.
ASL_MSG_FMT_XML
¶ Formatted as XML property lists.
-
asl.
ASL_MSG_FMT_MSG
¶ (Undocumented format)
File time formats¶
-
asl.
ASL_TIME_FMT_SEC
¶ Show timestamps as seconds since the epoch.
-
asl.
ASL_TIME_FMT_UTC
¶ Show timestamps in UTC in the format “yyyy-mm-dd hh:mm:ssZ”.
-
asl.
ASL_TIME_FMT_LCL
¶ Show timestaps in the local timezone with format “mmm dd hh:mm:ss”.
Filter masks¶
These are used for client-side filtering.
-
asl.
ASL_FILTER_MASK_EMERG
¶
-
asl.
ASL_FILTER_MASK_ALERT
¶
-
asl.
ASL_FILTER_MASK_CRIT
¶
-
asl.
ASL_FILTER_MASK_ERR
¶
-
asl.
ASL_FILTER_MASK_WARNING
¶
-
asl.
ASL_FILTER_MASK_NOTICE
¶
-
asl.
ASL_FILTER_MASK_INFO
¶
-
asl.
ASL_FILTER_MASK_DEBUG
¶
Open options¶
-
asl.
ASL_OPT_STDERR
¶ Write a copy of log lines to the stderr stream.
-
asl.
ASL_OPT_NO_DELAY
¶ Immediately create a connection to the logging subsystem, instead of waiting for the first log message.
-
asl.
ASL_OPT_NO_REMOTE
¶ Ignore the server side log filter for messages send using this connection. Using this option requires root privileges.
File descriptor types¶
-
asl.
ASL_LOG_DESCRIPTOR_READ
¶ File descriptor is readable, ASL will read log lines from it.
-
asl.
ASL_LOG_DESCRIPTOR_WRITE
¶ File descriptor is writable. ASL will convert the file descriptor to another writable descriptor where the application can write lines that will be converted to log messages.