GUIDE TECHNIQUE · OPENTELEMETRY
Corréler logs et traces avec OpenTelemetry
Corréler journaux et traces avec trace_id et span_id : propager le contexte W3C, l'injecter dans un logger Java compatible, puis rechercher le même identifiant dans le backend. Une trace ne rend pas automatiquement les logs corrélés.
01 · CADRAGE
Ce que vous allez mettre en place
Corréler journaux et traces avec trace_id et span_id : propager le contexte W3C, l'injecter dans un logger Java compatible, puis rechercher le même identifiant dans le backend. Une trace ne rend pas automatiquement les logs corrélés.
Pour qui : Administrateurs, équipes observabilité et exploitation
OpenTelemetry Java agent récent (configuration de l'export OTLP à vérifier selon la version), application Java utilisant Logback ; adaptation nécessaire pour d'autres langages/loggers.
Vérifiez la compatibilité avec votre environnement réel. Les versions ne sont jamais présumées identiques d’un tenant à l’autre.
02 · AVANT DE COMMENCER
Prérequis et points de contrôle
- Application Java de recette utilisant un logger Logback et javaagent OpenTelemetry compatible.
- Backend recevant à la fois les traces ET les journaux, ou deux pipelines debug en laboratoire.
- Propagation W3C tracecontext activée entre services ; requête HTTP de recette reproductible.
- Données de test non sensibles et droits sur la configuration des logs.
03 · VUE D’ENSEMBLE
Comprendre l’architecture et les flux
Illustration éditoriale validée ADN Consulting, distincte d’une capture de console.
Source : ADN Consulting04 · TUTORIEL
Procédure complète, étape par étape
Chaque étape explique l’action, sa raison, le contrôle attendu et les erreurs habituelles. Adaptez les exemples aux paramètres de votre propre environnement.
ÉTAPE 1 / 5
Tracer une requête métier
Il faut une transaction unique pour comparer trace et journaux de la même exécution.
- Appeler une route de recette qui écrit au moins un log et génère un span.
- Relever un trace_id (32 caractères hexadécimaux) et le span_id (16) dans le backend.
- Noter la période, le service.name et le périmètre.
# Exemple de traceparent (à ne PAS recopier comme identifiant réel) :
# 00-0123456789abcdef0123456789abcdef-0123456789abcdef-01À vérifier : Un identifiant de trace réel est visible pour la requête choisie.
Point de vigilance ADN : Un identifiant créé manuellement ne prouve aucune corrélation.
ÉTAPE 2 / 5
Propager correctement le contexte
Les services doivent partager le même contexte de trace pour représenter un parcours distribué.
- Vérifier que les appels sortants propagent l'en-tête W3C traceparent.
- Comparer trace_id en amont et en aval ; tracer une rupture sur les bibliothèques non instrumentées.
- Activer les propagators adaptés si la propagation n'est pas automatique.
OTEL_PROPAGATORS=tracecontext,baggage
# Le paramètre doit être appliqué au processus Java instrumentéÀ vérifier : Deux services d'une même requête partagent le trace_id et portent des span_id distincts.
Point de vigilance ADN : Ne créez pas un nouvel identifiant de trace pour chaque microservice.
ÉTAPE 3 / 5
Ajouter le contexte aux journaux
Un fichier de logs non structuré n'inclut pas nécessairement le contexte MDC.
- Avec l'agent Java et Logback supportés, faire apparaître les champs du contexte MDC dans le pattern.
- Dans logback.xml, appliquer l'exemple puis redémarrer la seule application de recette.
- Déclencher une requête et vérifier les valeurs non vides au sein d'une période tracée.
<pattern>%d{ISO8601} %-5level [%X{trace_id} %X{span_id}] %logger - %msg%n</pattern>
# Extrait XML à intégrer sous un appender Logback de recette ; pas un fichier complet.À vérifier : Le log émis pendant un span affiche son trace_id et son span_id.
Point de vigilance ADN : Les valeurs MDC dépendent de la bibliothèque de logs, de l'agent et de sa version ; sans contexte actif elles peuvent être vides.
ÉTAPE 4 / 5
Traiter les flux dans le Collector
L'enrichissement du log n'est pas une preuve qu'il arrive au même backend que les traces.
- Vérifier séparément un pipeline traces OTLP et un pipeline logs réellement alimenté (SDK, collecteur de fichier ou agent de logs).
- En laboratoire, utiliser debug pour les deux flux ; en production, un exporteur sécurisé.
- Contrôler la conservation des identifiants dans le parsing et le schéma du backend.
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [debug]
logs:
receivers: [otlp]
processors: [batch]
exporters: [debug]
# Extrait de service.pipelines ; receivers/processors/exporters à déclarer ailleurs.À vérifier : Les deux flux existent et la collecte des logs n'est pas confondue avec celle des traces.
Point de vigilance ADN : Le simple ajout d'un pipeline logs ne collecte PAS les fichiers Logback ; configurer l'émetteur ou un receiver filelog adapté.
ÉTAPE 5 / 5
Tester la recherche corrélée
Une corrélation est utilisable seulement si la recherche est bidirectionnelle.
- Depuis la trace, copier le trace_id réel, filtrer les logs sur sa valeur exacte et relever le service.
- Depuis un journal corrélé, ouvrir la trace et vérifier service.name, période et span_id.
- Tester une requête sans contexte et documenter les limites de sampling, rétention et parsing.
# Dans la recherche de logs du backend, filtrer :
# trace_id:<ID_DE_TRACE_OBSERVE>
# Le champ et la syntaxe de filtre dépendent du backend.À vérifier : La même requête est identifiable depuis la trace et les logs, sur un jeu de test connu.
Point de vigilance ADN : Un ID partagé ne garantit pas une rétention identique des journaux et des traces.
05 · RECETTE
Comment vérifier que tout fonctionne ?
traceparent est transmis entre au moins deux services de test.
Les logs émis pendant des spans possèdent trace_id et span_id non vides.
Les deux flux sont ingérés dans le backend ou vérifiés séparément en debug.
Un identifiant pris dans une trace permet de retrouver le journal correspondant.
Les données sensibles et la politique d'échantillonnage ont été vérifiées.
06 · DIAGNOSTIC
Problèmes fréquents et résolution
trace_id absent des logs
Cause probable : MDC non injecté ou pattern Logback incomplet
Que faire : Vérifier logger, agent Java, version et %X{trace_id}.
Traces liées à d'autres IDs
Cause probable : Contexte perdu entre services
Que faire : Inspecter l'en-tête W3C traceparent et les propagators.
Logs absents du backend
Cause probable : Pipeline de logs non configuré malgré les traces
Que faire : Vérifier shipper, receiver, exporter et parsing.
Une partie des traces manque
Cause probable : Échantillonnage ou rétention différents
Que faire : Comparer politiques de sampling et fenêtres de conservation.
Le conseil de l’expert ADN
Avant de généraliser cette configuration, validez-la sur un périmètre représentatif, documentez les critères de réussite et conservez une procédure de retour arrière. Une instrumentation utile se juge sur les données effectivement exploitables, pas sur la seule installation de l’outil.
07 · QUESTIONS PRATIQUES
Questions fréquentes
Le Collector relie-t-il automatiquement un fichier Logback à une trace ?
Non. Le contexte doit être présent dans les logs, et le flux journal doit être collecté puis indexé.
Peut-on appliquer ce pattern à Node.js ou Python ?
Non directement : adapter l'instrumentation et le logger à chaque langage.