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

# Datadog

> Post DevHelm incidents to Datadog as events in your Event Stream and Event Explorer

Connect DevHelm to Datadog to post incidents as **Datadog Events**. Each DevHelm incident event is delivered through the [Datadog Events API v1](https://docs.datadoghq.com/api/latest/events/) and shows up in your Event Stream and Event Explorer, where you can correlate it with metrics, build event monitors, and trigger workflows.

## Setup

<Steps>
  <Step title="Create a Datadog API key">
    1. In Datadog, open **Organization Settings** (click your avatar in the bottom-left)
    2. Under **Access**, go to **API Keys**
    3. Click **New Key**, give it a name, and copy the key

    <Warning>Use an **API key**, not an **Application key**. Events submitted to the Events API authenticate with the API key only — an Application key returns a 403.</Warning>
  </Step>

  <Step title="Identify your Datadog site">
    Your site is the domain in your Datadog URL. DevHelm sends events to `https://api.{site}/api/v1/events`, so a wrong site causes 403s. If you're on US1 you can omit `site` (it defaults to `datadoghq.com`).

    | Site          | `site` value        |
    | ------------- | ------------------- |
    | US1 (default) | `datadoghq.com`     |
    | US3           | `us3.datadoghq.com` |
    | US5           | `us5.datadoghq.com` |
    | EU1           | `datadoghq.eu`      |
    | AP1           | `ap1.datadoghq.com` |
    | US1-FED       | `ddog-gov.com`      |
  </Step>

  <Step title="Create the alert channel in DevHelm">
    <CodeGroup>
      ```bash CLI theme={null}
      devhelm alert-channels create \
        --name "Datadog Events" \
        --type datadog \
        --config '{"channelType":"datadog","apiKey":"your-datadog-api-key","site":"datadoghq.eu","tags":"service:api,env:production,team:platform"}'
      ```

      ```yaml devhelm.yml theme={null}
      alertChannels:
        - name: Datadog Events
          config:
            channelType: datadog
            apiKey: ${DATADOG_API_KEY}
            site: datadoghq.eu
            tags: service:api,env:production,team:platform
      ```
    </CodeGroup>
  </Step>

  <Step title="Test the channel">
    ```bash theme={null}
    devhelm alert-channels test <channel-id>
    ```
  </Step>
</Steps>

## Configuration

| Field    | Description                                                                     | Required |
| -------- | ------------------------------------------------------------------------------- | -------- |
| `apiKey` | Datadog API key (not an Application key)                                        | Yes      |
| `site`   | Datadog site region; defaults to `datadoghq.com` (US1)                          | No       |
| `tags`   | Comma-separated tags attached to every event, e.g. `service:api,env:production` | No       |

## Tags

Tags you set in `tags` are attached to each event verbatim, so you can filter, group, and build event monitors in Datadog by `service`, `env`, `team`, and so on. DevHelm also auto-appends two tags per event:

* `monitor:<monitor name>`
* `severity:<incident severity>`

## Troubleshooting

<AccordionGroup>
  <Accordion title="Events return a 403 (Forbidden)">
    1. Confirm you used an **API key**, not an **Application key**
    2. Verify the `site` matches your Datadog account region — an EU or US3/US5 account with the default `datadoghq.com` site will be rejected
    3. Check the key hasn't been revoked in **Organization Settings → API Keys**
  </Accordion>

  <Accordion title="Events aren't showing up in Datadog">
    Events appear in the **Event Explorer** / Event Stream, not as metrics or logs. Search by `source:devhelm` or one of your configured tags. Note that the Events API accepts a submission with a 202 even before the event is indexed, so allow a few seconds.
  </Accordion>

  <Accordion title="Tags aren't filtering as expected">
    Use Datadog's `key:value` tag format and separate entries with commas, with no spaces around the commas — for example `service:api,env:production`. Free-form text without a colon is still accepted but is harder to filter on.
  </Accordion>
</AccordionGroup>