Skip to main content

​
Macosunifiedlogging Receiver

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

​
Supported Telemetry

Logs

​
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

OptionTypeDefaultDescription
archive_pathstring""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
predicatestring""Filter predicate (e.g., "subsystem == 'com.apple.example'")
start_timestring""Start time in format “2006-01-02 15:04:05”
end_timestring""End time in format “2006-01-02 15:04:05” (archive mode only)
max_poll_intervalduration30sMaximum interval between polling for new logs (live mode only). Uses exponential backoff starting at 100ms
max_log_ageduration24hMaximum age of logs to read on startup (live mode only)
formatstring”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-04-13