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

# Connecting entities to Datadog

> [!NOTE]
>
> Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.

This article explains how to connect Cortex entities to Datadog. For configuration instructions, see [Configuring the integration for Datadog](https://docs.cortex.io/ingesting-data-into-cortex/integrations/datadog). For what you can do once entities are connected, see [Using the integration for Datadog](https://docs.cortex.io/ingesting-data-into-cortex/integrations/datadog/using-the-integration-for-datadog.md).

## Connecting an entity to Datadog monitors, SLOs, and dependencies

### How Cortex matches entities to Datadog

Cortex uses the [Cortex tag](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities#cortex-tag) as the "best guess" for the Datadog tag. For example, if your Cortex tag is `payment-service`, then the corresponding tag in Datadog should also be `payment-service`.

If your Datadog tags don’t cleanly match the Cortex tag, you can override this in the Cortex entity descriptor (YAML).

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

#### Service tags

You can use service tags to connect Datadog services to Cortex entities. These tags are used to discover your monitors and SLOs. Cortex finds monitors and SLOs by querying `tag:value OR tag:value2 ...`

```yaml theme={null}
x-cortex-apm:
  datadog:
    serviceTags:
      - tag: service
        value: payments-api
        alias: datadog-us
      - tag: service
        value: payments-worker
        alias: datadog-eu
```

Service tags have the following field definitions:

| Field | Description | Required? |
| - | - | - |
| `tag` | Tag key to match on in Datadog. | |
| `value` | Value for the tag in Datadog. | |
| `alias` | Alias for the configuration in Cortex (only needed if you have opted into multi-account support). | |

To hard code and/or override discovery, you can define a monitor or SLOs block in the YAML, as described in [Monitors and SLOs](https://docs.cortex.io/ingesting-data-into-cortex/integrations/datadog/connecting-entities-to-datadog.md#monitors-and-slos) below.

#### Monitors and SLOs

Adding monitors lets you see information about their current status directly from a catalog and in the **Observability** tab, located on an [entity's details page](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/details.md).

* Locate **Connections** in the left details sidebar, expand **Observability**, then select Datadog.

You can find your monitors in Datadog on the **Manage Monitors** page.

The monitor ID is found in the URL when you click on a monitor in your Datadog dashboard, e.g.  `https://app.datadoghq.com/monitors/<id>`.

```yaml theme={null}
x-cortex-apm:
  datadog: 
    monitors:
      - id: 138472901
        alias: datadog-us
      - id: 138473055
        alias: datadog-us
```

Like monitors, Datadog SLOs can be found in the **Observability** tab, located on an [entity's details page](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/details.md).

* Locate **Connections** in the left details sidebar, expand **Observability**, then select Datadog.

You can find the SLOs for your instance in Datadog on the **SLO status** page.

The SLO ID is found in the URL when you click on an SLO in the Datadog dashboard, e.g.  `https://app.datadoghq.com/slo?slo_id=<id>&timeframe=7d&tab=status_and_history`.

```yaml theme={null}
x-cortex-slos:
  datadog:
    - id: 0b73859a3e2504bf09ad23a161702654
      alias: datadog-us
    - id: 228499184a9efe34d4e4e9df838c7fa1
      alias: datadog-eu
```

Monitors and SLOs have the same field definitions:

| Field | Description | Required? |
| - | - | - |
| `id` | The Datadog ID for the monitor or SLO. | |
| `alias` | Alias for the configuration in Cortex (only needed if you have opted into multi-account support). | |

#### Dependency mapping

Cortex syncs dependencies from Datadog's Service Map automatically, matching entities on the entity identifier (`x-cortex-tag`). Those relationships feed into the [Relationship graph](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/relationship-graph.md), so you can visualize the connections between your entities.

For a dependency to sync, both entities must already exist in Cortex, and each identifier must exactly match the corresponding entity name in the Service Map. For example, if `entity-one` and `entity-two` have a dependency edge in Datadog, both need Cortex tags of `entity-one` and `entity-two`.

> [!NOTE]
>
> If a Cortex tag doesn't exactly match the entity identifier in Datadog, that dependency won't sync. Override automatic discovery in the YAML.

You can override discovery two ways:

* Set `serviceTags` with `tag: entity` and the Service Map entity name as the value. See Service tags.
* Connect an APM service directly:

```yaml theme={null}
x-cortex-apm:
  datadog:
    serviceName: payments-api
```

## Connecting an entity to Datadog incidents

Datadog incidents link to entities automatically, with no configuration required. Cortex reads the incident's `services` field and matches each value to an entity's [Cortex tag](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities#cortex-tag).

Cortex also reads the incident's `teams` field and matches each team handle to the entity with the same Cortex tag. Only that entity is linked, so the services a team owns aren't linked unless the incident also names them in its `services` field.

* **Services** - Cortex matches each value in the incident's `services` field to an entity's [Cortex tag](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities#cortex-tag).
* **Teams** - Cortex matches each team handle in the incident's `teams` field to the entity with the same Cortex tag. Only the team entity is linked. The services that team owns aren't linked unless the incident also names them in its `services` field.

Matching compares the whole value and ignores case. For example, the team handle `payments-team` matches an entity tagged `Payments-Team`, but not one tagged `payments-team-eu`. Archived entities aren't linked.

Incidents declared from a monitor, or with a service attached, carry a `services` value. Incidents declared by hand often don't, and won't match a service until one is set.

If a Datadog team's handle doesn't match its team entity's Cortex tag, incidents for that team won't link to it. Change the handle in Datadog or the entity's Cortex tag so they match. For more on team entities, see [Adding teams](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams).

To confirm what matched, go to **Integrations > Data** in the main sidebar, then select the **Incidents** tab.

## Connecting an entity to Datadog On-Call

> [!NOTE]
>
> Datadog On-Call is not available on Datadog for Government (US1-FED) sites. On gov-site tenants, on-call surfaces in Cortex will be empty. Incidents are unaffected.

Connect on-call schedules from Datadog to see current on-call information for an entity in the catalog. An entity gets linked to a schedule in one of two ways:

* **Automatic mapping** - Cortex creates the link on its own, using the Datadog team handle. No configuration needed.
* **Registration** - You link a specific schedule or team to an entity, either on the entity's details page or in the YAML.

Registration takes precedence. If an entity has an on-call registration, Cortex doesn't automatically map schedules to it. Remove the registration and automatic mapping resumes, normally within an hour.

### Automatic mapping

Cortex connects unlinked Datadog schedules to entities on its own. If a schedule belongs to a Datadog team, and that team's handle matches an entity's Cortex tag, Cortex creates the link with no registration needed.

Mapping runs in both directions and keeps running: new schedules find your existing entities, and new entities find your existing schedules. Allow up to an hour for a new link to appear.

To confirm what matched, go to **Integrations > Data** in the main sidebar, select the **On-call shifts** tab, and check the **Entities** column.

Two cases don't map on their own:

* **A schedule with no team in Datadog**. Schedules migrated from another on-call tool often arrive without one. Attach a team in Datadog whose handle matches the entity's Cortex tag, or add a registration.
* **A team whose handle doesn't match a Cortex tag**. Change the handle to match, or add a registration.

### Registering a schedule or team

Register a schedule or team when the Datadog team handle can't be made to match the entity's Cortex tag, or when you want one specific rotation on an entity. You can register in one of two ways:

* **By schedule** - Select one or more specific Datadog schedules to link directly to the entity.
* **By team** - Select a team from Datadog. Every schedule associated with that team is linked to the entity, so new schedules for that team appear without additional configuration.

Register by team when the team owns the entity and you don't want to revisit the mapping each time its rotations change. Register by schedule when you need a specific rotation on the entity and not everything the team runs.

You can register on-call from an entity's details page, or in the YAML.

### **Connecting from an entity's details page**

1. Navigate to an [entity's details page](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/details.md) in Cortex.
2. In the upper-right corner, click **Configure entity**.
3. From the left sidebar, locate the **Connections** section, then select the **On-call** tab.
4. From the **Integration** dropdown, select Datadog.
5. Do one of the following:
   1. From the **Schedule name** dropdown, select a schedule to link to the entity.
   2. From the **Team name** dropdown, select a team to link to the entity.
6. Click **Save changes**.

Registrations added through the editor take effect immediately; no re-sync is required.

### Connecting in the YAML

To register on-call in the YAML, add an `x-cortex-oncall` block to the entity's descriptor.

> [!NOTE]
>
> The YAML examples on this page show only the `x-cortex-*` block. When you add one to an entity descriptor, nest it inside the `info` section. Blocks at the root level of the file are ignored without an error. For a full example, see [Defining entities with YAML](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/yaml#metadata-in-entity-descriptor-yaml-files).

| Field | Description | Required? |
| - | - | - |
| `type` | Either `SCHEDULE` or `TEAM` | |
| `id` | The Datadog ID for the schedule or team. | |

#### Schedules

To map a single schedule to an entity, use the schedule's ID. You can find it in the schedule URL: `app.datadoghq.com/on-call/schedules/<id>`.

```yaml theme={null}
x-cortex-oncall:
  datadog:
    - type: SCHEDULE
      id: ee409e39-5449-4eb8-900f-8bea9d2162d7
```

Multiple schedules can be mapped to an entity:

```yaml theme={null}
x-cortex-oncall:
  datadog:
    - type: SCHEDULE
      id: ee409e39-5449-4eb8-900f-8bea9d2162d7
    - type: SCHEDULE
      id: 7c1d0a84-2f6b-41e0-b3aa-5d92c8f4e011
```

#### Teams

To map every schedule a team owns to an entity, use the team's ID. You can find it in the team page URL: `app.datadoghq.com/teams/<id>`.

```yaml theme={null}
x-cortex-oncall:
  datadog:
    - type: TEAM
      id: b6b8ec6a-9bf1-4496-be8d-09825a2704b9
```

Multiple teams can be mapped to an entity:

```yaml theme={null}
x-cortex-oncall:
  datadog:
    - type: TEAM
      id: b6b8ec6a-9bf1-4496-be8d-09825a2704b9
    - type: TEAM
      id: 3f0be512-8d47-4a91-9c26-a1e7f3b60d84
```

> [!NOTE]
>
> Registrations are made by ID, not by name, and do not take an alias. A `TEAM` registration only affects on-call. Incidents link to teams by handle, as described in [Connecting an entity to Datadog incidents](#connecting-an-entity-to-datadog-incidents).

#### Schedules and Teams

You can register both on the same entity. Use this when a team owns the entity but you also want a specific shared rotation on it:

```yaml theme={null}
x-cortex-oncall:
  datadog:
    - type: TEAM
      id: b6b8ec6a-9bf1-4496-be8d-09825a2704b9
    - type: SCHEDULE
      id: ee409e39-5449-4eb8-900f-8bea9d2162d7
```

### **How Datadog users map to Cortex users**

Datadog on-call users are resolved to Cortex users by email address. If a Datadog user has no matching Cortex account, Cortex displays their email address instead of a linked user.


## Related topics

- [Datadog](https://docs.cortex.io/ingesting-data-into-cortex/integrations/datadog.md)
- [Using the integration for Datadog](https://docs.cortex.io/ingesting-data-into-cortex/integrations/datadog/using-the-integration-for-datadog.md)
- [Connecting entities to Kubernetes](https://docs.cortex.io/ingesting-data-into-cortex/integrations/kubernetes/connecting-entities-to-kubernetes.md)