macOS OSLog (im_macoslog)

This module collects logs from macOS’s unified logging system (ULS) using Apple’s OSLog API, which is available starting with macOS 10.15 (Catalina). For older macOS versions, use the macOS ULS input module instead.

To examine the supported platforms, see the list of installation packages.

Configuration

The im_macoslog module accepts the following directives in addition to the common module directives.

Optional directives

Lag

Set this directive to the number of seconds the module subtracts from the current time to define a cutoff when reading new records. New records may not be immediately available through the OSLog API, so reading up to the current time risks silently missing them. Increase this value if you notice recent records missing from the output. Decrease it to reduce collection latency but risk occasionally missing very recent records.

This directive accepts fractional values, for example, 1.5 or +1.55555. The minimum value is 0. The maximum value is 3600 (1 hour). The default is 1 second.

MinLevel

Set this directive to the minimum severity level to collect. The accepted values, from least to most severe, are Debug, Info, Notice, Error, and Fault. By default, the module collects all severity levels.

PollInterval

Set this directive to the number of seconds between checks for new log records. The default value is 1.

ReadFromLast

This boolean directive instructs the module on where to start reading events from the log source when NXLog Agent starts.

When TRUE, NXLog Agent will only read events logged after NXLog Agent started, unless SavePos is TRUE and a saved position for this log source exists in the cache file.

When FALSE, NXLog Agent will read all events from the log source, unless SavePos is TRUE and a saved position for this log source exists in the cache file.

The default is TRUE.

The following matrix shows the outcome of this directive in conjunction with the SavePos directive:

ReadFromLast SavePos Saved position Outcome

TRUE

Yes

Reads events from the saved position.

TRUE

Reads events that are logged after NXLog Agent is started.

TRUE

FALSE

Yes

Reads events that are logged after NXLog Agent is started.

TRUE

FALSE

Reads events that are logged after NXLog Agent is started.

FALSE

TRUE

Yes

Reads events from the saved position.

FALSE

TRUE

Reads all events.

FALSE

Yes

Reads all events.

FALSE

Reads all events.

If the NoCache directive is TRUE, it overrides the SavePos directive. In this case, the module behaves as if SavePos is FALSE.

ResolveUserGroup

Set this directive to TRUE to resolve the UID and GID of the process that logged each entry into the userName and groupName fields. The default is FALSE, the module only populates the numeric UID and GID fields.

The module resolves the UID and GID from the PID recorded by the OSLog infrastructure for the event. This can reflect the current owner of the PID rather than the process that originally logged the event. The module takes precautions against this, but on rare occasions the reported userName and groupName might be incorrect.

SavePos

Set this directive to TRUE to save the position of the last processed event before NXLog Agent exits. On the next startup, the agent reads the saved position from the cache file and resumes from that point. Together with the ReadFromLast directive, this directive allows the agent to continue reading events from the saved position.

The default is TRUE; the position of the last read event is saved and will be read from the cache file on the next startup.

If the NoCache directive is TRUE, it overrides the SavePos directive. In this case, the module behaves as if SavePos is FALSE.

Source

Set this directive to filter which log records the module collects, using the Subsystem/Category format. Use * in place of either the subsystem or the category to match any value for that part, for example com.apple.network/* or */DNS. A value that does not contain a / is not valid. You can specify this directive multiple times to collect from more than one subsystem/category combination. By default, the module collects records from all subsystems and categories.

Fields

The following fields are created by im_macoslog.

$raw_event (type: string): A list of event fields in key-value pairs.
$activityIdentifier (type: string): A numeric ID for an activity.
$category (type: string): The category of the event.
$eventMessage (type: string): The message associated with the event.
$EventTime (type: datetime): The timestamp of the event.
$eventType (type: string): The type of event. For this module, the value is eventLog.
$formatString (type: string): The format string used to form eventMessage.
$GID (type: integer): The group identifier associated with the $processID when the module collects the event. See the ResolveUserGroup directive for more information.
$groupName (type: string): If ResolveUserGroup is TRUE and the name is successfully resolved, this field contains the group name associated with the $GID.
$processID (type: integer): The ID of the process that logged the event.
$processName (type: string): The name of the process that logged the event.
$Severity (type: string): The log level of the event. The possible values are Undefined, Debug, Info, Notice, Error, or Fault.
$subsystem (type: string): The subsystem used to log the event.
$threadID (type: string): The ID of the thread that logged the event.
$UID (type: integer): The user identifier associated with the $processID when the module collects the event. See the ResolveUserGroup directive for more information.
$userName (type: string): If ResolveUserGroup is TRUE and the name is successfully resolved, this field contains the user name associated with the $UID.

Examples

Example 1. Basic im_macoslog configuration

This configuration collects all records logged after the module’s first start.

nxlog.conf

<Input macoslog>
    Module    im_macoslog
</Input>

Example 2. Narrowing to specific sources and severity

This configuration uses Source to collect only records from the com.apple.securityd subsystem and any subsystem’s connection category, then uses MinLevel to drop anything less severe than Notice.

nxlog.conf

<Input macoslog>
    Module      im_macoslog
    Source      com.apple.securityd/*
    Source      */connection
    MinLevel    Notice
</Input>

Example 3. Collecting all available logs with lag tolerance and GUID resolution

This configuration sets ReadFromLast to FALSE to read all available records on the module’s first start. It also increases Lag to tolerate a 2-second ingestion lag, and turns on ResolveUserGroup to populate the userName and groupName fields.

nxlog.conf

<Input macoslog>
    Module              im_macoslog
    ReadFromLast        FALSE
    Lag                 2
    ResolveUserGroup    TRUE
</Input>