Qu'est-ce qu'une trace distribuée

Quand une requête traverse cinq services en 800ms, comment savoir lequel a volé 700ms ? Les métriques te disent qu'il y a un problème. Les traces te disent où exactement.

Imagine une commande sur un site e-commerce. Elle touche successivement l'API gateway, le service d'authentification, le service produits, une base de données, et un cache Redis. Chaque service loggue des événements. Chaque service expose des métriques. Mais si la commande prend 2 secondes au lieu de 200ms, aucun log ni aucune métrique ne te dit où exactement le temps a disparu.

C'est précisément ce que résout la trace distribuée.

Les trois piliers — rôles complémentaires

La visualisation en waterfall

Une trace se lit comme un diagramme de Gantt : chaque ligne est un span, positionné horizontalement selon son heure de début, sa largeur représentant sa durée. Les spans enfants sont indentés sous leur parent. Tu vois instantanément les opérations séquentielles vs parallèles, et où le temps s'accumule.

Le simulateur ci-dessous anime une trace en temps réel : les spans apparaissent dans l'ordre où ils ont été créés, puis le waterfall complet se lit d'un coup.

Spans — l'unité de base

Une trace est un arbre de spans. Chaque span représente une opération : un appel HTTP, une requête SQL, un appel de service externe. Comprendre un span, c'est comprendre tout le modèle.

Un span est l'enregistrement d'une opération unitaire dans une trace. Il a un début, une fin, un nom, et peut transporter un grand nombre d'informations contextuelles. Plusieurs spans forment un arbre : le span racine représente la requête entière, les spans enfants représentent les opérations internes.

Attributs vs Événements

"http.method": "POST"
"http.url": "/api/orders"
"http.status_code": 200
"db.system": "postgresql"
"db.statement": "SELECT * FROM orders"

{
  "name": "exception",
  "timestamp": "14:32:09.412",
  "attributes": {
    "exception.type": "TimeoutException",
    "exception.message": "…"
  }
}

Status et Kind

Construis un span dans le simulateur ci-dessous en ajoutant des attributs et des événements. Observe comment le JSON évolue.

Propagation de contexte W3C TraceContext

Sans propagation, chaque service voit sa propre trace isolée. L'en-tête traceparent est le fil invisible qui relie tous les spans d'une même requête en un seul arbre.

Une trace distribuée n'a de sens que si tous les services qui traitent une requête sont conscients du même identifiant de trace. Sans mécanisme de propagation, chaque service crée sa propre trace isolée et le lien entre elles est perdu.

Le standard W3C TraceContext

Le W3C a standardisé le format des en-têtes de propagation en 2021. Deux en-têtes :

# Format : version-traceId(128bit)-parentSpanId(64bit)-flags
traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01

# Données vendor-specific optionnelles
tracestate: grafana=abc123,dd=xyz789

Le simulateur ci-dessous montre étape par étape comment l'en-tête traceparent voyage entre trois services. Clique sur "Étape suivante" pour avancer.

OpenTelemetry — instrumenter son code

OpenTelemetry est le standard CNCF pour collecter métriques, logs et traces depuis n'importe quel langage, vers n'importe quel backend. Deux modes : auto-instrumentation et instrumentation manuelle.

OpenTelemetry (OTel) est le projet CNCF qui standardise la façon de collecter métriques, logs et traces depuis n'importe quel langage, vers n'importe quel backend. C'est le successeur d'OpenTracing et OpenCensus — les deux ont fusionné pour donner OTel.

Auto-instrumentation vs instrumentation manuelle

# composer.json
"open-telemetry/opentelemetry-auto-symfony": "^1.0"
"open-telemetry/opentelemetry-auto-doctrine": "^1.0"
"open-telemetry/opentelemetry-auto-psr18": "^1.0"

# .env
OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://tempo:4318
OTEL_SERVICE_NAME=my-api

use OpenTelemetry\API\Globals;

$tracer = Globals::tracerProvider()
    ->getTracer('my-app');

$span = $tracer->spanBuilder('ProcessOrder')
    ->setSpanKind(SpanKind::KIND_INTERNAL)
    ->startSpan();

$span->setAttribute('order.id', $orderId);
$span->setAttribute('order.total', $total);

try {
    $this->processOrder($order);
    $span->setStatus(StatusCode::STATUS_OK);
} catch (Exception $e) {
    $span->recordException($e);
    $span->setStatus(StatusCode::STATUS_ERROR);
} finally {
    $span->end();
}

OTLP — le protocole de transport

OTLP (OpenTelemetry Protocol) est le format de sérialisation standard d'OTel pour envoyer les traces, métriques et logs. Deux transports : gRPC (port 4317) et HTTP/Protobuf (port 4318). Tempo, Grafana Mimir, et la plupart des backends modernes acceptent OTLP nativement.

Le simulateur ci-dessous visualise quels spans apparaissent automatiquement et comment un span manuel s'imbrique dans la trace. Clique sur "Ajouter span manuel" pour voir la différence.

Grafana Tempo — stocker et visualiser

Tempo stocke les traces dans un objet-store (S3-compatible) sans index full-text. La visualisation en waterfall te montre d'un coup d'œil où le temps a été dépensé.

Grafana Tempo est le backend de stockage des traces dans la stack LGTM. Sa particularité : il stocke les traces dans un objet-store (S3, GCS, Azure Blob) et n'indexe que l'identifiant de trace. Pas d'index full-text sur les attributs de spans — ce qui le rend extrêmement économique en comparaison de Jaeger ou Elasticsearch.

La vue Waterfall dans Grafana

Dans Grafana Explore, une trace s'affiche sous forme de waterfall : chaque span est une ligne horizontale, indentée selon sa profondeur dans l'arbre. La largeur représente la durée. La couleur indique le statut (vert = OK, rouge = ERROR).

Intégration avec Loki

Si tes logs contiennent un champ trace_id, Grafana Loki peut configurer des Derived Fields qui créent automatiquement un lien cliquable vers Tempo. Tu passes en un clic d'un log d'erreur à la trace complète.

Dans le simulateur ci-dessous, clique sur un span pour voir ses attributs. Identifie le span ERROR et comprends pourquoi la requête a été lente.

TraceQL — requêter les traces

TraceQL est à Tempo ce que LogQL est à Loki : un langage pour filtrer, agréger et analyser les traces. Il opère sur les spans individuels et sur la structure des traces.

TraceQL est le langage de requête de Grafana Tempo. Contrairement à LogQL qui filtre des lignes, TraceQL filtre des spans — et peut raisonner sur la structure de la trace (relations parent-enfant, ordres entre spans).

# Tous les spans en erreur
{status = error}

# Spans HTTP avec status 5xx
{span.http.status_code >= 500}

# Requêtes SQL lentes
{span.db.system = "postgresql" && duration > 500ms}

# Traces où payment-service a une erreur
{resource.service.name = "payment-service" && status = error}

Opérateurs de structure

TraceQL peut exprimer des relations entre spans — ce qu'aucun autre système de logs ne peut faire.

Metric queries

Comme LogQL, TraceQL a un mode metric query qui agrège des traces en séries temporelles :

# Taux d'erreurs par service
{ status = error } | by(resource.service.name) | rate()

# P95 de la durée des spans HTTP
{ span.http.method != "" } | quantile_over_time(duration, 0.95) by(resource.service.name)

# Nombre de spans par service les 5 dernières minutes
{ } | count() by(resource.service.name)

Le simulateur ci-dessous montre des traces de production simulées. Active des filtres TraceQL pour voir lesquelles correspondent.

Synthèse — traces en production

Instrumenter, propager, collecter, stocker, requêter — le pipeline complet. Et les décisions qui font la différence : sampling, granularité, corrélation.

Les traces distribuées ferment la boucle de l'observabilité. Voici le pipeline complet, de l'instrumentation jusqu'à l'investigation.

Sampling — ne pas tout enregistrer

En production, enregistrer 100 % des traces est souvent trop coûteux. Il faut échantillonner.

Pièges classiques

Les trois piliers — guide de choix définitif