Les traces en profondeur

1. Anatomie d'une trace #

Trace, span, contexte.

Trace et spans #

Une trace représente le parcours complet d'une requête. Elle se compose de spans : des opérations nommées, avec un début, une fin, un parent, des attributs, des événements et un statut. Tous les spans partagent le même trace_id (16 octets) ; chacun a son span_id (8 octets).

SpanKind #

2. Instrumenter manuellement #

Attributs, statut, événements, liens.

Créer des spans #

from opentelemetry import trace
from opentelemetry.trace import SpanKind, Status, StatusCode, Link

tracer = trace.get_tracer("shop.checkout", "1.4.0")

def payer(commande):
    with tracer.start_as_current_span("payer commande", kind=SpanKind.INTERNAL) as span:
        span.set_attribute("shop.order.id", commande.id)          # attribut métier
        span.set_attribute("shop.order.amount", commande.total)
        span.add_event("fraude.verifiee", {"shop.fraud.score": 0.12})
        try:
            passerelle.debiter(commande)
        except PaiementRefuse as exc:
            span.record_exception(exc)                            # événement "exception"
            span.set_status(Status(StatusCode.ERROR, "paiement refusé"))
            raise

Statut et erreurs #

Le statut vaut Unset par défaut. On le passe à Error quand l'opération a échoué ; on ne met Ok que pour forcer un succès malgré une règle contraire. Pour HTTP, les conventions disent : côté serveur, seules les réponses 5xx sont des erreurs ; côté client, 4xx et 5xx le sont.

Erreur Courante : N'utilisez pas les attributs pour stocker des données volumineuses ou personnelles (corps de requête, e-mails) : coût, cardinalité et RGPD.

Liens #

Un lien relie un span à un ou plusieurs autres contextes sans relation parent-enfant : un traitement par lots qui agrège 100 messages venant de 100 traces différentes, ou une tâche asynchrone déclenchée par une requête. tracer.start_as_current_span("lot", links=[Link(ctx1), Link(ctx2)]).

3. Le pipeline des spans dans le SDK #

Processors, exportateurs, limites.

Span processors #

Arrêt propre #

Bonne Pratique : Appelez provider.shutdown() (ou force_flush()) à l'arrêt d'un processus court (job, fonction serverless) : sinon le dernier lot de spans est perdu.

4. Échantillonnage #

Garder les bonnes traces sans payer pour toutes.

Head et tail #

processors:
  tail_sampling:
    decision_wait: 10s
    policies:
      - { name: erreurs, type: status_code, status_code: { status_codes: [ERROR] } }
      - { name: lentes,  type: latency, latency: { threshold_ms: 1000 } }
      - { name: reste,   type: probabilistic, probabilistic: { sampling_percentage: 5 } }

Erreur Courante : Le tail sampling exige que tous les spans d'une trace arrivent sur le même Collector : placez devant un Collector avec l'exportateur loadbalancing routé par TraceID.

Interroger les traces #

{ resource.service.name = "checkout" && status = error }
{ span.http.route = "/orders" && duration > 500ms }
{ span.db.system.name = "postgresql" } | count() > 20          # traces qui font plus de 20 requêtes SQL (N+1)
{ resource.service.name = "frontend" } >> { resource.service.name = "payment" && status = error }