OTLP Trace Ingestion by the Datadog Agent

Cette page n'est pas encore disponible en français, sa traduction est en cours.
Si vous avez des questions ou des retours sur notre projet de traduction actuel, n'hésitez pas à nous contacter.

OTLP Ingest in the Agent is a way to send telemetry data directly from applications instrumented with OpenTelemetry SDKs to Datadog Agent. Since versions 6.32.0 and 7.32.0, the Datadog Agent can ingest OTLP traces and OTLP metrics through gRPC or HTTP.

OTLP Ingest in the Agent allows you to use trace observability features in the Datadog Agent. Because the application is instrumented with OpenTelemetry SDK, some Datadog Tracing Library specific features aren’t available for the ingested data including Application Security Monitoring, Continuous Profiler, Runtime Metrics, and Ingestion Rules.

To get started, you first instrument your application with OpenTelemetry SDKs. Then, export the telemetry data in OTLP format to the Datadog Agent. Configuring this varies depending on the kind of infrastructure your service is deployed on, as described on the page below.

Read the OpenTelemetry instrumentation documentation to understand how to point your instrumentation to the Agent. The receiver section described below follows the OpenTelemetry Collector OTLP receiver configuration schema.

Enabling OTLP Ingestion on the Datadog Agent

OTLP ingestion is off by default, and you can turn it on by updating your datadog.yaml file configuration or by setting environment variables. The following datadog.yaml configurations enable endpoints on the default ports.

For gRPC, default port 4317:

otlp_config:
  receiver:
    protocols:
      grpc:

For HTTP, default port 4318:

otlp_config:
  receiver:
    protocols:
      http:

Alternatively, configure the endpoints by providing the port through the environment variables:

  • For gRPC (0.0.0.0:4317): DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_GRPC_ENDPOINT
  • For HTTP (0.0.0.0:4318): DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT

These must be passed to both the core Agent and trace Agent if they are running in separate containers.

Configure either gRPC or HTTP for this feature. Here is an example application that shows configuration for both.

Deprecation Notice: The use of the `experimental:` configuration listed below for configuring OTLP receiving in `datadog.yaml` and the corresponding environment variables `DD_OTLP_HTTP_PORT` and `DD_OTLP_GRPC_PORT` is now deprecated and will be removed in Agent version `7.37.0`.
experimental:
  otlp:
    receiver:
      protocols:
        grpc:
        http:
  1. Follow the Datadog Docker Agent setup.

  2. For the Datadog Agent container, set the following endpoint environment variables and expose the corresponding port:

    • For gPRC: DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_GRPC_ENDPOINT and port 4317
    • For HTTP: DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT and port 4318
  1. Follow the Kubernetes Agent setup.

  2. Configure the following environment variables in both the trace Agent container and the core Agent container:

    For gPRC:

    name: DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_GRPC_ENDPOINT # enables gRPC receiver on port 4317
    value: "0.0.0.0:4317"
    

    For HTTP:

    name: DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT # enables HTTP receiver on port 4318
    value: "0.0.0.0:4318"
    
  3. Map the container ports 4317 or 4318 to the host port for the core Agent container:

    For gPRC:

    ports:
      - containerPort: 4317
        hostPort: 4317
        name: traceportgrpc
        protocol: TCP
    

    For HTTP

    ports:
      - containerPort: 4318
        hostPort: 4318
        name: traceporthttp
        protocol: TCP
    
  1. Follow the Kubernetes Agent setup.

  2. Set environment variables for the Agent editing the datadog.env parameter of the values.yaml file:

    For gRPC:

    env:
      - name: DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_GRPC_ENDPOINT
        value: "0.0.0.0:4317"
    

    For HTTP:

    env: 
      - name: DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT
        value: "0.0.0.0:4318"
    
  3. Map the container ports (4317 for gRPC or 4318 for HTTP) to the host port for the core Agent container setting them in the agents.containers.agent.ports parameter of the values.yaml file:

    For gRPC:

      ports: 
        - containerPort: 4317
          hostPort: 4317
          name: traceportgrpc
          protocol: TCP
    

    For HTTP:

      ports: 
        - containerPort: 4318
          hostPort: 4318
          name: traceporthttp
          protocol: TCP
    
  1. Follow the Kubernetes Agent setup.

  2. Set environment variables for the Agent using set commands:

    For gRPC:

    --set "datadog.env[0].name=DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_GRPC_ENDPOINT,datadog.env[0].value=0.0.0.0:4317"
    

    For HTTP:

    --set "datadog.env[0].name=DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT,datadog.env[0].value=0.0.0.0:4318"
    
  3. Map the container ports (4317 for gRPC or 4318 for HTTP) to the host port for the core Agent container:

    For gRPC:

    --set 'agents.containers.agent.ports[0].containerPort=4317,agents.containers.agent.ports[0].hostPort=4317,agents.containers.agent.ports[0].name=traceportgrpc,agents.containers.agent.ports[0].protocol=TCP' 
    

    For HTTP:

    --set 'agents.containers.agent.ports[0].containerPort=4318,agents.containers.agent.ports[0].hostPort=4318,agents.containers.agent.ports[0].name=traceporthttp,agents.containers.agent.ports[0].protocol=TCP'
    

There are many other environment variables and settings supported in the Datadog Agent. To get an overview of them all, see the configuration template.

Sending OTLP traces from the application to Datadog Agent

  1. For the application container, set OTEL_EXPORTER_OTLP_ENDPOINT environment variable to point to the Datadog Agent container. For example:

    OTEL_EXPORTER_OTLP_ENDPOINT=http://<datadog-agent>:4318.
    
  2. Both containers must be defined in the same bridge network, which is handled automatically if you use Docker Compose. Otherwise, follow the Docker example in Tracing Docker Applications to set up a bridge network with the correct ports.

  1. In the application deployment file, configure the endpoint that the OpenTelemetry client sends traces to with the OTEL_EXPORTER_OTLP_ENDPOINT environment variable:

    For gPRC:

    env:
     - name: DD_AGENT_HOST
       valueFrom:
         fieldRef:
           fieldPath: status.hostIP
     - name: OTEL_EXPORTER_OTLP_ENDPOINT
       value: "http://$(DD_AGENT_HOST):4317" # sends to gRPC receiver on port 4317
    

    For HTTP:

    env:
     - name: DD_AGENT_HOST
       valueFrom:
         fieldRef:
           fieldPath: status.hostIP
     - name: OTEL_EXPORTER_OTLP_ENDPOINT
       value: "http://$(DD_AGENT_HOST):4318" # sends to HTTP receiver on port 4318
    
Check the documentation of your OTLP Library. Some of them must send traces to `/v1/traces` instead of the `/` root path.

Further Reading

Documentation, liens et articles supplémentaires utiles: