> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/internal-developer-portal/use-idp/software-catalog/create-entity/catalog-discovery/integrations/datadog.md).
# Datadog Integration
The Datadog integration automatically discovers services from your [Datadog](https://www.datadoghq.com/) account and brings them into the [IDP Catalog](/internal-developer-portal/use-idp/software-catalog/overview.md). Once discovered, entities can be registered as new catalog entries or merged into existing ones.
For each service, the integration collects the following resources from Datadog:
| Resource | What it provides |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Service** | Core metadata from the Datadog Service Catalog such as description, contacts, resources, and repository information. |
| **Monitor** | Monitor metrics and health summary using queries. |
| **SLO** | Service Level Objective data associated with the service. |
| **Service Dependency** | Upstream and downstream service relationships, scoped to an environment you configure. |
***
### Before you begin
The following are needed to get the integration running:
* Ensure the feature flag `IDP_INTEGRATIONS` is enabled. Contact [Harness Support](mailto:support@harness.io) to enable them.
* You have the required RBAC permissions to manage integrations. All integration operations require the `IDP_INTEGRATION_EDIT` permission on the `IDP_INTEGRATION` resource type.
* A Datadog connector is configured in Harness with a valid Datadog URL, Application Key, and API Key. You can also create the connector during the integration setup.
{% hint style="info" %}
**PROXY CONFIGURATION**
If your environment blocks outbound third-party traffic and routes it through a proxy, you will need to configure proxy settings on your Harness Delegate. Once configured there, the proxy settings are automatically picked up by IDP integrations. No additional setup is needed on the integration side.
Go to [Configure delegate proxy settings](/harness-ai/use-harness-platform/delegates/delegate/manage-delegates/configure-delegate-proxy-settings.md) to configure proxy settings on your Harness Delegate.
{% endhint %}
***
### Enable the Datadog integration
#### 1. Navigate to the integrations page
1. In Harness, open the **Internal Developer Portal**.
2. From the left sidebar, click **Configure**.
3. In the left navigation menu, click **Integrations**.
Figure 1: Navigation Path of Datadog Integration
4. On the Integrations page, click **+ New Integration** at the top.
5. Select **DataDog** from the integration type picker. You will be taken to the **Datadog Integration** configuration page.
#### 2. Configure setup & connectivity
This section connects Harness IDP to your Datadog account.
Figure 2: Setup & Connectivity
1. Enter a name in the **Integration Name** field. This name appears on the integration card on the **Integrations** page (e.g., `Datadog Prod Observability`).
2. Click the **Choose Datadog connector** dropdown and select the Datadog connector you want to use to pull data into the IDP.
DO NOT HAVE A DATADOG CONNECTOR YET?
If no connectors appear in the dropdown, you need to first create a Datadog connector in Harness.
Service dependencies are tracked by Datadog based on recent APM traces. If a service is down and not generating traces, it will not appear in the dependency view.
The Datadog Application Key. Click Create or Select a Secret to store it securely. The following scopes are required:
apm\_service\_catalog\_readapm\_readmonitors\_readslos\_readmetrics\_read
|
| **Encrypted API Key** | The Datadog API Key. Click **Create or Select a Secret** to store it securely. |
4. **Delegates Setup**: Select the delegate(s) this connector will use to communicate with Datadog.
* Choose **Use any available Delegate** to let Harness automatically select an available delegate.
* Choose **Only use Delegates with all of the following tags** to pin the connector to specific delegates by tag.
Click **Save and Continue**.
5. **Verify Connection**: Harness tests the connection using the provided credentials and delegate. Once verified, click **Finish** to save the connector.
#### 3. Configure mapping & correlation
This section defines how Datadog services are mapped to IDP catalog entities and how they are correlated with existing records.
Figure 3: Mapping & Correlation
**Service entity**
The Service Entity mapping imports Datadog services as catalog components.
1. Ensure the **Service Entity** toggle is turned on.
2. Under **Entity Registration Behavior**, choose how services are brought into the catalog:
* **Register & Merge** *(Default)* - Registers new entities and updates existing ones when a match is found. This is the recommended option for most setups.
* **Register** - Creates new catalog entities from Datadog. Does not merge with existing entities.
* **Merge** - Links discovered services to existing catalog entities. Matching entities are recommended automatically, but you can choose a different one.
3. The default **Kind** is `Component` and **Type** is `Service`. These are pre-configured and apply to all Datadog service imports.
4. Under **Correlation Mapping**, set the **Ingested Data Path** (from Datadog) and the corresponding **Catalog YAML Path** (from your IDP entity) to define how records are matched. The operator defaults to `Equals`.
5. Optionally, click **Configure** next to **Configure fields** to customize which Datadog fields are synced to the catalog. By default, all available fields are selected.
Figure 4: Configure Datadog Service Fields
#### 4. Configure advanced settings
The **Advanced Settings** section controls how frequently IDP syncs with Datadog.
Figure 5: Advanced Settings
1. Select an **Update Frequency** from the dropdown to control how often IDP polls Datadog for new data.
Available options: `10 min`, `30 min`, `1 hour`, `3 hours`, `6 hours`, `12 hours`, `1 day`, `2 days`, `7 days`.
2. Once all sections are configured, click **Confirm & Enable**.
The integration is now enabled and IDP begins syncing data from Datadog. Discovered services appear in the [**Discovered** tab](#discovered-tab).
***
### Discover and import Datadog entities
This section covers how to view the Datadog services discovered by the integration and import them into your IDP Catalog.
#### Discovered tab
After the integration runs, all Datadog services detected appear in the **Discovered** tab. If no entities appear yet, the tab shows a **Discovering Services** state, indicating the sync is still in progress.
Figure 6: Discovered tab in progress
Use the **Sync** button at the top right to manually trigger a refresh if needed.
Once discovery completes, each discovered service appears with its name, recommended catalog action, kind, type, and detection date. You can bring entities into the catalog using one of the following actions:
* **Register** *(typically used when no matching catalog entity exists)* - Creates a new catalog entity populated with Datadog metadata.
* **Merge** *(shown as Recommended when a matching catalog entity is found)* - Links the discovered entity to an existing catalog entity, enriching it with Datadog data. If IDP finds a catalog entity with a matching name, **Merge** is pre-selected and the suggested entity is shown automatically.
{% hint style="info" %}
**BULK IMPORT**
Select services individually using the checkboxes, or use the snackbar at the bottom of the page to bulk-select by action type. Open the dropdown to choose **All services**, **Register**, or **Merge (Recommended)**, then click **Import selected services**.
{% endhint %}
#### Imported tab
The **Imported** tab displays all Datadog services that have been brought into the catalog.
Figure 7: Imported tab
It displays the following data:
| Column | Description |
| -------------------- | -------------------------------------------------------------------------------------- |
| **Datadog Services** | The name of the service from Datadog, along with its import status (e.g., **Merged**). |
| **Entity** | The linked IDP catalog entity and its ID. |
| **Kind** | The catalog entity kind (e.g., `component`). |
| **Type** | The catalog entity type (e.g., `service`). |
| **Scope** | The Harness account scope the entity belongs to. |
| **Imported** | The timestamp when the entity was imported. |
{% hint style="warning" %}
**UNLINK AN IMPORTED ENTITY**
To stop syncing a specific entity without deleting the catalog entity, use the three-dot menu on any row and select **Unlink**. This stops sync updates while keeping the IDP entity and its existing data intact.
{% endhint %}
#### Events tab
The **Events** tab logs all sync and lifecycle activity for this integration. Use it to verify that syncs are running, confirm that imports completed successfully, and investigate any failures.
For the full event type reference and detail panel fields, go to [Integration Events](/internal-developer-portal/use-idp/software-catalog/create-entity/catalog-discovery/integration-events.md).
***
### View Datadog entities in the catalog
Once imported, Datadog entities are available in the **Catalog** section of IDP as standard catalog entities.
Each imported Datadog service is registered with:
* **Kind:** `Component`
* **Type:** `Service`
* **Scope:** The Harness account the integration belongs to
Open any entity to view Datadog-sourced data directly on the entity details page. This data is displayed through two dedicated UI components: one on the **Overview** tab and an **Observability** tab. Both require a one-time layout configuration, described in the [next section](#layout-for-datadog-components).
#### Layout for Datadog components
To display Datadog data on the [entity details](/internal-developer-portal/use-idp/software-catalog/create-entity/entity-details.md) page, you need to add the two Datadog components to the relevant entity layout. This is a one-time configuration per entity kind and type.
1. From the left sidebar of IDP, go to **Configure** → **Layout** → **Catalog Entities**.
2. Edit the existing layout for your entity or create a new one.
3. Select the **Entity Kind** (e.g., `component`) and the **Entity Type** (e.g., `service`) that matches your imported Datadog entities.
4. In the YAML editor, add the `IntegrationsContent` component inside the **Overview** tab's `contents` block, and add a new **Observability** tab using the `ObservabilityTabContent` component.
Figure 8: Layout configuration for Datadog cards in Overview tab and Observability tab
The relevant YAML additions are:
```yaml
- component: IntegrationsContent
specs:
props:
variant: gridItem
gridProps:
md: 12
```
```yaml
- name: Observability
path: /observabilitiy
title: Observability
contents:
- component: ObservabilityTabContent
```
5. Click **Save** to apply the layout changes. The Datadog components will now appear on all entity detail pages of the selected kind and type that have Datadog data.
#### Cards in overview tab
After the layout is configured, cards like `Monitors` and `SLOs` appear in the **Overview** tab of any entity that has Datadog data linked to it. The card displays the key Datadog metadata ingested for that entity, sourced from the entity's [ingested properties](#ingested-properties).
Figure 9a: IDP Catalog Entity Page for a Datadog service
Figure 9b: Dependencies of a Datadog-imported service
If the Datadog integration has not been configured for the entity, the card shows a **Not configured** state with a link to the Integrations page.
#### Observability tab
The **Observability** tab provides a more complete view of the Datadog data for the entity. This tab fetches latest possible data using the integration ID and entity UUID.
Figure 10: Observability tab showing full Datadog resource details
#### Ingested properties
To inspect the raw data ingested from Datadog, open the entity and click **View YAML**, then select **Ingested Properties** in the Entity Inspector.
Figure 11: Entity Inspector showing Datadog Ingested Properties
Ingested properties are stored in two sections of the entity YAML:
* **`metadata.integration`** - Tracks which Datadog integration instances are linked to this entity, including the entity action (e.g., `MERGE`) and the linked entity UUID.
* **`integration_properties.Datadog`** - Contains the Datadog-specific data for the entity, including fields like `description`, `monitorCount`, `monitors_summary`, `monitors_summary_count`, `links`, `contacts`, `docs`, `downstreamServiceNames`, `githubHtmlUrl`, `languages`, and more.
***
### Manage the Datadog integration
#### Edit the integration
To update the integration name, switch the Datadog connector, or change the mapping and correlation settings, navigate to the **Integrations** page, find your Datadog integration card, and click **View**. From there, click **Configuration** to open the edit screen.
#### Suspend auto-discovery
If auto-discovery is suspended, new entities will not appear in the **Discovered** tab. Existing imported entities remain unchanged in the catalog and the sync between Datadog and their corresponding IDP entities will stop.
To suspend auto-discovery:
1. Go to **Integrations** and open your Datadog integration using the **View** button.
2. Click **Configuration** at the top.
3. In the **Danger Zone** section, click **Suspend**.
4. Confirm the action.
You may re-enable it at any time by following the same steps.