infra / monitoring-observabilite

Installer Prometheus

Leçon 21 exercice

Explication

Ce que vous allez apprendre

Installer Prometheus soit en binaire natif, soit via Docker Compose
Comprendre la structure minimale d'un fichier prometheus.yml
Distinguer le modèle "pull" de Prometheus des systèmes de monitoring "push" plus anciens
Vérifier qu'une cible est bien scrapée via l'API et l'endpoint de santé
Recharger la configuration sans interrompre la collecte en cours

Dans quel contexte ?

Une équipe backend vient de terminer le développement de mon-api, une API FastAPI qui tourne en conteneur Docker. Avant même de coder la moindre métrique applicative, il faut un endroit où ces métriques vont atterrir : c'est le rôle de Prometheus, qu'on installe en local via Docker Compose pour reproduire fidèlement ce qui tournera plus tard en production.

D'abord, il faut choisir comment Prometheus va tourner

Deux options existent : télécharger le binaire officiel et le lancer directement sur la machine, ou passer par une image Docker via docker-compose. La seconde est presque toujours préférée en développement, car elle isole complètement la version de Prometheus des autres logiciels installés sur la machine hôte.

Dans les deux cas, Prometheus a besoin d'un seul fichier essentiel pour démarrer : prometheus.yml. Sans lui, il ne sait tout simplement pas quoi surveiller.

Une fois Prometheus lancé, il faut comprendre comment il fonctionne réellement

C'est ici que Prometheus se distingue de la plupart des anciens systèmes de monitoring. Beaucoup d'outils historiques fonctionnent en mode "push" : c'est l'application elle-même qui envoie activement ses métriques vers un serveur central, à intervalles réguliers.

Prometheus fait l'inverse : il fonctionne en mode "pull". C'est LUI qui va périodiquement chercher ("scraper") les métriques exposées par chaque application, via un simple endpoint HTTP /metrics que l'application doit exposer.

Aspect	Modèle "push" (ex: StatsD historique)	Modèle "pull" (Prometheus)
Qui initie la collecte	L'application elle-même	Le serveur Prometheus
Détection d'une app tombée	Difficile (silence = ambigu)	Facile (`up == 0`)
Configuration centralisée	Dispersée dans chaque app	Centralisée dans `prometheus.yml`
Surcharge réseau en cas de pic	Peut saturer le serveur central	Contrôlée par `scrape_interval`

Prérequis

Un minimum de familiarité avec Docker Compose (voir le cours dédié) aide à comprendre les fichiers de configuration de cette leçon, mais n'est pas strictement indispensable pour suivre.

Il reste un avantage caché du mode "pull" : détecter les pannes

Comme c'est Prometheus qui va chercher les données, l'absence de réponse d'une cible devient elle-même une information exploitable : la métrique interne up passe automatiquement à 0 dès qu'une cible ne répond plus. C'est un signal de panne gratuit, sans écrire une seule ligne de code applicatif supplémentaire.

Bonne pratique

Vérifie toujours l'état de tes cibles via curl http://localhost:9090/api/v1/targets après chaque modification de prometheus.yml. Une faute de frappe dans un nom de service Docker (mon-api au lieu de mon_api) est l'erreur la plus fréquente et se détecte instantanément avec cette commande.

Maintenant que Prometheus tourne, une nuance essentielle sur son modèle de données

Chaque combinaison unique d'un nom de métrique et de ses labels forme une "série temporelle" distincte, stockée séparément dans le TSDB (time series database) interne de Prometheus. Cette notion de labels comme dimensions est le concept central sur lequel repose tout PromQL, le langage de requête que tu découvriras dans deux leçons.

Le piège à connaître avant de continuer

Beaucoup de débutants oublient que scrape_interval (dans global) définit la fréquence par défaut, mais peut être surchargée job par job. Un scrape_interval trop court sur une cible qui répond lentement peut créer des scrapes qui se chevauchent et surcharger inutilement l'application surveillée elle-même.

La prochaine leçon s'attaque directement à la brique manquante : comment une application (en Python ou Node.js) expose-t-elle concrètement ces fameuses métriques que Prometheus vient scraper ?

Commandes & code

Installer Prometheus

# Installation via binaire officiel (Linux)
wget https://github.com/prometheus/prometheus/releases/download/v2.53.0/prometheus-2.53.0.linux-amd64.tar.gz
tar xvf prometheus-2.53.0.linux-amd64.tar.gz
cd prometheus-2.53.0.linux-amd64
./prometheus --config.file=prometheus.yml

# docker-compose.yml — méthode la plus rapide pour un environnement de dev/démo
services:
  prometheus:
    image: prom/prometheus:v2.53.0
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus_data:/prometheus
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
      - "--storage.tsdb.retention.time=15d"

volumes:
  prometheus_data:

# prometheus.yml : configuration minimale
global:
  scrape_interval: 15s        # fréquence de collecte par défaut pour toutes les cibles
  evaluation_interval: 15s    # fréquence d'évaluation des règles d'alerte/recording

scrape_configs:
  - job_name: "prometheus"     # Prometheus se scrape lui-même (métriques internes)
    static_configs:
      - targets: ["localhost:9090"]

  - job_name: "mon_api"
    metrics_path: /metrics     # endpoint exposé par l'app (voir leçon suivante)
    static_configs:
      - targets: ["mon-api:8000"]
        labels:
          env: "production"
          team: "backend"

# Vérifier que Prometheus tourne et scrape bien ses cibles
curl -s http://localhost:9090/-/healthy
curl -s http://localhost:9090/api/v1/targets | jq '.data.activeTargets[] | {job: .labels.job, health: .health}'

# Recharger la config sans redémarrer (si --web.enable-lifecycle est activé)
curl -X POST http://localhost:9090/-/reload

Modèle de données Prometheus :

  http_requests_total{method="GET", status="200", path="/api/users"} = 8421
  \_______________/  \___________________________________________/   \___/
     nom de la              labels (dimensions)                      valeur

  -> Prometheus est un TSDB (time series database) : chaque combinaison unique
     de nom + labels forme UNE série temporelle distincte.

Résumé

Prometheus fonctionne en mode "pull" : il va lui-même scraper (scrape_interval) des endpoints /metrics exposés par les apps.
scrape_configs liste les cibles ; static_configs convient pour du fixe, la découverte dynamique (Kubernetes, Consul) est vue plus loin.
Une série temporelle = un nom de métrique + une combinaison unique de labels ; attention à ne pas multiplier les labels à haute cardinalité (leçon dédiée).

Exercices pratiques

1 disponible

Mission : la cible fantôme

Objectif : Diagnostiquer et corriger une configuration de scraping Prometheus qui ne remonte aucune donnée pour une cible pourtant démarrée.

Contexte

mon-api tourne bien en conteneur Docker, exposée sur le port 8000, mais son dashboard Grafana reste désespérément vide. Le fichier prometheus.yml de l'équipe déclare pourtant un job pour cette cible. Ton travail : retrouver ce qui cloche dans le modèle "pull" de Prometheus et écrire la configuration corrigée.

Résoudre l’exercice →