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

# Datadog

> Forward Beacon endpoint events into Datadog Logs with Datadog Agent custom log collection.

## Forwarding Overview

Beacon streams endpoint events to Datadog by writing local JSONL and letting the Datadog Agent tail that file. Beacon does not store Datadog API keys or site configuration.

Use this guide for a first-time macOS setup with Datadog Logs. You can complete the setup entirely from the command line; the Datadog UI steps below are optional and are included to show where the same values appear in the Datadog onboarding flow.

## What You Need

* Beacon CLI installed.
* Datadog Agent installed and connected to your Datadog organization.
* Permission to edit `/opt/datadog-agent/etc/datadog.yaml` and restart the Datadog Agent.

## Choose User Or System Mode

| Setup                   | Beacon commands                                     | Runtime log                             |
| ----------------------- | --------------------------------------------------- | --------------------------------------- |
| Local user testing      | `beacon endpoint ...`                               | `~/.beacon/endpoint/logs/runtime.jsonl` |
| MDM or managed endpoint | `sudo /opt/beacon/bin/beacon endpoint ... --system` | `/var/log/beacon-agent/runtime.jsonl`   |

For production or MDM deployment, prefer **system mode**. It avoids per-user home-directory permissions because the Datadog Agent can tail `/var/log/beacon-agent/runtime.jsonl`.

## 1. Install Beacon And Confirm Logs

For local testing:

```bash title="Set up local testing" theme={null}
brew tap asymptote-labs/tap
brew install beacon

beacon endpoint install
beacon endpoint status
ls -l ~/.beacon/endpoint/logs/runtime.jsonl
```

For system mode:

```bash title="Use system mode" theme={null}
sudo /opt/beacon/bin/beacon endpoint install --system
sudo /opt/beacon/bin/beacon endpoint status --system
sudo ls -l /var/log/beacon-agent/runtime.jsonl
```

<Frame caption="Confirm Beacon is writing a runtime JSONL log.">
  <img src="https://mintcdn.com/asymptotelabs/tyyEDXJLE7M3G0qu/images/datadog-runtime-log-file-check.png?fit=max&auto=format&n=tyyEDXJLE7M3G0qu&q=85&s=f7b6763a79d2e11d42118baaf2ff78be" alt="Terminal showing the Beacon runtime JSONL log exists at the user-mode path." width="1812" height="144" data-path="images/datadog-runtime-log-file-check.png" />
</Frame>

## 2. Enable Datadog Log Collection

Open the Datadog Agent config:

```bash title="Open the Datadog Agent config" theme={null}
sudo nano /opt/datadog-agent/etc/datadog.yaml
```

Set:

```yaml theme={null}
logs_enabled: true
```

You do not need to configure Datadog's OpenTelemetry Agent for this setup. Beacon v0 uses Datadog Agent custom file log collection on macOS.

<Frame caption="Enable log collection in datadog.yaml.">
  <img src="https://mintcdn.com/asymptotelabs/tyyEDXJLE7M3G0qu/images/datadog-yaml.png?fit=max&auto=format&n=tyyEDXJLE7M3G0qu&q=85&s=6c3d0c6953a0ce8b2b7d2183f79afa5d" alt="Datadog Agent datadog.yaml showing logs_enabled set to true." width="1484" height="1212" data-path="images/datadog-yaml.png" />
</Frame>

## 3. Optional: Review Custom File Logs In Datadog

This step is optional. Beacon generates the Datadog Agent config in the next step, so you do not need to copy anything manually from the Datadog UI.

If you want to see where the values come from in Datadog, open **Logs** > **Add a Log Source**.

<Frame caption="Open Logs > Add a Log Source in Datadog.">
  <img src="https://mintcdn.com/asymptotelabs/tyyEDXJLE7M3G0qu/images/datadog-log-source-navigation.png?fit=max&auto=format&n=tyyEDXJLE7M3G0qu&q=85&s=9c4eb936fa158e8c392a1e225a975815" alt="Datadog navigation showing Logs and Add a Log Source selected." width="1200" height="842" data-path="images/datadog-log-source-navigation.png" />
</Frame>

Choose **Server** > **Custom Files**.

Fill the form with:

| Field   | Local user testing                                  | System / MDM                          |
| ------- | --------------------------------------------------- | ------------------------------------- |
| Path    | `/Users/<user>/.beacon/endpoint/logs/runtime.jsonl` | `/var/log/beacon-agent/runtime.jsonl` |
| Service | `beacon-endpoint-agent`                             | `beacon-endpoint-agent`               |
| Source  | `beacon`                                            | `beacon`                              |

Leave multiline parsing blank. Beacon writes one JSON event per line.

<Frame caption="Configure Datadog's Custom Files source for Beacon.">
  <img src="https://mintcdn.com/asymptotelabs/tyyEDXJLE7M3G0qu/images/datadog-configure-custom-log-source.png?fit=max&auto=format&n=tyyEDXJLE7M3G0qu&q=85&s=5691fd47dbe0752bc09c3beaa4850085" alt="Datadog Custom Files setup page filled with Beacon runtime log path, service beacon-endpoint-agent, and source beacon." width="3420" height="1988" data-path="images/datadog-configure-custom-log-source.png" />
</Frame>

## 4. Generate And Install The Beacon Config

Generate Beacon's Datadog content pack:

```bash title="Generate Beacon's Datadog content pack" theme={null}
beacon endpoint datadog install-pack --output ./beacon-datadog-pack
```

For system mode:

```bash title="Use system mode" theme={null}
sudo /opt/beacon/bin/beacon endpoint datadog install-pack --system --output ./beacon-datadog-pack
```

<Frame caption="Generate the Beacon Datadog content pack.">
  <img src="https://mintcdn.com/asymptotelabs/tyyEDXJLE7M3G0qu/images/datadog-install-pack.png?fit=max&auto=format&n=tyyEDXJLE7M3G0qu&q=85&s=42dcabf06c561cc1ffd74c3e8d85f062" alt="Terminal showing beacon endpoint datadog install-pack writing the beacon-datadog-pack directory." width="1830" height="94" data-path="images/datadog-install-pack.png" />
</Frame>

Install the generated Datadog Agent config and restart the Agent:

```bash title="Install the generated Datadog Agent config and restart the Agent" theme={null}
sudo mkdir -p /opt/datadog-agent/etc/conf.d/beacon.d
sudo cp ./beacon-datadog-pack/conf.yaml /opt/datadog-agent/etc/conf.d/beacon.d/conf.yaml
sudo chmod 0644 /opt/datadog-agent/etc/conf.d/beacon.d/conf.yaml
sudo launchctl kickstart -k system/com.datadoghq.agent
```

## 5. Validate End To End

Write a test event:

```bash title="Write a test event" theme={null}
beacon endpoint datadog validate
```

For system mode:

```bash title="Use system mode" theme={null}
sudo /opt/beacon/bin/beacon endpoint datadog validate --system
```

<Frame caption="Write a Beacon Datadog validation event.">
  <img src="https://mintcdn.com/asymptotelabs/tyyEDXJLE7M3G0qu/images/datadog-validate-command.png?fit=max&auto=format&n=tyyEDXJLE7M3G0qu&q=85&s=3fd800dd4e0d46269dd1dfc1f56e4b7e" alt="Terminal showing beacon endpoint datadog validate writing a validation event and printing the Datadog query." width="1852" height="202" data-path="images/datadog-validate-command.png" />
</Frame>

Check Datadog Agent status:

```bash title="Check Datadog Agent status" theme={null}
sudo datadog-agent status
```

Look for:

* `beacon`
* `Status: OK`
* `Service: beacon-endpoint-agent`
* `Source: beacon`
* `LogsProcessed` and `LogsSent` greater than zero

<Frame caption="Datadog Agent status should show the Beacon log source as OK.">
  <img src="https://mintcdn.com/asymptotelabs/tyyEDXJLE7M3G0qu/images/datadog-agent-status.png?fit=max&auto=format&n=tyyEDXJLE7M3G0qu&q=85&s=364128b2bdfd947a40d04441f3b0042b" alt="Datadog Agent status showing Logs Agent and beacon integration with Status OK, service beacon-endpoint-agent, source beacon, and logs sent." width="2712" height="1380" data-path="images/datadog-agent-status.png" />
</Frame>

## 6. Search In Datadog

In Datadog Log Explorer, search for:

```text theme={null}
service:beacon-endpoint-agent
```

To find the validation event:

```text theme={null}
service:beacon-endpoint-agent "Beacon endpoint datadog validation event"
```

<Frame caption="Search for the Beacon validation event in Datadog Log Explorer.">
  <img src="https://mintcdn.com/asymptotelabs/tyyEDXJLE7M3G0qu/images/datadog-validation-test.png?fit=max&auto=format&n=tyyEDXJLE7M3G0qu&q=85&s=5e36f87f2f405d790c2499d764f80050" alt="Datadog Log Explorer showing a query for service beacon-endpoint-agent and the Beacon Datadog validation event." width="3194" height="1286" data-path="images/datadog-validation-test.png" />
</Frame>

When everything is wired up, Beacon events appear under `service:beacon-endpoint-agent`. Expanding a log shows the normalized Beacon fields such as `event.action`, `harness.name`, `prompt.text`, `content.retention`, `repository`, and `session`.

<Frame caption="Beacon events in Datadog include the normalized JSON fields for investigation.">
  <img src="https://mintcdn.com/asymptotelabs/tyyEDXJLE7M3G0qu/images/datadog-full-results.png?fit=max&auto=format&n=tyyEDXJLE7M3G0qu&q=85&s=9f4d98f33fad572f3841244dab077a72" alt="Datadog Log Explorer showing Beacon endpoint logs with the expanded Fields and Attributes panel, including event, harness, prompt, content, repository, and session fields." width="2828" height="2054" data-path="images/datadog-full-results.png" />
</Frame>

## Troubleshooting

If Datadog status shows `permission denied`, the Agent cannot read the runtime log. The Datadog Agent usually runs as `_dd-agent`.

For local user testing, either grant `_dd-agent` access to the user-mode log path or use system mode instead. For MDM deployment, use system mode so the Agent tails `/var/log/beacon-agent/runtime.jsonl`.

If Log Explorer is empty:

* Confirm `logs_enabled: true`.
* Confirm `/opt/datadog-agent/etc/conf.d/beacon.d/conf.yaml` exists.
* Restart the Agent.
* Run `beacon endpoint datadog validate` again.
* Check `sudo datadog-agent status`.

## Content Handling

Beacon applies redaction, sanitization, truncation, and event-size limits before events are written to `runtime.jsonl` and tailed by Datadog Agent. Review log access, indexes, retention, and downstream consumers so retained telemetry matches your approved collection policy.

## OpenTelemetry Note

Datadog's DDOT Collector is a good fit for OTel-first Linux or Kubernetes deployments, but Beacon's macOS endpoint v0 uses native Datadog Agent file log collection because it is the supported host path for tailing local JSONL files.

## Related

<Columns cols={2}>
  <Card title="Log forwarding" icon="tower-broadcast" href="/log-forwarding">
    Review forwarding patterns across Wazuh, Splunk HEC, Elastic, Datadog, and other SIEMs.
  </Card>

  <Card title="Command reference" icon="terminal" href="/cli">
    Review Datadog command syntax and related endpoint commands.
  </Card>

  <Card title="Endpoint event schema" icon="code" href="/telemetry-schema/event-schema">
    Review normalized Beacon JSONL fields and example events.
  </Card>

  <Card title="Agent harness integrations" icon="list-check" href="/runtimes">
    Review supported runtimes, deployment modes, storage, and forwarding.
  </Card>
</Columns>