Python Academy · Lezione

Logging strutturato

Generi log in formato JSON per ottenere un output leggibile dalle macchine.

Logging strutturato è una lezione Python Academy gratuita su CoddyKit. Questa è la lezione 3 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Python Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Python Academy include 4 lezioni in totale.

Che cos'è il logging strutturato?

Il logging strutturato emette i record di log come dati leggibili dalle macchine (JSON) invece che come testo in formato libero, rendendoli facili da indicizzare, cercare e utilizzare per gli alert.

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")

Formatter JSON personalizzato

Estenda logging.Formatter per emettere JSON invece di testo semplice.

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

Il pacchetto python-json-logger fornisce un formatter JSON pronto all'uso, con campi standard e aggiuntivi.

# 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 è una popolare libreria di terze parti che separa l'accumulo del contesto dalla formattazione e supporta pipeline di processor.

# pip install structlog
import structlog

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

Associare il contesto con structlog

structlog consente di associare coppie chiave-valore a un logger, che le mantiene in tutte le chiamate successive.

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}

Aggiungere timestamp e informazioni sul chiamante

I processor possono arricchire automaticamente i record. Aggiunga TimeStamper e CallsiteParameterAdder a ogni record di log.

import structlog

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

Registrare gli ID delle richieste nelle app web

In un framework web, associ un ID della richiesta all'inizio di ogni richiesta, così ogni riga di log durante quella richiesta lo include.

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 di log ECS

Elastic Common Schema (ECS) è un formato standard per i log JSON utilizzato da Elastic Stack. Utilizzi ecs-logging per 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")

Sistemi di aggregazione dei log

I log JSON strutturati confluiscono naturalmente negli strumenti di aggregazione: 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

Evitare i dati personali nei log

Rimuova le informazioni che consentono di identificare personalmente un individuo prima di registrarle. Utilizzi un processor o un filtro personalizzato per mascherare email, token e password.

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

Compromessi tra log strutturati e non strutturati

I log strutturati sono facili da cercare e utilizzare per gli alert, ma prolissi. Combini il logging strutturato in produzione con una formattazione leggibile dalle persone durante lo sviluppo, usando una configurazione basata sull'ambiente.

import structlog, os

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

structlog.configure(processors=[renderer])

Verifica rapida

Qual è il principale vantaggio dei log strutturati in JSON rispetto ai log in testo semplice?

Riepilogo

Il logging strutturato emette record JSON chiave-valore. Utilizzi un JSONFormatter, python-json-logger o structlog. Associ il contesto (ID della richiesta, utente) all'inizio di un'operazione, così ogni riga di log durante quell'operazione lo mantiene.

Domande Frequenti

La lezione «Logging strutturato» è gratuita?

Sì — il testo completo di «Logging strutturato» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Python Academy, passa a CoddyKit PRO. Il corso Python Academy include 4 lezioni in totale.

Cosa imparerò in «Logging strutturato»?

Generi log in formato JSON per ottenere un output leggibile dalle macchine. Eserciti Python Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare Python Academy?

Non è richiesta alcuna esperienza precedente. Python Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 3 di 4.

Quanto tempo richiede la lezione «Logging strutturato»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione Python Academy?

Sì. Ogni lezione Python Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

← Torna a Python Academy