macOS ULS to OSLog Migration Guide | NXLog Platform Documentation

This guide helps you move macOS log collection from the macOS ULS input module to the new macOS OSLog input module. The newer module uses Apple’s OSLog API instead of reading .tracev3 files directly. This reduces the risk of crashes, removes file path dependencies, and allows native pre-read filtering.

The module you should use depends on the macOS version of your endpoints:

macOS 27 and later: Use im_macoslog with NXLog Agent version 6.16 or later. The im_maculs module is not supported on these macOS versions.
macOS 13 to 26: Both modules are supported, but im_maculs is deprecated. We recommend migrating to im_macoslog.
macOS 12 and earlier: Continue using im_maculs with an earlier NXLog Agent version. NXLog Agent version 6.16 and later does not support these macOS versions.

If you need further guidance on migrating your configuration, get in touch with our customer success team using the Support Portal.

Prerequisites

Before migrating, your environment must meet the following requirements.

The target endpoints run macOS 13 or later.
The target endpoints have NXLog Agent version 6.16 or later installed.
If your deployment needs access to unredacted private log fields, plan to deploy the required Apple logging profile through MDM. See Private data in the macOS integration guide.

1. Replace the existing input module instance

Remove the im_maculs input instance and create a new im_macoslog input instance. The new module does not require the UUIDTextPath, TimeSyncPath, or TraceV3Path directives because Apple’s API resolves the log store internally.

<Input macos_syslog>
    Module      im_macoslog
    MinLevel    Debug
    Source      com.apple.loginwindow/*
    Source      com.apple.launchd/*
    Source      com.apple.opendirectory/*
    Source      com.apple.security/*
    Source      com.apple.alf/*
</Input>

2. Update your filtering strategy

Move simple filtering from post-read Exec blocks into native directives wherever possible. Use MinLevel, Source subsystem/*, and Source */category to reduce noise before events enter NXLog Agent. Keep Exec blocks only for complex rules that you cannot express with native filters.

3. Reset the saved read position

This step is only required if the module instances have the same names.

The im_maculs module stores the read position as a byte offset in .tracev3 files, while im_macoslog resumes using a timestamp-based position. Before starting NXLog Agent with im_macoslog for the first time, delete or rename the configcache.dat file to reset the last read position. By default, this file is located in /opt/nxlog/var/spool/nxlog.

4. Validate behavior after deployment

Start NXLog Agent and check the nxlog.log file for configuration errors. By default, it is located in /opt/nxlog/var/log/nxlog.
Verify that events are flowing with the expected fields and volume.
If key fields appear as <private>, deploy the required Apple configuration profile to allow access to private data.

Appendix A. Directive mapping

The following table maps im_maculs directives to their im_macoslog equivalents.

im_maculs im_macoslog Migration note

im_maculs	im_macoslog	Migration note
-	`Lag`	New directive to set the number of seconds to subtract from the current time. Use it to prevent missing events due to latency.
-	`ResolveUserGroup`	New directive to resolve the `UID` and `GID` of the process that logged the event to the `userName` and `groupName` fields.
`UUIDTextPath`	Removed	No path configuration is needed because Apple’s OSLog API resolves log data internally.
`TimeSyncPath`	Removed	No replacement is required.
`TraceV3Path`	Removed	No replacement is required.
`SavePos`	`SavePos`	The directive name remains the same, but the stored state is not compatible across modules.
`ReadFromLast`	`ReadFromLast`	The behavior is similar on the first run after migration.
Post-read `Exec` filtering	`MinLevel` and `Source`	Prefer native filtering for efficiency and lower event volume.

Lag

New directive to set the number of seconds to subtract from the current time. Use it to prevent missing events due to latency.

ResolveUserGroup

New directive to resolve the UID and GID of the process that logged the event to the userName and groupName fields.

UUIDTextPath

Removed

No path configuration is needed because Apple’s OSLog API resolves log data internally.

TimeSyncPath

Removed

No replacement is required.

TraceV3Path

Removed

No replacement is required.

SavePos

The directive name remains the same, but the stored state is not compatible across modules.

ReadFromLast

The behavior is similar on the first run after migration.

Post-read Exec filtering

MinLevel and Source

Prefer native filtering for efficiency and lower event volume.

Appendix B. Configuration comparison

The following examples show an im_maculs configuration and its equivalent im_macoslog replacement.

im_maculs configuration

<Input macos_syslog>
    Module          im_maculs
    UUIDTextPath    "/var/db/uuidtext"
    TimeSyncPath    "/var/db/diagnostics/timesync"
    TraceV3Path     "/var/db/diagnostics"
    <Exec>
        if ($processImagePath !~ /loginwindow|launchd|opendirectoryd|security|alf/) {
            drop();
        }
    </Exec>
</Input>

im_macoslog replacement

<Input macos_syslog>
    Module          im_macoslog
    MinLevel        Debug
    Source          com.apple.loginwindow/*
    Source          com.apple.launchd/*
    Source          com.apple.opendirectory/*
    Source          com.apple.security/*
    Source          com.apple.alf/*
</Input>