Logging estructurado con JSONL
Una guía completa de logging estructurado en formato JSONL (JSON Lines). Aprende a integrarlo con ELK Stack, Fluentd, CloudWatch, GCP Logging y Azure Monitor, con ejemplos de código listos para producción.
¿Por qué usar JSONL para el logging estructurado?
Los logs tradicionales en texto plano son fáciles de leer para una persona, pero resulta casi imposible analizarlos de forma fiable con herramientas automáticas. Una línea como '2024-01-15 ERROR User login failed for admin' mezcla la gravedad, el tipo de evento y el nombre de usuario en una cadena sin estructura. Las herramientas de agregación de logs tienen que recurrir a expresiones regulares frágiles para interpretar el contenido, y cualquier cambio en el formato del log rompe el pipeline.
El logging estructurado resuelve este problema generando cada entrada de log como un objeto JSON con campos bien definidos. JSONL (JSON Lines) va un paso más allá: un objeto JSON por línea, sin un array que los contenga ni comas al final. Así, es fácil añadir entradas a los logs JSONL, procesarlos en streaming y analizarlos con cualquiera de las principales plataformas de logs. En esta guía aprenderás a generar logs JSONL en Python, Node.js y Go, y a enviarlos a ELK, Fluentd y los tres principales proveedores de servicios en la nube.
Frente a otros formatos estructurados, como CSV o XML, JSONL ofrece el mejor equilibrio entre flexibilidad, compatibilidad con herramientas y facilidad de lectura. Permite anidar campos, conserva los tipos de datos y no te obliga a definir un esquema fijo de antemano. Por eso se ha convertido en el estándar de facto del logging estructurado en las infraestructuras modernas.
Bibliotecas de logging por lenguaje
La mayoría de las bibliotecas de logging modernas permiten generar JSON estructurado de forma nativa o con un sencillo cambio de configuración. Estas son las bibliotecas recomendadas para Python, Node.js y Go; todas generan una salida compatible con JSONL.
Python: structlog
Recomendadostructlog es la biblioteca de referencia para el logging estructurado en Python. Se apoya en el módulo estándar logging y genera JSON por defecto. Su pipeline de procesadores te permite enriquecer, filtrar y transformar las entradas de log antes de serializarlas.
import structlog
# Configure structlog for JSONL output
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()
# Each call produces one JSONL line
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
El más rápidopino es el logger más rápido de Node.js y genera JSONL por defecto, sin necesidad de configuración. Reduce la sobrecarga mediante escritura asíncrona y un proceso de serialización mínimo. El paquete complementario pino-pretty ofrece una salida fácil de leer durante el desarrollo local.
import pino from 'pino';
// pino outputs JSONL by default
const log = pino({
level: 'info',
timestamp: pino.stdTimeFunctions.isoTime,
});
// Each call produces one JSONL line
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"}
// Child loggers inherit context
const reqLog = log.child({ requestId: 'req-abc-123' });
reqLog.info({ path: '/api/users' }, 'request.start');Go: zerolog
Sin asignaciones de memoriazerolog es un logger JSON para Go que no realiza asignaciones de memoria, diseñado para ofrecer el máximo rendimiento en servicios que procesan grandes volúmenes de datos. Escribe directamente en un io.Writer sin asignaciones intermedias, lo que lo hace ideal para aplicaciones sensibles a la latencia. Su API de llamadas encadenadas es cómoda de usar y eficiente.
package main
import (
"os"
"github.com/rs/zerolog"
"github.com/rs/zerolog/log"
)
func main() {
// Configure JSONL output to stdout
zerolog.TimeFieldFormat = zerolog.TimeFormatUnix
log.Logger = zerolog.New(os.Stdout).With().Timestamp().Logger()
// Each call produces one JSONL line
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")
}Integración con ELK Stack
ELK Stack (Elasticsearch, Logstash, Kibana) es la plataforma de código abierto más utilizada para gestionar logs. Los logs JSONL se integran sin complicaciones porque Logstash y Filebeat analizan JSON de forma nativa, sin necesidad de patrones grok complejos.
Filebeat es una herramienta ligera que lee las nuevas entradas a medida que se añaden a tus archivos de log JSONL y las envía a Logstash o Elasticsearch. Al establecer json.keys_under_root en true, los campos JSON pasan a ser campos de primer nivel en Elasticsearch y puedes buscarlos directamente en 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}"
# Optional: send to Logstash instead
# output.logstash:
# hosts: ["logstash:5044"]Si necesitas transformar o enriquecer los logs antes de indexarlos, coloca Logstash entre Filebeat y Elasticsearch. El códec json analiza automáticamente cada línea JSONL. Usa el filtro mutate para cambiar nombres de campos, añadir etiquetas o eliminar datos sensibles antes de almacenarlos.
# logstash.conf
input {
beats {
port => 5044
codec => json
}
}
filter {
# Parse timestamp from the JSON field
date {
match => ["timestamp", "ISO8601"]
target => "@timestamp"
}
# Add environment tag
mutate {
add_field => { "environment" => "production" }
remove_field => ["agent", "ecs", "host"]
}
# Route by log level
if [level] == "error" or [level] == "fatal" {
mutate { add_tag => ["alert"] }
}
}
output {
elasticsearch {
hosts => ["http://elasticsearch:9200"]
index => "app-logs-%{+YYYY.MM.dd}"
}
}Fluentd y Fluent Bit
Fluentd y su alternativa más ligera, Fluent Bit, son proyectos que han alcanzado el nivel de graduados en la CNCF y se utilizan ampliamente en entornos Kubernetes. Ambos admiten logs JSONL de forma nativa y pueden enviarlos a prácticamente cualquier destino, desde Elasticsearch o S3 hasta servicios de logs nativos de la nube.
Fluent Bit es el recolector de logs preferido para Kubernetes y los entornos con recursos limitados. Consume aproximadamente 450KB de memoria y puede procesar cientos de miles de registros por segundo. El parser json admite entradas JSONL sin necesidad de configuración personalizada.
[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 cuenta con un ecosistema de plugins más amplio que Fluent Bit, con más de 500 plugins de la comunidad. Úsalo cuando necesites enrutamiento avanzado, almacenamiento en búfer o transformaciones. El plugin in_tail con formato json lee archivos JSONL de forma nativa.
# 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>Plataformas de logging en la nube
Los tres principales proveedores de servicios en la nube aceptan logs en formato JSONL y convierten automáticamente los campos JSON en atributos que puedes buscar y filtrar. Así dispones de las mismas posibilidades de consulta estructurada sin tener que mantener tu propia infraestructura de logs.
AWS CloudWatch Logs
AWSCloudWatch Logs analiza automáticamente las entradas de log JSON y permite consultar todos sus campos con CloudWatch Logs Insights. Si tu aplicación se ejecuta en ECS, Lambda o EC2 con el agente de CloudWatch, la salida JSONL se indexa como datos estructurados sin configuración adicional. Usa la sintaxis similar a SQL de Logs Insights para consultar millones de entradas de log en segundos.
# CloudWatch Logs Insights query examples
# Find all errors in the last hour
fields @timestamp, level, event, user_id
| filter level = "error"
| sort @timestamp desc
| limit 100
# Aggregate error counts by event type
fields event
| filter level = "error"
| stats count(*) as error_count by event
| sort error_count desc
# P99 latency by 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 (antes Stackdriver) ofrece soporte nativo completo para tratar los datos JSON como entradas de log estructuradas. Cuando escribes JSONL en stdout en Cloud Run, GKE o Cloud Functions, el agente de logging convierte cada línea en un LogEntry estructurado. El campo severity se corresponde directamente con los niveles de gravedad de Cloud Logging, y los campos de jsonPayload se indexan para que puedas realizar búsquedas sobre ellos.
# Python example for Cloud Run / Cloud Functions
import json
import sys
def log(severity: str, message: str, **fields):
"""Write a JSONL log entry compatible with GCP Cloud Logging."""
entry = {
"severity": severity.upper(), # Maps to Cloud Logging severity
"message": message,
**fields,
}
print(json.dumps(entry), file=sys.stdout, flush=True)
# GCP automatically parses these as structured logs
log("INFO", "user.login", user_id="u-42", ip="10.0.0.1")
log("ERROR", "db.timeout", host="db-primary", latency_ms=5200)
# Query in Cloud Logging:
# jsonPayload.user_id = "u-42"
# severity >= ERRORAzure Monitor Logs
AzureAzure Monitor recibe logs JSONL a través de Azure Monitor Agent o directamente mediante su API. Application Insights analiza automáticamente las trazas JSON y los eventos personalizados. KQL (Kusto Query Language) permite realizar consultas avanzadas sobre los datos de logs estructurados, con funciones de agregación, análisis de series temporales y detección de anomalías.
// KQL queries for JSONL logs in Azure Monitor
// Find recent errors
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
// Error rate over time (5-minute buckets)
AppTraces
| where SeverityLevel >= 3
| summarize ErrorCount = count() by bin(TimeGenerated, 5m)
| render timechart
// Top error events
AppTraces
| where SeverityLevel >= 3
| extend parsed = parse_json(Message)
| summarize Count = count() by tostring(parsed.event)
| top 10 by CountBuenas prácticas de logging con JSONL
Aplicar las mismas convenciones en todos tus servicios facilita las consultas sobre los logs JSONL, la correlación de entradas y la configuración de alertas. Estas buenas prácticas proceden de sistemas en producción que procesan miles de millones de entradas de log al día.
Usa niveles de log consistentes
Adopta una escala de gravedad estándar y aplícala de forma uniforme en todos los servicios. La convención más habitual utiliza cinco niveles: DEBUG para el diagnóstico durante el desarrollo, INFO para el funcionamiento normal, WARN para problemas recuperables, ERROR para fallos que requieren atención y FATAL para fallos irrecuperables. Durante la ingesta, convierte los niveles numéricos (como la escala 10-60 de pino) a estos nombres de texto para poder realizar consultas uniformes.
{"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"}Estandariza los nombres de los campos
Define un esquema compartido para los campos comunes a todos los servicios. Usa snake_case para los nombres de los campos, ISO 8601 para las marcas de tiempo y un criterio uniforme para nombrar los identificadores de correlación. Cada entrada de log debe incluir, como mínimo, timestamp, level, event (un nombre de evento que las herramientas puedan interpretar) y service. Las entradas asociadas a una petición deben incluir request_id y user_id para facilitar su seguimiento.
// Recommended field schema
{
"timestamp": "2026-02-15T08:30:00.000Z", // ISO 8601, always UTC
"level": "info", // debug|info|warn|error|fatal
"event": "order.created", // dot-notation event name
"service": "order-api", // emitting service
"version": "1.4.2", // service version
"request_id": "req-abc-123", // correlation ID
"trace_id": "4bf92f3577b34da6", // distributed trace ID
"user_id": "u-42", // authenticated user
"duration_ms": 120, // numeric, not string
"order_id": "ord-789", // domain-specific context
"items_count": 3 // domain-specific context
}Consideraciones de rendimiento
El logging estructurado añade un coste de serialización a cada llamada al logger. En servicios que procesan grandes volúmenes de datos, este coste puede ser considerable. Usa logging asíncrono (pino, zerolog) para sacar la serialización de la ruta crítica de ejecución. Evita registrar objetos grandes o cuerpos de peticiones y respuestas en el nivel INFO. Aplica muestreo cuando se genere un gran volumen de logs de depuración. Escribe en archivos locales y deja que un sidecar (Filebeat, Fluent Bit) se encargue del envío, en lugar de enviar los logs por la red de forma síncrona.
Usa loggers asíncronos (pino, zerolog) para no bloquear el hilo principal durante la serialización JSON.
Nunca registres los cuerpos completos de las peticiones o respuestas en el nivel INFO. Usa el nivel DEBUG y actívalo solo para diagnosticar problemas.
Aplica muestreo a los eventos que se generen en grandes volúmenes. Registra 1 de cada 100 peticiones de health-check en lugar de registrarlas todas.
Escribe los logs en archivos locales y envíalos de forma asíncrona con Filebeat o Fluent Bit. Evita las llamadas de red síncronas en el código que genera los logs.
Fija un tamaño máximo por línea de log (por ejemplo, 16KB) para evitar que las entradas demasiado grandes atasquen el pipeline.
Configura la rotación de archivos de log con logrotate o con la función de rotación de la propia biblioteca para evitar que se llene el disco.
Valida tus logs JSONL en línea
Usa nuestras herramientas gratuitas en el navegador para inspeccionar, validar y convertir archivos de log JSONL. No necesitas subir archivos: todo se procesa localmente.
Aprende a transmitir datos JSONL en tiempo real con Node.js, Python, Server-Sent Events y WebSockets. Crea pipelines de streaming para logs, métricas y flujos de datos en directo.
Estrategias para procesar gigabytes de datos JSONL: lectura en streaming, gestión de memoria, división de archivos, compresión y herramientas online.
Valida archivos JSONL línea por línea. Detecta al instante errores de sintaxis, problemas de codificación y fallos de formato.
Da formato a los archivos JSONL con una sangría adecuada para facilitar su lectura, depuración y revisión.
Abre archivos .jsonl y .ndjson en una tabla ágil y con búsqueda, directamente en tu editor. Diseñada para archivos demasiado grandes para recorrerlos a mano y para logs que aún se están escribiendo.