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.
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 rapidepino 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.
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 allocationzerolog 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.
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.
# 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.
# 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.
[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 OnFluentd 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.
# 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
AWSCloudWatch 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.
# 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 descGCP Cloud Logging
GCPGoogle 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.
# 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 >= ERRORAzure Monitor Logs
AzureAzure 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.
// 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 CountBonnes 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.
{"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.
// 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.
Validez vos logs JSONL en ligne
Utilisez nos outils gratuits dans votre navigateur pour inspecter, valider et convertir vos fichiers de logs JSONL. Aucun envoi de fichier n’est nécessaire : tout le traitement s’effectue localement.
Apprenez à streamer des données JSONL en Node.js et Python. Couvre SSE, WebSockets et le traitement de logs en temps réel.
Les stratégies pour traiter des gigaoctets de données JSONL : lecture en streaming, gestion de la mémoire, découpage des fichiers, compression et outils en ligne.
Validez vos fichiers JSONL ligne par ligne. Repérez immédiatement les erreurs de syntaxe et les problèmes d’encodage ou de format.
Mettez en forme vos fichiers JSONL avec une indentation adaptée pour les rendre plus lisibles et faciliter le débogage et la revue des données.
Ouvrez vos fichiers .jsonl et .ndjson dans un tableau fluide avec fonction de recherche, directement dans votre éditeur. L'extension est conçue pour les fichiers trop volumineux pour être parcourus par défilement et les logs en cours d'écriture.