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(etopenTelemetryTrace.ingestpour 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_logdans 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) ouhttps://<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
Resourcepour les traces et les logs : Dynatrace rattache ainsi les deux au même service. LoggingHandlerconvertit chaque enregistrementloggingen log OpenTelemetry, avec letrace_iddu span actif.- Les modules
_logsportent un tiret bas : l’API logs du SDK Python est encore marquée expérimentale. Depuis opentelemetry-sdk 1.40,LoggingHandlerest en outre déprécié au profit du paquetopentelemetry-instrumentation-logging(LoggingInstrumentor) ; le code ci-dessus fonctionne encore, mais épinglez vos versions et prévoyez la migration. extradevient 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 champsTraceId/SpanIddu modèle OTel. C’est ce qui rend la corrélation native.- Adaptez
attributes.trace_idau 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
- Côté Collector, cherchez les erreurs d’export :
kubectl -n observability logs ds/otel-node-opentelemetry-collector | grep -iE "logs|error|401|413"Un
413indique un lot trop gros : réduisezsend_batch_size. - 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 1avant de filtrer. - Reprenez un
trace_idtrouvé, puis :fetch spans, from: now() - 30m | filter trace.id == "<trace_id>" | fields start_time, span.name, durationSi 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.
- 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.