> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Datadog

> OpenTelemetry receiver for Datadog

# Datadog Receiver

![Status](https://img.shields.io/badge/status-alpha-red)

**Available in:** `contrib`

**Maintainers:** [@boostchicken](https://github.com/boostchicken), [@MovieStoreGuy](https://github.com/MovieStoreGuy)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/datadogreceiver)

## Supported Telemetry

![Logs](https://img.shields.io/badge/logs-alpha-blue) ![Metrics](https://img.shields.io/badge/metrics-alpha-green) ![Traces](https://img.shields.io/badge/traces-alpha-orange)

## Overview

## Configuration

Configuration wise is very simple, just need to specify where the Datadog receiver should listen and the read timeout.

Then, the receiver must be configured in the pipeline where it will be used.

The feature gate `receiver.datadogreceiver.Enable128BitTraceID` (enabled by default) makes the receiver reconstruct
full 128-bit trace ids from spans coming from a datadog instrumented service, so they correlate with OpenTelemetry
spans. Datadog splits a 128-bit trace id into a lower 64-bit part (`TraceID`) and an upper 64-bit part (`_dd.p.tid`);
the receiver concatenates them. Disable the gate to fall back to 64-bit (zero-padded) trace ids.

```yaml theme={null}
receivers:
  datadog:
    endpoint: localhost:8126
    read_timeout: 60s
    trace_id_cache_size: 100
    idle_series_timeout: 60m
    idle_series_cleanup_interval: 5m

exporters:
  debug:

service:
  pipelines:
    metrics:
      receivers: [datadog]
      exporters: [debug]
    traces:
      receivers: [datadog]
      exporters: [debug]
```

### read\_timeout (Optional)

The read timeout of the HTTP Server

Default: 60s

### trace\_id\_cache\_size (Optional)

The size of the LRU cache used to cache 64-bit trace ids and their matching 128-bit trace ids. This only has en effect
when the feature gate `receiver.datadogreceiver.Enable128BitTraceID` is enabled.

Default: 100

### idle\_series\_timeout (Optional)

The duration a specific series (metric name + unique tags) can be idle (not receive data) before being considered stale and removed from memory. This is useful to release memory in High Cardinality scenarios (e.g. ephemeral pods) where the number of series grows indefinitely.

Recommendation: If enabled, ensure this value is significantly higher than the interval of your slowest emitting metric or cronjob. For example, if you have a job that runs every 30 minutes, set this to at least 60m to avoid resetting the start timestamp for those metrics.

Default: 0s (Disabled - series are kept indefinitely)

### idle\_series\_cleanup\_interval (Optional)

The duration between runs of the idle series cleanup task. This setting is only used when idle\_series\_timeout is enabled (greater than 0).
The value must be a string with a unit (e.g. "5m", "60s").

Default: "5m"

### logs.decode\_json\_message (Optional)

When `true`, log records whose `message` is itself a JSON object are expanded, mirroring Datadog's
server-side "Preprocessing for JSON logs". The Datadog Agent forwards an application's JSON log as an
opaque `message` string (JSON parsing normally happens in the Datadog backend), so without this the
whole line becomes the log body. With it enabled, the inner reserved attributes take precedence over
the agent envelope:

* inner `message` → log body
* `status`/`level`/`severity` → severity
* `timestamp`/`@timestamp`/`date` → timestamp (the application's emit time, overriding the agent's collection time)
* `hostname`/`host` → `host.name`, `service` → `service.name`
* `dd.trace_id`/`dd.span_id` (decimal) → the record's `TraceID`/`SpanID`, enabling trace-log correlation
* remaining inner keys → log attributes (with Datadog→OTel key translation)

Default: `true`. Set to `false` to keep the raw JSON message as the log body.

```yaml theme={null}
receivers:
  datadog:
    endpoint: localhost:8126
    logs:
      decode_json_message: true
```

### HTTP Service Config

All config params here are valid as well

[https://github.com/open-telemetry/opentelemetry-collector/tree/main/config/confighttp#server-configuration](https://github.com/open-telemetry/opentelemetry-collector/tree/main/config/confighttp#server-configuration)

### `/intake` Config

The `datadog-agent` forwards metadata about its runtime environment via the `/intake` API endpoint.
This receiver supports receiving this data and forwarding it directly to Datadog.
(Note that this data isn't telemetry data, so it does not go through any configured collector pipelines.)

This feature can be enabled in the config:

```
receivers:
  datadog:
    intake:
      behavior: proxy
      proxy:
        api:
          key: ${env:DD_API_KEY}
          site: datadoghq.com
          fail_on_invalid_key: true
```

### Metric Tag→Attribute Conversion

Datadog [metric tags](https://docs.datadoghq.com/getting_started/tagging/) are expected to be in a `key:value` format.
Tags not in this format will be given an `unnamed_` prefix when added to the attribute map (e.g. the tag `prod` will be converted to `unnamed_prod = prod`).

By default, multiple tags for the same data point with the same `key:` prefix will only have the last tag retained (e.g. `["env:a","env:b"]` will be converted to `{env = b}`).
If the `receiver.datadogreceiver.EnableMultiTagParsing` feature gate is enabled, multiple tags with the same key will instead be stored as a slice (e.g. `["env:a","env:b"]` will be converted to `{env = [a,b]}`).

### Default Attributes

* `dd.span.Resource`: The datadog resource name (as distinct from the span name)

### Optional Attributes

* `_dd.span_links`: This receiver supports DD Agent's `_dd.span_links` attribute for span links creation, as produced by Datadog's tracing libraries.
  Format example can be found [here](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/datadogreceiver/internal/translator/traces_translator_test.go).

### Datadog's API support

**Traces**

| Datadog API Endpoint | Status | Notes                        |
| -------------------- | ------ | ---------------------------- |
| /v0.3/traces         | Alpha  | Support for msgpack and json |
| /v0.4/traces         | Alpha  | Support for msgpack and json |
| /v0.5/traces         | Alpha  | Msgpack custom format        |
| /v0.7/traces         | Alpha  |                              |
| /api/v0.2/traces     | Alpha  |                              |

**Metrics**

| Datadog API Endpoint         | Status      | Notes                      |
| ---------------------------- | ----------- | -------------------------- |
| /api/v1/series               | Development |                            |
| /api/v2/series               | Development |                            |
| /api/v1/check\_run           | Development |                            |
| /api/v1/sketches             | Development |                            |
| /api/beta/sketches           | Development |                            |
| /api/v1/distribution\_points | Development |                            |
| /intake                      | Development | Support for proxying calls |

**Logs**

| Datadog API Endpoint | Status      | Notes                        |
| -------------------- | ----------- | ---------------------------- |
| /api/v2/logs         | Development | Support for msgpack and json |

### Temporality considerations

Some backends use a different [timestamp temporality](https://opentelemetry.io/docs/specs/otel/metrics/data-model/#temporality) than Datadog uses. Both delta and cumulative temporalities are allowed in the spec.
In order to store metrics on these backends, the receiver will need to translate the timestamps.
For backends that use cumulative temporality, a [delta to cumulative processor](../../processor/deltatocumulativeprocessor/README.md) can be configured in the pipeline.

***

*Last generated: 2026-07-06*