Macosunifiedlogging Receiver

Available in: contrib Maintainers: @Caleb-Hurshman, @atoulme Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

Requirements

macOS 10.12 (Sierra) or later
The log command must be available in PATH
For archive mode: Read access to the .logarchive directory
For live mode: Appropriate permissions to read system logs

Configuration

Configuration Options

Option	Type	Default	Description
`archive_path`	string	""	Path or glob pattern to `.logarchive` directory(ies). If empty, reads live system logs. Supports glob patterns (e.g., `.logarchive`, `/logs/.logarchive`) which will match multiple archives
`predicate`	string	""	Filter predicate (e.g., `"subsystem == 'com.apple.example'"`)
`start_time`	string	""	Start time in format “2006-01-02 15:04:05”
`end_time`	string	""	End time in format “2006-01-02 15:04:05” (archive mode only)
`max_poll_interval`	duration	30s	Maximum interval between polling for new logs (live mode only). Uses exponential backoff starting at 100ms
`max_log_age`	duration	24h	Maximum age of logs to read on startup (live mode only)
`format`	string	”default”	Output format: `default`, `ndjson`, `json`, `syslog`, or `compact`

Exponential Backoff Behavior

In live mode, the receiver uses exponential backoff to optimize polling based on log activity:

Active Logging: When logs are actively being written, the receiver polls frequently (starting at 100ms) to minimize latency and catch logs written immediately after the previous poll
Idle Period: When no logs are found, the polling interval increases exponentially (doubling each time) up to max_poll_interval
Automatic Reset: As soon as logs are detected again, the interval resets to the minimum (100ms)

This approach minimizes both latency during active logging and resource usage during idle periods.

Basic Configuration (Live Mode)

receivers:
  macos_unified_logging:
    max_poll_interval: 30s  # Maximum interval between polls (uses exponential backoff)
    max_log_age: 24h        # How far back to read on startup

Archive Mode (Single Archive)

receivers:
  macos_unified_logging:
    archive_path: "/path/to/system_logs.logarchive"
    start_time: "2024-01-01 00:00:00"
    end_time: "2024-01-02 00:00:00"

Archive Mode (Glob Pattern - Multiple Archives)

receivers:
  macos_unified_logging:
    archive_path: "/logs/**/*.logarchive"  # Matches all .logarchive directories recursively
    format: "ndjson"

With Filtering

receivers:
  macos_unified_logging:
    archive_path: "./logs.logarchive"
    predicate: "subsystem == 'com.apple.systempreferences'"

With Custom Format

receivers:
  macos_unified_logging:
    format: ndjson             # Use structured JSON output
    max_poll_interval: 30s
    max_log_age: 24h

Predicate Examples

Filter by subsystem:

subsystem == 'com.apple.systempreferences'

Filter by process:

process == 'kernel'

Filter by message type:

messageType == 'Error'

Combine filters:

subsystem == 'com.apple.example' AND messageType IN {'Error', 'Fault'}

For a full description of predicate expressions, run log help predicates.

Security Note

Predicate values are validated to ensure only valid predicate syntax is used. The following are not allowed:

Command separators: ;
Pipes: | (|| are normalized to OR)
Variable expansion: $
Backticks: `
Redirects: >>, <<
Control characters: newlines, carriage returns

Valid predicate operators like && (logical AND), <, > (comparison) are allowed. The > operator is allowed for comparisons (e.g., processID > 100) but blocked when followed by file paths. Note that && is automatically normalized to AND for consistency. Use standard predicate syntax as documented by Apple’s log command.

Output Format

The receiver converts macOS logs to OpenTelemetry log records:

Body: Contains the entire log line as a string
Attributes: Not set

Format Options

`ndjson` and `json` Formats

When using JSON formats, each log line is captured as a complete JSON string in the body, with timestamp and severity extracted:

Timestamp: Parsed from the timestamp field in the JSON
Severity: Mapped from messageType (Error, Fault, Default, Info, Debug)

`default`, `syslog`, and `compact` Formats

When using plain text formats, each log line is captured as plain text in the body:

Timestamp: Set to observed time (when the log was received)
Severity: Not set

Example

Complete example configuration:

receivers:
  macos_unified_logging:
    archive_path: "./system_logs.logarchive"
    predicate: "subsystem BEGINSWITH 'com.apple'"
    start_time: "2024-01-01 00:00:00"

exporters:
  file:
    path: "./output/logs.json"
    format: json

service:
  pipelines:
    logs:
      receivers: [macosunifiedlogging]
      exporters: [file]

Last generated: 2026-08-24

​Macosunifiedlogging Receiver

​Supported Telemetry

​Overview

​Requirements

​Configuration

​Configuration Options

​Exponential Backoff Behavior

​Basic Configuration (Live Mode)

​Archive Mode (Single Archive)

​Archive Mode (Glob Pattern - Multiple Archives)

​With Filtering

​With Custom Format

​Predicate Examples

​Security Note

​Output Format

​Format Options

​ndjson and json Formats

​default, syslog, and compact Formats

​Example