Propagación de contexto Kafka: trazas W3C de extremo a extremo en Dynatrace

Propagación de contexto Kafka: inyecta traceparent en las cabeceras, une producer y consumer en una sola traza de Dynatrace y compruébalo con DQL.
Propagation contexte Kafka : des traces W3C de bout en bout dans Dynatrace

Un pedido pasa por la API, entra en un topic de Kafka y un consumer lo procesa dos segundos después. En Dynatrace ves dos trazas sin relación: la llamada HTTP por un lado y el procesamiento por otro. Falta la propagación de contexto Kafka, y el equipo de guardia pierde tiempo recomponiendo las piezas a mano durante un incidente.

Objetivo de este tutorial: hacer viajar el contexto W3C Trace Context (cabecera traceparent) en las cabeceras de los mensajes de Kafka, para obtener una sola traza del producer al consumer en Dynatrace. El contenido sirve para Dynatrace SaaS y Dynatrace Managed en cuanto a la ingesta OTLP; las consultas DQL de verificación suponen un entorno SaaS sobre Grail.

Si las trazas no llegan en absoluto a Dynatrace, empieza por el diagnóstico de las trazas de OpenTelemetry ausentes y vuelve después aquí.

El problema: una traza cortada en dos

En HTTP, la propagación es evidente: el cliente añade traceparent a las cabeceras de la petición y el servidor lo lee. Con Kafka no hay petición directa. El producer escribe un mensaje, el broker lo almacena y el consumer lo lee más tarde. Si nadie escribe el contexto en el mensaje, el consumer inicia una traza nueva.

Consecuencia para SRE: no se puede medir el tiempo de extremo a extremo de un pedido, es imposible calcular un SLI de latencia «pedido procesado» y el MTTR aumenta porque hay que correlacionar por marca de tiempo.

Propagación de contexto Kafka: cómo funciona

Desde Kafka 0.11, cada mensaje (record) puede llevar cabeceras clave-valor. El principio es sencillo:

  1. En el producer se crea un span de tipo PRODUCER y el propagador W3C escribe traceparent (y tracestate si existe) en las cabeceras del record.
  2. En el consumer, el propagador lee esas cabeceras, reconstruye el contexto e inicia un span de tipo CONSUMER unido a la misma traza (como hijo o mediante un enlace de span, según la instrumentación).

Los atributos útiles siguen las convenciones semánticas de mensajería de OpenTelemetry: messaging.system = kafka, messaging.destination.name = nombre del topic, messaging.operation.type (publish, process…, que sustituye al antiguo messaging.operation, obsoleto). Comprueba los nombres vigentes en las convenciones semánticas de Kafka de OpenTelemetry.

Requisitos previos

  • Servicios producer y consumer instrumentados con OpenTelemetry (agente Java, SDK de Python, etc.) o con OneAgent.
  • Una exportación OTLP a Dynatrace, directa o mediante un Collector: consulta el Collector de OpenTelemetry para Dynatrace.
  • Un token de API con el scope openTelemetryTrace.ingest (SaaS y Managed).
  • Brokers Kafka 0.11 o superior (cabeceras de mensajes).

Paso 1 — Java: dejar que el agente de OpenTelemetry inyecte el contexto

El agente Java de OpenTelemetry instrumenta los clientes kafka-clients sin modificar el código. Inyecta traceparent al enviar y lo extrae al recibir. Basta la configuración básica:

export OTEL_SERVICE_NAME=order-api
export OTEL_PROPAGATORS=tracecontext,baggage
export OTEL_EXPORTER_OTLP_ENDPOINT=https://<environment-id>.live.dynatrace.com/api/v2/otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Api-Token%20${DT_API_TOKEN}"
java -javaagent:opentelemetry-javaagent.jar -jar order-api.jar

Líneas críticas: OTEL_PROPAGATORS debe contener tracecontext en ambos lados; si no, el consumer no entiende la cabecera. En Managed, la URL OTLP tiene la forma https://<cluster>/e/<environment-id>/api/v2/otlp. El detalle del agente está en el agente de OpenTelemetry para Java con Dynatrace.

Punto de atención: según la versión del agente y sus opciones sobre la telemetría de recepción (receive), el span de procesamiento es hijo del span del producer o un span enlazado. Ambos aparecen en la misma vista distribuida de Dynatrace si el enlace se conserva, pero la representación difiere. Consulta el README de la instrumentación de Kafka de tu versión.

Paso 2 — Python: propagar el contexto a mano

Con confluent-kafka, la instrumentación automática existe pero sigue siendo parcial según la versión. La propagación manual es corta y explícita:

from opentelemetry import trace, propagate
from opentelemetry.trace import SpanKind

tracer = trace.get_tracer("order-api")

def send_order(producer, payload: bytes):
    with tracer.start_as_current_span("orders publish", kind=SpanKind.PRODUCER) as span:
        span.set_attribute("messaging.system", "kafka")
        span.set_attribute("messaging.destination.name", "orders")
        carrier = {}
        propagate.inject(carrier)  # écrit traceparent (et tracestate)
        producer.produce("orders", value=payload, headers=list(carrier.items()))

En el consumer se leen las cabeceras (bytes) y se reconstruye el contexto:

def handle(msg):
    carrier = {k: v.decode("utf-8") for k, v in (msg.headers() or []) if v is not None}
    ctx = propagate.extract(carrier)
    with tracer.start_as_current_span("orders process", context=ctx, kind=SpanKind.CONSUMER) as span:
        span.set_attribute("messaging.system", "kafka")
        span.set_attribute("messaging.destination.name", "orders")
        process(msg.value())

Línea crítica: context=ctx. Sin ella, el span del consumer se convierte en la raíz de una traza nueva. El propagador por defecto del SDK de Python es tracecontext,baggage.

Paso 3 — Caso mixto de OneAgent y OpenTelemetry

Si el producer está monitorizado por OneAgent y el consumer por OpenTelemetry (o al revés), ambos deben hablar W3C Trace Context. OneAgent admite W3C Trace Context, pero la propagación en mensajería depende de la tecnología y de la versión: consulta la página de Kafka de la documentación de OneAgent en docs.dynatrace.com. Evita también instrumentar dos veces el mismo cliente: es la fuente clásica de spans duplicados entre OneAgent y OpenTelemetry.

Paso 4 — No romper el contexto por el camino

  • Kafka Streams, MirrorMaker, conectores: un componente que copia un mensaje puede perder o conservar las cabeceras. Prueba cada salto.
  • Procesamiento por lotes: un poll devuelve varios mensajes de trazas distintas. Crea un span por mensaje, o un span de lote con enlaces a cada contexto.
  • Muestreo: con un sampler parentbased_*, el consumer sigue la decisión del producer. Un muestreo distinto en cada lado produce trazas incompletas.

Cómo comprobar que funciona

Primero, mira un mensaje en bruto: kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic orders --property print.headers=true --from-beginning --max-messages 1. Debes ver traceparent:00-<trace-id>-<span-id>-01.

Después, en Dynatrace SaaS, abre un Notebook y cuenta las trazas que contienen a la vez un span producer y un span consumer:

fetch spans, from: now() - 1h
| filter messaging.system == "kafka"
| summarize kinds = collectDistinct(span.kind), services = collectDistinct(service.name), by: { trace.id }
| filter arraySize(kinds) >= 2
| limit 20

Si la consulta no devuelve nada aunque los dos servicios envían spans, el contexto se pierde entre ambos. Los valores exactos de span.kind y el nombre de los campos pueden variar: compruébalos primero con fetch spans | limit 10. En Managed, abre una PurePath del servicio consumer en la vista de trazas distribuidas y comprueba que el servicio producer aparece aguas arriba.

Buenas prácticas

  • Un único formato de propagación en toda la cadena: tracecontext. Retira los formatos propietarios en cuanto puedas.
  • Nombra los spans «<topic> publish» y «<topic> process»: la búsqueda sigue siendo legible.
  • Mide el retraso entre producción y procesamiento: suele ser el mejor SLI de un pipeline asíncrono.
  • No pongas nunca datos personales en baggage: viaja en cada mensaje.

Preguntas frecuentes

¿Hay que modificar los brokers de Kafka?

No. Las cabeceras las transporta el broker tal cual. Solo participan en la propagación los clientes producer y consumer.

¿Por qué aparece el consumer en una traza separada a pesar de la cabecera?

Lo más habitual es que el propagador del consumer no sea tracecontext, que el contexto extraído no se pase al span, o que la instrumentación produzca un enlace de span en lugar de una relación padre-hijo. Revisa estos tres puntos en ese orden.

¿Funciona con Dynatrace Managed?

Sí para la ingesta OTLP de trazas y la vista distribuida. En cambio, las consultas DQL sobre fetch spans requieren un entorno SaaS sobre Grail.

Conclusión

Unas pocas líneas de configuración bastan para que un pedido siga siendo una sola traza, de la API al consumer. Ganas una latencia de extremo a extremo medible e investigaciones más cortas. Siguiente paso: convertir ese retraso en un SLI, como en OpenTelemetry de extremo a extremo.

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.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Logs OpenTelemetry : Dynatrace et la corrélation logs-traces par trace_id

Logs de OpenTelemetry en Dynatrace: correlación entre logs y trazas por trace_id

Next Post
Tail sampling OpenTelemetry avant Dynatrace : maîtriser coûts et volume de traces

Tail sampling OpenTelemetry antes de Dynatrace: controla costes y volumen de trazas

Related Posts