Monitoring Stack : Prometheus + Grafana

1. Quoi ? — Définition et contexte

La Monitoring Stack assure l’observabilité de toute l’infrastructure. Elle collecte les métriques système et applicatives, les visualise via des dashboards, et déclenche des alertes en cas d’anomalie.

Composants

Service	Port	Rôle
Prometheus	9090	Collecte et stockage des métriques (mode pull)
Grafana	3000	Visualisation et dashboards
Alertmanager	9093	Routage et groupement des alertes
Node Exporter	9100	Métriques système (CPU, RAM, disque)
cAdvisor	8080	Métriques conteneurs Docker
OTEL Collector	4317, 8889	Agrégation télémétrie (Claude Code)

Mode pull

Prometheus fonctionne en mode “pull” : il interroge régulièrement (scrape) les services pour récupérer leurs métriques. C’est Prometheus qui va chercher les données, pas les services qui les envoient.

Architecture visuelle

┌─────────────────────────────────────────────────────────────┐
│                    Scrape Targets                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │ Node Exporter│  │   cAdvisor   │  │ OTEL Collector   │   │
│  │  (host:9100) │  │  (host:8080) │  │   (host:8889)    │   │
│  └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘   │
└─────────┼─────────────────┼────────────────────┼─────────────┘
          │                 │                    │
          ▼                 ▼                    ▼
    ┌─────────────────────────────────────────────────┐
    │              Prometheus (port 9090)              │
    │  ├─ Scrape toutes les 15s                       │
    │  ├─ Évalue les règles d'alerte                  │
    │  └─ Stocke 15 jours / 5 GB max                  │
    └─────────────────┬───────────────────────────────┘
                      │
          ┌───────────┴───────────┐
          ▼                       ▼
┌──────────────────┐    ┌──────────────────────┐
│ Alertmanager     │    │ Grafana (port 3000)  │
│ (port 9093)      │    │ ├─ Linux System      │
│ ├─ Groupe alerts │    │ ├─ Docker Containers │
│ └─ Route → N8N   │    │ └─ Claude Code       │
└────────┬─────────┘    └──────────────────────┘
         │
         ▼
N8N webhook: /webhook/prometheus/alert
→ Notification Hub → Telegram

---

2. Pourquoi ? — Enjeux et motivations

Problèmes résolus par le monitoring

Problème	Sans monitoring	Avec monitoring
Container crash	Découvert par un utilisateur	Alerte immédiate
Disque plein	Service inaccessible	Anticipé avant saturation
Fuite mémoire	OOM killer aléatoire	Tendance visible, action préventive
Coûts Claude	Surprise en fin de mois	Suivi en temps réel

Alertes les plus utiles en pratique

Alerte	Déclenchée	Utilité constatée
ContainerDown	Service crash	Détection rapide, restart manuel ou auto
Claude Code telemetry	Sessions Claude	Suivi du temps passé et des tokens utilisés
DiskSpaceLow	Espace disque < 15%	Prévention avant incident
HighMemoryUsage	RAM > 85%	Non encore déclenchée (marge suffisante)

Télémétrie Claude Code

L’intégration OTEL permet de suivre les sessions Claude Code : tokens consommés, coût estimé, temps actif. Ces métriques alimentent les dashboards Grafana pour le suivi de productivité.

---

3. Comment ? — Mise en œuvre technique

Configuration Prometheus

prometheus/prometheus.yml

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']

  - job_name: 'node-exporter'
    static_configs:
      - targets: ['node-exporter:9100']

  - job_name: 'cadvisor'
    static_configs:
      - targets: ['cadvisor:8080']

  - job_name: 'otel-collector'
    static_configs:
      - targets: ['otel-collector:8889']

Rétention des données

# Dans docker-compose.yaml, commande Prometheus
command:
  - '--storage.tsdb.retention.time=15d'
  - '--storage.tsdb.retention.size=5GB'

Dimensionnement

15 jours et 5 GB suffisent pour une infrastructure personnelle. Pour des besoins d’historique plus long, considérez Thanos ou Victoria Metrics.

Règles d’alerte

prometheus/alerts.yml

groups:
  - name: infrastructure
    rules:
      - alert: HighMemoryUsage
        expr: (1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100 > 85
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Mémoire haute sur {{ $labels.instance }}"
          description: "Usage mémoire: {{ $value | printf \"%.1f\" }}%"

      - alert: HighCPUUsage
        expr: 100 - (avg(irate(node_cpu_seconds_total{mode="idle"}[5m])) * 100) > 80
        for: 5m
        labels:
          severity: warning

      - alert: DiskSpaceLow
        expr: (1 - (node_filesystem_avail_bytes{fstype!="tmpfs"} / node_filesystem_size_bytes)) * 100 > 85
        for: 5m
        labels:
          severity: critical

      - alert: ContainerDown
        expr: absent(container_last_seen{name!=""})
        for: 1m
        labels:
          severity: critical

      - alert: ServiceDown
        expr: up == 0
        for: 1m
        labels:
          severity: critical

Alertmanager → N8N

alertmanager/alertmanager.yml

global:
  resolve_timeout: 5m

route:
  receiver: 'n8n'
  group_by: ['alertname', 'severity']
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 4h

receivers:
  - name: 'n8n'
    webhook_configs:
      - url: 'http://n8n:5678/webhook/prometheus/alert'
        send_resolved: true

Le Notification Hub analyse la sévérité pour router les alertes : critiques → Telegram immédiat, warnings → regroupés.

Claude Code Metrics (OTEL)

Configuration Claude Code pour exporter la télémétrie :

~/.claude/settings.json

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318",
    "OTEL_SERVICE_NAME": "claude-code"
  }
}

Métrique	Description
claude_code_token_usage_tokens_total	Tokens par modèle et type
claude_code_cost_usage_USD_total	Coût cumulé en USD
claude_code_active_time_seconds_total	Temps actif
claude_code_lines_of_code_count_total	Lignes modifiées

Exemples PromQL

# CPU usage percentage
100 - (avg(irate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)

# Memory usage percentage
(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100

# Disk usage percentage
(1 - (node_filesystem_avail_bytes{fstype!="tmpfs"} / node_filesystem_size_bytes)) * 100

# Container memory usage (top 5)
topk(5, container_memory_usage_bytes{name!=""})

# Claude Code tokens total by model
sum(claude_code_token_usage_tokens_total) by (model)

# Claude Code cost USD
sum(claude_code_cost_usage_USD_total)

Dashboards Grafana

Dashboard	Métriques
Linux System	CPU, RAM, disque, réseau, load average
Docker Containers	CPU/RAM par conteneur, I/O, restarts
Claude Code	Tokens, coûts, temps actif, lignes de code

---

4. Et si ? — Perspectives et limites

Problème connu : cAdvisor + Docker 29+

Incompatibilité

cAdvisor ne fonctionne pas correctement avec Docker 29+ sur Debian avec overlayfs. Les métriques container_* peuvent être absentes.

Symptômes :

• Aucune métrique container_* dans Prometheus
• Erreurs Failed to identify the read-write layer ID dans les logs
• Dashboard “Docker Containers” vide

Workaround : Utiliser docker-exporter ou une version spécifique de cAdvisor compatible.

Limites actuelles

Limite	Impact	Mitigation
Rétention 15 jours	Pas d’historique long terme	Exporter vers S3/Thanos si besoin
Pas de tracing	Debugging workflows limité	Considérer Jaeger si besoin
OTEL Collector single	SPOF pour la télémétrie	Acceptable pour usage personnel

Scénarios d’évolution

Si besoin d’historique > 15 jours :

• Déployer Thanos pour le stockage long terme
• Ou exporter des snapshots vers S3

Si besoin de tracer les workflows N8N :

• Ajouter Jaeger ou Tempo
• Instrumenter N8N avec OTEL traces

Si le volume de métriques explose :

• Augmenter la rétention de Prometheus
• Considérer Victoria Metrics (plus performant)

Commandes de dépannage

# Vérifier les targets Prometheus
curl http://localhost:9090/api/v1/targets | jq '.data.activeTargets[] | {job: .labels.job, health: .health}'

# Tester la connectivité exporter
docker exec prometheus wget -qO- http://node-exporter:9100/metrics | head

# Vérifier les alertes actives
curl http://localhost:9093/api/v1/alerts

# Tester le webhook N8N
curl -X POST http://n8n:5678/webhook/prometheus/alert \
  -H "Content-Type: application/json" \
  -d '{"alerts":[{"labels":{"alertname":"test"}}]}'

---

Pages liées

Infrastructure

• Architecture VPS — Vue d’ensemble
• Security Stack — Caddy expose Grafana

Workflows

• Notification Hub — Routage des alertes

Référence

• Glossaire — Prometheus, PromQL, OTEL, Scrape