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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bindplane.com/integrations/sources/macos-unified-logging.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.