> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# macOS Unified Logging

<Badge className="hny-badge-enterprise-addon" stroke>Ent+</Badge>

<Note>
  This feature is available as an add-on for the [Honeycomb Enterprise plan](https://www.honeycomb.io/pricing/).
  Please contact your Honeycomb account team for details.
</Note>

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.