Écrire et nommer ses recording rules

3. Écrire ses premières règles #

La syntaxe, un exemple complet et les options du groupe.

Un fichier de règles #

Déclarez le fichier dans prometheus.yml, puis écrivez les règles. Ces exemples portent sur les métriques de Prometheus lui-même, pour pouvoir les essayer immédiatement :

global:
  scrape_interval: 5s
  evaluation_interval: 15s

rule_files:
  - /etc/prometheus/rules.yml

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

groups:
  - name: http_prometheus
    rules:
      - record: job_handler:prometheus_http_requests:rate5m
        expr: sum by (job, handler) (rate(prometheus_http_requests_total[5m]))

      - record: job:prometheus_http_requests:rate5m
        expr: sum by (job) (job_handler:prometheus_http_requests:rate5m)

      - record: job:prometheus_http_requests_errors:rate5m
        expr: sum by (job) (rate(prometheus_http_requests_total{code=~"5.."}[5m]))

      - record: job:prometheus_http_requests_errors:ratio_rate5m
        expr: |
          (job:prometheus_http_requests_errors:rate5m or job:prometheus_http_requests:rate5m * 0)
            / job:prometheus_http_requests:rate5m

      - record: job:prometheus_http_request_duration_seconds:p95_rate5m
        expr: |
          histogram_quantile(0.95,
            sum by (job, le) (rate(prometheus_http_request_duration_seconds_bucket[5m])))

Dans Grafana, la requête devient très simple :

# Avant : recalculé à chaque actualisation de chaque panneau
sum by (job) (rate(http_requests_total[5m]))

# Après : simple lecture de la série enregistrée
job:http_requests:rate5m

Les options d'un groupe #

groups:
  - name: agregats_http
    interval: 30s        # sinon : evaluation_interval du fichier global
    query_offset: 30s    # évalue un peu dans le passé, si les données arrivent en retard
    limit: 1000          # échec de la règle si elle produit plus de 1000 séries
    labels:
      equipe: plateforme # ajouté à toutes les règles du groupe
    rules:
      - record: job:http_requests:rate5m
        expr: sum by (job) (rate(http_requests_total[5m]))

4. Bien nommer ses règles #

La convention niveau:métrique:opérations.

La convention officielle #

La documentation de Prometheus recommande le format niveau:métrique:opérations. Le nom dit ainsi ce que contient la série, sans ouvrir le fichier de règles. Les deux-points sont réservés à cet usage : les exporteurs ne doivent pas en utiliser.

5. Les pièges à éviter #

Ratios, séries absentes, ordre des opérations.

Ne jamais faire la moyenne de ratios #

Un service à 10 requêtes par seconde avec 50 % d'erreurs et un autre à 1000 requêtes par seconde avec 0 % n'ont pas 25 % d'erreurs en moyenne, mais environ 0,5 %. Enregistrez donc le numérateur et le dénominateur, puis divisez leurs sommes :

# Faux : moyenne de ratios, un petit service pèse autant qu'un gros
avg by (job) (instance:http_requests_errors:ratio_rate5m)

# Juste : on agrège le numérateur et le dénominateur séparément
sum by (job) (instance:http_requests_errors:rate5m)
  / sum by (job) (instance:http_requests:rate5m)

Le ratio qui disparaît quand tout va bien #

C'est le piège le plus sournois, constaté en préparant ce chapitre. Si aucune série 5xx n'existe, le filtre ne renvoie rien, et une division par un résultat vide donne un résultat vide, pas 0. Le tableau de bord affiche « No data » : impossible alors de distinguer « aucune erreur » d'une panne de la collecte.

# Vide tant qu'aucune erreur 5xx n'a été observée
job:requests_errors:rate5m / job:requests:rate5m

# Vaut 0 quand il n'y a aucune erreur
(job:requests_errors:rate5m or job:requests:rate5m * 0) / job:requests:rate5m

Les autres erreurs fréquentes #

• rate d'abord, sum ensuite : sum(rate(x[5m])). Additionner des compteurs avant le rate fausse la détection de leurs remises à zéro.
• Histogrammes : gardez l'étiquette le dans le sum by, sinon histogram_quantile ne peut rien calculer.
• Trop d'étiquettes : une règle qui conserve instance ou pod garde presque toute la cardinalité.
• Changer une règle : si l'expression change de sens, changez aussi le nom : sinon l'ancienne et la nouvelle logique se mélangent dans la même série.