Descripción general

El punto de conexión de la API de ingesta de trazas del protocolo OpenTelemetry (OTLP) de Datadog permite que las aplicaciones, las plataformas administradas y los colectores de OpenTelemetry envíen trazas a Datadog a través de OTLP HTTP.

Utilice la configuración directa en esta página cuando necesite enviar trazas sin el Datadog Agent o un colector de OpenTelemetry. Para implementaciones de colector en producción, utilice Configurar el colector de OpenTelemetry.

Para cargas de trabajo Serverless, consulte OTLP Intake for Serverless. Para plataformas administradas como Cloudflare, Vercel y Heroku, consulte Ingesta OTLP para plataformas administradas.

Configuración

Para exportar datos OTLP al punto de conexión de ingesta de trazas OTLP de Datadog:

1. Configure el exportador OTLP HTTP Protobuf.
   • Establezca el punto de conexión de ingesta de trazas OTLP de Datadog.
   • Configure los encabezados HTTP requeridos.
2. (Opcional) Establezca el dd-otel-span-mappingencabezado HTTP para asignar o filtrar tramos.

Configure el exportador

Para enviar datos OTLP al punto de conexión de ingesta de trazas OTLP de Datadog, necesita usar el exportador OTLP HTTP Protobuf. El proceso difiere dependiendo de si está utilizando instrumentación automática o manual para OpenTelemetry.

Las métricas de traza no se calculan de forma predeterminada para las trazas enviadas directamente al punto de conexión de ingesta de trazas OTLP de Datadog. Los siguientes ejemplos incluyen compute_stats=true para habilitar las métricas de traza.

Instrumentación automática

Si está utilizando instrumentación automática de OpenTelemetry, establezca las siguientes variables de entorno:

export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=""
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="dd-api-key=${DD_API_KEY},compute_stats=true"

Instrumentación manual

Si está utilizando instrumentación manual con SDK de OpenTelemetry, configure el exportador OTLP HTTP Protobuf mediante programación.

const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');  // OTLP http/protobuf exporter

const exporter = new OTLPTraceExporter({
  url: '${YOUR_ENDPOINT}', // Replace this with the correct endpoint
  headers: {
    'dd-api-key': process.env.DD_API_KEY,
    'dd-otel-span-mapping': '{span_name_as_resource_name: true}',
    'compute_stats': 'true',
  },
});

import io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporter;

OtlpHttpSpanExporter exporter = OtlpHttpSpanExporter.builder()
    .setEndpoint("${YOUR_ENDPOINT}") // Replace this with the correct endpoint
    .addHeader("dd-api-key", System.getenv("DD_API_KEY"))
    .addHeader("dd-otel-span-mapping", "{span_name_as_resource_name: true}")
    .addHeader("compute_stats", "true")
    .build();

import "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"

traceExporter, err := otlptracehttp.New(
	ctx,
	otlptracehttp.WithEndpoint("${YOUR_ENDPOINT}"), // Replace this with the correct endpoint
	otlptracehttp.WithURLPath("/v1/traces"),
	otlptracehttp.WithHeaders(
		map[string]string{
			"dd-api-key": os.Getenv("DD_API_KEY"),
			"dd-otel-span-mapping": "{span_name_as_resource_name: true}",
			"compute_stats": "true",
		}),
)

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="${YOUR_ENDPOINT}", # Replace this with the correct endpoint
    headers={
        "dd-api-key": os.environ.get("DD_API_KEY"),
        "dd-otel-span-mapping": "{span_name_as_resource_name: true}",
        "compute_stats": "true",
    },
)

(Opcional) Asigne o filtre nombres de tramos

Utilice el encabezado dd-otel-span-mapping para configurar la asignación y el filtrado de tramos. El encabezado JSON contiene los siguientes campos:

• ignore_resources: Una lista de expresiones regulares para deshabilitar trazas según su nombre de recurso.
• span_name_remappings: Un mapa de nombres de tramos de Datadog a nombres preferidos.
• span_name_as_resource_name: Especifica si se debe usar el nombre del tramo de OpenTelemetry como el nombre de la operación del tramo de Datadog (predeterminado: true). Si es false, el nombre de la operación se deriva de una combinación del nombre del contexto de instrumentación y el tipo de tramo.

Por ejemplo:

{
  "span_name_as_resource_name":false,
  "span_name_remappings":{
    "io.opentelemetry.javaagent.spring.client":"spring.client"
  },
  "ignore_resources":[
    "io.opentelemetry.javaagent.spring.internal"
  ]
}

OpenTelemetry Collector

Configure la configuración recomendada de OpenTelemetry Collector para exportar trazas a este punto de conexión y generar métricas de traza de APM antes del muestreo.

Solución de problemas

Error: 403 Forbidden

Si recibe un error 403 Forbidden al enviar trazas al punto de conexión de ingesta de trazas OTLP de Datadog, verifique que el punto de conexión coincida con su sitio de Datadog. Su sitio es , así que use el punto de conexión.

Error: 413 Request Entity Too Large

Si recibe un error 413 Request Entity Too Large al enviar trazas al punto de conexión de ingesta de trazas OTLP de Datadog, indica que el tamaño de la carga útil enviada por el exportador OTLP excede el límite de 15 MiB (sin comprimir) del punto de conexión de ingesta de trazas de Datadog.

Este error generalmente ocurre cuando el SDK de OpenTelemetry agrupa demasiados datos de telemetría en una sola carga útil de solicitud.

Solución: Reduzca el tamaño del lote de exportación del procesador de tramos por lotes del SDK. Aquí hay un ejemplo de cómo modificar el BatchSpanProcessorBuilder en el SDK de Java de OpenTelemetry:

CopyBatchSpanProcessor batchSpanProcessor =
    BatchSpanProcessor
        .builder(exporter)
        .setMaxExportBatchSize(10)  // Default is 512
        .build();

Ajuste el valor de setMaxExportBatchSize según sus necesidades. Un valor más pequeño resulta en exportaciones más frecuentes con cargas útiles más pequeñas, lo que reduce la probabilidad de exceder el límite de 15 MiB.

Advertencia: "traces export: failed … 202 Accepted" en Go

Si está utilizando el SDK de Go de OpenTelemetry y ve un mensaje de advertencia similar a traces export: failed … 202 Accepted, se debe a un problema conocido en el exportador HTTP OTLP de OpenTelemetry para Go.

El exportador HTTP OTLP de OpenTelemetry para Go trata cualquier código de estado HTTP que no sea 200 como un error, incluso si la exportación tiene éxito (Issue 3706). En contraste, otros SDK de OpenTelemetry consideran cualquier código de estado en el rango [200, 300) como un éxito. El punto de conexión de ingesta de trazas OTLP de Datadog devuelve un código de estado 202 Accepted para las exportaciones exitosas.

La comunidad de OpenTelemetry aún está discutiendo si otros códigos de estado 2xx deben tratarse como éxitos (Issue 3203).

Solución: Si está utilizando el punto de conexión de ingesta de trazas OTLP de Datadog con el SDK de OpenTelemetry para Go, puede ignorar este mensaje de advertencia de forma segura. Sus trazas se están exportando correctamente a pesar de la advertencia.

Problema: Nombres de operación de tramo inesperados

Al utilizar el punto de conexión de ingesta de trazas OTLP de Datadog, es posible que note que los nombres de las operaciones de tramo son diferentes a los generados al utilizar el Datadog Agent o el OpenTelemetry Collector.

El punto de conexión de ingesta de trazas OTLP de Datadog tiene la opción span_name_as_resource_name establecida en true de forma predeterminada. Esto significa que Datadog utiliza el nombre del tramo de OpenTelemetry como nombre de la operación. Por el contrario, el Datadog Agent y el OpenTelemetry Collector tienen esta opción establecida en false de forma predeterminada.

Cuando span_name_as_resource_name se establece en false, el nombre de la operación se deriva de una combinación del nombre del contexto de instrumentación y el tipo de tramo. Por ejemplo, un nombre de operación podría aparecer como opentelemetry.client.

Solución: Si desea deshabilitar la opción span_name_as_resource_name en el punto de conexión de ingesta de trazas OTLP de Datadog para que coincida con el comportamiento del Datadog Agent o del OpenTelemetry Collector, siga estos pasos:

1. Consulte Asignar o filtrar nombres de tramo en este documento.
2. Establezca la opción span_name_as_resource_name en false en el encabezado dd-otel-span-mapping.

Por ejemplo:

jsonCopy{
  "span_name_as_resource_name": false,
  ...
}

Esto garantiza que los nombres de las operaciones de tramo sean consistentes en el punto de conexión de ingesta de trazas OTLP de Datadog, el Datadog Agent y el OpenTelemetry Collector.

Lecturas adicionales

Documentación, enlaces y artículos útiles adicionales:

Configuración general del SDK de OpenTelemetrySITIO EXTERNO Especificación de variables de entorno de OpenTelemetrySITIO EXTERNO Exportador del protocolo OpenTelemetrySITIO EXTERNO