2. Usage

2.1. Overview

This module provides Python bindings for the unified logging and tracing system of macOS.

It requires macOS 10.12 or higher.

Log objects on macOS are encapsulated in Python using class macos_oslog.Log.

The standard log objects of macOS are available in Python as follows:

OS_LOG_DEFAULT: Log object that is enabled for all log levels.
OS_LOG_DISABLED: Log object that is disabled for all log levels.

Additional user-specific log objects can be created with os_log_create(). They should be released with os_log_release().

Log objects can be tested for being enabled for a specific log level with os_log_enabled().

The log levels supported by macOS are represented in Python as follows:

OS_LOG_TYPE_DEBUG: Debug-level messages.
OS_LOG_TYPE_INFO: Info-level messages.
OS_LOG_TYPE_DEFAULT: Default/warning-level messages.
OS_LOG_TYPE_ERROR: Error-level messages.
OS_LOG_TYPE_FAULT: Fault-level messages.

The unified logging and tracing system of macOS provides a central place that has all log messages in memory buffers and that propagates log messages to a data store dependent on the persistence setting of the log object. These log levels have different settings as to whether they are put into the log and whether they are propagated to the data store. The ‘log’ command on macOS can be used to change the persistence setting of a macOS log object.

2.2. Log class

class macos_oslog.Log

A macOS log object.

A macos_oslog.Log object encapsulates a macOS log object.

A macOS log object has subsystem and category identifiers. These identifiers allow filtering and grouping of log messages when viewing the unified log in the macOS ‘Console’ app or with the ‘log’ command on macOS, and can be used for log related settings in the logging system.

Attributes:

`category`	category identifier of the macOS log object
`log`	opaque handle to the macOS log object
`subsystem`	subsystem identifier of the macOS log object

category: category identifier of the macOS log object

log: opaque handle to the macOS log object

subsystem: subsystem identifier of the macOS log object

2.3. Log related functions

macos_oslog.os_log_create()

Creates a new log object.

The log object should be released when no longer used via os_log_release().

Parameters

subsystem (str) – A subsystem identifier chosen by the caller. This identifier has macOS system-wide scope, but there can be multiple log objects that use the same subsystem identifier. It is recommended to use reverse DNS format (i.e. ‘com.company.mysubsystem’). The subsystem identifier is used by macOS for categorization and filtering of related log messages, as well as for grouping related logging settings.
category (str) – A category identifier chosen by the caller. This identifier has a scope only within the subsystem of the log object. There can be multiple log objects that use the same category identifier within a particular subsystem. MacOS uses the category identifier to categorize and filter related log messages, as well as to group related logging settings within the subsystem’s settings. A category’s logging settings override those of the parent subsystem.

Returns

The new log object.

Return type

macos_oslog.Log

macos_oslog.os_log_release()

Releases a log object.

The log object must have been created with os_log_create(). The standard log objects OS_LOG_DEFAULT and OS_LOG_DISABLED cannot be released.

Parameters: log (macos_oslog.Log) – The log object to be released.

macos_oslog.os_log_enabled()

Checks if a log object is enabled for a specific log level.

The log object can have been created with os_log_create() or can be one of the standard log objects OS_LOG_DEFAULT or OS_LOG_DISABLED.

Parameters

log (macos_oslog.Log) – The log object to be checked.
level (int) – Log level, using one of the following values: OS_LOG_TYPE_DEBUG, OS_LOG_TYPE_INFO, OS_LOG_TYPE_DEFAULT, OS_LOG_TYPE_ERROR, OS_LOG_TYPE_FAULT.

Returns

Boolean indicating whether the log object is enabled for the specified log level.

Return type

bool

macos_oslog.os_log()

Inserts a log message into the unified logging and tracing system of macOS.

The log message is inserted in accordance with the preferences specified by the provided log object.

For log messages that are configured to be written to the data store of the logging system, the message is truncated to 1024 Bytes before being written. This does not affect the corresponding log message in memory.

The log object can have been created with os_log_create() or can be one of the standard log objects OS_LOG_DEFAULT or OS_LOG_DISABLED.

The macOS logging system automatically creates a timestamp for the log message and captures process name, process ID, thread ID and log level. Therefore, these values do not need to be put into the message string.

Parameters

log (macos_oslog.Log) – The log object to be used.
level (int) – Log level, using one of the following values: OS_LOG_TYPE_DEBUG, OS_LOG_TYPE_INFO, OS_LOG_TYPE_DEFAULT, OS_LOG_TYPE_ERROR, OS_LOG_TYPE_FAULT.
message (str) – The message string. Formatting strings are not supported, so any formatting needs to be done by the caller.

2.4. Log levels

macos_oslog.OS_LOG_TYPE_DEBUG: int = 2

Debug-level messages.

Use this level to capture information that may be useful during development or while troubleshooting a specific problem.

Debug-level messages are only captured in memory when debug logging is enabled through a configuration change. They are purged in accordance with the configuration’s persistence setting.

macos_oslog.OS_LOG_TYPE_INFO: int = 1

Info-level messages.

Use this level to capture information that may be helpful, but isn’t essential, for troubleshooting errors.

Info-level messages are initially stored in memory buffers. Without a configuration change, they are not moved to the data store and are purged as memory buffers fill. They are, however, captured in the data store when faults and, optionally, errors occur. When info-level messages are added to the data store, they remain there until a storage quota is exceeded, at which point, the oldest messages are purged.

macos_oslog.OS_LOG_TYPE_DEFAULT: int = 0

Default (=warning) level messages.

Use this level to capture information about things that might result in a failure. This makes them equivalent to warning-level messages.

Default-level messages are initially stored in memory buffers. Without a configuration change, they are compressed and moved to the data store as memory buffers fill. They remain there until a storage quota is exceeded, at which point, the oldest messages are purged.

macos_oslog.OS_LOG_TYPE_ERROR: int = 16

Error-level messages.

Use this log level to report process-level errors.

Error-level messages are always saved in the data store. They remain there until a storage quota is exceeded, at which point, the oldest messages are purged. If an activity object exists, logging at this level captures information for the entire process chain.

macos_oslog.OS_LOG_TYPE_FAULT: int = 17

Fault-level messages.

Use this level only to capture system-level or multi-process information when reporting system errors.

Fault-level messages are always saved in the data store. They remain there until a storage quota is exceeded, at which point, the oldest messages are purged. If an activity object exists, logging at this level captures information for the entire process chain.

2.5. Standard log objects

macos_oslog.OS_LOG_DEFAULT: macos_oslog.Log: A standard log object that initially has all levels enabled.

macos_oslog.OS_LOG_DISABLED: macos_oslog.Log: A standard log object that initially has all levels disabled.