Propagation contexte Kafka : des traces W3C de bout en bout dans Dynatrace

Propagation contexte Kafka : injectez traceparent dans les en-têtes, reliez producer et consumer dans une seule trace Dynatrace et vérifiez-le en DQL.
Propagation contexte Kafka : des traces W3C de bout en bout dans Dynatrace

Une commande passe par l’API, part dans un topic Kafka, puis un consumer la traite deux secondes plus tard. Dans Dynatrace, vous voyez deux traces sans lien : l’appel HTTP d’un côté, le traitement de l’autre. La propagation contexte Kafka manque, et l’astreinte perd du temps à recoller les morceaux à la main pendant un incident.

Objectif de ce tutoriel : faire voyager le contexte W3C Trace Context (en-tête traceparent) dans les en-têtes des messages Kafka, pour obtenir une seule trace du producer au consumer dans Dynatrace. Le contenu vaut pour Dynatrace SaaS et Dynatrace Managed pour l’ingestion OTLP ; les requêtes DQL de vérification supposent un environnement SaaS sur Grail.

Si les traces n’arrivent pas du tout dans Dynatrace, commencez par le diagnostic des traces OpenTelemetry absentes, puis revenez ici.

Le problème : une trace coupée en deux

En HTTP, la propagation est évidente : le client ajoute traceparent dans les en-têtes de la requête et le serveur le lit. Avec Kafka, il n’y a pas de requête directe. Le producer écrit un message, le broker le stocke, le consumer le lit plus tard. Si personne n’écrit le contexte dans le message, le consumer démarre une nouvelle trace.

Conséquence SRE : le temps de bout en bout d’une commande n’est pas mesurable, un SLI de latence « commande traitée » est impossible à calculer, et le MTTR augmente parce qu’il faut corréler par horodatage.

Propagation contexte Kafka : comment ça marche

Depuis Kafka 0.11, chaque message (record) peut porter des en-têtes clé-valeur. Le principe est simple :

  1. Côté producer, un span de type PRODUCER est créé et le propagateur W3C écrit traceparent (et tracestate s’il existe) dans les en-têtes du record.
  2. Côté consumer, le propagateur lit ces en-têtes, reconstruit le contexte et démarre un span de type CONSUMER rattaché à la même trace (comme enfant ou via un lien de span, selon l’instrumentation).

Les attributs utiles suivent les conventions sémantiques messaging d’OpenTelemetry : messaging.system = kafka, messaging.destination.name = nom du topic, messaging.operation.type (publish, process…, qui remplace l’ancien messaging.operation, déprécié). Vérifiez les noms en vigueur dans les conventions sémantiques Kafka d’OpenTelemetry.

Prérequis

  • Des services producer et consumer instrumentés avec OpenTelemetry (agent Java, SDK Python, etc.) ou par OneAgent.
  • Un export OTLP vers Dynatrace, direct ou via un Collector : voir le Collector OpenTelemetry pour Dynatrace.
  • Un token API avec le scope openTelemetryTrace.ingest (SaaS et Managed).
  • Des brokers Kafka 0.11 ou plus (en-têtes de messages).

Étape 1 — Java : laisser l’agent OpenTelemetry injecter le contexte

L’agent Java OpenTelemetry instrumente les clients kafka-clients sans modifier le code. Il injecte traceparent à l’envoi et l’extrait à la réception. La configuration de base suffit :

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

Lignes critiques : OTEL_PROPAGATORS doit contenir tracecontext des deux côtés, sinon le consumer ne comprend pas l’en-tête. En Managed, l’URL OTLP prend la forme https://<cluster>/e/<environment-id>/api/v2/otlp. Le détail de l’agent est dans l’agent OpenTelemetry Java avec Dynatrace.

Point d’attention : selon la version de l’agent et ses options sur la télémétrie de réception (receive), le span de traitement est un enfant du span producer ou un span lié. Les deux apparaissent dans la même vue distribuée côté Dynatrace si le lien est conservé, mais le rendu diffère. Consultez le README de l’instrumentation Kafka de votre version.

Étape 2 — Python : propager le contexte à la main

Avec confluent-kafka, l’instrumentation automatique existe mais reste partielle selon les versions. La propagation manuelle est courte et explicite :

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()))

Côté consumer, on lit les en-têtes (des octets) et on reconstruit le contexte :

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())

Ligne critique : context=ctx. Sans elle, le span consumer devient la racine d’une nouvelle trace. Le propagateur par défaut du SDK Python est tracecontext,baggage.

Étape 3 — Cas mixte OneAgent et OpenTelemetry

Si le producer est surveillé par OneAgent et le consumer par OpenTelemetry (ou l’inverse), les deux doivent parler W3C Trace Context. OneAgent prend en charge W3C Trace Context, mais la propagation sur la messagerie dépend de la technologie et de la version : vérifiez la page Kafka de la documentation OneAgent sur docs.dynatrace.com. Évitez aussi d’instrumenter deux fois le même client : c’est la source classique de spans en double entre OneAgent et OpenTelemetry.

Étape 4 — Ne pas casser le contexte en route

  • Kafka Streams, MirrorMaker, connecteurs : un composant qui recopie un message peut perdre ou conserver les en-têtes. Testez chaque saut.
  • Traitement par lots : un poll renvoie plusieurs messages de traces différentes. Créez un span par message, ou un span de lot avec des liens vers chaque contexte.
  • Échantillonnage : avec un sampler parentbased_*, le consumer suit la décision du producer. Un échantillonnage différent de chaque côté produit des traces incomplètes.

Comment vérifier que ça fonctionne

D’abord, regardez un message brut : kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic orders --property print.headers=true --from-beginning --max-messages 1. Vous devez voir traceparent:00-<trace-id>-<span-id>-01.

Ensuite, dans Dynatrace SaaS, ouvrez un Notebook et comptez les traces qui contiennent à la fois un span producer et 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 requête ne renvoie rien alors que les deux services envoient des spans, le contexte est perdu entre les deux. Les valeurs exactes de span.kind et le nom des champs peuvent varier : contrôlez-les d’abord avec fetch spans | limit 10. En Managed, ouvrez une PurePath du service consumer dans la vue des traces distribuées et vérifiez que le service producer apparaît en amont.

Bonnes pratiques

  • Un seul format de propagation dans toute la chaîne : tracecontext. Retirez les formats propriétaires dès que possible.
  • Nommez les spans « <topic> publish » et « <topic> process » : la recherche reste lisible.
  • Mesurez le délai entre production et traitement : c’est souvent le meilleur SLI d’un pipeline asynchrone.
  • Ne mettez jamais de données personnelles dans baggage : il voyage dans chaque message.

Questions fréquentes

Faut-il modifier les brokers Kafka ?

Non. Les en-têtes sont transportés tels quels par le broker. Seuls les clients producer et consumer participent à la propagation.

Pourquoi le consumer apparaît-il dans une trace séparée malgré l’en-tête ?

Le plus souvent, le propagateur du consumer n’est pas tracecontext, le contexte extrait n’est pas passé au span, ou l’instrumentation produit un lien de span plutôt qu’une relation parent-enfant. Vérifiez ces trois points dans cet ordre.

Cela fonctionne-t-il avec Dynatrace Managed ?

Oui pour l’ingestion OTLP des traces et la vue distribuée. Les requêtes DQL sur fetch spans demandent en revanche un environnement SaaS sur Grail.

Conclusion

Quelques lignes de configuration suffisent pour qu’une commande reste une seule trace, de l’API au consumer. Vous gagnez une latence de bout en bout mesurable et des enquêtes plus courtes. Prochaine étape : transformer ce délai en SLI, comme dans OpenTelemetry de bout en bout.

span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC. Dynatrace est une marque de Dynatrace LLC. Les fonctionnalités évoluent vite : vérifiez leur disponibilité dans votre environnement et dans la documentation officielle.

Total
0
Shares
Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

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

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

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

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

Related Posts