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