Par Jerry Fan

Logs structurés avec JSONL

Un guide complet pour produire des logs structurés au format JSONL (JSON Lines) et les intégrer à ELK Stack, Fluentd, CloudWatch, GCP Logging et Azure Monitor, avec des exemples de code prêts pour la production.

Pourquoi utiliser JSONL pour vos logs structurés ?

Les logs classiques en texte brut sont lisibles par un humain, mais leur analyse fiable par une machine est presque impossible. Dans une ligne comme '2024-01-15 ERROR User login failed for admin', le niveau de gravité, le type d’événement et le nom d’utilisateur sont noyés dans une chaîne non structurée. Chaque outil d’agrégation de logs doit recourir à des expressions régulières fragiles pour en extraire les informations, et le moindre changement de format casse le pipeline.

La journalisation structurée résout ce problème : chaque entrée de log est un objet JSON aux champs bien définis. JSONL (JSON Lines) va plus loin : un objet JSON par ligne, sans tableau englobant ni virgule finale. Ce format permet d’ajouter facilement des entrées en fin de fichier, de traiter les logs en streaming et de les analyser simplement avec toutes les grandes plateformes de gestion de logs. Dans ce guide, vous apprendrez à produire des logs JSONL en Python, Node.js et Go, puis à les envoyer vers ELK, Fluentd et les trois principaux fournisseurs cloud.

Par rapport à d’autres formats structurés comme CSV ou XML, JSONL offre le meilleur équilibre entre souplesse, prise en charge par les outils et lisibilité. Les champs peuvent être imbriqués, les types sont conservés et vous n’avez pas besoin de définir un schéma fixe à l’avance. C’est pourquoi JSONL est devenu le standard de fait pour les logs structurés dans les infrastructures modernes.

Bibliothèques de logging par langage

La plupart des bibliothèques de logging modernes peuvent produire du JSON structuré, nativement ou après un simple ajustement de configuration. Voici les bibliothèques recommandées pour Python, Node.js et Go. Toutes produisent une sortie compatible avec JSONL.

Python : structlog

Recommandé

structlog est la bibliothèque de référence pour la journalisation structurée en Python. Elle s’appuie sur le module standard logging et produit du JSON par défaut. Son pipeline de processeurs permet d’enrichir, de filtrer et de transformer les entrées de log avant leur sérialisation.

Python : structlog
import structlog


# Configurer structlog pour une sortie JSONL
structlog.configure(
    processors=[
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.add_log_level,
        structlog.processors.StackInfoRenderer(),
        structlog.processors.JSONRenderer(),
    ],
    wrapper_class=structlog.BoundLogger,
    context_class=dict,
    logger_factory=structlog.PrintLoggerFactory(),
)


log = structlog.get_logger()


# Chaque appel produit une ligne JSONL
log.info("user.login", user_id="u-42", ip="10.0.0.1")
# {"event":"user.login","user_id":"u-42","ip":"10.0.0.1","level":"info","timestamp":"2026-02-15T08:30:00Z"}


log.error("db.connection_failed", host="db-primary", retries=3)
# {"event":"db.connection_failed","host":"db-primary","retries":3,"level":"error","timestamp":"2026-02-15T08:30:01Z"}

Node.js : pino

Le plus rapide

pino est le logger Node.js le plus rapide. Il produit du JSONL par défaut, sans aucune configuration. L’écriture asynchrone et un traitement minimal lors de la sérialisation limitent son surcoût. Le package complémentaire pino-pretty fournit une sortie facile à lire pour le développement local.

Node.js : pino
import pino from 'pino';


// pino produit du JSONL par defaut
const log = pino({
  level: 'info',
  timestamp: pino.stdTimeFunctions.isoTime,
});


// Chaque appel produit une ligne JSONL
log.info({ userId: 'u-42', ip: '10.0.0.1' }, 'user.login');
// {"level":30,"time":"2026-02-15T08:30:00.000Z","userId":"u-42","ip":"10.0.0.1","msg":"user.login"}


log.error({ host: 'db-primary', retries: 3 }, 'db.connection_failed');
// {"level":50,"time":"2026-02-15T08:30:01.000Z","host":"db-primary","retries":3,"msg":"db.connection_failed"}


// Les loggers enfants heritent du contexte
const reqLog = log.child({ requestId: 'req-abc-123' });
reqLog.info({ path: '/api/users' }, 'request.start');

Go : zerolog

Zéro allocation

zerolog est un logger JSON pour Go qui fonctionne sans allocation mémoire, conçu pour maximiser les performances des services à haut débit. Il écrit directement dans un io.Writer, sans allocation intermédiaire, ce qui le rend idéal pour les applications sensibles à la latence. Son API à appels chaînés est à la fois ergonomique et efficace.

Go : zerolog
package main


import (
    "os"
    "github.com/rs/zerolog"
    "github.com/rs/zerolog/log"
)


func main() {
    // Configurer la sortie JSONL vers stdout
    zerolog.TimeFieldFormat = zerolog.TimeFormatUnix
    log.Logger = zerolog.New(os.Stdout).With().Timestamp().Logger()


    // Chaque appel produit une ligne JSONL
    log.Info().
        Str("user_id", "u-42").
        Str("ip", "10.0.0.1").
        Msg("user.login")
    // {"level":"info","user_id":"u-42","ip":"10.0.0.1","time":1739608200,"message":"user.login"}


    log.Error().
        Str("host", "db-primary").
        Int("retries", 3).
        Msg("db.connection_failed")
}

Intégration à ELK Stack

ELK Stack (Elasticsearch, Logstash, Kibana) est la plateforme open source de gestion de logs la plus déployée. Les logs JSONL s’y intègrent facilement : Logstash et Filebeat savent analyser le JSON nativement, ce qui évite d’avoir à définir des motifs grok complexes.

Filebeat est un agent léger qui suit les nouvelles lignes de vos fichiers de logs JSONL et les transmet à Logstash ou Elasticsearch. En définissant json.keys_under_root à true, vous placez les champs JSON à la racine du document Elasticsearch, ce qui permet de les rechercher directement dans Kibana.

Configuration de Filebeat
# filebeat.yml
filebeat.inputs:
  - type: log
    enabled: true
    paths:
      - /var/log/app/*.jsonl
    json.keys_under_root: true
    json.add_error_key: true
    json.message_key: message
    json.overwrite_keys: true


output.elasticsearch:
  hosts: ["http://elasticsearch:9200"]
  index: "app-logs-%{+yyyy.MM.dd}"


# Optionnel : envoyer vers Logstash a la place
# output.logstash:
#   hosts: ["logstash:5044"]

Si vous devez transformer ou enrichir les logs avant leur indexation, intercalez Logstash entre Filebeat et Elasticsearch. Le codec json analyse automatiquement chaque ligne JSONL. Utilisez le filtre mutate pour renommer les champs, ajouter des tags ou supprimer les données sensibles avant le stockage.

Pipeline Logstash
# logstash.conf
input {
  beats {
    port => 5044
    codec => json
  }
}


filter {
  # Analyser l'horodatage depuis le champ JSON
  date {
    match => ["timestamp", "ISO8601"]
    target => "@timestamp"
  }


  # Ajouter un tag d'environnement
  mutate {
    add_field => { "environment" => "production" }
    remove_field => ["agent", "ecs", "host"]
  }


  # Router par niveau de log
  if [level] == "error" or [level] == "fatal" {
    mutate { add_tag => ["alert"] }
  }
}


output {
  elasticsearch {
    hosts => ["http://elasticsearch:9200"]
    index => "app-logs-%{+YYYY.MM.dd}"
  }
}

Fluentd et Fluent Bit

Fluentd et sa variante légère Fluent Bit sont des projets au statut « graduated » de la CNCF, largement utilisés dans les environnements Kubernetes. Tous deux prennent en charge les logs JSONL nativement et peuvent les transmettre à presque n’importe quelle destination : Elasticsearch, S3 ou encore les services de logs natifs du cloud.

Fluent Bit est le collecteur de logs de prédilection pour Kubernetes et les environnements aux ressources limitées. Il consomme environ 450 Ko de mémoire et peut traiter des centaines de milliers d’enregistrements par seconde. Le parseur json prend en charge les données JSONL en entrée sans configuration particulière.

Configuration de Fluent Bit
[SERVICE]
    Flush        5
    Daemon       Off
    Log_Level    info
    Parsers_File parsers.conf


[INPUT]
    Name         tail
    Path         /var/log/app/*.jsonl
    Parser       json
    Tag          app.*
    Refresh_Interval 5


[FILTER]
    Name         modify
    Match        app.*
    Add          cluster production-us-east-1
    Add          service my-api


[OUTPUT]
    Name         es
    Match        app.*
    Host         elasticsearch
    Port         9200
    Index        app-logs
    Type         _doc
    Logstash_Format On

Fluentd dispose d’un écosystème de plugins plus riche que Fluent Bit, avec plus de 500 plugins communautaires. Utilisez-le pour des besoins avancés de routage, de mise en mémoire tampon ou de transformation. Le plugin in_tail, avec format json, lit nativement les fichiers JSONL.

Configuration de Fluentd
# fluentd.conf
<source>
  @type tail
  path /var/log/app/*.jsonl
  pos_file /var/log/fluentd/app.pos
  tag app.logs
  <parse>
    @type json
    time_key timestamp
    time_format %Y-%m-%dT%H:%M:%S%z
  </parse>
</source>


<filter app.logs>
  @type record_transformer
  <record>
    hostname "#{Socket.gethostname}"
    environment production
  </record>
</filter>


<match app.logs>
  @type elasticsearch
  host elasticsearch
  port 9200
  index_name app-logs
  logstash_format true
  <buffer>
    @type memory
    flush_interval 5s
    chunk_limit_size 5m
  </buffer>
</match>

Plateformes de gestion de logs dans le cloud

Les trois principaux fournisseurs cloud acceptent les logs au format JSONL et en extraient automatiquement les champs JSON pour permettre la recherche et le filtrage. Vous conservez ainsi les mêmes possibilités de requêtes sur les données structurées, sans avoir à exploiter votre propre infrastructure de logs.

AWS CloudWatch Logs

AWS

CloudWatch Logs analyse automatiquement les entrées de log JSON et permet d’interroger chaque champ avec CloudWatch Logs Insights. Si votre application s’exécute sur ECS, Lambda ou EC2 avec l’agent CloudWatch, la sortie JSONL est indexée sous forme de données structurées sans configuration supplémentaire. La syntaxe de Logs Insights, proche de SQL, permet d’interroger des millions d’entrées de log en quelques secondes.

AWS CloudWatch Logs
# Exemples de requetes CloudWatch Logs Insights
# Trouver toutes les erreurs de la derniere heure
fields @timestamp, level, event, user_id
| filter level = "error"
| sort @timestamp desc
| limit 100


# Agreger les comptes d'erreurs par type d'evenement
fields event
| filter level = "error"
| stats count(*) as error_count by event
| sort error_count desc


# Latence P99 par endpoint
fields path, duration_ms
| filter ispresent(duration_ms)
| stats pct(duration_ms, 99) as p99 by path
| sort p99 desc

GCP Cloud Logging

GCP

Google Cloud Logging (anciennement Stackdriver) prend nativement en charge les données JSON sous forme d’entrées de log structurées. Lorsque vous écrivez du JSONL sur stdout dans Cloud Run, GKE ou Cloud Functions, l’agent de collecte convertit chaque ligne en un objet LogEntry structuré. Le champ severity correspond directement aux niveaux de gravité de Cloud Logging, et les champs de jsonPayload sont indexés et peuvent faire l’objet de recherches.

GCP Cloud Logging
# Exemple Python pour Cloud Run / Cloud Functions
import json
import sys


def log(severity: str, message: str, **fields):
    """Ecrire une entree de journal JSONL compatible avec GCP Cloud Logging."""
    entry = {
        "severity": severity.upper(),  # Correspond a la severite Cloud Logging
        "message": message,
        **fields,
    }
    print(json.dumps(entry), file=sys.stdout, flush=True)


# GCP analyse automatiquement ces journaux comme structures
log("INFO", "user.login", user_id="u-42", ip="10.0.0.1")
log("ERROR", "db.timeout", host="db-primary", latency_ms=5200)


# Requete dans Cloud Logging :
# jsonPayload.user_id = "u-42"
# severity >= ERROR

Azure Monitor Logs

Azure

Azure Monitor ingère les logs JSONL via Azure Monitor Agent ou directement par API. Application Insights analyse automatiquement les traces JSON et les événements personnalisés. KQL (Kusto Query Language) permet d’exécuter des requêtes puissantes sur les logs structurés, avec des fonctions d’agrégation, d’analyse de séries temporelles et de détection d’anomalies.

Azure Monitor Logs
// Requetes KQL pour les journaux JSONL dans Azure Monitor
// Trouver les erreurs recentes
AppTraces
| where SeverityLevel >= 3
| extend parsed = parse_json(Message)
| project TimeGenerated, parsed.event, parsed.user_id,
          parsed.error_message
| order by TimeGenerated desc
| take 100


// Taux d'erreur dans le temps (intervalles de 5 minutes)
AppTraces
| where SeverityLevel >= 3
| summarize ErrorCount = count() by bin(TimeGenerated, 5m)
| render timechart


// Top des evenements d'erreur
AppTraces
| where SeverityLevel >= 3
| extend parsed = parse_json(Message)
| summarize Count = count() by tostring(parsed.event)
| top 10 by Count

Bonnes pratiques pour les logs JSONL

Des conventions communes à tous vos services facilitent les requêtes sur les logs JSONL, leur corrélation et la création d’alertes. Ces bonnes pratiques sont issues de systèmes en production qui traitent des milliards d’entrées de log par jour.

Utilisez des niveaux de log cohérents

Adoptez une échelle de gravité standard et appliquez-la de manière cohérente à tous vos services. La convention la plus courante comporte cinq niveaux : DEBUG pour les diagnostics pendant le développement, INFO pour le fonctionnement normal, WARN pour les problèmes dont le système peut se remettre, ERROR pour les échecs qui nécessitent une intervention et FATAL pour les plantages irrécupérables. À l’ingestion, convertissez les niveaux numériques (comme l’échelle 10-60 de pino) en ces libellés textuels afin d’uniformiser les requêtes.

Utilisez des niveaux de log cohérents
{"level":"debug","event":"cache.miss","key":"user:42","timestamp":"2026-02-15T08:30:00Z"}
{"level":"info","event":"request.completed","method":"GET","path":"/api/users","status":200,"duration_ms":45,"timestamp":"2026-02-15T08:30:01Z"}
{"level":"warn","event":"rate_limit.approaching","client_id":"c-99","current":950,"limit":1000,"timestamp":"2026-02-15T08:30:02Z"}
{"level":"error","event":"payment.failed","order_id":"ord-123","error":"card_declined","timestamp":"2026-02-15T08:30:03Z"}
{"level":"fatal","event":"startup.failed","reason":"missing DATABASE_URL","timestamp":"2026-02-15T08:30:04Z"}

Uniformisez les noms de champs

Définissez un schéma commun pour les champs partagés par tous les services. Utilisez snake_case pour les noms de champs, ISO 8601 pour les horodatages et une convention de nommage cohérente pour les identifiants de corrélation. Chaque entrée de log doit contenir au minimum timestamp, level, event (un nom d’événement exploitable par une machine) et service. Les entrées associées à une requête doivent inclure request_id et user_id pour permettre le traçage.

Uniformisez les noms de champs
// Schema de champs recommande
{
  "timestamp": "2026-02-15T08:30:00.000Z",  // ISO 8601, toujours UTC
  "level": "info",                            // debug|info|warn|error|fatal
  "event": "order.created",                    // nom d'evenement en notation pointee
  "service": "order-api",                      // service emetteur
  "version": "1.4.2",                          // version du service
  "request_id": "req-abc-123",                 // ID de correlation
  "trace_id": "4bf92f3577b34da6",              // ID de trace distribuee
  "user_id": "u-42",                           // utilisateur authentifie
  "duration_ms": 120,                          // numerique, pas chaine
  "order_id": "ord-789",                       // contexte specifique au domaine
  "items_count": 3                             // contexte specifique au domaine
}

Performances : les points à surveiller

La journalisation structurée ajoute un coût de sérialisation à chaque appel au logger. Ce surcoût peut devenir important dans les services à haut débit. Utilisez des loggers asynchrones (pino, zerolog) pour sortir la sérialisation du chemin critique. Évitez de consigner de gros objets ou le corps des requêtes et des réponses au niveau INFO. Échantillonnez les logs de débogage volumineux. Écrivez dans des fichiers locaux et confiez l’expédition à un sidecar (Filebeat, Fluent Bit), plutôt que d’envoyer les logs sur le réseau de manière synchrone.

Utilisez des loggers asynchrones (pino, zerolog) pour éviter de bloquer le thread principal pendant la sérialisation JSON.

Ne consignez jamais le corps complet des requêtes ou des réponses au niveau INFO. Utilisez le niveau DEBUG et ne l’activez que pour diagnostiquer un problème.

Échantillonnez les événements très fréquents. Consignez 1 requête de health-check sur 100 plutôt que de toutes les enregistrer.

Écrivez les logs dans des fichiers locaux et transmettez-les de manière asynchrone avec Filebeat ou Fluent Bit. Évitez les appels réseau synchrones lors de l’écriture des logs.

Fixez une taille maximale par ligne de log (par exemple 16 Ko) pour éviter que des entrées trop volumineuses n’engorgent le pipeline.

Mettez en place une rotation des fichiers de logs avec logrotate ou les mécanismes intégrés à la bibliothèque pour éviter de saturer le disque.

Inspectez vos logs JSONL dans votre navigateur

Visualisez vos fichiers de logs JSONL jusqu’à 1 Go, effectuez des recherches et validez leur contenu. Chargement instantané, traitement côté client, confidentialité à 100%.

Questions fréquentes

Références