Overview

Follow this guide to install the Datadog Distribution of OpenTelemetry (DDOT) Collector on Linux-based bare-metal hosts and virtual machines.

Requirements

To complete this guide, you need the following:

Datadog account:

1. Create a Datadog account if you don’t have one.
2. Find or create your Datadog API key.

Software:

• A supported Linux distribution (for example, Debian, Ubuntu, CentOS, RHEL, Fedora, SUSE).
• curl must be installed to use the one-line installation script.

Install the Datadog Agent with OpenTelemetry Collector

Installation

To install the DDOT Collector on a Linux host, use the following one-line installation command:

DD_API_KEY=<DATADOG_API_KEY> DD_SITE="" DD_OTELCOLLECTOR_ENABLED=true DD_AGENT_MAJOR_VERSION=7 DD_AGENT_MINOR_VERSION=69.4-1 bash -c "$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)"

This command installs both the core Datadog Agent package and the DDOT Collector that runs alongside it.

Validation

Run the Agent’s status command to verify installation.

sudo datadog-agent status

A successful installation returns an Agent Status report that begins with Agent information like this:

====================
Agent (v7.x.x)
====================
  Status date: 2025-08-22 18:35:17.449 UTC (1755887717449)
  Agent start: 2025-08-22 18:16:27.004 UTC (1755886587004)
  Pid: 2828211
  Go Version: go1.24.6
  Python Version: 3.12.11
  Build arch: amd64
  Agent flavor: agent
  FIPS Mode: not available
  Log Level: info

There will also be an OTel Agent status section that includes OpenTelemetry information:

==========
OTel Agent
==========

  Status: Running
  Agent Version: 7.x.x
  Collector Version: v0.129.0

  Receiver
  ==========================
    Spans Accepted: 0
    Metric Points Accepted: 1055
    Log Records Accepted: 0

  Exporter
  ==========================
    Spans Sent: 0
    Metric Points Sent: 1055
    Log Records Sent: 0

Configure the Datadog Agent

Enable the DDOT Collector

The configuration file for the Datadog Agent is automatically installed at /etc/datadog-agent/datadog.yaml. The installation script adds the following configuration settings to /etc/datadog-agent/datadog.yaml to enable the DDOT Collector:

otelcollector:
  enabled: true
agent_ipc:
  port: 5009
  config_refresh_interval: 60

DDOT automatically binds the OpenTelemetry Collector to ports 4317 (grpc) and 4318 (http) by default.

(Optional) Enable additional Datadog features

For a complete list of available options, refer to the fully commented reference file at /etc/datadog-agent/datadog.yaml.example or the sample config_template.yaml file.

When enabling additional Datadog features, always use the Datadog or OpenTelemetry Collector configuration files instead of relying on Datadog environment variables.

Configure the OpenTelemetry Collector

The installation script provides a sample OpenTelemetry Collector configuration at /etc/datadog-agent/otel-config.yaml that you can use as a starting point.

extensions:
  health_check:
    endpoint: localhost:13133
  pprof:
    endpoint: localhost:1777
  zpages:
    endpoint: localhost:55679
  ddflare:
    endpoint: localhost:7777


receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
    # Collect own metrics
  prometheus:
    config:
      scrape_configs:
      - job_name: 'otel-collector'
        fallback_scrape_protocol: PrometheusText0.0.4
        metric_name_validation_scheme: legacy
        metric_name_escaping_scheme: underscores
        scrape_interval: 60s
        scrape_protocols:
          - PrometheusText0.0.4
        static_configs:
        - targets: ['0.0.0.0:8888']
        metric_relabel_configs:
        - source_labels: [__name__]
          regex: ".*grpc_io.*"
          action: drop
exporters:
  datadog:
    hostname: "otelcol-docker"
    api:
      key: <DATADOG_API_KEY>
      site: <DATADOG_SITE>
processors:
  infraattributes:
  batch:
  # using the sampler
  probabilistic_sampler:
    sampling_percentage: 30
connectors:
  # Use datadog connector to compute stats for pre-sampled traces
  datadog/connector:
    traces:
      compute_stats_by_span_kind: true
      peer_tags_aggregation: true
service:
  extensions: [health_check, pprof, zpages, ddflare]
  pipelines:
    traces: # this pipeline computes APM stats
      receivers: [otlp]
      processors: [batch]
      exporters: [datadog/connector]
    traces/sampling: # this pipeline uses sampling and sends traces
      receivers: [otlp]
      processors: [probabilistic_sampler, infraattributes,batch]
      exporters: [datadog]
    metrics:
      receivers: [otlp, datadog/connector, prometheus]
      processors: [infraattributes,batch]
      exporters: [datadog]
    logs:
      receivers: [otlp]
      processors: [infraattributes, batch]
      exporters: [datadog]

service:
  extensions: [health_check, pprof, zpages, ddflare]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [infraattributes, batch]
      exporters: [datadog, datadog/connector]
    metrics:
      receivers: [otlp, datadog/connector, prometheus]
      processors: [infraattributes, batch]
      exporters: [datadog]
    logs:
      receivers: [otlp]
      processors: [infraattributes, batch]
      exporters: [datadog]

Key components

To send telemetry data to Datadog, the following components are defined in the configuration:

Datadog connector

The Datadog connector computes Datadog APM trace metrics.

connectors:
  datadog/connector:
    traces:

Datadog exporter

The Datadog exporter exports traces, metrics, and logs to Datadog.

exporters:
  datadog:
    api:
      key: <DATADOG_API_KEY>
      site: <DATADOG_SITE>

Note: If key is not specified or set to a secret, or if site is not specified, the system uses values from the core Agent configuration. By default, the core Agent sets site to datadoghq.com (US1).

Prometheus receiver

The Prometheus receiver collects health metrics from the OpenTelemetry Collector for the metrics pipeline.

receivers:
  prometheus:
    config:
      scrape_configs:
        - job_name: "otel-collector"
          scrape_interval: 60s
          static_configs:
            - targets: ["0.0.0.0:8888"]

For more information, see the Collector Health Metrics documentation.

Send your telemetry to Datadog

To send your telemetry data to Datadog:

1. Instrument your application
2. Configure the application
3. Correlate observability data
4. Run your application

Instrument the application

Instrument your application using the OpenTelemetry API.

@WithSpan(kind = SpanKind.CLIENT)
public String getDate() {
    Span span = Span.current();
    span.setAttribute("peer.service", "random-date-service");
    ...
}

Configure the application

Your application must send data to the DDOT Collector on the same host. Ensure that the OTEL_EXPORTER_OTLP_ENDPOINT environment variable is set on your application.

If using the example application, run-otel-local.sh sets up the required environment variables and runs the application:

export OTEL_METRICS_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"

Correlate observability data

Unified service tagging ties observability data together in Datadog so you can navigate across metrics, traces, and logs with consistent tags.

In bare-metal environments, env, service, and version are set through the OpenTelemetry Resource Attributes environment variables. The DDOT Collector detects this tagging configuration and applies it to the data it collects from applications.

In the example application, this is done in run-otel-local.sh:

export OTEL_RESOURCE_ATTRIBUTES="service.name=my-calendar-service,service.version=1.0,deployment.environment.name=otel-test,host.name=calendar-host"

Run the application

Redeploy your application to apply the changes made in your environment variables. After the updated configuration is active, unified service tagging is fully enabled for your metrics, traces, and logs.

Explore observability data in Datadog

Use Datadog to explore the observability data for your application.

Fleet automation

Explore your Datadog Agent and Collector configuration.

Infrastructure monitoring

View runtime and infrastructure metrics to visualize, monitor, and measure the performance of your hosts.

Logs

View logs to monitor and troubleshoot application and system operations.

Traces

View traces and spans to observe the status and performance of requests processed by your application, with infrastructure metrics correlated in the same trace.

Runtime metrics

Monitor your runtime (JVM) metrics for your applications.

Collector health metrics

View metrics from the DDOT Collector to monitor the Collector health.

Further reading

Documentation, liens et articles supplémentaires utiles:

Use Custom OpenTelemetry Components with Datadog AgentDOCUMENTATION