Por Jerry Fan

Logging estruturado com JSONL

Um guia completo de logging estruturado no formato JSONL (JSON Lines). Aprenda a integrar seus logs com ELK Stack, Fluentd, CloudWatch, GCP Logging e Azure Monitor, com exemplos de código prontos para produção.

Por que usar JSONL para logging estruturado?

Logs tradicionais em texto puro são fáceis de ler, mas analisá-los de forma confiável por software é quase impossível. Em uma linha como '2024-01-15 ERROR User login failed for admin', a severidade, o tipo de evento e o nome de usuário ficam embutidos em uma string sem estrutura. Para extrair essas informações, as ferramentas de agregação de logs precisam recorrer a expressões regulares frágeis. Qualquer alteração no formato do log quebra o pipeline.

O logging estruturado resolve esse problema ao gerar cada entrada de log como um objeto JSON com campos bem definidos. O JSONL (JSON Lines) vai além: cada linha contém um objeto JSON, sem um array que englobe os objetos e sem vírgulas no final. Assim, é fácil acrescentar novas entradas, transmitir os logs por streaming e processá-los nas principais plataformas de logs. Neste guia, você vai aprender a gerar logs JSONL em Python, Node.js e Go e a enviá-los para ELK, Fluentd e os três principais provedores de nuvem.

Em comparação com outros formatos estruturados, como CSV ou XML, o JSONL oferece o melhor equilíbrio entre flexibilidade, suporte de ferramentas e facilidade de leitura. Os campos podem ser aninhados, os tipos são preservados e você não precisa definir um schema fixo de antemão. Por isso, o JSONL se tornou o padrão de fato para logging estruturado na infraestrutura moderna.

Bibliotecas de logging por linguagem

A maioria das bibliotecas modernas de logging gera JSON estruturado nativamente ou com uma simples alteração na configuração. Veja a seguir as bibliotecas recomendadas para Python, Node.js e Go. Todas geram saída compatível com JSONL.

Python: structlog

Recomendado

O structlog é a principal biblioteca de logging estruturado para Python. Ele encapsula o módulo logging da biblioteca padrão e gera saída em JSON por padrão. Seu pipeline de processadores permite enriquecer, filtrar e transformar as entradas de log antes da serialização.

Python: structlog
import structlog


# Configura structlog para saída 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()


# Cada chamada produz uma linha 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

Mais rápido

O pino é o logger mais rápido para Node.js e gera saída em JSONL por padrão, sem precisar de configuração. Ele mantém baixo o custo adicional de processamento com escrita assíncrona e um processo de serialização enxuto. O pacote complementar pino-pretty formata a saída para facilitar a leitura durante o desenvolvimento local.

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


// pino produz JSONL por padrão
const log = pino({
  level: 'info',
  timestamp: pino.stdTimeFunctions.isoTime,
});


// Cada chamada produz uma linha 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"}


// Loggers filhos herdam o contexto
const reqLog = log.child({ requestId: 'req-abc-123' });
reqLog.info({ path: '/api/users' }, 'request.start');

Go: zerolog

Sem alocações

O zerolog é um logger JSON para Go que não faz alocações de memória, projetado para oferecer o máximo desempenho em serviços com alto volume de processamento. Ele escreve diretamente em um io.Writer, sem alocações intermediárias, o que o torna ideal para aplicações sensíveis à latência. Sua API permite encadear chamadas de forma prática e eficiente.

Go: zerolog
package main


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


func main() {
    // Configura saída JSONL para stdout
    zerolog.TimeFieldFormat = zerolog.TimeFormatUnix
    log.Logger = zerolog.New(os.Stdout).With().Timestamp().Logger()


    // Cada chamada produz uma linha 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")
}

Integração com o ELK Stack

O ELK Stack (Elasticsearch, Logstash, Kibana) é a plataforma de código aberto mais usada para gerenciamento de logs. A integração com logs JSONL é simples: o Logstash e o Filebeat interpretam JSON nativamente, dispensando padrões grok complexos.

O Filebeat é uma ferramenta leve que acompanha as novas entradas nos seus arquivos de log JSONL e as encaminha para o Logstash ou o Elasticsearch. Ao definir json.keys_under_root como true, os campos JSON passam a ser campos de nível superior no Elasticsearch e podem ser pesquisados diretamente no Kibana.

Configuração do 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}"


# Opcional: enviar para Logstash
# output.logstash:
#   hosts: ["logstash:5044"]

Se você precisa transformar ou enriquecer os logs antes da indexação, o Logstash atua entre o Filebeat e o Elasticsearch. O codec json interpreta cada linha JSONL automaticamente. Use o filtro mutate para renomear campos, adicionar tags ou remover dados sensíveis antes do armazenamento.

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


filter {
  # Parseia timestamp do campo JSON
  date {
    match => ["timestamp", "ISO8601"]
    target => "@timestamp"
  }


  # Adiciona tag de ambiente
  mutate {
    add_field => { "environment" => "production" }
    remove_field => ["agent", "ecs", "host"]
  }


  # Roteia por nível 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 e Fluent Bit

O Fluentd e sua alternativa mais leve, o Fluent Bit, são projetos graduados pela CNCF e muito usados em ambientes Kubernetes. Ambos processam logs JSONL nativamente e podem encaminhá-los para praticamente qualquer destino, do Elasticsearch e do S3 a serviços de logs nativos da nuvem.

O Fluent Bit é o coletor de logs preferido para Kubernetes e ambientes com recursos limitados. Ele consome cerca de 450KB de memória e pode processar centenas de milhares de registros por segundo. O parser json processa a entrada em JSONL sem precisar de configuração personalizada.

Configuração do 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

O Fluentd tem um ecossistema de plugins mais amplo que o do Fluent Bit, com mais de 500 plugins da comunidade. Use-o quando precisar de roteamento avançado, buffering ou transformações. O plugin in_tail com format json lê arquivos JSONL nativamente.

Configuração do 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 na nuvem

Os três principais provedores de nuvem aceitam logs em JSONL e interpretam automaticamente os campos JSON, convertendo-os em atributos que podem ser pesquisados e filtrados. Assim, você tem os mesmos recursos de consulta a dados estruturados sem precisar manter sua própria infraestrutura de logs.

AWS CloudWatch Logs

AWS

O CloudWatch Logs interpreta automaticamente as entradas de log em JSON e permite consultar qualquer campo com o CloudWatch Logs Insights. Quando sua aplicação roda no ECS, no Lambda ou no EC2 com o agente do CloudWatch, a saída JSONL é indexada como dados estruturados sem configuração adicional. Use a sintaxe semelhante a SQL do Logs Insights para consultar milhões de entradas de log em segundos.

AWS CloudWatch Logs
# Exemplos de consultas CloudWatch Logs Insights
# Encontrar todos os erros na última hora
fields @timestamp, level, event, user_id
| filter level = "error"
| sort @timestamp desc
| limit 100


# Agregar contagem de erros por tipo de evento
fields event
| filter level = "error"
| stats count(*) as error_count by event
| sort error_count desc


# Latência P99 por 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

O Google Cloud Logging (antigo Stackdriver) oferece suporte nativo a payloads JSON como entradas de log estruturadas. Quando você escreve JSONL em stdout no Cloud Run, no GKE ou no Cloud Functions, o agente de logging interpreta cada linha e a converte em um LogEntry estruturado. O campo severity corresponde diretamente aos níveis de severidade do Cloud Logging, e os campos de jsonPayload são indexados e ficam disponíveis para pesquisa.

GCP Cloud Logging
# Exemplo Python para Cloud Run / Cloud Functions
import json
import sys


def log(severity: str, message: str, **fields):
    """Escreve uma entrada de log JSONL compatível com GCP Cloud Logging."""
    entry = {
        "severity": severity.upper(),  # Mapeia para severidade do Cloud Logging
        "message": message,
        **fields,
    }
    print(json.dumps(entry), file=sys.stdout, flush=True)


# GCP automaticamente parseia como logs estruturados
log("INFO", "user.login", user_id="u-42", ip="10.0.0.1")
log("ERROR", "db.timeout", host="db-primary", latency_ms=5200)


# Consulta no Cloud Logging:
# jsonPayload.user_id = "u-42"
# severity >= ERROR

Azure Monitor Logs

Azure

O Azure Monitor recebe logs JSONL pelo Azure Monitor Agent ou diretamente pela API de ingestão. O Application Insights interpreta automaticamente traces em JSON e eventos personalizados. A KQL (Kusto Query Language) oferece recursos avançados de consulta a dados de logs estruturados, com suporte a agregação, análise de séries temporais e detecção de anomalias.

Azure Monitor Logs
// Consultas KQL para logs JSONL no Azure Monitor
// Encontrar erros 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


// Taxa de erros ao longo do tempo (intervalos de 5 minutos)
AppTraces
| where SeverityLevel >= 3
| summarize ErrorCount = count() by bin(TimeGenerated, 5m)
| render timechart


// Principais eventos de erro
AppTraces
| where SeverityLevel >= 3
| extend parsed = parse_json(Message)
| summarize Count = count() by tostring(parsed.event)
| top 10 by Count

Boas práticas de logging com JSONL

Adotar as mesmas convenções em todos os seus serviços facilita a consulta e a correlação dos logs JSONL, além da criação de alertas com base neles. Estas boas práticas vêm de sistemas em produção que processam bilhões de entradas de log por dia.

Use níveis de log consistentes

Adote uma escala padrão de severidade e aplique-a de forma consistente em todos os serviços. A convenção mais comum usa cinco níveis: DEBUG para diagnósticos durante o desenvolvimento, INFO para operações normais, WARN para problemas recuperáveis, ERROR para falhas que exigem atenção e FATAL para falhas irrecuperáveis que encerram a aplicação. Na ingestão, converta os níveis numéricos (como os da escala 10-60 do pino) para esses nomes em string, para padronizar as consultas.

Use níveis 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"}

Padronize os nomes dos campos

Defina um schema compartilhado para os campos comuns a todos os serviços. Use snake_case nos nomes dos campos, ISO 8601 nos timestamps e uma nomenclatura consistente nos identificadores de correlação. Toda entrada de log deve conter, no mínimo: timestamp, level, event (um nome de evento que possa ser interpretado por software) e service. As entradas associadas a uma requisição devem incluir request_id e user_id para permitir o rastreamento.

Padronize os nomes dos campos
// Schema de campos recomendado
{
  "timestamp": "2026-02-15T08:30:00.000Z",  // ISO 8601, sempre UTC
  "level": "info",                            // debug|info|warn|error|fatal
  "event": "order.created",                    // nome do evento em notação de ponto
  "service": "order-api",                      // serviço emissor
  "version": "1.4.2",                          // versão do serviço
  "request_id": "req-abc-123",                 // ID de correlação
  "trace_id": "4bf92f3577b34da6",              // ID de trace distribuído
  "user_id": "u-42",                           // usuário autenticado
  "duration_ms": 120,                          // numérico, não string
  "order_id": "ord-789",                       // contexto específico do domínio
  "items_count": 3                             // contexto específico do domínio
}

Considerações sobre desempenho

O logging estruturado acrescenta um custo de serialização a cada chamada de log. Em serviços com alto volume de processamento, esse custo pode ser significativo. Use logging assíncrono (pino, zerolog) para tirar a serialização do caminho crítico. Evite registrar objetos grandes ou corpos de requisições e respostas no nível INFO. Use amostragem quando houver um grande volume de logs de debug. Escreva os logs em arquivos locais e deixe o envio por conta de um sidecar (Filebeat, Fluent Bit), em vez de enviá-los pela rede de forma síncrona.

Use loggers assíncronos (pino, zerolog) para não bloquear a thread principal durante a serialização do JSON.

Nunca registre corpos completos de requisições ou respostas no nível INFO. Use o nível DEBUG e ative-o apenas ao investigar problemas.

Use amostragem para eventos de alto volume. Registre 1 a cada 100 requisições de health-check, em vez de registrar todas.

Escreva os logs em arquivos locais e envie-os de forma assíncrona com o Filebeat ou o Fluent Bit. Evite chamadas de rede síncronas durante o registro dos logs.

Defina um tamanho máximo por linha de log (por exemplo, 16KB) para evitar que entradas grandes demais congestionem o pipeline.

Use o logrotate ou o recurso de rotação da própria biblioteca para fazer a rotação dos arquivos de log e evitar que o espaço em disco se esgote.

Inspecione logs JSONL no seu navegador

Visualize, pesquise e valide arquivos de log JSONL de até 1GB. Carregamento instantâneo, processamento no seu navegador e 100% de privacidade.

Perguntas frequentes

Referências