Distributed Tracing: OpenTelemetry

Distributed Tracing: OpenTelemetry

1) Pourquoi OTel et ce qu'il donne

• Visibilité de bout en bout des chemins de requête (gateway → services → OBD/cache/files d'attente).
• RCA/débogage rapide des dégradations et des versions (canaries/bleu-vert).
• Lien avec SLO et auto-reculs (solutions d'exploitation sur les données).
• Vendor-agnosticité : exportation vers n'importe quel backend, sans lien vers un seul APM.

Principes de base : standardize, sample smart, secure by default, correlate everything.

2) Bases : contexte, dormeurs, attributs

Trace - arborescence/graphe des appels ; Span - opération (RPC, SQL, appel de file d'attente).
Span Kind: `SERVER`, `CLIENT`, `PRODUCER`, `CONSUMER`, `INTERNAL`.
W3C Trace Context : titres « traceparent », « tracestate » ; le contexte est transposé entre les services.
Attributes - clé-valeur (faible cardinalité !), Événements - étiquettes temporelles, État - code/description de l'erreur.
Liens - lien span en dehors de la hiérarchie stricte (important pour async/fan-out/fan-in).

• HTTP : 'HTTP {METHOD}' ('GET/withdraw' en tant qu'attribut)
• DB: `DB SELECT` / `DB INSERT`
• Queue: `QUEUE publish topic=X` / `QUEUE consume topic=X`

3) Conventions sémantiques (semconv)

• HTTP/GRPC: `http. method`, `http. route`, `http. status_code`, `url. full`.
• DB: `db. system=postgresql`, `db. statement '(pressage sûr seulement !),' db. name`.
• Messaging: `messaging. system=kafka`, `messaging. operation=receive`, `messaging. destination`.
• Cloud/K8s/Host: `cloud. region`, `k8s. pod. name`, `container. id`.
• Attributes de ressources (obligatoire) : 'service. name`, `service. version`, `deployment. environment`.

Indiquez la stabilité du schéma via 'schemaUrl'dans les ressources SDK/Collector.

4) Sampling : head, tail, adaptive

Head-based (en SDK) : décide à l'avance, pas cher ; bon pour le high-QPS, mais peut manquer les pistes « intéressantes ».
Tail-based (en Collector) : décide une fois la piste terminée ; permet les règles par statut, latence, attributs.
Adaptive/Dynamique : Augmente la proportion de sample en cas d'erreur/croissance p95.

Recette de niveau prod : Tête 1-5 % global + Tail sélection « importante » : 'status = ERROR', 'latency> p95', 'itinéraires monétaires', erreurs PSP/KYC.

5) Corrélation : métriques, logs, tracés

Exemples : étiquettes avec 'trace _ id'dans les histogrammes des métriques (saut rapide vers la piste).
Logs : ajoutez 'trace _ id '/' span _ id' et passez des logs à la piste.
SpanMetrics (processeur) : agrégera à partir des pistes des métriques RED (« requests, errors, during ») pour SLO/alerts.

6) Architecture de déploiement

Agent (DaemonSet) sur chaque nœud recueille à partir d'applications (OTLP) et forward.
Gateway (Cluster/Region) est un collecteur central (beaucoup de répliques) avec des pipes de routage/sampling/enrichissement.
OTLP: gRPC `4317`, HTTP `4318`; activez TLS/mTLS.

Avantages de « agent + gateway » : isolation, tampon, backpressure locale, réseau simplifié.

7) OpenTelemetry Collector - modèle de base (gateway)

yaml receivers:
otlp:
protocols:
grpc: { endpoint: 0. 0. 0. 0:4317 }
http: { endpoint: 0. 0. 0. 0:4318 }

processors:
memory_limiter: { check_interval: 5s, limit_percentage: 75 }
batch: { timeout: 2s, send_batch_size: 8192 }
attributes:
actions:
- key: deployment. environment action: upsert value: prod resource:
attributes:
- key: service. namespace action: upsert value: core tail_sampling:
decision_wait: 5s policies:
- name: errors type: status_code status_code: { status_codes: [ERROR] }
- name: slow_traces type: latency latency: { threshold_ms: 800 }
- name: important_routes type: string_attribute string_attribute:
key: http. route values: ["/withdraw", "/deposit"]
- name: baseline_prob type: probabilistic probabilistic: { sampling_percentage: 5 }

exporters:
otlp/apm:
endpoint: apm-backend:4317 tls: { insecure: true }
prometheus:
endpoint: 0. 0. 0. 0:9464

extensions:
health_check: {}
pprof: { endpoint: 0. 0. 0. 0:1777 }
zpages: { endpoint: 0. 0. 0. 0:55679 }

service:
extensions: [health_check, pprof, zpages]
pipelines:
traces:  { receivers: [otlp], processors: [memory_limiter,attributes,resource,batch,tail_sampling], exporters: [otlp/apm] }
metrics: { receivers: [otlp], processors: [batch], exporters: [prometheus] }
logs:   { receivers: [otlp], processors: [batch], exporters: [] }

8) SpanMetrics et RED pour SLO

yaml processors:
spanmetrics:
metrics_exporter: prometheus histogram:
explicit:
buckets: [50ms,100ms,200ms,400ms,800ms,1600ms,3200ms]
service:
pipelines:
traces: { receivers: [otlp], processors: [spanmetrics,batch,tail_sampling], exporters: [otlp/apm] }
metrics: { receivers: [otlp], processors: [batch], exporters: [prometheus] }

Il y a maintenant 'traces _ spanmetrics _ calls {service, route, code}' et 'durée _ bucket' pour SLO/alerts.

9) K8s : Déploiement du collecteur (DaemonSet + Deployment)

yaml apiVersion: apps/v1 kind: DaemonSet metadata: { name: otel-agent, namespace: observability }
spec:
template:
spec:
containers:
- name: otelcol image: otel/opentelemetry-collector:latest args: ["--config=/conf/agent. yaml"]
ports:
- { containerPort: 4317, name: otlp-grpc }
- { containerPort: 4318, name: otlp-http }

Gateway (Deployment) - plusieurs répliques, Service ClusterIP/Ingress, HPA par CPU/QPS.

10) Sécurité et vie privée

TLS/mTLS между SDK → Agent → Gateway → Backend.
Authentification (Basic/OAuth/Headers) à l'entrée Gateway ; limitez les origines.
Révision PII : filtrer/masquer les attributs ('user. email ',' card') dans le processeur Collector.
Limites : dans le SDK, limitez la taille de l'événement/le nombre d'attributs (protection contre la cardinalité).
RBAC en backend + neimspace de projets individuels/tenants.

yaml processors:
attributes/redact:
actions:
- key: user. email action: delete
- key: payment. card action: delete

11) Instrumentation : Démarrage rapide

Node. js

js import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-grpc";
import { Resource } from "@opentelemetry/resources";
import { SemanticResourceAttributes as R } from "@opentelemetry/semantic-conventions";

const sdk = new NodeSDK({
traceExporter: new OTLPTraceExporter({ url: "http://otel-agent. observability:4317" }),
resource: new Resource({
[R.SERVICE_NAME]: "payments-api",
[R.SERVICE_VERSION]: "1. 14. 2",
[R.DEPLOYMENT_ENVIRONMENT]: "prod"
}),
instrumentations: [getNodeAutoInstrumentations()],
});
sdk. start();

Java (Spring)

java
// Gradle: io. opentelemetry. instrumentation:opentelemetry-spring-boot-starter
// application. yml otel:
service:
name: orders-api exporter:
otlp:
endpoint: http://otel-agent. observability:4317 traces:
sampler: parentbased_traceidratio sampler-arg: 0. 05

Python (FastAPI)

python from opentelemetry import trace from opentelemetry. sdk. resources import Resource from opentelemetry. exporter. otlp. proto. grpc. trace_exporter import OTLPSpanExporter from opentelemetry. sdk. trace import TracerProvider from opentelemetry. sdk. trace. export import BatchSpanProcessor

provider = TracerProvider(resource=Resource. create({"service. name":"fraud-scoring","deployment. environment":"prod"}))
provider. add_span_processor(BatchSpanProcessor(OTLPSpanExporter(endpoint="http://otel-agent. observability:4317", insecure=True)))
trace. set_tracer_provider(provider)

Go

go exp, _:= otlptracegrpc. New(ctx, otlptracegrpc. WithEndpoint("otel-agent. observability:4317"), otlptracegrpc. WithInsecure())
res:= resource. NewWithAttributes(semconv. SchemaURL, semconv. ServiceNameKey. String("gateway"), semconv. DeploymentEnvironmentKey. String("prod"))
tp:= sdktrace. NewTracerProvider(sdktrace. WithBatcher(exp), sdktrace. WithResource(res), sdktrace. WithSampler(sdktrace. ParentBased(sdktrace. TraceIDRatioBased(0. 05))))
otel. SetTracerProvider(tp)

12) Asynchrone : files d'attente, pneus, cron

PRODUCTEUR/CONSOMMATEUR avec communication via 'liens' (les messages ont leur propre cycle de vie).
Promouvoir le contexte dans les titres des messages ('traceparent '/' baggage').
Avec batch-consume, créez par span un message ou agrégez-le avec l'attribut 'messaging. batch. size`.
Pour cron/job : nouvelle trace à lancer + liens vers les événements primaires (le cas échéant).

13) Baggage et ciblage

Stocker un minimum de clés stables ('tenant _ id', 'region', 'vip _ tier') dans le baggage ; interdire les PII.
Pour agréger ensuite les métriques par segment, faites un tri via le logger gateway/gateway.

14) Intégration avec les versions et le jeu SLO

Étapes canaries → vérifiez 'traces _ spanmetrics _' sur les itinéraires/segments de yuz.
En cas de dégradation (5xx/p95), auto-stop et retour en arrière (Argo Rollouts AnalysisTemplate + BouQL).
Les instances des métriques sont directement dirigées vers les « mauvaises » pistes de l'intervalle de sortie.

15) Limites et performances

Ограничивайте: `OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT`, `OTEL_SPAN_EVENT_COUNT_LIMIT`, `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT`.
Samplifier les exceptions/stacktrace en fonction de la probabilité/fréquence.
Un processeur de batch dans le SDK et le collecteur ; Gardez les files d'attente pour ne pas perdre les pistes en cas de surtension.

16) Compatibilité et migration

Promoteurs : utiliser le W3C ; Prendre en charge la lecture des B3/X-Ray lors de la migration.
Exportation : OTLP → APM (Jaeger/Tempo/Elastic/X-Ray, etc.).
Versions stables de semconv - fixez 'schemaUrl' et planifiez les mises à niveau.

17) Anti-modèles

La cardinalité élevée des attributs ('user _ id'dans le label, clés dynamiques).
Логи sans ' trace_id ' → il n'y a pas de corrélation.
Exporte directement des applications vers l'APM Internet (pas de passerelle, pas de TLS/mTLS).
La collecte de « seulement » 100 % dans la vente est coûteuse et inutile.
Décharges de requêtes SQL avec données utilisateur dans 'db. statement`.
Nom incohérent du service/version - métriques « s'effondrent ».

18) Chèque de mise en œuvre (0-45 jours)

0-10 jours

Activer le SDK/auto-outil sur 2-3 services critiques.
Configurer Agent (DaemonSet) + Gateway (Deployment), OTLP 4317/4318 avec TLS.
Ajouter 'service. name`, `service. version`, `deployment. l'environnement est partout.

11-25 jours

Tail-sampling par erreurs/latence/itinéraires » monétaires ».
SpanMetrics → Prometheus, activer Exemplars et dashboards RED/SLO.
Promouvoir le W3C via la passerelle API/NGINX/mesh ; corréler les logs.

26-45 jours

Couvrir les files d'attente/bases de données/cache ; liens pour async.
Les politiques de rédaction PII du Collecteur ; limites d'attribut dans le SDK.
Intégrer les versions SLO-Gate et Auto-back.

19) Métriques de maturité

La couverture des demandes entrantes par le traçage est ≥ à 95 % (compte tenu de sampling head/tail).
Part des métriques avec Exemplars ≥ 80 %.
Temps RCA « de la métrique à la piste » ≤ 2 min (p50).
0 fuites PII dans les attributs/événements (scanner).
Tous les services ont un service. name/version/environment 'et sémantique cohérente.

20) Applications : Fragments utiles

nginx proxy_set_header traceparent $http_traceparent;
proxy_set_header tracestate $http_tracestate;
proxy_set_header baggage   $http_baggage;

histogram_quantile(0. 95, sum(rate(traces_spanmetrics_duration_bucket{route="/withdraw"}[5m])) by (le))

Politique : Interdiction des attributs PII (pseudo-linter)

yaml forbid_attributes:
- user. email
- payment. card
- personal.

21) Conclusion

OpenTelemetry transforme l'observabilité en un contour standardisé et gérable : une sémantique unique, une propagande sûre, un sampling intelligent et une forte corrélation avec les métriques et les logs. Construisez agent + gateway, ajoutez tail-sampling, spanmetrics et Exemplars, suivez PII et cardinalité - et le tracing deviendra un outil non seulement pour le débogage, mais aussi pour les solutions SRE/Release automatisées, réduisant MTTR et les risques à chaque sortie.