Python Academy · Aula

Registro estruturado

Emita registros formatados em JSON para obter uma saída legível por máquinas.

Registro estruturado é uma aula grátis de Python Academy no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Python Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Python Academy inclui 4 aulas no total.

O que é registro estruturado?

O registro estruturado emite registros como dados legíveis por máquina (JSON), em vez de texto livre, facilitando a indexação, a pesquisa e a geração de alertas.

import logging, json

def log_json(level, msg, **kw):
    record = {"level": level, "msg": msg, **kw}
    print(json.dumps(record))

log_json("INFO", "Request received", path="/api/users", method="GET")

Formatador JSON personalizado

Crie uma subclasse de logging.Formatter para emitir JSON em vez de texto simples.

import logging, json

class JSONFormatter(logging.Formatter):
    def format(self, record):
        return json.dumps({
            "time": self.formatTime(record),
            "level": record.levelname,
            "name": record.name,
            "msg": record.getMessage(),
        })

handler = logging.StreamHandler()
handler.setFormatter(JSONFormatter())
logging.getLogger().addHandler(handler)

python-json-logger

O pacote python-json-logger fornece um formatador JSON pronto, com campos padrão e extras.

# pip install python-json-logger
import logging
from pythonjsonlogger import jsonlogger

logger = logging.getLogger()
handler = logging.StreamHandler()
handler.setFormatter(jsonlogger.JsonFormatter())
logger.addHandler(handler)
logger.info("User created", extra={"user_id": 42})

structlog

structlog é uma biblioteca popular de terceiros que separa a acumulação de contexto da formatação e oferece fluxos de processamento.

# pip install structlog
import structlog

log = structlog.get_logger()
log = log.bind(request_id="abc123")
log.info("payment_processed", amount=49.99, currency="USD")

Vinculando contexto com structlog

O structlog permite vincular pares de chave e valor a um logger, que os mantém em todas as chamadas subsequentes.

import structlog

log = structlog.get_logger().bind(
    service="auth",
    env="prod"
)
log.warning("login_failed", user="alice", reason="bad_password")
# {service:auth, env:prod, user:alice, reason:bad_password}

Adicionando marcas de data e hora e informações do chamador

Os processadores podem enriquecer os registros automaticamente. Adicione TimeStamper e CallsiteParameterAdder a cada registro.

import structlog

structlog.configure(
    processors=[
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.CallsiteParameterAdder([structlog.processors.CallsiteParameter.FILENAME]),
        structlog.processors.JSONRenderer(),
    ]
)

Registrando IDs de solicitação em aplicações web

Em uma estrutura web, vincule um ID de solicitação no início de cada solicitação para que todas as linhas de registro durante essa solicitação o incluam.

import structlog

def middleware(request, call_next):
    req_id = request.headers.get("X-Request-Id", generate_id())
    log = structlog.get_logger().bind(request_id=req_id)
    log.info("request_started", path=request.url.path)
    response = call_next(request)
    log.info("request_finished", status=response.status_code)
    return response

Formato de registro ECS

O Elastic Common Schema (ECS) é um formato padrão de registro JSON usado pelo Elastic Stack. Use ecs-logging para Python.

# pip install ecs-logging
import logging
import ecs_logging

logger = logging.getLogger("app")
handler = logging.StreamHandler()
handler.setFormatter(ecs_logging.StdlibFormatter())
logger.addHandler(handler)
logger.info("Event logged in ECS format")

Sistemas de agregação de registros

Os registros JSON estruturados fluem naturalmente para ferramentas de agregação: Elasticsearch/Kibana (ELK), Grafana Loki, Datadog, AWS CloudWatch Logs Insights.

# Loki query example:
# {app="myservice"} | json | level="ERROR"

# CloudWatch Insights:
# fields @timestamp, level, msg
# | filter level = "ERROR"
# | sort @timestamp desc

Evitando PII nos registros

Remova informações de identificação pessoal antes de registrar. Use um processador ou filtro personalizado para mascarar endereços de e-mail, tokens e senhas.

import re

def mask_pii(_, __, event_dict):
    msg = event_dict.get("event", "")
    event_dict["event"] = re.sub(
        r"[\w.+-]+@[\w-]+\.[\w.]+", "***@***.***", msg
    )
    return event_dict

Compensações entre registros estruturados e não estruturados

Os registros estruturados permitem pesquisas e alertas, mas são detalhados. Combine o registro estruturado em produção com a formatação legível para pessoas durante o desenvolvimento, usando uma configuração baseada no ambiente.

import structlog, os

if os.getenv("ENV") == "production":
    renderer = structlog.processors.JSONRenderer()
else:
    renderer = structlog.dev.ConsoleRenderer()

structlog.configure(processors=[renderer])

Verificação rápida

Qual é a principal vantagem dos registros estruturados em JSON em relação aos registros de texto simples?

Recapitulação

O registro estruturado emite registros JSON de chave e valor. Use um JSONFormatter, python-json-logger ou structlog. Vincule o contexto (ID de solicitação, usuário) no início de uma operação para que todas as linhas de registro durante essa operação carreguem esse contexto.

Perguntas Frequentes

A aula “Registro estruturado” é grátis?

Sim — o texto completo de “Registro estruturado” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Python Academy, atualize para CoddyKit PRO. O curso de Python Academy inclui 4 aulas no total.

O que vou aprender em “Registro estruturado”?

Emita registros formatados em JSON para obter uma saída legível por máquinas. Você pratica Python Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Python Academy?

Nenhuma experiência prévia é necessária. Python Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “Registro estruturado”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Python Academy?

Sim. Cada aula de Python Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para Python Academy