--- title: Datadog Extension description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: Docs > OpenTelemetry in Datadog > Integrations > Datadog Extension --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Datadog Extension ## Overview{% #overview %} As of OpenTelemetry Collector Contrib [modules v0.129.0](https://github.com/open-telemetry/opentelemetry-collector-contrib/releases/tag/v0.129.0) and newer, the Datadog Extension is included in [contrib distributions](https://github.com/open-telemetry/opentelemetry-collector-releases/releases/tag/v0.129.1) of OpenTelemetry Collector. It is also available for [custom builds](https://opentelemetry.io/docs/collector/custom-collector/) of OpenTelemetry Collector. In the [DDOT Collector](https://docs.datadoghq.com/opentelemetry/setup/ddot_collector.md), the extension is automatically enabled. The Datadog Extension allows you to view OpenTelemetry Collector configuration and build information directly in Datadog using [Fleet Automation](https://app.datadoghq.com/fleet), the [Infrastructure List](https://app.datadoghq.com/infrastructure), and [Resource Catalog](https://app.datadoghq.com/infrastructure/catalog). The extension works with the recommended OTLP HTTP exporter setup and with the Datadog Exporter. {% image source="https://docs.dd-static.net/images/agent/fleet_automation/fleet-automation-pipeline-view.a669402744743088964b9801c2155281.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/agent/fleet_automation/fleet-automation-pipeline-view.a669402744743088964b9801c2155281.png?auto=format&fit=max&w=850&dpr=2 2x" alt="View OTel Collector configurations with Pipeline Visualization in Fleet Automation" /%} ## Key features{% #key-features %} - **Collector Configuration Visibility**: View the complete configuration of any OTel Collector in your infrastructure. - **Build Information**: See Collector version, build details, and component information. - **Local Inspection Endpoint**: Use an HTTP endpoint for local debugging and configuration verification. - **Fleet Management**: Monitor and manage your OpenTelemetry Collector fleet from the Datadog UI. ## Setup{% #setup %} {% alert level="danger" %} If you use the [DDOT Collector](https://docs.datadoghq.com/opentelemetry/setup/ddot_collector.md), do **not** manually configure the Datadog Extension. It is automatically enabled in all DDOT Collector versions. {% /alert %} ### 1. Add the Datadog Extension to your Collector configuration Configure the Datadog Extension in your OpenTelemetry Collector configuration file: ```yaml extensions: datadog: api: key: ${env:DD_API_KEY} site: # hostname: "my-collector-host" # Optional: must match the hostname in exported telemetry service: extensions: [datadog] ``` ### 2. Configure an active telemetry pipeline Configure at least one active telemetry pipeline and export its data to Datadog. For the recommended configuration, use the [OTLP HTTP exporter setup](https://docs.datadoghq.com/opentelemetry/setup/collector_exporter.md). The extension uses Collector and host metadata to associate the reported configuration with the corresponding host in Datadog. ### 3. (Optional) Add custom resource attributes The Datadog Extension automatically collects resource attributes from the Collector's internal telemetry and includes them in the metadata payload it sends to Datadog. To attach custom attributes such as deployment environment, team, or Kubernetes cluster name, set them under `service.telemetry.resource`: ```yaml service: telemetry: resource: deployment.environment.name: production team.name: platform k8s.cluster.name: prod-us-east1-cluster-a ``` The Collector automatically attaches `service.name`, `service.version`, and `service.instance.id` (a randomly generated UUID) to its internal telemetry. You don't need to set these manually. ### 4. (Optional) Configure gateway topology (preview) When you have an OpenTelemetry Collector gateway setup that forwards telemetry through one or more gateway Collectors before reaching Datadog, the Datadog Extension can publish the topology so it appears as a connected pipeline graph in [Fleet Automation](https://app.datadoghq.com/fleet): {% image source="https://docs.dd-static.net/images/opentelemetry/integrations/datadog_extension_gateway_topology.6a5e9f5c122efda2e5ac1cbed5bf716b.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/opentelemetry/integrations/datadog_extension_gateway_topology.6a5e9f5c122efda2e5ac1cbed5bf716b.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Gateway topology view in Fleet Automation showing DaemonSet Collectors forwarding through two layers of gateway Collectors to Datadog" /%} To enable this view, configure each Collector in the pipeline: - Set `deployment_type` to `daemonset` for agent or DaemonSet Collectors and `gateway` for gateway Collectors. - Set `gateway_destination` on Collectors that forward to a downstream gateway. The value is the Kubernetes Service of the receiving gateway, in `/` form. - Set `gateway_service` on gateway Collectors. The value is the Kubernetes Service that fronts the gateway pods. - A **middle** gateway in a multi-layer pipeline sets **both** `gateway_service` (its own service) and `gateway_destination` (the next gateway). - Set `k8s.cluster.name` under `service.telemetry.resource` on every Collector in the pipeline. This is **required**: together with `gateway_service` and `gateway_destination`, it forms the join key that Fleet Automation uses to reconstruct the pipeline graph. - Enable Collector internal metrics so the extension can attribute logs, metrics, or traces volume data to each edge in the graph with the **Show traffic** toggle. See [OpenTelemetry Collector Health Metrics](https://docs.datadoghq.com/opentelemetry/integrations/collector_health_metrics.md). The example below covers the common two-layer case: a node-local DaemonSet forwards to a gateway Deployment, which sends to Datadog with the Datadog Exporter. Each Collector exposes its own health metrics on a Prometheus pull endpoint via `service.telemetry.metrics`, scrapes that endpoint with a `prometheus/internal` receiver, and routes the result through the same metrics pipeline as application telemetry. This is what populates each node and edge in the topology view. #### DaemonSet Collector{% #daemonset-collector %} ```yaml receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 prometheus/internal: config: scrape_configs: - job_name: otelcol-internal scrape_interval: 10s static_configs: - targets: ['localhost:8888'] exporters: otlp: endpoint: otelcol-gateway.monitoring.svc.cluster.local:4317 tls: insecure: true extensions: datadog: api: key: ${env:DD_API_KEY} site: deployment_type: daemonset gateway_destination: monitoring/otelcol-gateway service: telemetry: metrics: level: normal readers: - pull: exporter: prometheus: host: 0.0.0.0 port: 8888 without_type_suffix: true without_units: true resource: k8s.cluster.name: my-cluster k8s.node.name: ${env:K8S_NODE_NAME} k8s.pod.name: ${env:K8S_POD_NAME} extensions: [datadog] pipelines: metrics: receivers: [otlp, prometheus/internal] exporters: [otlp] traces: receivers: [otlp] exporters: [otlp] logs: receivers: [otlp] exporters: [otlp] ``` The DaemonSet's `metrics` pipeline includes `prometheus/internal` so the Collector's own health metrics travel over OTLP to the gateway alongside application telemetry, reaching Datadog through the gateway's Datadog Exporter. #### Gateway Collector{% #gateway-collector %} ```yaml receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 prometheus/internal: config: scrape_configs: - job_name: otelcol-internal scrape_interval: 10s static_configs: - targets: ['localhost:8888'] exporters: datadog: api: key: ${env:DD_API_KEY} site: metrics: resource_attributes_as_tags: true sending_queue: batch: flush_timeout: 10s extensions: datadog: api: key: ${env:DD_API_KEY} site: deployment_type: gateway gateway_service: monitoring/otelcol-gateway service: telemetry: metrics: level: normal readers: - pull: exporter: prometheus: host: 0.0.0.0 port: 8888 without_type_suffix: true without_units: true resource: k8s.cluster.name: my-cluster k8s.node.name: ${env:K8S_NODE_NAME} k8s.pod.name: ${env:K8S_POD_NAME} extensions: [datadog] pipelines: metrics: receivers: [otlp, prometheus/internal] exporters: [datadog] traces: receivers: [otlp] exporters: [datadog] logs: receivers: [otlp] exporters: [datadog] ``` The gateway's `metrics` pipeline accepts both forwarded telemetry (from the DaemonSet over OTLP) and its own internal metrics from `prometheus/internal`, then exports everything to Datadog. #### Multi-layer gateway pipelines{% #multi-layer-gateway-pipelines %} For pipelines with more than one gateway layer, set `gateway_service` and `gateway_destination` together on the middle layer. For example, in a three-layer topology with a Layer-2 gateway between the DaemonSet and a Layer-1 gateway, the Layer-2 gateway extension is configured as: ```yaml extensions: datadog: api: key: ${env:DD_API_KEY} site: deployment_type: gateway gateway_service: monitoring/otelcol-gateway-l2 gateway_destination: monitoring/otelcol-gateway-l1 ``` The DaemonSet forwards to `monitoring/otelcol-gateway-l2`, the Layer-2 gateway forwards to `monitoring/otelcol-gateway-l1`, and the Layer-1 gateway sends to Datadog. Each Collector reports the same `k8s.cluster.name`. ## Configuration options{% #configuration-options %} | Parameter | Description | Default | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | `api.key` | Datadog API key (required). | - | | `api.site` | Datadog site (for example, `us5.datadoghq.com`). | `datadoghq.com` | | `api.fail_on_invalid_key` | Exit at startup if the API key is invalid. | `true` | | `hostname` | Custom hostname for the Collector. | Auto-detected | | `http.endpoint` | Local HTTP server endpoint. | `localhost:9875` | | `http.path` | HTTP server path for metadata. | `/metadata` | | `deployment_type` | Identifies how the Collector is deployed. This value appears in [Fleet Automation](https://app.datadoghq.com/fleet) and is required for gateway topology. One of: `gateway`, `daemonset`, or `unknown`. The default `unknown` means the deployment type was not set. | `unknown` | | `installation_method` | How the Collector was installed. One of: `kubernetes`, `bare-metal`, `docker`, `ecs-fargate`, `eks-fargate`, or unset. Available in Collector v0.148.0 and later. | unset | | `gateway_service` | Set on **gateway** Collectors only. The Kubernetes Service fronting the gateway Collector pods. Format: `service` or `namespace/service`. Available in Collector v0.150.0 and later. | - | | `gateway_destination` | Set on any Collector that forwards telemetry to a downstream gateway. The Kubernetes Service that this Collector forwards telemetry to. Must match `gateway_service` on the receiving gateway Collector. Format: `service` or `namespace/service`. Available in Collector v0.150.0 and later. | - | | `proxy_url` | HTTP proxy URL for outbound requests. | - | | `timeout` | Timeout for HTTP requests. | `30s` | | `tls.insecure_skip_verify` | Skip TLS certificate verification. | `false` | {% alert level="danger" %} **Hostname matching**: If you specify a custom `hostname` in the Datadog Extension, it must match the host name in exported telemetry. The extension does not infer a hostname from application telemetry in your pipelines; it obtains its hostname from system or cloud-provider APIs or from manual configuration. If you use the Datadog Exporter, its `hostname` value must also match. Otherwise, Datadog might not correlate telemetry to the correct host, and duplicate hosts can appear. {% /alert %} ### Complete configuration example with the Datadog Exporter{% #complete-configuration-example-with-the-datadog-exporter %} The following example uses the Datadog Exporter. The extension itself does not require it; for the recommended pipeline, use the OTLP HTTP exporter configuration from [Set Up the OpenTelemetry Collector](https://docs.datadoghq.com/opentelemetry/setup/collector_exporter.md). ```yaml extensions: datadog: api: key: ${env:DD_API_KEY} site: hostname: "my-collector-host" http: endpoint: "localhost:9875" path: "/metadata" proxy_url: "http://proxy.example.com:8080" timeout: 30s tls: insecure_skip_verify: false exporters: datadog/exporter: api: key: ${env:DD_API_KEY} site: hostname: "my-collector-host" sending_queue: batch: flush_timeout: 10s service: extensions: [datadog] pipelines: traces: receivers: [otlp] exporters: [datadog/exporter] metrics: receivers: [otlp] exporters: [datadog/exporter] ``` ## Viewing Collector configuration{% #viewing-collector-configuration %} Once configured, you can view your OpenTelemetry Collector configuration and build information in various locations: ### Fleet Automation{% #fleet-automation %} 1. Navigate to [Integrations > Fleet Automation](https://app.datadoghq.com/fleet). 1. Filter for OTel Collector hosts using the Collector facets, then click a host. 1. In the side panel, select the Info tab to view build information. 1. Select the Configurations tab to view the full YAML file or a pipeline visualization of your OTel Collector configurations. {% image source="https://docs.dd-static.net/images/agent/fleet_automation/fleet-automation-yaml-view.1973a6356b449819d1cf838e39a3d14a.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/agent/fleet_automation/fleet-automation-yaml-view.1973a6356b449819d1cf838e39a3d14a.png?auto=format&fit=max&w=850&dpr=2 2x" alt="View OTel Collector configuration YAMLs in Fleet Automation" /%} ### Infrastructure List (Host List){% #infrastructure-list-host-list %} 1. Navigate to [Infrastructure > Hosts](https://app.datadoghq.com/infrastructure) in your Datadog account. 1. Click on any host running the OpenTelemetry Collector (**Note**: Filter by `field:apps:otel` to only show Collector instances). 1. In the host details panel, select the OTel Collector tab to see build info and full Collector configuration. ### Resource Catalog{% #resource-catalog %} 1. Navigate to [Infrastructure > Resource Catalog](https://app.datadoghq.com/infrastructure/catalog) in your Datadog account 1. Filter for hosts or search for your Collector instances. 1. Click on any host running the OpenTelemetry Collector. 1. Scroll down to Collector to see build info and full Collector configuration. ## Local HTTP server{% #local-http-server %} The Datadog Extension includes a local HTTP server for debugging and inspection: ```bash # Access collector metadata locally curl http://localhost:9875/metadata ``` This endpoint provides: - Collector configuration (scrubbed of sensitive information) - Build information and version details - Active component list - Extension status ## Troubleshooting{% #troubleshooting %} ### Configuration not appearing in Datadog{% #configuration-not-appearing-in-datadog %} 1. **Check hostname matching**: Confirm that the Datadog Extension hostname matches the host name in exported telemetry. If you use the Datadog Exporter, confirm that its hostname also matches. 1. **Verify API key**: Confirm the API key is valid and has appropriate permissions. 1. **Check Collector logs**: Look for extension initialization and data submission logs. 1. **Confirm extension is enabled**: Verify the extension is listed in the service configuration. ### HTTP server issues{% #http-server-issues %} 1. **Port conflicts**: Ensure port 9875 is available or configure a different port. 1. **Network access**: Verify the HTTP server is accessible from your debug location. 1. **Check logs**: Review extension logs for HTTP server startup issues. ## Further reading{% #further-reading %} Additional helpful documentation, links, and articles: - [Setting Up the OpenTelemetry Collector](https://docs.datadoghq.com/opentelemetry/setup/collector_exporter.md) - [Infrastructure List](https://docs.datadoghq.com/infrastructure/list.md) - [Resource Catalog](https://docs.datadoghq.com/infrastructure/resource_catalog.md)