macOS Unified Logging

The macOS Unified Logging Receiver collects logs from macOS systems using the native log command. This receiver supports both live system logs and archived log files (.logarchive).

Supported Platforms

Platform	Metrics	Logs	Traces
macOS (10.12+)		✓

Available in the Bindplane Distro for OpenTelemetry Collector v1.87.0+ .

Prerequisites

• macOS 10.12 (Sierra) or later.

• The log command must be available in PATH.

• For archive mode: Read access to the .logarchive directory.

• For stream mode: Appropriate permissions to read system logs.

Configuration Table

Parameter	Type	Default	Description
mode	enum	stream	The collection mode to run the collector in.
format	enum	default	The format of the logs to collect.
archive_path	string	""	The path to the .logarchive directory to collect logs from. Only applicable in archive mode.
predicate	predicate	""	The expression to use to filter logs.
start_time	datetime	""	The time to start collecting logs from.
end_time	datetime	""	The time to stop collecting logs at. Only applicable in archive mode.
poll_interval	int	30	The interval to poll for new logs in seconds. Only applicable in stream mode.
max_log_age	int	24	The maximum age of a log to collect in hours. Only applicable in stream mode.

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

Security Note

Since the source passes values to the built-in log command on the agent, there are security risks in using this source if malicious code is passed in by a user. The source uses the following validation to mitigate these risks:

• The following predicate values are not allowed:

  • Command separators: ;

  • Pipes: |

  • 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.

  • The && operator is automatically normalized to AND to prevent command chaining.

  • The || operator is normalized to OR to prevent piping.

• Archive file paths are sanitized and validated.