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

# Migrating from Datadog

> Send logs, traces, and metrics from existing Datadog agents to managed or self-managed ClickHouse Observability.

[Experimental feature](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#experimental-features)

Send logs, traces, and metrics from your existing Datadog agents to ClickHouse Observability. Your applications can keep their Datadog SDKs. Choose a managed endpoint or configure a Datadog receiver in your own collector, then use the same Agent configuration steps below.

## Prerequisites

* A managed or self-managed ClickHouse Observability service.
* A running Datadog Agent collecting the signals you want to migrate. For traces, your application must already send traces to that Agent through a Datadog SDK.
* Network access from the Agent to your Datadog receiver endpoint.

## Set up your destination

> [tab] Fully managed
>
> [Beta offering](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)
>
> Open your service and navigate to **Team Settings → Data → Managed Telemetry**. Copy the **OTLP HTTP endpoint** and **API key**.
>
> ![Managed Telemetry showing the masked OTLP HTTP endpoint and API key](https://mintcdn.com/private-7c7dfe99/Zk1feNn6fCQBpold/images/clickstack/getting-started/observability-managed-telemetry.png?fit=max\&auto=format\&n=Zk1feNn6fCQBpold\&q=85\&s=e63a2ac2e6ab996d3fc360ebe0f487a5)
>
> The Datadog endpoint uses the same hostname with port `8126`. No additional collector is required. Use these values in the Agent configuration below:
>
> | Setting | Value |
> | - | - |
> | `YOUR_API_KEY` | Your service's ingestion API key |
> | `YOUR_DATADOG_URL` | `https://YOUR_OTEL_HOST:8126` |
> | `YOUR_DATADOG_HOST_PORT` | `YOUR_OTEL_HOST:8126` |
> | `logs_no_ssl` | `false` |

> [tab] Self-managed
>
> The [ClickStack OpenTelemetry collector](https://clickhouse.com/docs/clickstack/self-configured/ingesting-data/collector.md) includes the [Datadog receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/datadogreceiver). Configure the receiver and connect it to your logs, traces, and metrics pipelines.
>
> Save the following configuration overlay as `datadog-collector.yaml`. It adds the Datadog receiver to the collector's existing logs, traces, and metrics pipelines while preserving the OTLP receiver:
>
> ```yaml theme={null}
> receivers:
>   datadog:
>     endpoint: 0.0.0.0:8126
>
> service:
>   pipelines:
>     logs/in:
>       receivers: [otlp/hyperdx, datadog]
>     traces:
>       receivers: [otlp/hyperdx, datadog]
>     metrics:
>       receivers: [otlp/hyperdx, datadog]
> ```
>
> Set your ClickHouse connection details and start the collector. Normal startup creates the telemetry schema in the database specified by `HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE`; the ClickHouse user needs permission to create the database and tables. Use your existing telemetry database name if you already have one.
>
> This example requires Docker, uses collector version `2.40.0`, and publishes the Datadog receiver only on the local host:
>
> ```shell theme={null}
> export CLICKHOUSE_ENDPOINT='https://YOUR_CLICKHOUSE_HOST:8443'
> export CLICKHOUSE_USER='YOUR_CLICKHOUSE_USER'
> export CLICKHOUSE_PASSWORD='YOUR_CLICKHOUSE_PASSWORD'
> export HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE='default'
>
> docker run --rm --name datadog-collector \
>   -e CLICKHOUSE_ENDPOINT \
>   -e CLICKHOUSE_USER \
>   -e CLICKHOUSE_PASSWORD \
>   -e HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE \
>   -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/datadog-collector.yaml \
>   -v "$(pwd)/datadog-collector.yaml:/etc/datadog-collector.yaml:ro" \
>   -p 127.0.0.1:18126:8126 \
>   clickhouse/clickstack-otel-collector:2.40.0
> ```
>
> Leave the collector running in this terminal while you configure and verify the Agent. Use a separate terminal for the remaining commands.
>
> Use these values for an Agent running on the same host:
>
> | Setting | Value |
> | - | - |
> | `YOUR_API_KEY` | A nonempty placeholder such as `local-test`; this local receiver does not validate it |
> | `YOUR_DATADOG_URL` | `http://localhost:18126` |
> | `YOUR_DATADOG_HOST_PORT` | `localhost:18126` |
> | `logs_no_ssl` | `true` |
>
> Host port `18126` keeps this destination separate from the Agent's application trace listener on port `8126`. For a containerized Agent, connect both containers to the same Docker network and use `http://datadog-collector:8126` and `datadog-collector:8126` as the destination values.
>
> This example uses an unauthenticated HTTP listener restricted to the local host. For Agents on other hosts, provide a protected network path and configure TLS and authentication at your ingress before exposing the receiver. `OTLP_AUTH_TOKEN` configures the collector's OTLP authentication; it does not secure this Datadog listener.

## Configure the Datadog Agent

Update your Agent's [`datadog.yaml` configuration file](https://docs.datadoghq.com/agent/configuration/agent-configuration-files/). Typical locations are `/etc/datadog-agent/datadog.yaml` on Linux and `/opt/datadog-agent/etc/datadog.yaml` on macOS.

Merge the following settings into your existing configuration, using the destination values from the tab above:

```yaml theme={null}
api_key: "YOUR_API_KEY"

# Metrics destination
dd_url: "YOUR_DATADOG_URL"

# Use the v2 metrics intake.
use_v3_api:
  series:
    enabled: false

# Trace destination
apm_config:
  enabled: true
  apm_dd_url: "YOUR_DATADOG_URL"
  features:
    - disable-convert-traces

# Log destination
logs_enabled: true
logs_config:
  logs_dd_url: "YOUR_DATADOG_HOST_PORT"
  force_use_http: true
  logs_no_ssl: false # Set to true for the local HTTP receiver.

remote_updates: false
remote_configuration:
  enabled: false
```

Replace `YOUR_DATADOG_URL` with the full destination URL and `YOUR_DATADOG_HOST_PORT` with its `hostname:port`, without a scheme. Set `logs_no_ssl` to the value specified for your destination.

> [!NOTE]
>
> `disable-convert-traces` keeps Agent trace payloads compatible with the Datadog receiver. With Datadog Agent 7.85.2 and collector core 0.155.0, the Agent's default indexed payload was accepted with HTTP 200 but produced no spans. Use the setting above for trace forwarding, and preserve any other entries in your existing `apm_config.features` list.

Keep your existing log collection integrations and application tracing configuration. These settings change where the Agent sends telemetry; they do not enable log collection for individual applications or add instrumentation. If you configure the Agent through [environment variables](https://docs.datadoghq.com/agent/guide/environment-variables/), update the corresponding settings there too, including `DD_API_KEY`.

This configuration redirects the Agent's logs, traces, and metrics from Datadog to ClickHouse Observability. To evaluate it first, apply it to a test Agent before updating your wider deployment.

## Restart and verify

Restart the Agent to apply the configuration. On Linux:

```shell theme={null}
sudo systemctl restart datadog-agent
sudo datadog-agent status
```

On macOS:

```shell theme={null}
sudo launchctl kickstart -k system/com.datadoghq.agent
```

For a containerized Agent, update its configuration and redeploy the container.

Generate fresh application activity, then open ClickHouse Observability and select a recent time range:

* **Logs:** select your Logs source and filter by the application's `ServiceName`.
* **Traces:** select your Traces source and filter by the application's `ServiceName`.
* **Metrics:** search for a metric emitted by your application or Agent. For a DogStatsD test, emit a named gauge and check its value.

Check the Agent status for delivery errors if data does not appear. Verify the hostname, port, API key, and your service's network access settings. Confirm that the Agent is collecting the relevant signal and that any environment-variable overrides use the same destination.

For traces, verify a known trace ID rather than relying only on successful Agent delivery counters. If a service filter hides the trace, search by `TraceId`: the receiver can use the tracer's base service as the resource service name while retaining a per-span service override in the `service.name` span attribute. Set `DD_SERVICE` in your application's tracing configuration to establish its base service name.

## Supported signals

The Datadog receiver is experimental. It translates Datadog logs, traces, and supported metrics into the OpenTelemetry data model used by ClickHouse Observability. The configuration above selects the v2 metrics intake; other Datadog backend features are outside this migration flow.

You can retain your existing Datadog instrumentation while migrating applications to OpenTelemetry gradually.