Overview

As of OpenTelemetry Collector Contrib modules v0.129.0 and newer, the Datadog Extension is included in contrib distributions of OpenTelemetry Collector. It is also available for custom builds of OpenTelemetry Collector. In the DDOT Collector, the extension is automatically enabled.

The Datadog Extension allows you to view OpenTelemetry Collector configuration and build information directly in Datadog using Fleet Automation, the Infrastructure List, and Resource Catalog. When used with the Datadog Exporter, this extension gives you visibility into your Collector fleet without leaving the Datadog UI.

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

1. Add the Datadog Extension to your Collector configuration

Configure the Datadog Extension in your OpenTelemetry Collector configuration file:

extensions:
  datadog:
    api:
      key: ${env:DD_API_KEY}
      site: 
    # hostname: "my-collector-host"  # Optional: must match Datadog Exporter hostname if set

service:
  extensions: [datadog]

2. Configure the Datadog Exporter

This feature requires the Datadog Exporter to be configured and enabled in an active pipeline (traces or metrics). The extension uses the exporter’s telemetry to associate the Collector’s configuration with a specific host in Datadog.

exporters:
  datadog/exporter:
    api:
      key: ${env:DD_API_KEY}
      site: 
    # hostname: "my-collector-host"  # Optional: must match Datadog Extension hostname if set
    sending_queue:
      batch:
        flush_timeout: 10s

3. Enable the extension in your service configuration

Add the Datadog Extension to your service extensions:

service:
  extensions: [datadog]
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [datadog/exporter]
    metrics:
      receivers: [otlp]
      exporters: [datadog/exporter]

4. (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:

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.

5. (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:

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 <namespace>/<service> 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.

The example below covers the common two-layer case: a node-local DaemonSet forwards to a gateway Deployment, which sends to Datadog.

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

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

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

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:

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

Complete configuration example

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

Once configured, you can view your OpenTelemetry Collector configuration and build information in various locations:

Fleet Automation

1. Navigate to Integrations > Fleet Automation.
2. Filter for OTel Collector hosts using the Collector facets, then click a host.
3. In the side panel, select the Info tab to view build information.
4. Select the Configurations tab to view the full YAML file or a pipeline visualization of your OTel Collector configurations.

Infrastructure List (Host List)

1. Navigate to Infrastructure > Hosts in your Datadog account.
2. Click on any host running the OpenTelemetry Collector (Note: Filter by field:apps:otel to only show Collector instances).
3. In the host details panel, select the OTel Collector tab to see build info and full Collector configuration.

Resource Catalog

1. Navigate to Infrastructure > Resource Catalog in your Datadog account
2. Filter for hosts or search for your Collector instances.
3. Click on any host running the OpenTelemetry Collector.
4. Scroll down to Collector to see build info and full Collector configuration.

Local HTTP server

The Datadog Extension includes a local HTTP server for debugging and inspection:

# 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

Configuration not appearing in Datadog

1. Check hostname matching: Ensure hostnames match between the Datadog Extension and Datadog Exporter.
2. Verify API key: Confirm the API key is valid and has appropriate permissions.
3. Check Collector logs: Look for extension initialization and data submission logs.
4. Confirm extension is enabled: Verify the extension is listed in the service configuration.

HTTP server issues

1. Port conflicts: Ensure port 9875 is available or configure a different port.
2. Network access: Verify the HTTP server is accessible from your debug location.
3. Check logs: Review extension logs for HTTP server startup issues.

Further reading

Additional helpful documentation, links, and articles:

Setting Up the OpenTelemetry CollectorDOCUMENTATION Infrastructure ListDOCUMENTATION Resource CatalogDOCUMENTATION