Has instrumentado un servicio, el Collector está en marcha y, aun así, las trazas de OpenTelemetry ausentes en Dynatrace dejan vacía la pantalla Distributed Tracing. Mientras tanto, el incidente en curso no tiene contexto, el MTTR sube y el equipo duda de toda la cadena de telemetría.
Objetivo de este tutorial: seguir una lista de comprobación de resolución de problemas OTLP en 8 pasos, de la aplicación a Grail, y aislar en menos de 30 minutos el eslabón que pierde los spans. El contenido sirve para Dynatrace SaaS y Dynatrace Managed; las diferencias de URL se indican en cada caso.
Si aún no tienes un Collector, empieza por instalar y configurar el Collector de OpenTelemetry para Dynatrace y vuelve después aquí.
El principio: remontar la cadena eslabón por eslabón
Una traza recorre cuatro eslabones: el SDK en la aplicación, la exportación OTLP, el Collector (si existe) y, por último, el endpoint OTLP de Dynatrace. Cada paso siguiente prueba un solo eslabón. No te saltes ninguno: la causa más frecuente suele ser la más banal (ruta de URL incorrecta, token sin el scope adecuado).
Requisitos previos
- Acceso de lectura a los logs de la aplicación y del Collector.
- Un token de API de Dynatrace con el scope
openTelemetryTrace.ingest(Ingest OpenTelemetry traces). curlen una máquina de la misma red que la aplicación.- SaaS: acceso a Notebooks o a la aplicación Distributed Tracing. Managed: acceso a la pantalla Distributed traces del entorno.
Trazas de OpenTelemetry ausentes: la lista de comprobación en 8 pasos
Paso 1: comprobar que el SDK produce spans
Activa un exporter de consola junto al exporter OTLP. Con la autoinstrumentación (Java, Python, Node.js), bastan las variables de entorno estándar:
export OTEL_SERVICE_NAME=checkout
export OTEL_TRACES_EXPORTER=otlp,console
export OTEL_TRACES_SAMPLER=always_on
Si no aparece ningún span en la salida estándar, el problema está en la aplicación: agente no cargado, biblioteca sin instrumentar o sampler en always_off. La compatibilidad con el valor console depende del lenguaje: consulta la documentación de tu SDK.
Paso 2: comprobar el protocolo y el puerto
El endpoint OTLP de Dynatrace acepta OTLP sobre HTTP (protobuf). Un SDK configurado con gRPC (puerto 4317) directamente hacia Dynatrace no llegará a nada. Fija el protocolo de forma explícita:
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
Si la aplicación envía a un Collector local, funcionan tanto gRPC en el 4317 como HTTP en el 4318, siempre que el receiver correspondiente esté activado en el Collector.
Paso 3: comprobar la URL exacta
Es la causa número uno. La variable genérica OTEL_EXPORTER_OTLP_ENDPOINT recibe la base, y el SDK añade /v1/traces. La variable específica OTEL_EXPORTER_OTLP_TRACES_ENDPOINT recibe la URL completa.
# SaaS
export OTEL_EXPORTER_OTLP_ENDPOINT=https://<env-id>.live.dynatrace.com/api/v2/otlp
# Managed
export OTEL_EXPORTER_OTLP_ENDPOINT=https://<votre-domaine>/e/<env-id>/api/v2/otlp
# ActiveGate d'environnement
export OTEL_EXPORTER_OTLP_ENDPOINT=https://<activegate>:9999/e/<env-id>/api/v2/otlp
Error clásico: poner /api/v2/otlp/v1/traces en la variable genérica, lo que da /v1/traces/v1/traces y una respuesta 404. Comprueba el formato exacto en la documentación de la API OTLP de Dynatrace.
Paso 4: comprobar el token y su cabecera
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Api-Token%20dt0c01.XXXX"
El prefijo Api-Token seguido de un espacio es obligatorio; en esta variable, el espacio se escribe %20. Un 401 indica un token inválido o mal formado, un 403 un scope ausente. Prueba el endpoint a mano para decidirlo:
curl -s -o /dev/null -w "%{http_code}\n" -X POST \
"https://<env-id>.live.dynatrace.com/api/v2/otlp/v1/traces" \
-H "Authorization: Api-Token $DT_TOKEN" \
-H "Content-Type: application/x-protobuf" \
--data-binary @/dev/null
Un cuerpo vacío no es una traza válida: quédate sobre todo con la diferencia entre 401/403 (autenticación), 404 (ruta) y una respuesta 2xx o 400 (el endpoint es accesible y el token se acepta). El código exacto para un cuerpo vacío puede variar.
Paso 5: comprobar la red y el TLS
Desde el pod o el host de la aplicación (no desde tu equipo):
curl -v https://<env-id>.live.dynatrace.com/api/v2/otlp/v1/traces 2>&1 | grep -E "Connected|SSL|HTTP/"
Un timeout apunta a un cortafuegos, a un proxy de salida sin configurar o a una NetworkPolicy de Kubernetes. Un error de certificado en Managed suele indicar una autoridad interna que el runtime de la aplicación no conoce; añádela al almacén de confianza del runtime.
Paso 6: leer los logs y las métricas del Collector
Si hay un Collector en la cadena, añade temporalmente el exporter debug al pipeline de trazas:
exporters:
debug:
verbosity: detailed
otlphttp:
endpoint: https://<env-id>.live.dynatrace.com/api/v2/otlp
headers:
Authorization: "Api-Token ${env:DT_API_TOKEN}"
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [otlphttp, debug]
Si los spans aparecen en el log de debug pero no en Dynatrace, el problema está en la salida (pasos 3 a 5). Si no aparecen, el receiver no recibe nada (pasos 1 y 2). Las métricas internas del Collector, expuestas por defecto en el puerto 8888, confirman el diagnóstico: compara otelcol_receiver_accepted_spans, otelcol_exporter_sent_spans y otelcol_exporter_send_failed_spans (según la versión puede añadirse el sufijo _total).
Paso 7: comprobar el muestreo y los filtros
Un processor filter o tail_sampling demasiado estricto puede descartar todas las trazas de un servicio con poca carga. Un sampler parentbased_traceidratio a 0.01 en un servicio de prueba con 10 peticiones por hora casi no produce nada. Vuelve temporalmente a always_on y retira los filtros para confirmarlo.
Paso 8: buscar los spans en el sitio correcto de Dynatrace
A veces los spans llegan, pero con otro nombre de servicio, en otro periodo o fuera de tu zona de gestión. En SaaS, consulta Grail directamente:
fetch spans, from: now() - 30m
| filter contains(service.name, "checkout")
| summarize spans = count(), by: { service.name, k8s.namespace.name }
En Managed, abre Distributed traces, filtra por el periodo reciente y quita la zona de gestión. Una marca de tiempo errónea (reloj del contenedor desajustado) también deja los spans fuera de la ventana mostrada: compara la hora del servidor con un servidor NTP.
Cómo comprobar que funciona
- Los logs del Collector ya no muestran errores de exportación, y
otelcol_exporter_send_failed_spansse mantiene estable. - La consulta DQL del paso 8 devuelve un número de spans distinto de cero para tu servicio.
- Se abre una traza de extremo a extremo y muestra los spans de cada servicio, con un padre común.
Para profundizar en la propagación entre servicios, lee OpenTelemetry de extremo a extremo con Dynatrace.
Buenas prácticas
- Mantén un pipeline de prueba mínimo (receiver OTLP, batch, exportación) y documéntalo en el runbook de guardia.
- Monitoriza el propio Collector: una alerta sobre los fallos de exportación evita descubrir la avería en pleno incidente.
- Guarda el token en un secreto, nunca en claro en un manifiesto o un repositorio.
- Evita la doble instrumentación: si OneAgent ya instrumenta el proceso, consulta en la documentación cómo convive con un SDK de OpenTelemetry.
- Cuando las trazas vuelvan, conviértelas en indicadores: consulta crear un SLO sobre datos de OpenTelemetry.
Preguntas frecuentes
¿Dynatrace acepta OTLP por gRPC?
El endpoint OTLP de la API de Dynatrace está documentado para OTLP sobre HTTP. Para enviar gRPC, coloca un Collector que reciba en gRPC y exporte en HTTP hacia Dynatrace.
Las métricas llegan pero las trazas no: ¿por qué?
Cada señal tiene su ruta (/v1/traces, /v1/metrics, /v1/logs) y su scope de token. Comprueba que el token incluye también openTelemetryTrace.ingest y que el pipeline traces existe en el Collector.
¿Cuánto hay que esperar para ver los spans?
En general, de unos segundos a un minuto, según el processor batch y la ingesta. Pasados unos minutos, retoma la lista de comprobación en lugar de esperar.
Conclusión
Ocho comprobaciones bastan casi siempre: producción, protocolo, URL, token, red, Collector, muestreo y búsqueda. Guarda esta lista en tu runbook: el próximo incidente de telemetría se resolverá en minutos, no en horas.
span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC. Dynatrace es una marca de Dynatrace LLC. Comprueba siempre los valores (puertos, versiones, tamaños) en la documentación oficial correspondiente a tu versión. Las funciones de SaaS evolucionan rápido: comprueba su disponibilidad en tu entorno y en la documentación oficial.