OS_LOG(3) Library Functions Manual OS_LOG(3)

os_log, os_log_info, os_log_debug, os_log_error, os_log_fault — log a message scoped by the current activity (if present)

#include <os/log.h>

void
os_log(os_log_t log, const char *format, ...);

void
os_log_info(os_log_t log, const char *format, ...);

void
os_log_debug(os_log_t log, const char *format, ...);

void
os_log_error(os_log_t log, const char *format, ...);

void
os_log_fault(os_log_t log, const char *format, ...);

The unified logging system provides a single, efficient, high performance set of APIs for capturing log messages across all levels of the system. This unified system centralizes the storage of log data in memory and in a data store on disk. The system implements global settings that govern logging behavior and persistence, while at the same time providing fine-grained control during debugging via the log(1) command-line tool and through the use of custom logging configuration profiles (see os_log(5)). Log messages are viewed using the Console app in /Applications/Utilities/ and the log(1) command-line tool. Logging and activity tracing are integrated to make problem diagnosis easier. If activity tracing is used while logging, related messages are automatically correlated.

The unified logging system considers dynamic strings and complex dynamic objects to be private, and does not collect them automatically. To ensure the privacy of users, it is recommended that log messages consist strictly of static strings and numbers, which are collected automatically by the system.

The logging system supports three privacy levels for controlling the visibility of log arguments:

public
Declares that an argument should always be visible in logs, regardless of privacy settings. Use this for data that would not compromise user privacy. For example, %{public}s.
private
Declares that an argument contains private data that should be redacted by default. This is the default privacy level for dynamic strings and objects. For example, %{private}d.
sensitive
Declares that an argument contains sensitive data. Use this for sensitive information such as user data etc. For example, %{sensitive}s.

Logging configuration profiles can be used to adjust privacy levels and enable collection of private or sensitive data for debugging purposes See os_log(5).

To format a log message, use a printf(3) format string. You may also use the "%@" format specifier for use with Obj-C/CF/Swift objects, and %.*P which can be used to decode arbitrary binary data. The logging system also supports custom decoding of values by denoting value types inline in the format %{value_type}d. The built-in value type decoders are:

Value type      Custom specifier         Example output
BOOL            %{BOOL}d                 YES
bitrate         %{bitrate}d              123 kbps
bool            %{bool}d                 true
bytes           %{bytes}d                4.72 kB
darwin.errno    %{darwin.errno}d         [32: Broken pipe]
darwin.mode     %{darwin.mode}d          drwxr-xr-x
darwin.signal   %{darwin.signal}d        [sigsegv: Segmentation Fault]
errno           %{errno}d                [32: Broken pipe]
iec-bitrate     %{iec-bitrate}d          118 Kibps
iec-bytes       %{iec-bytes}d            4.61 KiB
mach.errno      %{mach.errno}d           [0x10000003: (ipc/send) invalid destination port]
multichar       %{multichar}x            [H264]
sockaddr        %{network:sockaddr}.*P   fe80::f:86ff:fee9:5c16
in_addr         %{network:in_addr}u      127.0.0.1
in6_addr        %{network:in6_addr}.16P  fe80::f:86ff:fee9:5c16
time_t          %{time_t}d               2016-01-12 19:41:37
timespec        %{timespec}.*P           2016-01-12 19:41:37.2382382823
timeval         %{timeval}.*P            2016-01-12 19:41:37.774236
uuid            %{uuid}.16P              10742E39-0657-41F8-AB99-878C5EC2DCAA
uuid_t          %{uuid_t}.16P            10742E39-0657-41F8-AB99-878C5EC2DCAA

Use os_log and its variants to log messages to the system datastore based on rules defined by the os_log_t object, see os_log_create(3).

Generally, use the OS_LOG_DEFAULT constant to perform logging using the system defined behavior. Create a custom log object when you want to tag messages with a specific subsystem and category for the purpose of filtering, or to customize the logging behavior of your subsystem with a profile for debugging purposes.

os_log is a "default" type of log message that is always captured in memory and on disk. Limit use to messages that would help diagnose a failure, crash, etc. for production installations.

os_log_info is an "info" type of log message with a short lifetime. These entries are normally appended to a global memory buffer, and the most recent ones are written out at collection time. (They can be optionally configured to persist to disk using a profile or via the log(1) command-line tool.)

os_log_debug is a "debug" type of log message that is only recorded when it is specifically requested by tools or configured as such. Debug messages should be used for development use, i.e., additional information that is typically only useful during code development.

os_log_error is an "error" type of log message that is related to the local process or framework.

os_log_fault is a "fault" type of log message that indicates a bug in the code. For example, it can be used to give context to a violated assumption.

Example use of log messages.

#include <os/log.h>
#include <pwd.h>
#include <errno.h>

int main(int argc, const char * argv[])
{
    uid_t uid;

    os_log(OS_LOG_DEFAULT, "Standard log message.");
    os_log_info(OS_LOG_DEFAULT, "Additional info for troubleshooting.");
    os_log_debug(OS_LOG_DEFAULT, "Debug level messages.");

    struct passwd *pwd = getpwuid(uid);
    if (pwd == NULL) {
        /* Like most library functions, os_log does not preserve errno. */
        int err = errno;
        os_log_error(OS_LOG_DEFAULT,
                "failed to lookup user %d: %{darwin.errno}d", uid, err);
        return err;
    }
}

log(1), os_activity_initiate(3), os_log_create(3), os_log(5)

June 2, 2016 Darwin