> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/ingesting-data-into-cortex/integrations/datadog/connecting-entities-to-datadog.md). # Connecting entities to Datadog {% hint style="info" %} 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. {% endhint %} This article explains how to connect Cortex entities to Datadog. For configuration instructions, see [Configuring the integration for Datadog](/ingesting-data-into-cortex/integrations/datadog.md). For what you can do once entities are connected, see [Using the integration for Datadog](/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](/ingesting-data-into-cortex/entities-overview/entities.md#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). #### 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 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:
FieldDescriptionRequired?
tagTag key to match on in Datadog.:check:
valueValue for the tag in Datadog.:check:
aliasAlias for the configuration in Cortex (only needed if you have opted into multi-account support).:x:
To hard code and/or override discovery, you can define a monitor or SLOs block in the YAML, as described in [Monitors and SLOs](#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](/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/`. ```yaml 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](/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=&timeframe=7d&tab=status_and_history`. ```yaml x-cortex-slos: datadog: - id: 0b73859a3e2504bf09ad23a161702654 alias: datadog-us - id: 228499184a9efe34d4e4e9df838c7fa1 alias: datadog-eu ``` Monitors and SLOs have the same field definitions:
FieldDescriptionRequired?
idThe Datadog ID for the monitor or SLO.:check:
aliasAlias for the configuration in Cortex (only needed if you have opted into multi-account support).:x:
#### 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](/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`. {% hint style="info" %} If a Cortex tag doesn't exactly match the entity identifier in Datadog, that dependency won't sync. Override automatic discovery in the YAML. {% endhint %} 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 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 it to an entity's [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities.md#cortex-tag). 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 until one is set. To confirm what matched, go to **Integrations > Data** in the main sidebar, then select the **Incidents** tab (note that the **Incidents** tab is part of a Private Beta). An incident's teams field works differently: it only links if the entity has a Datadog team registration. See [Adding teams](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/teams.md) for how to add one. ## Connecting an entity to Datadog On-Call {% hint style="info" %} Datadog On-Call is in Public Beta. Note that 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. {% endhint %} 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](/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 Schedules and teams have the same field definitions:
FieldDescriptionRequired?
typeEither SCHEDULE or TEAM:check:
idThe Datadog ID for the schedule or team.:check:
#### 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/`. ```yaml x-cortex-oncall: datadog: - type: SCHEDULE id: ee409e39-5449-4eb8-900f-8bea9d2162d7 ``` Multiple schedules can be mapped to an entity: ```yaml 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/`. ```yaml x-cortex-oncall: datadog: - type: TEAM id: b6b8ec6a-9bf1-4496-be8d-09825a2704b9 ``` Multiple teams can be mapped to an entity: ```yaml x-cortex-oncall: datadog: - type: TEAM id: b6b8ec6a-9bf1-4496-be8d-09825a2704b9 - type: TEAM id: 3f0be512-8d47-4a91-9c26-a1e7f3b60d84 ``` {% hint style="info" %} Registrations are made by ID, not by name, and do not take an alias. A `TEAM` registration also links Datadog incidents whose teams field matches that team. {% endhint %} #### 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 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.