Instrumentation

L’instrumentation est la première étape du pipeline d’observabilité : c’est le code qui génère les signaux — métriques, logs, traces — au sein même de vos applications. Sans instrumentation de qualité, les meilleurs backends et dashboards du monde ne servent à rien : “garbage in, garbage out”.

Mais “instrumenter” n’est pas un seul outil. C’est un empilement de couches qui vont de votre code jusqu’au backend. Cette page vous explique comment ces briques s’assemblent.

Les couches de l’instrumentation

Vue d’ensemble

Voici comment les signaux circulent de votre code jusqu’à vos backends :

Couches d'instrumentation : du code applicatif aux backends

L’idée clé : plus vous descendez dans le pipeline, plus c’est centralisé (facile à gouverner), mais moins vous êtes “proche” de la logique métier.

1. API / Facade : l’interface que le code appelle

L’API fournit une interface stable dans le code : tracer, meter, logger. Votre code appelle ces primitives sans savoir quel backend stockera les données.

Outil	Ce qu’il fait
OpenTelemetry API	Interface standard pour traces, métriques, logs (multi-langage)
Micrometer (Java)	Facade “metrics-first” très utilisée dans l’écosystème Spring

Dans le code, ça ressemble à :

# Créer un span (trace)
with tracer.start_as_current_span("checkout.process") as span:
    span.set_attribute("cart.items", 3)
    # ... logique métier

// Incrémenter un compteur (métrique)
counter.add(1, Attributes.of(stringKey("status"), "success"));

2. SDK : l’implémentation qui collecte et exporte

Le SDK transforme ce que produit l’API en télémétrie exploitable :

Responsabilité	Ce que ça fait
Buffering / Batch	Regroupe les signaux avant export (économise le réseau)
Retry	Ré-essaie en cas d’échec réseau
Sampling	Décide quelles traces garder (ratio, parent-based…)
Propagation	Injecte/extrait le contexte (trace-id) entre services
Export	Envoie les signaux vers OTLP (ou autre format)

C’est dans le SDK que vous configurez :

# Identité du service
OTEL_SERVICE_NAME=checkout-api
OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3,deployment.environment=production

# Export OTLP vers le Collector
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc

# Sampling (10% des traces)
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

3. Auto-instrumentation : le “zéro code”

L’auto-instrumentation intercepte automatiquement les appels aux frameworks et librairies (HTTP, DB, messaging) sans modifier votre code.

Langage	Comment ça marche
Java	Agent JVM : `-javaagent:opentelemetry-javaagent.jar`
Python	Wrapper : `opentelemetry-instrument python app.py`
Node.js	Require : `--require @opentelemetry/auto-instrumentations-node/register`
.NET	Runtime hooks (variable `CORECLR_ENABLE_PROFILING`)
Go	Instrumentation des packages (net/http, database/sql…)
PHP	Extension PHP : `opentelemetry.so`

Quand l’utiliser ?

Pour couvrir rapidement 80% des spans (HTTP entrant/sortant, SQL, Redis, Kafka…)
Sur du legacy où vous ne voulez pas toucher le code
En complément de spans manuels pour la logique métier

4. Exporters : comment les signaux sortent de l’application

L’exporter envoie les signaux vers une destination. En 2026, le standard est :

App (SDK) → OTLP → Collector

Pourquoi OTLP vers un Collector (et pas directement vers le backend) ?

Avantage	Explication
Découplage	Votre app ne “connaît” qu’un endpoint OTLP
Flexibilité	Changez de backend (Jaeger → Tempo) sans recoder
Gouvernance	Filtrage, redaction, routing centralisés
Résilience	Le Collector bufferise si le backend est down

5. Collector : la gouvernance hors du code

Le Collector est le routeur central de votre télémétrie. Il reçoit les signaux OTLP et les transforme/route vers vos backends.

Ce qu’il fait :

Fonction	Exemple
Normaliser	Convertir différents formats en un seul
Enrichir	Ajouter metadata Kubernetes (namespace, pod, node)
Filtrer	Exclure les healthchecks, les routes internes
Redacter	Masquer les tokens, emails, données sensibles
Router	Traces → Tempo, Métriques → Mimir, Logs → Loki
Bufferiser	Queue + retry si backend indisponible

Synthèse : qui fait quoi ?

Couche	Exemple	Où ça vit	À quoi ça sert
API / Facade	OTel API, Micrometer	Dans le code	Interface stable, appels de l’app
SDK	OTel SDK Java/Python/Node	Dans le runtime	Collecte, batching, sampling, export
Auto-instrumentation	Java Agent, Python distro	Autour de l’app	Spans/metrics automatiques sans toucher le code
Exporter	OTLP exporter	Dans l’app	Sortie des signaux
Collector	OTel Collector	Infra	Gouvernance, routing, résilience

3 architectures types

Chaque environnement a ses contraintes. Voici les trois patterns les plus courants :

1. Démarrage rapide (POC, service isolé)

L’app exporte directement vers le backend.

✅ Simple, rapide à mettre en place
❌ Couplé au backend, difficile à faire évoluer
❌ Pas de gouvernance centralisée

Quand l’utiliser : POC, application standalone, environnement de développement.

2. Standard moderne (recommandé)

Toutes les applications exportent vers un Collector central qui route vers les backends.

Architecture standard avec Collector central

✅ Découplage apps ↔ backends
✅ Gouvernance centralisée (filtering, redaction, sampling)
✅ Multi-backends sans modifier le code applicatif

Quand l’utiliser : dès que vous avez plusieurs services en production.

3. Kubernetes à l’échelle (agent + gateway)

Chaque node a un agent (DaemonSet) qui collecte localement, puis envoie à un gateway central.

Architecture Kubernetes agent + gateway

✅ Collecte locale (faible latence réseau)
✅ Enrichissement Kubernetes (namespace, pod, node)
✅ Routing centralisé + HA (gateway répliqué)

Quand l’utiliser : clusters Kubernetes de production, multi-tenants, équipes plateforme.

Cheat-sheet de décision

Vous voulez…	Solution
Zéro code	Auto-instrumentation + OTLP → Collector
Du contexte métier	Spans manuels via API + SDK
Découpler du backend	OTLP exporter vers Collector
Standardiser cross-langage	OpenTelemetry partout
Juste des métriques JVM	Micrometer (mais OTel reste compatible)
Migrer du legacy	OTel Shim pour OpenTracing/OpenCensus

Minimum Viable Instrumentation

Avant de tout tracer, instrumentez l’essentiel :

Checklist

Étape	Ce qu’il faut faire
1. Identité	`OTEL_SERVICE_NAME`, `service.version`, `deployment.environment`
2. Propagation	W3C Trace Context (`traceparent`) activé
3. Spans métier	3-5 opérations clés (checkout, paiement, génération PDF)
4. Métriques RED	Rate, Errors, Duration (p50/p95/p99)
5. Redaction	Masquer tokens, emails, PII avant export
6. Sampling	Ratio 10-20% pour commencer, affiner ensuite

Configuration minimale

# Identité du service
OTEL_SERVICE_NAME=checkout-api
OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3,deployment.environment=production

# Export OTLP
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317

# Sampling (ajuster selon le volume)
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

Ce qu’il ne faut PAS faire

Anti-pattern	Conséquence	Solution
IDs uniques en tags/labels	Explosion cardinalité, coûts	Utiliser des catégories (status, region)
Tout tracer sans sampling	Overhead perf, coûts stockage	Ratio 10-20% puis tail-based
Spans trop verbeux	Bruit, difficile à exploiter	5-10 attributs max par span
Pas de validation locale	Bugs découverts en prod	Exporter vers console/debug en dev
Ignorer `service.name`	Traces anonymes, inutilisables	Toujours définir l’identité
Exporter direct vers backend	Couplage, pas de gouvernance	Passer par le Collector

Outils par catégorie

Standards & SDK

OpenTelemetry Standard d'instrumentation multi-langage : API, SDK, semantic conventions.

Auto-instrumentation

Guides prévus : OpenTelemetry Java Agent, Python, Node.js, et l’Operator K8s.

Facades & alternatives

Micrometer Façade métriques JVM pour Spring Boot — intégration OTel disponible.

Guides associés

OpenTelemetry (fondamentaux) Comprendre le modèle OTel : signaux, contexte, propagation.

Corrélation des signaux Lier logs, métriques et traces pour un diagnostic efficace.

OpenTelemetry Collector Recevoir, traiter et exporter les signaux générés par vos SDK.