Por Jerry Fan

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

Recomendado

structlog 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.

Python: structlog
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ápido

pino 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.

Node.js: pino
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 memoria

zerolog 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.

Go: zerolog
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.

Configuración 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}"


# 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.

Pipeline de Logstash
# 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.

Configuración 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 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.

Configuración 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>

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

AWS

CloudWatch 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.

AWS CloudWatch Logs
# 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 desc

GCP Cloud Logging

GCP

Google 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.

GCP Cloud Logging
# 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 >= ERROR

Azure Monitor Logs

Azure

Azure 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.

Azure Monitor Logs
// 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 Count

Buenas 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.

Usa niveles de log consistentes
{"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.

Estandariza los nombres de los campos
// 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.

Inspecciona logs JSONL en tu navegador

Visualiza, busca y valida archivos de log JSONL de hasta 1GB. Carga instantánea, procesamiento en el navegador y privacidad del 100%.

Preguntas frecuentes

Referencias