.\" Copyright (c) 2019 Apple Inc. All rights reserved.
.Dd June 24, 2019
.Dt os_log 5
.Os Darwin
.Sh NAME
.Nm os_log
.Nd logging configuration profiles
.Sh DESCRIPTION
Logging configuration profiles are property list dictionaries that customize
the behavior of the
.Xr os_log 3
and os_signpost APIs.
.Pp
Customization is on a subsystem and category basis, i.e., for particular
os_log_t objects returned by
.Xr os_log_create 3 .
Behavior involving the OS_LOG_DEFAULT constant is not affected by configuration
profiles.
.Pp
There are two types of logging configuration profiles, system-wide and
application-specific.
.Bl -bullet -offset indent
.It
System-wide profiles are located in the
/System/Library/Preferences/Logging/Subsystems directory.
Files in this directory define logging configuration settings used by system
components (e.g., system libraries and frameworks).
Their names indicate which subsystems they configure; each contains a
dictionary for that subsystem.
.It
Application-specific profiles are in an application's Info.plist file, in an
.Sy OSLogPreferences
dictionary.
Keys in this dictionary correspond to subsystem names, and its values are
subsystem dictionaries.
.El
.Pp
Subsystem dictionaries are further organized into sub-dictionaries that
correspond to categories.
Subsystem dictionary keys are category names and values are dictionaries that
define logging configuration settings for that subsystem and category.
.Pp
The special
.Sy DEFAULT-OPTIONS
category key can be used to define common settings for all categories in a
subsystem.
(Settings in particular category dictionaries will take precedence over these
common settings.)
.Sh KEYS
Category dictionaries contain one or more of the following keys.
.Bl -ohang
.It Sy Level <dictionary>
Enable and disable logs.
Control how they are written.
.Pp
.Xr os_log 3
has three levels.
In order from lowest to highest, they are: Debug, Info, and Default.
Debug level is associated with os_log_debug; Info with os_log_info; and Default
with os_log, os_log_error, and os_log_fault.
.Pp
The system settings are that: Debug level logging is disabled; Info level is
enabled and written to a memory buffer; Default level logging is enabled and
persisted to disk.
.Bl -ohang -offset indent
.It Sy Enable <string> (default: Inherit)
Turn logs on for a particular level and any higher levels with the options:
Off, Default, Info, and Debug.
Inherit means to use the common settings for a subsystem, if defined, or to use
the system settings otherwise.
.It Sy Persist <string> (default: Inherit)
Save logs to disk for a particular level and any higher levels with the
options: Off, Default, Info, and Debug.
Inherit means to use the common settings for a subsystem, if defined, or to use
the system settings otherwise.
Levels that are enabled but not persisted are written to a memory buffer so
that recent history can be saved at collection time.
.El
.It Sy Enable-Oversize-Messages <boolean> (default: false)
Use a standard or increased message size limit.
Log messages have a 1024-byte encoded size limit.
Enabling oversize messages increases this encoded size limit to 32 kilobytes.
Oversize messages are expensive.
They should not be logged from performance-sensitive code paths like the main
thread.
.It Sy Enable-Private-Data <boolean> (default: false)
Enable or disable the capturing of private arguments.
See
.Xr os_log 3
for discussion about public versus private arguments.
.It Sy Signpost-Enabled <boolean> (default: true)
Enable and disable signposts.
.It Sy Signpost-Persisted <boolean> (default: false)
Control whether signposts are persisted to disk or written to a memory buffer.
.It Sy Signpost-Scope <string> (default: Process)
Control signpost interval scope with the options: Thread, Process, and System.
See <os/signpost.h> for details.
.It Sy Signpost-Backtraces-Enabled <boolean> (default: false)
Enable and disable the capture of backtrace data for signposts.
.El
.Sh EXAMPLES
If the following plist were at
/System/Library/Preferences/Logging/Subsystems/com.example.plist, it would turn
off logging for the "Transactions" category in the "com.example" subsystem.
A profile or the
.Xr log 1
config command could be used to turn it on when needed.
.Bd -literal -offset indent
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Transactions</key>
    <dict>
        <key>Level</key>
        <dict>
            <key>Enable</key>
            <string>Off</string>
        </dict>
    </dict>
</dict>
</plist>
.Ed
.Pp
If the following
.Sy OSLogPreferences
dictionary were in the Info.plist of an application, it would enable all levels
and persist the Info and Default levels for the "Details" category in the
"com.example" subsystem; and it would enable signpost backtraces for the
"Measurements" category.
.Bd -literal -offset indent
<key>OSLogPreferences</key>
<dict>
    <key>com.example</key>
    <dict>
        <key>Details</key>
        <dict>
            <key>Level</key>
            <dict>
                <key>Enable</key>
                <string>Debug</string>
                <key>Persist</key>
                <string>Info</string>
            </dict>
        </dict>
        <key>Measurements</key>
        <dict>
            <key>Signpost-Backtraces-Enabled</key>
            <true/>
        </dict>
    </dict>
</dict>
.Ed
.Sh SEE ALSO
.Xr log 1 ,
.Xr os_log 3 ,
.Xr os_log_create 3 ,
.Xr plist 5
.Sh HISTORY
Application-specific logging configuration was introduced in macOS 10.15.