Observabilité Traefik : logs, métriques Prometheus et tracing

Traefik voit passer tout votre trafic : bien instrumenté, il devient votre meilleure source de diagnostic. Il expose les trois piliers de l'observabilité : des access logs détaillés, des métriques Prometheus, et des traces distribuées via OpenTelemetry. Ce guide s'adresse à ceux qui veulent passer d'une boîte noire à un reverse proxy mesurable, pour repérer une latence ou un pic d'erreurs avant les utilisateurs.

Tous les exemples ont été testés sur Traefik v3.7.6.

Ce que vous allez apprendre

• Activer les access logs au format JSON exploitable.
• Exposer les métriques Prometheus et les scraper.
• Envoyer métriques et traces via OpenTelemetry (OTLP).
• Exploiter et sécuriser le dashboard.
• Poser des alertes sur les erreurs et la latence.

Les trois piliers

L'observabilité repose sur trois signaux complémentaires, tous produits par Traefik.

Pilier	Ce qu'il répond	Backend typique
Logs	Que s'est-il passé sur cette requête ?	Loki, ELK
Métriques	Combien, à quelle vitesse, quel taux d'erreur ?	Prometheus
Traces	Où le temps est-il passé dans la chaîne ?	Tempo, Jaeger

Glissez pour voir

Pour relier ces signaux entre eux, voir corrélation des signaux et le standard OpenTelemetry.

Access logs

Les access logs enregistrent chaque requête traversant Traefik. Activez-les au format JSON, bien plus exploitable qu'un format texte pour un agrégateur de logs.

File

# configuration statique
accessLog:
  format: json
  filters:
    statusCodes:
      - "400-499"
      - "500-599"

Docker

command:
  - "--accesslog=true"
  - "--accesslog.format=json"

Chaque ligne JSON contient notamment DownstreamStatus (le code HTTP renvoyé), RequestHost, RequestPath et Duration (la latence). En lab, une requête vers un service produit bien une entrée {"DownstreamStatus":200,"RequestHost":"...","Duration":...}, prête à être ingérée par Loki ou Elasticsearch.

Filtrer pour réduire le bruit

Le champ filters.statusCodes ne journalise que les codes qui vous intéressent (les erreurs 4xx/5xx, par exemple). C'est essentiel sur un service à fort trafic pour éviter de noyer les vraies anomalies.

Métriques Prometheus

Traefik expose des métriques Prometheus sur un endpoint dédié. La bonne pratique : les servir sur un entrypoint séparé (non public) plutôt que sur le trafic applicatif.

1. Activer les métriques sur un entrypoint dédié :

   # configuration statique
   entryPoints:
     metrics:
       address: ":8082"
   metrics:
     prometheus:
       entryPoint: metrics

2. Vérifier l'endpoint (les métriques Traefik y apparaissent) :

   curl -s http://localhost:8082/metrics | grep traefik_
   # traefik_entrypoint_requests_total{code="200",entrypoint="web",...} 5
   # traefik_service_requests_total{...,service="whoami@docker"} 5

3. Scraper avec Prometheus en pointant sur cet endpoint :

   prometheus.yml

   scrape_configs:
     - job_name: traefik
       static_configs:
         - targets: ["traefik:8082"]

   La cible passe alors à l'état up dans Prometheus. Pour la visualisation, connectez Grafana à Prometheus.

Métriques utiles

Métrique	Description
traefik_entrypoint_requests_total	Requêtes par entrypoint (avec le code HTTP)
traefik_entrypoint_request_duration_seconds	Latence par entrypoint (histogramme)
traefik_router_requests_total	Requêtes par router
traefik_service_requests_total	Requêtes par service backend
traefik_service_server_up	État des backends (1 = up)
traefik_config_reloads_total	Nombre de rechargements de configuration

Glissez pour voir

Le code HTTP est un label (code="200"), ce qui permet de calculer directement un taux d'erreur par entrypoint ou par service en PromQL.

OpenTelemetry (métriques et traces)

Traefik v3 intègre OpenTelemetry nativement, via le protocole OTLP. C'est la voie recommandée pour envoyer métriques et traces vers un collecteur unique, puis les router vers vos backends.

# métriques via OTLP
metrics:
  otlp:
    http:
      endpoint: "http://otel-collector:4318/v1/metrics"

# traces via OTLP
tracing:
  otlp:
    http:
      endpoint: "http://otel-collector:4318/v1/traces"

L'OpenTelemetry Collector reçoit ces données et les exporte vers Prometheus (métriques), Tempo ou Jaeger (traces). Ce découplage évite de coupler Traefik à un backend précis.

Tracing distribué

Les traces montrent le chemin d'une requête à travers vos services et où le temps est passé. Avec OTLP activé, Traefik crée un span par requête et propage le contexte aux services en aval via les en-têtes W3C traceparent.

Vous exportez ensuite vers le backend de votre choix, tous compatibles OTLP :

• Grafana Tempo : stockage économique, requêtes TraceQL, intégration Grafana.
• Jaeger : plateforme de tracing CNCF, UI de recherche de spans.

OTLP remplace les anciens exportateurs

En Traefik v3, OpenTelemetry (OTLP) remplace les intégrations OpenTracing et OpenCensus des versions précédentes. Configurez un exportateur OTLP unique plutôt que des exportateurs spécifiques par backend.

Dashboard Traefik

Le dashboard affiche en direct les routers, services, middlewares et entrypoints détectés. C'est le premier réflexe pour vérifier qu'une route est bien prise en compte.

# active l'API et le dashboard
api:
  dashboard: true

Jamais insecure en production

N'activez jamais api.insecure=true en production : le dashboard exposerait toute votre topologie sans authentification. Placez-le derrière une route protégée (BasicAuth ou ForwardAuth + filtrage IP + TLS), comme détaillé dans Sécuriser Traefik.

Health checks

Traefik expose un endpoint ping pour vérifier qu'il est vivant, utile pour un load balancer amont ou les sondes Kubernetes.

ping:
  entryPoint: web

Sur Kubernetes, branchez les sondes liveness et readiness du pod Traefik sur cet endpoint. Côté backends, la métrique traefik_service_server_up signale un serveur indisponible, à surveiller de près.

Alerting

Les métriques ne servent qu'exploitées. Posez des alertes Prometheus sur les signaux critiques.

# règles Prometheus (extrait)
groups:
  - name: traefik
    rules:
      - alert: TraefikHighErrorRate
        expr: |
          sum(rate(traefik_service_requests_total{code=~"5.."}[5m]))
          / sum(rate(traefik_service_requests_total[5m])) > 0.05
        for: 5m
        labels: { severity: warning }
        annotations:
          summary: "Taux d'erreur 5xx supérieur à 5%"
      - alert: TraefikBackendDown
        expr: traefik_service_server_up == 0
        for: 2m
        labels: { severity: critical }

La première alerte se déclenche quand plus de 5% des requêtes renvoient une erreur serveur ; la seconde quand un backend tombe. Ajustez les seuils à votre trafic réel.

Dépannage via observabilité

L'observabilité n'a de valeur que si elle accélère le diagnostic. Voici les réflexes.

Question	Où regarder
Pic d'erreurs 5xx ?	traefik_service_requests_total{code=~"5.."} + access logs filtrés sur 5xx
Latence anormale ?	traefik_entrypoint_request_duration_seconds puis une trace pour localiser l'étape lente
Une route ne répond pas ?	dashboard (le router apparaît-il ?) + access logs
Backend instable ?	traefik_service_server_up

Glissez pour voir

À retenir

• Traefik expose les trois piliers : access logs, métriques Prometheus, traces OpenTelemetry.
• Les access logs JSON (avec filtrage sur les codes) alimentent Loki ou ELK.
• Les métriques exposent le code HTTP en label : taux d'erreur et latence se calculent en PromQL.
• OpenTelemetry (OTLP) est la voie v3 pour router métriques et traces via un collecteur.
• Le dashboard ne s'expose jamais en insecure : protégez-le.
• Posez des alertes sur le taux d'erreur 5xx et l'état des backends.

Prochaines étapes

Sécuriser Traefik Protéger le dashboard et les endpoints.

Prometheus Collecter et requêter les métriques Traefik.

Grafana Tempo Stocker et explorer les traces distribuées.

OpenTelemetry Le standard d'instrumentation universel.

×

📖 Voir la documentation →