Comment installer Grafana Tempo en 2026

Introduction

Grafana Tempo est un système de traçage distribué open-source, conçu pour stocker et interroger des traces à grande échelle sans échantillonnage ni indexation coûteuse. Contrairement à Jaeger ou Zipkin, Tempo utilise un stockage objet (S3, GCS) pour des coûts minimes et une scalabilité infinie.

Pourquoi l'utiliser en 2026 ? Dans un monde de microservices et de Kubernetes omniprésents, le tracing est essentiel pour déboguer les latences et les erreurs distribuées. Tempo s'intègre nativement à Grafana pour des dashboards visuels intuitifs, et supporte OpenTelemetry, le standard universel. Ce tutoriel débutant vous guide pas à pas : de l'installation Docker Compose à la génération et visualisation de traces réelles avec une app démo HotROD. À la fin, vous maîtriserez les bases pour monitorer vos applications. Temps estimé : 15 minutes. (128 mots)

Prérequis

Docker et Docker Compose installés (version 20+).
Port 3000 (Grafana) et 8080 (Tempo) libres.
Connaissances basiques en YAML et ligne de commande.
Un navigateur web.
Optionnel : MinIO pour stockage persistant (inclus dans l'exemple).

Créer le fichier Docker Compose

docker-compose.yml

version: "3"
services:
  tempo:
    image: grafana/tempo:latest
    command: [ "-config.file=/etc/tempo.yaml" ]
    volumes:
      - ./tempo.yaml:/etc/tempo.yaml
      - tempo-data:/tmp/tempo
    ports:
      - "3200:3200"       # tempo
      - "3200:3200/udp"  # tempo gRPC
      - "4317:4317"      # OTLP gRPC
      - "4318:4318"      # OTLP HTTP
      - "9411:9411"      # Zipkin
      - "14268:14268"    # Jaeger gRPC
      - "14250:14250"    # Jaeger thrift HTTP
      - "8080:8080"
    networks:
      - tempo

  grafana:
    image: grafana/grafana:latest
    volumes:
      - grafana-data:/var/lib/grafana
    ports:
      - "3000:3000"
    networks:
      - tempo
    environment:
      - GF_AUTH_ANONYMOUS_ENABLED=true
      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
      - GF_USERS_ALLOW_SIGN_UP=false
      - GF_EXPLORE_ENABLED=true

  hotrod:
    image: grafana/hotrod:latest
    ports:
      - "8080:8080"
    environment:
      - OTEL_SERVICE_NAME=hotrod
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://tempo:4318
      - OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production
    networks:
      - tempo
    depends_on:
      - tempo

  minio:
    image: minio/minio:latest
    volumes:
      - minio-data:/data
      - ./minio.yaml:/etc/minio/config.yaml
    command: server /data --console-address ":9001"
    environment:
      - MINIO_ROOT_USER=minioadmin
      - MINIO_ROOT_PASSWORD=minioadmin
    ports:
      - "9000:9000"
      - "9001:9001"
    networks:
      - tempo

volumes:
  grafana-data: {}
  minio-data: {}
  tempo-data: {}

networks:
  tempo:
    driver: bridge

Ce Docker Compose déploie Tempo, Grafana, une app démo HotROD (instrumentée OTEL), et MinIO pour le stockage backend. HotROD simule un e-commerce avec traçage auto. Les ports exposés permettent l'accès direct. Attention : créez aussi le fichier tempo.yaml avant de lancer.

Lancer la stack

Créez un dossier projet, collez le docker-compose.yml ci-dessus, puis exécutez docker compose up -d. Vérifiez les logs avec docker compose logs tempo. La stack est prête en 1-2 minutes : Grafana sur http://localhost:3000, Tempo API sur http://localhost:8080/ready (doit retourner 'ready'). HotROD sur http://localhost:8080.

Analogie : C'est comme assembler un kit Lego observabilité : chaque conteneur est une brique interconnectée via le réseau 'tempo'.

Configurer Tempo (fichier YAML)

tempo.yaml

server:
  http_listen_port: 8080

distributor:
  receivers:
    otlp:
      protocols:
        grpc:
          endpoint: 0.0.0.0:4317
        http:
          endpoint: 0.0.0.0:4318
    jaeger:
      protocols:
        grpc:
          endpoint: 0.0.0.0:14250
        thrift_http:
          endpoint: 0.0.0.0:14268
    zipkin:
      endpoint: 0.0.0.0:9411

storage:
  trace:
    backend: s3
    wal:
      path: /tmp/tempo/wal
    s3:
      bucket: tempo
      endpoint: minio:9000
      access_key: minioadmin
      secret_key: minioadmin
      insecure: true

minio:
  endpoint: "minio:9000"
  bucket_name: "tempo"
  access_key: "minioadmin"
  secret_key: "minioadmin"
  insecure: true

querier:
  frontend_worker:
    frontend_address: 127.0.0.1:9095
    log_level: error

Cette config active les receivers OTLP/Zipkin/Jaeger pour ingérer des traces. Le stockage WAL + S3 (via MinIO) assure persistance sans index. 'Insecure: true' pour dev ; en prod, utilisez HTTPS et clés réelles. Le querier optimise les requêtes.

Générer des traces avec HotROD

Accédez à http://localhost:8080. Cliquez sur les boutons 'Checkout', 'Log in', etc., pour générer du trafic. Chaque action crée une trace distribuée (frontend → DB → payment).

Ouvrez Grafana (admin/admin ou anonyme) > Explore > Sélectionnez Tempo comme source (ajoutez-la via Configuration > Data sources > Tempo, URL: http://tempo:3200). Recherchez par service='hotrod' ou traceID. Astuce : Les traces apparaissent en <1s.

Script Bash pour générer du trafic

generate-traces.sh

#!/bin/bash
for i in {1..10}; do
  curl "http://localhost:8080/checkout?item=widget-$i"
  curl "http://localhost:8080/login"
  echo "Generated batch $i"
done

# Vérifier Tempo ready
curl http://localhost:8080/ready

Ce script simule 10 checkouts et logins, générant des traces riches. Exécutez chmod +x generate-traces.sh && ./generate-traces.sh. Vérifiez 'ready' pour confirmer que Tempo ingère. Utile pour tester à échelle.

Explorer les traces dans Grafana

Étapes dans Grafana Explore :

Data source : Tempo.
Query : { .service.name = "hotrod" } | unparam (TraceQL).
Filtrez par 'duration > 100ms'.
Cliquez sur une trace pour voir la waterfall (timeline spans).

Analogie : Comme un film en slow-motion d'une transaction : chaque span est une scène actorisée.

Exemple instrumentation Python OTEL

app.py

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

# Config exporter vers Tempo
trace.set_tracer_provider(TracerProvider(resource=Resource.create({"service.name": "python-app"}))
provider = trace.get_tracer_provider()

processor = BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces"))
provider.add_span_processor(processor)

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("main"):
    with tracer.start_as_current_span("slow-operation"):
        import time
        time.sleep(0.5)
    print("Trace envoyée à Tempo!")

# pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-grpc

Ce script Python crée deux spans (main + slow-op) et les exporte via OTLP HTTP vers Tempo. Lancez-le après pip install .... Vérifiez dans Grafana avec { .service.name = "python-app" }. Idéal pour intégrer vos apps existantes.

Query TraceQL avancée

traceql-query.txt

{ .service.name = "hotrod" } | spanKind = "server" and .name =~ "payment" and duration > 100ms | select(span)

Cette requête TraceQL filtre les spans serveur de 'payment' lents (>100ms) dans HotROD. Collez-la dans Grafana Explore. TraceQL est puissant comme PromQL pour traces : regex, maths, agrégations.

Bonnes pratiques

Toujours utiliser OpenTelemetry : Standard neutre, évite vendor-lock.
Stockage persistant : Remplacez MinIO par S3/GCS en prod avec insecure: false.
Sécurité : Activez auth Grafana, exposez pas tous les ports.
Scalabilité : Déployez en cluster avec ingesters multiples.
Logs + Traces : Intégrez Loki pour corrélation full observabilité.

Erreurs courantes à éviter

Oublier le WAL : Sans wal.path, les traces se perdent au redémarrage.
Ports mal configurés : Vérifiez firewall ; OTLP 4318 bloqué = traces fantômes.
Query vide : Ajoutez explicitement Tempo comme datasource dans Grafana.
Pas de backend : Tempo refuse les traces sans S3/MinIO configuré.

Pour aller plus loin

Docs officielles : Grafana Tempo.
OpenTelemetry : Démarrer OTEL.
Kubernetes : Helm chart Tempo.
Formations expertes : Maîtrisez l'observabilité avec nos formations Learni.