NXLog Agent 6.16 adds the macOS OSLog input module (im_macoslog), which reads macOS logs through Apple’s own OSLog API. If you collect logs from Macs running macOS 13 or later, it’s now the module we recommend. It’s more stable, simpler to configure, and lets you filter events before NXLog Agent reads them.

One change to plan for: the macOS ULS input module (im_maculs) is deprecated, and NXLog Agent doesn’t support it on macOS 27 and later. It still works on earlier macOS versions, but we’ll remove it in a future release, so plan your move now.

This post explains what’s different, who should switch, and where to find the step-by-step migration guide.

Why we built im_macoslog

macOS stores its unified log in binary .tracev3 files. Apple doesn’t document that format. im_maculs reads those files directly, so it depends on file paths and on a format that can change between macOS releases.

im_macoslog takes a different route. It asks macOS for events through the OSLog API, Apple’s supported interface for reading the unified log. That gives you three practical benefits:

More stable collection

The module no longer parses undocumented binary files, which lowers the risk of crashes after a macOS update.

Simpler configuration

The path directives UUIDTextPath, TimeSyncPath, and TraceV3Path are gone. Apple’s API finds the log store for you.

Filtering before the read

New MinLevel and Source directives drop the events you don’t need by log level, subsystem, or category before they reach NXLog Agent. Less noise in, less volume out to your SIEM.

The module also adds the ResolveUserGroup directive, which turns the user and group IDs of the logging process into readable userName and groupName fields.

Who should switch

im_macoslog is available in NXLog Agent 6.16 and later and runs on every macOS version NXLog Agent supports. We recommend NXLog Agent 6.16.1 or later, the first release that supports macOS 27. Which module to use depends on the macOS version:

macOS 27 and later

Use im_macoslog with NXLog Agent 6.16.1 or later. NXLog Agent doesn’t support im_maculs on these versions.

macOS 13 to 26

Both modules work, but im_maculs is deprecated. Switch to im_macoslog.

macOS 12 and earlier

Keep im_maculs on an earlier NXLog Agent release. Versions 6.16 and later don’t support these macOS versions.

A few things work differently after the switch, so plan for them:

Saved read position

im_maculs remembers where it stopped as a byte offset in the log files. im_macoslog uses a timestamp instead, so the old saved position can’t carry over.

Filtering

Simple Exec filters can move to the new native directives. Keep Exec for rules too complex to express there.

Private fields

macOS redacts some log values as <private>. To see them, deploy Apple’s logging profile through mobile device management (MDM).

How to migrate

We’ve published a step-by-step guide in the NXLog Documentation: macOS ULS to OSLog migration guide. It covers:

  • The prerequisites to check on each endpoint

  • How to replace your im_maculs input with an im_macoslog one

  • How to move your filters to the new native directives

  • When and how to reset the saved read position

  • What to check once the new configuration is running

It also includes a directive-by-directive mapping table and a before-and-after configuration example you can adapt.

Need a hand?

For most configurations, the switch is a short edit to your input block and a restart. If you’d like help planning the move across a larger fleet, our customer success team is happy to work through it with you. Reach out through the Support Portal.

For the full list of directives and fields, see the macOS OSLog input module reference.

NXLog Platform is an on-premises solution for centralized log management with
versatile processing forming the backbone of security monitoring.

With our industry-leading expertise in log collection and agent management, we comprehensively
address your security log-related tasks, including collection, parsing, processing, enrichment, storage, management, and analytics.

Start free Contact us
Share
Related Posts