OTel Agent

Active contributors: Yang Song, Olivier G, Stanley Liu

Purpose

otel-agent is a Datadog-built OpenTelemetry Collector flavor. It packages the OTel Collector core with a Datadog exporter, the Datadog-specific extensions, and the Agent's component framework so it can be deployed as a drop-in OTLP-first observability agent.

Customers who want OTel-based instrumentation without losing Datadog backend integration use the OTel Agent. It is also the basis for Datadog Distribution of OpenTelemetry (DDOT), the supported variant.

Directory layout

cmd/otel-agent/
├── main.go
├── command/, subcommands/
├── config/             # OTel config translation, validation
├── dist/               # Default config files
├── windows/, windows_resources/
└── BUILD.bazel

comp/otelcol/           # The component bundle that wires the OTel collector
├── otlpingest/         # OTLP receiver components
├── ddflareextension/   # Flare extension that talks to the Agent's flare component
├── converter/          # Datadog converter pieces
├── extension/, processor/, receiver/  # Custom OTel pipeline components
└── ...

Architecture

graph LR
    APP[Instrumented apps] -->|OTLP| RECV[OTLP receiver]
    RECV --> PIPE[Collector pipeline<br/>processors / connectors]
    PIPE --> DDEXP[Datadog exporter]
    PIPE --> OTEL_BACKEND[Other OTel backends<br/>optional]
    DDEXP -->|HTTP| INTAKE[Datadog intake]

The OTel Agent uses the upstream OTel Collector engine internally, but the full pipeline is composed via the same Fx component framework as the rest of the Agent. This lets the OTel Collector reuse Agent components (config, log, secrets, tagger, …) where it makes sense.

DDOT and the converter

Datadog ships a converter (comp/otelcol/converter/) that takes the OTel Collector's pipeline declaration and turns parts of it into Datadog-specific equivalents (e.g., Datadog exporter, attribute mapping). This means a customer can write a near-stock OTel config and have it produce a sensible Datadog deployment.

A recent commit ([OTAGENT-1028] reuse user-defined datadog extension in converter, PR #50135) is illustrative: the converter participates in user-supplied extensions rather than blindly overriding them.

Subcommands

Subcommand	Purpose
run	Long-running collector daemon.
version	Version info.
validate	Validate an OTel config.
flare	Build a flare archive (with OTel pipeline state).
status	Status snapshot.

Configuration

Unlike the rest of the Agent, the OTel Agent's primary configuration is an OTel-style YAML pipeline, not datadog.yaml. Default templates live in cmd/otel-agent/dist/.

When deployed as DDOT, the OTel Agent can also read parts of datadog.yaml for things like the API key, hostname, and tags — this is the converter's job.

Components

The OTel Agent introduces several Datadog-specific extensions and processors:

• DD flare extension (comp/otelcol/ddflareextension/) — exposes flare-style introspection over the OTel collector's API.
• Datadog exporter — the canonical exporter for Datadog APM/metrics/logs.
• Custom receivers under comp/otelcol/otlpingest/ for the embedded ingestion path.

Trace path

The OTel Agent shares a lot of code with the standalone Trace Agent: OTLP receiver, transformation pipeline, sampler. See Trace Agent for the underlying machinery.

Key abstractions

Type / package	Location	Purpose
Component	comp/otelcol/	The bundle that exposes the OTel collector to Fx
Converter	comp/otelcol/converter/	Translates Datadog config to OTel pipeline
Flare extension	comp/otelcol/ddflareextension/	Adds OTel pipeline state to flares

Entry points for modification

• Adding a new processor or extension: place it under comp/otelcol/processor/<name>/ or comp/otelcol/extension/<name>/ and register it in the bundle.
• Adjusting the converter: extend comp/otelcol/converter/.
• Adding a new exporter is unusual; Datadog typically reuses the upstream Datadog exporter.

Related pages

• Apps: Trace Agent — shares the OTLP receiver and trace-processing code.
• Features: APM tracing — end-to-end tracing.