Configuring Datadog with OpenTelemetry

Evolve services export traces and metrics through OpenTelemetry (OTel) to an OTel Collector or directly to a backend. Datadog is OTel-compatible and works without changes to service code. This guide covers configuring the Collector exporter, environment variables, and Terraform secrets.

1. Configure the OTel Collector exporter

Add a Datadog exporter to your OpenTelemetry Collector configuration. The local development setup in docker/otel-collector/otel-collector-config.yaml ships traces to Jaeger by default. For Datadog, add or replace the exporter:

# otel-collector-config.yaml
exporters:
  datadog:
    api:
      site: datadoghq.eu        # or datadoghq.com for US
      key: ${DD_API_KEY}

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [datadog]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [datadog]

The otlp receiver accepts data from services on gRPC (port 4317) and HTTP (port 4318). No changes to service code are required.

2. Set environment variables

Each service needs to know where to send telemetry. These variables are set in the service's Terraform or container configuration:

OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
OTEL_EXPORTER_OTLP_HEADERS=dd-api-key=<your-api-key>
OTEL_SERVICE_NAME=catalog-commercetools

The OTEL_SERVICE_NAME maps to the Datadog service name in APM. Use the same name as your component for consistency. The OTEL_EXPORTER_OTLP_HEADERS variable passes authentication headers to the Collector or directly to Datadog's OTLP endpoint.

Services initialize OTel through initObservability() in their run.ts entry point. This function configures the OpenTelemetry SDK, sets up the OTLP exporter (gRPC or HTTP based on OTEL_EXPORTER_OTLP_PROTOCOL), and optionally integrates with Sentry for error tracking.

3. Configure Mach Composer

Add the Datadog API key to your SOPS-encrypted secrets file:

# config/<cloud>/tst.secrets.yaml
secrets:
  datadog:
    api_key: <your-datadog-api-key>  # encrypted by SOPS

Then reference the secret in your Mach Composer environment config and pass it to all components as a global secret and variable:

# config/<cloud>/tst.yaml
global:
  variables:
    otel_exporter_otlp_endpoint: "https://your-otel-collector-endpoint"
  secrets:
    datadog_api_key: ${var.secrets.datadog.api_key}

4. Wire the Terraform variables

Each service's Terraform receives the secret through var.secrets and injects it as environment variables in locals.tf:

locals {
  env_vars = {
    OTEL_EXPORTER_OTLP_ENDPOINT = var.variables.otel_exporter_otlp_endpoint
    OTEL_EXPORTER_OTLP_HEADERS  = "dd-api-key=${var.secrets.datadog_api_key}"
    OTEL_SERVICE_NAME            = local.service_name
  }
}

Follow the existing patterns in backend/services/catalog-commercetools/terraform/aws/locals.tf (or the equivalent Azure/GCP directory) to see how other observability secrets are injected.

5. Verify traces and metrics

After deploying the updated Collector:

Open the Datadog APM page and look for your service names
Trigger a request through the storefront and check that a distributed trace appears spanning the gateway and backend services
Check the Metrics Explorer for OTel metrics (request duration, error rate)

If traces do not appear, check the Collector logs for export errors and verify that the API key and site are correct.

6. Add Core Web Vitals (optional)

Evolve's frontend reports Core Web Vitals through OTel. These metrics flow through the same Collector pipeline, so they appear in Datadog automatically once the exporter is configured. You can build dashboards tracking LCP, FID, and CLS per page and per deployment.

1. Configure the OTel Collector exporter​

2. Set environment variables​

3. Configure Mach Composer​

4. Wire the Terraform variables​

5. Verify traces and metrics​

6. Add Core Web Vitals (optional)​

Further reading​