Skip to main content
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. For what you can do once entities are connected, see Using the integration for Datadog.

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

​
How Cortex matches entities to Datadog

Cortex uses the 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).
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.

​
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 ...
Service tags have the following field definitions: To hard code and/or override discovery, you can define a monitor or SLOs block in the YAML, as described in 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.
  • 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>.
Like monitors, Datadog SLOs can be found in the Observability tab, located on an entity’s details page.
  • 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.
Monitors and SLOs have the same field definitions:

​
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, 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.
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:

​
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. 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.
  • 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. To confirm what matched, go to Integrations > Data in the main sidebar, then select the Incidents tab.

​
Connecting an entity to Datadog On-Call

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

​
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>.
Multiple schedules can be mapped to an entity:

​
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>.
Multiple teams can be mapped to an entity:
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.

​
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:

​
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.
Last modified on October 21, 2026