Grafana Tempo et OpenTelemetry : traçage distribué sur VPS

OpenTelemetry est un projet CNCF graduaté qui unifie les trois piliers de l'observabilité — traces, métriques et logs — sous un standard vendor-neutral. Contrairement aux agents Datadog ou New Relic qui vous enferment dans un contrat et un format propriétaire, l'OTel Collector reçoit, transforme et exporte la télémétrie vers n'importe quel backend compatible. Vous changez de stockage sans retoucher une ligne de votre code applicatif.

Les SDKs couvrent Node.js, Python, Go, Java, PHP, Ruby et la plupart des langages modernes. Les propagateurs de contexte W3C TraceContext et B3 sont inclus : ils transmettent automatiquement le trace-id entre vos microservices via les headers HTTP, sans configuration supplémentaire. Enfin, l'OTel Collector peut tourner en tant qu'agent local sur chaque VM ou en mode gateway centralisé — vous choisissez la topologie qui convient à votre infrastructure.

Votre VPS doit disposer d'au moins 2 Go de RAM (4 Go recommandés en production) et d'un accès root ou sudo. Docker Engine ≥ 24 et Docker Compose v2 doivent être installés.

Prévoyez un sous-domaine dédié — par exemple grafana.votre-domaine.com — pour exposer l'interface Grafana derrière un reverse proxy TLS (nginx ou Caddy). Les ports 4317 (OTLP/gRPC) et 4318 (OTLP/HTTP) doivent être ouverts dans votre pare-feu côté privé pour recevoir la télémétrie depuis vos applications ; ne les exposez pas sur l'interface publique. Le port 3200 de Tempo et le port 3000 de Grafana restent internes au réseau Docker.

Côté stockage, prévoyez au minimum 10 Go libres pour les blocs de traces. La valeur montée par défaut dans /tmp/tempo ne survit pas aux redémarrages : remplacez-la dès la mise en production par un volume Docker ou un montage sur un disque dédié.

Le flux de données suit quatre étapes :

1. Votre application instrumente ses requêtes avec un SDK OTel et exporte des spans vers l'OTel Collector (OTLP gRPC port 4317 ou HTTP port 4318).
2. L'OTel Collector reçoit, met en tampon par batch processor, puis exporte vers Tempo via OTLP gRPC interne. Il peut simultanément envoyer les métriques vers Prometheus et les logs vers Loki.
3. Grafana Tempo stocke les blocs de traces compressés sur disque (ou S3). Il expose une API TraceQL sur le port 3200 pour les requêtes de Grafana.
4. Grafana interroge Tempo avec TraceQL, affiche les flamegraphs, les service graphs et les span metrics. Si Tempo est lié à Loki, un clic sur un span ouvre les logs du service concerné sur la même fenêtre temporelle.

TraceQL est le langage de requête natif de Tempo. Une requête typique ressemble à : {service.name="api" && status=error && duration>500ms}. Vous filtrez par attribut de ressource, attribut de span, statut ou durée — et vous obtenez immédiatement les traces qui franchissent un seuil de latence.

Les Span Metrics sont un pipeline Tempo qui dérive automatiquement des métriques RED (Rate, Error, Duration) à partir des traces entrantes, sans que vous n'ajoutiez un seul compteur dans votre code. Ces métriques peuvent être scrappées par Prometheus et affichées dans des tableaux de bord Grafana standard.

Par défaut, Tempo stocke les blocs localement dans /tmp/tempo. Pour une installation durable, deux options s'offrent à vous.

Stockage local sur volume Docker : c'est la configuration recommandée pour un VPS standalone. Le volume tempo-data défini dans le docker-compose.yml ci-dessus persiste les données entre les redémarrages. Ajustez block_retention dans tempo.yaml selon votre besoin : 72 h pour un environnement de staging, 168 h (7 jours) à 720 h (30 jours) pour la production. Chaque heure de trace compressée occupe environ 100–300 Mo selon le volume de spans.

Stockage objet S3-compatible : pour une stack multi-nœuds ou un stockage sans plafond, remplacez le backend local par un backend s3 dans tempo.yaml :

storage:
  trace:
    backend: s3
    s3:
      bucket: mon-bucket-traces
      endpoint: s3.amazonaws.com
      region: eu-west-1
      access_key: ${S3_ACCESS_KEY}
      secret_key: ${S3_SECRET_KEY}
    wal:
      path: /tmp/tempo/wal

Tempo est compatible avec AWS S3, MinIO, Scaleway Object Storage et tout backend qui implémente l'API S3. La WAL (Write-Ahead Log) reste toujours sur disque local pour garantir la durabilité des traces en cours d'ingestion.

Le compacteur de Tempo fusionne les petits blocs et applique la politique de rétention. Il tourne en arrière-plan et ne nécessite aucune intervention manuelle. Surveillez la taille du dossier blocks/ avec docker exec tempo du -sh /tmp/tempo/blocks pour anticiper un éventuel manque d'espace.

L'auto-instrumentation OTel pour Node.js capture automatiquement les appels HTTP sortants, les requêtes Express/Fastify, les requêtes de base de données et bien d'autres bibliothèques sans modifier votre code métier.

Installez les packages nécessaires :

npm install @opentelemetry/sdk-node \
             @opentelemetry/auto-instrumentations-node \
             @opentelemetry/exporter-trace-otlp-grpc

Créez un fichier tracing.js à charger en premier :

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'grpc://localhost:4317',
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

Démarrez votre application en chargeant ce fichier en premier :

export OTEL_SERVICE_NAME=mon-api
export OTEL_EXPORTER_OTLP_ENDPOINT=http://votre-vps:4317
node --require ./tracing.js app.js

Pour les environnements Docker, passez les variables OTEL_SERVICE_NAME et OTEL_EXPORTER_OTLP_ENDPOINT dans votre docker-compose.yml ou votre manifest Kubernetes. Tous les appels HTTP entrants et sortants seront automatiquement tracés et corrélés par le propagateur W3C TraceContext.

Le package opentelemetry-distro fournit un mécanisme de bootstrap qui installe automatiquement tous les packages d'instrumentation pour les bibliothèques détectées dans votre environnement.

Installez et bootstrappez :

pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install

Lancez votre application en la préfixant avec opentelemetry-instrument :

export OTEL_SERVICE_NAME=mon-service-python
export OTEL_EXPORTER_OTLP_ENDPOINT=http://votre-vps:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
opentelemetry-instrument python app.py

Les frameworks Django, Flask, FastAPI, SQLAlchemy et les clients HTTP (requests, httpx, aiohttp) sont instrumentés automatiquement. Pour un déploiement en conteneur, définissez les variables OTEL_* dans votre fichier d'environnement et assurez-vous que le port 4317 de l'OTel Collector est accessible depuis le réseau de vos conteneurs.

Si vous préférez une instrumentation manuelle pour un contrôle plus fin, utilisez directement l'API OTel :

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("traitement-commande") as span:
    span.set_attribute("commande.id", commande_id)
    # votre logique métier

Grafana 10+ permet de définir des alertes directement sur les métriques dérivées des traces. Les Span Metrics de Tempo génèrent automatiquement trois métriques par service : traces_spanmetrics_calls_total (taux de requêtes), traces_spanmetrics_latency_bucket (histogramme de latence) et leur compteur d'erreurs associé.

Pour créer un SLO sur le taux d'erreur de votre API :
1. Dans Grafana, allez dans Alerting → Alert rules → New alert rule.
2. Choisissez la datasource Prometheus (ou Tempo via Span Metrics) et saisissez une requête comme rate(traces_spanmetrics_calls_total{status_code="STATUS_CODE_ERROR", service="mon-api"}[5m]) / rate(traces_spanmetrics_calls_total{service="mon-api"}[5m]).
3. Définissez le seuil d'alerte (par exemple > 0.05 pour un taux d'erreur supérieur à 5 %) et la fenêtre d'évaluation.
4. Configurez un contact point : Alertmanager, PagerDuty, Slack ou webhook — tout s'intègre depuis Alerting → Contact points.

Pour le P99 de latence, interrogez histogram_quantile(0.99, rate(traces_spanmetrics_latency_bucket{service="mon-api"}[5m])) et déclenchez une alerte si la valeur dépasse votre budget d'erreur (par exemple 2 secondes). Ces alertes basées sur des traces sont bien plus précises que des alertes sur des métriques synthétiques, car elles reflètent le vécu réel de chaque requête.

Aucun span n'arrive dans Tempo. Vérifiez d'abord que l'OTel Collector est joignable depuis votre application (telnet votre-vps 4317). Consultez les logs du Collector (docker compose logs otel-collector) : une erreur connection refused sur tempo:4317 indique que Tempo n'est pas encore démarré ou que son port interne n'est pas exposé sur le réseau Docker. Assurez-vous que les deux services sont sur le même réseau (observability).

Connexion refusée depuis l'application vers le Collector. Sur un pare-feu UFW ou firewalld, autorisez les ports 4317 et 4318 uniquement pour les IP de vos applications, pas pour l'ensemble d'Internet. En production, les applications et le Collector doivent être sur le même réseau privé ; n'exposez jamais le Collector sur l'interface publique sans authentification.

Traces tronquées ou spans manquants. Le batch processor du Collector regroupe les spans avant de les envoyer. Si votre application envoie peu de spans, les traces peuvent mettre jusqu'à timeout secondes (5 s par défaut) pour apparaître dans Grafana. Pour le développement, réduisez timeout: 1s dans le batch processor. Si des spans sont systématiquement absents, vérifiez que le propagateur de contexte est activé dans votre SDK (W3CTraceContextPropagator) — sans lui, les appels entre services génèrent des traces orphelines.

Tempo consomme trop d'espace disque. Réduisez block_retention dans tempo.yaml et relancez Tempo. Le compacteur appliquera la nouvelle politique au prochain cycle (toutes les 5 minutes par défaut). En cas d'urgence, supprimez manuellement les anciens blocs dans /tmp/tempo/blocks tout en laissant la WAL intacte.

Grafana ne trouve pas les traces depuis les logs Loki. Vérifiez que vos applications injectent bien le trace_id dans leurs logs (format structuré JSON recommandé) et que le champ Derived fields dans la datasource Loki pointe vers le bon pattern ("traceId": "(\w+)"). L'URL du lien doit pointer vers la datasource Tempo avec le bon identifiant de datasource Grafana.