Guide d'instrumentation OpenTelemetry

Conseils d'experts pour mettre en œuvre une télémétrie OpenTelemetry de haute qualité et économe.

Règles et référence rapide

Cas d'usage / Règle	Description
telemetry	Point d'entrée — types de signaux, corrélation et navigation
resolve-values	Résolution des valeurs de configuration à partir de la base de code
resources	Attributs de ressource — identité du service et environnement
k8s	Déploiement Kubernetes — API de descente, spécification de pod
spans	Spans — nommage, type, statut et hygiène
logs	Logs — journalisation structurée, sévérité, corrélation de trace
metrics	Métriques — types d'instruments, nommage, unités, cardinalité
sensitive-data	Données sensibles — prévention des PII, nettoyage, redaction
validation	Validation de la télémétrie — liste de contrôle de vérification post-déploiement
nodejs	Configuration d'instrumentation Node.js
go	Configuration d'instrumentation Go
python	Configuration d'instrumentation Python
java	Configuration d'instrumentation Java
scala	Configuration d'instrumentation Scala
dotnet	Configuration d'instrumentation .NET
ruby	Configuration d'instrumentation Ruby
php	Configuration d'instrumentation PHP
browser	Configuration d'instrumentation navigateur
nextjs	Instrumentation full-stack Next.js (App Router)

Documentation officielle

Démarrage

Suivez ces étapes pour instrumenter une application à partir de zéro :

Choisissez votre règle SDK — sélectionnez la règle spécifique au langage dans le tableau ci-dessus (p. ex. nodejs, python).
Configurez les attributs de ressource — définissez l'identité du service et l'environnement selon resources.
Ajoutez des spans, métriques et logs — instrumentez votre code en suivant spans, metrics et logs.
Protégez les données sensibles — nettoyez les PII avant export selon sensitive-data.
Validez — confirmez que la télémétrie atteint le backend en utilisant la liste de contrôle dans validation.

L'extrait ci-dessous montre un span complet avec attributs et statut pour Node.js — consultez nodejs pour la configuration complète incluant l'initialisation du SDK, la configuration de l'exportateur et l'instrumentation automatique :

const { trace, SpanStatusCode } = require('@opentelemetry/api');
const tracer = trace.getTracer('my-service', '1.0.0');

tracer.startActiveSpan('operation-name', async (span) => {
  try {
    span.setAttribute('user.id', userId);
    span.setAttribute('order.id', orderId);

    const result = await processOrder(orderId);

    span.setAttribute('order.status', result.status);
    span.setStatus({ code: SpanStatusCode.OK });
    return result;
  } catch (err) {
    span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
    span.recordException(err);
    throw err;
  } finally {
    span.end();
  }
});

Principes clés

Densité de signal plutôt que volume

Chaque élément de télémétrie doit remplir l'un de ces trois objectifs :

Détecter — aider à identifier qu'il y a un problème
Localiser — aider à préciser où se situe le problème
Expliquer — aider à comprendre pourquoi c'est arrivé

Si ce n'est pas le cas, ne l'émettez pas.

Échantillonner dans le pipeline, pas dans le SDK

Utilisez le sampler AlwaysOn (le paramètre par défaut) dans chaque SDK. Ne configurez pas les samplers côté SDK — ils prennent des décisions irréversibles avant que le résultat d'une requête soit connu. Déférez tout échantillonnage au Collector, où les politiques peuvent être modifiées de manière centralisée sans redéployer les applications.

SDK (AlwaysOn)  →  Collector (sampling)  →  Backend (retention)
     ↓                    ↓                       ↓
  Tous les spans    Échantillonnage      Politiques de
  exportés          tête ou queue         stockage

otel-instrumentation