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

Logs OpenTelemetry : Dynatrace les relie aux traces via le trace_id. Export depuis le SDK ou le Collector, puis vérification de la corrélation en DQL.
Logs OpenTelemetry : Dynatrace et la corrélation logs-traces par trace_id

Une alerte tombe : le taux d’erreurs d’un service grimpe. Vous trouvez la trace lente, puis vous cherchez les logs correspondants à la main, par horodatage, dans trois pods différents. Avec des logs OpenTelemetry, Dynatrace supprime cette étape grâce au trace_id : depuis une trace, vous ouvrez directement les lignes de log qu’elle a produites.

Objectif de ce tutoriel : faire porter le contexte de trace (trace_id, span_id) à chaque log, par deux chemins — le SDK OpenTelemetry qui exporte les logs en OTLP, et le Collector qui lit des fichiers de logs existants —, puis vérifier la corrélation. Le contenu vise Dynatrace SaaS (logs sur Grail) ; pour Dynatrace Managed, l’ingestion OTLP des logs existe aussi, mais vérifiez la version minimale et les écrans disponibles dans la documentation de votre cluster.

Ce sujet complète le collector OpenTelemetry vers Dynatrace et son déploiement sur Kubernetes.

Prérequis

  • Un token d’API avec le scope logs.ingest (et openTelemetryTrace.ingest pour les traces).
  • Une application déjà tracée avec OpenTelemetry. L’exemple utilise Python 3.10+ ; le principe est identique en Java, Go ou .NET.
  • Pour la partie fichiers : un Collector contrib (receiver filelog, renommé file_log dans les versions récentes ; l’ancien nom reste accepté comme alias déprécié).
  • Endpoint OTLP : https://<env-id>.live.dynatrace.com/api/v2/otlp (SaaS) ou https://<votre-domaine>/e/<env-id>/api/v2/otlp (Managed).

Logs OpenTelemetry : Dynatrace et la corrélation par trace_id

Un log OpenTelemetry est un enregistrement structuré. Le modèle de données prévoit deux champs dédiés, TraceId et SpanId. Quand le log est émis à l’intérieur d’un span actif, le SDK les remplit automatiquement. Dynatrace stocke alors ces identifiants avec le log, ce qui permet de passer de la trace au log et inversement. Sans ces champs, la corrélation repose sur l’heure, ce qui ne tient pas sous charge.

À retenir : un log n’est pas un span. N’émettez pas d’événements de span pour remplacer les logs, et inversement.

Chemin 1 : exporter les logs OpenTelemetry vers Dynatrace depuis le SDK

Étape 1 : installer les paquets

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

Étape 2 : brancher le handler de logs

import logging
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry._logs import set_logger_provider
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

resource = Resource.create({"service.name": "checkout"})

tp = TracerProvider(resource=resource)
tp.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(tp)

lp = LoggerProvider(resource=resource)
lp.add_log_record_processor(BatchLogRecordProcessor(OTLPLogExporter()))
set_logger_provider(lp)

logging.getLogger().addHandler(LoggingHandler(level=logging.INFO, logger_provider=lp))
logging.getLogger().setLevel(logging.INFO)

tracer = trace.get_tracer("checkout")
log = logging.getLogger("checkout")

with tracer.start_as_current_span("payer-commande"):
    log.warning("paiement refusé", extra={"order.id": "A-1042"})

Les lignes critiques :

  • Le même Resource pour les traces et les logs : Dynatrace rattache ainsi les deux au même service.
  • LoggingHandler convertit chaque enregistrement logging en log OpenTelemetry, avec le trace_id du span actif.
  • Les modules _logs portent un tiret bas : l’API logs du SDK Python est encore marquée expérimentale. Depuis opentelemetry-sdk 1.40, LoggingHandler est en outre déprécié au profit du paquet opentelemetry-instrumentation-logging (LoggingInstrumentor) ; le code ci-dessus fonctionne encore, mais épinglez vos versions et prévoyez la migration.
  • extra devient des attributs du log : gardez des clés stables et peu nombreuses.

Étape 3 : configurer l’export par variables d’environnement

export OTEL_EXPORTER_OTLP_ENDPOINT="https://<env-id>.live.dynatrace.com/api/v2/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Api-Token%20dt0c01.XXXX"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

L’espace après Api-Token est encodé en %20. Les exporteurs ajoutent eux-mêmes /v1/traces et /v1/logs à l’endpoint. En production, pointez plutôt vers un Collector local.

Chemin 2 : lire des fichiers de logs avec le Collector

Beaucoup d’applications écrivent déjà des logs JSON sur la sortie standard. Si elles y incluent le trace_id (par exemple via l’instrumentation logging qui ajoute otelTraceID au format), le Collector peut le promouvoir en champ de trace.

receivers:
  filelog:
    include: [/var/log/pods/*/*/*.log]
    include_file_path: true
    operators:
      - type: container          # retire l'enveloppe du runtime
      - type: json_parser
        parse_from: body
        parse_to: attributes
      - type: trace_parser
        trace_id:
          parse_from: attributes.trace_id
        span_id:
          parse_from: attributes.span_id

processors:
  batch: {}

exporters:
  otlphttp/dynatrace:
    endpoint: ${env:DT_ENDPOINT}
    headers:
      Authorization: "Api-Token ${env:DT_API_TOKEN}"

service:
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/dynatrace]
  • container : l’opérateur reconnaît les formats CRI et Docker. Sur les versions anciennes du Collector, il n’existe pas ; utilisez alors les opérateurs de parsing décrits dans la doc du receiver.
  • trace_parser : copie l’attribut dans les champs TraceId/SpanId du modèle OTel. C’est ce qui rend la corrélation native.
  • Adaptez attributes.trace_id au nom réel du champ dans vos logs (traceId, otelTraceID…).

Sur Kubernetes, ajoutez k8sattributes pour retrouver pod et namespace. Si vous préférez transformer les logs côté Dynatrace, l’ingestion de logs en self-service et OpenPipeline offrent une alternative.

Comment vérifier que ça fonctionne

  1. Côté Collector, cherchez les erreurs d’export :
    kubectl -n observability logs ds/otel-node-opentelemetry-collector | grep -iE "logs|error|401|413"

    Un 413 indique un lot trop gros : réduisez send_batch_size.

  2. En SaaS, dans un Notebook :
    fetch logs, from: now() - 30m
    | filter isNotNull(trace_id)
    | summarize logs = count(), by: {service.name, loglevel}

    Le nom exact des champs de trace sur les logs peut varier selon la source ; inspectez un enregistrement avec fetch logs | limit 1 avant de filtrer.

  3. Reprenez un trace_id trouvé, puis :
    fetch spans, from: now() - 30m
    | filter trace.id == "<trace_id>"
    | fields start_time, span.name, duration

    Si la trace et les logs sortent avec le même identifiant, la corrélation est en place. Dans l’interface, la vue d’une trace doit aussi proposer les logs associés.

  4. En Managed, ouvrez la visionneuse de logs, filtrez sur le service et vérifiez que le log affiche un lien vers la trace. L’emplacement exact dépend de la version : référez-vous à docs.dynatrace.com.

Bonnes pratiques

  • Un seul chemin par log : si l’application exporte en OTLP, ne relisez pas aussi son fichier, sinon chaque ligne arrive deux fois.
  • Niveau INFO minimum en production : le volume de logs est souvent le premier poste de coût.
  • Pas de données personnelles dans le corps ou les attributs ; masquez-les dans le Collector ou dans OpenPipeline.
  • Logs structurés : un JSON stable se parse une fois pour toutes et réduit le toil.
  • Échantillonnage cohérent : si vous échantillonnez les traces, certains logs pointeront vers une trace absente. C’est normal ; gardez tous les logs d’erreur.

Questions fréquentes

OneAgent fait-il déjà cette corrélation ?

Pour les technologies qu’il instrumente, OneAgent peut enrichir les logs avec le contexte de trace. Le chemin OpenTelemetry sert quand OneAgent n’est pas présent ou quand vous standardisez sur OTel.

Pourquoi mes logs arrivent-ils sans trace_id ?

Le log a été émis hors d’un span actif (démarrage, tâche de fond), ou le parsing n’a pas trouvé le champ. Vérifiez le nom du champ et le contexte d’exécution.

Faut-il envoyer les logs en gRPC ou en HTTP ?

L’API OTLP de Dynatrace accepte HTTP avec protobuf. Utilisez otlphttp vers Dynatrace ; gRPC reste possible entre vos applications et le Collector.

Conclusion

Des logs OpenTelemetry qui portent leur trace_id font gagner de précieuses minutes à chaque incident : la trace montre où, le log explique pourquoi. Commencez par un service critique, vérifiez la jointure en DQL, puis étendez à vos autres workloads. Pour la suite, liez ces signaux à vos objectifs avec des SLO OpenTelemetry en DQL.

span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC. Dynatrace est une marque de Dynatrace LLC. Les champs et écrans évoluent : vérifiez-les 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
Collector OpenTelemetry Kubernetes vers Dynatrace : Helm, Operator et k8sattributes

Collector OpenTelemetry Kubernetes vers Dynatrace : Helm, Operator et k8sattributes

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

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

Related Posts