Pourquoi les logs structurés

Ton application écrit des messages quelque part. La vraie question : sous quelle forme — pour que tu puisses les retrouver à 3h du matin.

Toute application produit des logs. La vraie question n'est pas si tu loggues, mais comment — et ce choix détermine si tu peux investiguer rapidement ou si tu passes des heures à grep des fichiers cryptiques.

[2024-01-15 14:32:07] INFO: User 42 logged in from 192.168.1.5
[2024-01-15 14:32:08] ERROR: Payment failed for order 1234 - timeout after 5000ms
[2024-01-15 14:32:09] WARN: Retry 2/3 for order 1234

{
  "ts": "2024-01-15T14:32:08Z",
  "level": "error",
  "msg": "Payment failed",
  "order_id": 1234,
  "reason": "timeout",
  "duration_ms": 5000,
  "trace_id": "abc123ef456"
}

Loki dans la stack LGTM

Loki est la brique de stockage et d'interrogation des logs dans la stack Grafana LGTM (Loki · Grafana · Tempo · Mimir). Elle est conçue pour être économique : contrairement à Elasticsearch qui indexe chaque mot de chaque log, Loki n'indexe que les labels — des métadonnées légères que tu définis — et stocke les lignes de log compressées sans les indexer.

Le simulateur ci-dessous montre le même événement dans les deux formats en temps réel. Observe ce qu'il est possible d'extraire de chacun.

Anatomie d'un log structuré

Un log structuré n'est qu'un objet JSON — mais chaque champ a un rôle précis, et Loki ne les traite pas tous de la même façon.

Un log structuré ressemble à n'importe quel objet JSON — mais les champs qu'il contient ne sont pas équivalents. Certains sont obligatoires, d'autres contextuels. Et Loki, en particulier, distingue deux catégories : ce qu'il indexe (les labels) et ce qu'il stocke (le reste de la ligne).

Labels Loki vs contenu de log

Loki fait une distinction fondamentale entre les champs d'un log :

Clique sur chaque champ du log ci-dessous pour comprendre son rôle et si Loki l'indexe.

Loki et son modèle de données

Loki stocke les logs comme Prometheus stocke les métriques : par labels. Ce qui est indexé, c'est uniquement les labels — pas le contenu des lignes.

Le modèle de données de Loki est directement inspiré de Prometheus. Là où Prometheus stocke des séries temporelles identifiées par un ensemble de labels, Loki stocke des streams de logs identifiés de la même façon.

http_requests_total{
  app="api",
  env="prod",
  method="POST"
} → valeurs numériques

{
  app="api",
  env="prod",
  level="error"
} → lignes de texte

La cardinalité des labels — même règle que Prometheus

Si tu as 3 valeurs pour app, 2 pour env et 4 pour level, tu as 3 × 2 × 4 = 24 streams. C'est parfaitement gérable. Mais si tu ajoutes user_id avec 50 000 utilisateurs distincts, tu passes à 24 × 50 000 = 1 200 000 streams — et Loki s'effondre sous la pression mémoire.

Le simulateur ci-dessous te montre comment le nombre de streams explose quand tu ajoutes des labels à haute cardinalité. Clique sur les labels pour les activer ou désactiver.

Collecter avec Promtail & Alloy

Les logs ne tombent pas dans Loki tout seuls. Il faut un agent qui les lise, les transforme, et les envoie.

Les logs de ton application atterrissent dans des fichiers ou dans journald. Pour qu'ils arrivent dans Loki, il faut un agent de collecte qui les lit, les transforme et les envoie. L'agent historique est Promtail ; son successeur dans l'écosystème Grafana est Alloy.

Configuration Promtail

# promtail.yml
clients:
  - url: http://loki:3100/loki/api/v1/push

scrape_configs:
  - job_name: app-logs
    static_configs:
      - targets: [localhost]
        labels:
          app: my-api           # label Loki statique
          env: production
          __path__: /var/log/app/*.log

    pipeline_stages:
      - json:                   # parse le JSON de chaque ligne
          expressions:
            level: level
            ts: ts
      - labels:                 # transforme en labels Loki
          level:
      - timestamp:              # parse le timestamp
          source: ts
          format: RFC3339
      - output:                 # définit la ligne finale stockée
          source: msg

Les pipeline stages — dans l'ordre

Le simulateur ci-dessous montre une ligne de log brute traverser chaque stage de la pipeline. Clique sur "Étape suivante" pour avancer.

LogQL — requêter les logs

LogQL est au log ce que PromQL est aux métriques : un langage de requête en deux modes.

LogQL est le langage de requête de Loki. Il fonctionne en deux modes : le log query qui retourne des lignes de log correspondant à un filtre, et le metric query qui transforme ces lignes en une série temporelle de nombres.

# Sélectionner des streams
{app="api", env="prod"}

# Filtrer sur le contenu
{app="api"} |= "error"

# Parser et filtrer sur les champs
{app="api"}
  | json
  | level = "error"
  | duration_ms > 1000

# Taux de lignes par seconde
rate({app="api"}[5m])

# Taux d'erreurs uniquement
rate({app="api"}
  |= "error" [5m])

# P95 latence depuis les logs
quantile_over_time(0.95,
  {app="api"}
  | json
  | unwrap duration_ms [5m])

La syntaxe d'un log query

Un log query LogQL se lit de gauche à droite comme un pipeline de filtres :

{app="api", env="prod"}   # 1. sélecteur de stream (obligatoire)
  | json                   # 2. parser : extrait les champs JSON
  | level = "error"       # 3. filtre sur un champ extrait
  | duration_ms > 500     # 4. filtre numérique
  | line_format "{{.msg}} ({{.duration_ms}}ms)" # 5. reformater la ligne

Le simulateur ci-dessous montre un flux de logs en temps réel. Active ou désactive les filtres pour voir quelles lignes passent.

Corrélation logs · métriques · traces

Un log sans contexte est une piste. Un log avec trace_id est une investigation complète.

Les logs, métriques et traces ont chacun leur rôle dans un scénario d'investigation. La vraie puissance vient quand on peut naviguer de l'un à l'autre sans friction — et c'est précisément ce que permet une stack LGTM bien configurée.

Labels communs — le pivot métriques ↔ logs

Si tes métriques Prometheus et tes logs Loki utilisent les mêmes labels (service, env, instance), Grafana peut superposer automatiquement des annotations de logs sur tes graphes de métriques — tu vois exactement quel log correspond à un pic d'erreurs.

Injecter trace_id dans tes logs PHP

// Symfony — avec OpenTelemetry SDK ou Monolog Processor
class TraceIdProcessor
{
    public function __invoke(array $record): array
    {
        $span = OpenTelemetry\API\Globals::tracerProvider()
            ->getTracer('app')
            ->injectContext();

        $record['extra']['trace_id'] = $span->getContext()->getTraceId();
        $record['extra']['span_id']  = $span->getContext()->getSpanId();

        return $record;
    }
}

Le simulateur ci-dessous montre un flux de logs applicatifs. Clique sur une ligne d'erreur pour suivre son trace_id jusqu'à la trace distribuée.

Synthèse — logs en production

Structurer, collecter, indexer, requêter, corréler — les cinq étapes d'une stack de logs robuste.

On a parcouru les cinq étapes d'une stack de logs moderne. Voici comment elles s'articulent en production.

Logs vs métriques — quand utiliser quoi

Les pièges classiques

Récap des composants