Vai al contenuto principale
LogBrew è una piattaforma di osservabilità per sviluppatori e agenti di codifica, con un piano gratuito generoso e senza carta di credito. Questa guida copre il logging in Python con il modulo standard logging, i 5 livelli di log di Python, la gestione degli errori in Python e i tipi di errore Python più comuni. Le ultime sezioni inviano gli stessi log e crash a LogBrew con logbrew-sdk 0.1.29. Tutti gli esempi girano su Python 3.13 e ogni blocco di output mostra l’output reale. Per un’app Flask, usa invece Logging in Flask. Quella guida aggiunge le tracce delle richieste alla stessa configurazione di logging.

Scrivi il tuo primo log Python

Salva questo file come app.py. Chiama logging.basicConfig() una sola volta, nel punto di ingresso del programma. Ottieni un logger con nome in ogni modulo.
Esegui python3 app.py. L’output va sullo standard error.
Il record debug non compare, perché il livello è INFO. logger.exception() registra a livello ERROR e aggiunge il traceback. Chiamalo solo in un blocco except. Passa i valori come argomenti, come in "payment retry %d of %d", 2, 3. Python costruisce il messaggio solo quando un handler accetta il record. Il modello del messaggio resta uguale a ogni nuovo tentativo, quindi puoi cercarlo.

Livelli di log in Python

Un logger invia un record solo quando il livello del record è uguale o superiore al livello del logger. Un handler può impostare un secondo livello, più alto. Il logger root parte da WARNING. Un nuovo logger ha il livello NOTSET (0) e usa il livello del suo genitore. Imposta INFO in produzione e DEBUG solo in sviluppo o per una breve diagnosi.
La prima riga mostra i record di debug di un modulo. La seconda riga elimina il rumore di una libreria.

Logger, handler e formatter

  • Un logger riceve la chiamata. Usa logging.getLogger(__name__) così il nome del logger segue il percorso del modulo.
  • Un handler invia i record a una destinazione, come la console, un file o LogBrew.
  • Un formatter trasforma un record in testo.
Una libreria non deve configurare il logging. Aggiunge solo un logging.NullHandler() al proprio logger. L’applicazione configura handler e livelli una sola volta. Per una configurazione ampia, usa logging.config.dictConfig().

Gestione degli errori in Python

Cattura l’eccezione più specifica che sai gestire. Usa else per il codice che gira solo in caso di successo. Usa finally per il codice che gira sempre. Usa raise ... from error per mantenere la causa originale. Salva questo file come orders.py.
L’output mostra entrambe le eccezioni della catena di eccezioni.
Segui queste regole per ogni eccezione.
  • Registra un’eccezione una sola volta, dove la gestisci. Non registrarla e rilanciarla a ogni strato, perché ogni strato aggiunge un record duplicato.
  • Non scrivere except Exception: pass. Se ignori un errore, registralo a livello WARNING o superiore con il motivo.
  • Cattura Exception, non BaseException. BaseException cattura anche KeyboardInterrupt e SystemExit, che fermano il programma di proposito.
  • Definisci classi di eccezione tue per gli errori che il codice chiamante deve gestire, come fa OrderError.

Segnala più di un errore

Python 3.11 e versioni successive possono sollevare un ExceptionGroup. Usalo quando un controllo trova più di un errore. Gestisci ogni tipo con except*.

Tipi di errore comuni in Python

Tutti gli errori integrati che un programma può gestire ereditano da Exception. Questa tabella elenca gli errori Python che vedi più spesso e il primo controllo per ciascuno. KeyboardInterrupt e SystemExit ereditano da BaseException, non da Exception. Non sono errori nel tuo codice.

Invia i log Python a LogBrew

LogBrewLoggingHandler è un handler di logging standard. Invia a LogBrew ogni record che accetta. L’handler della console resta uguale.
1

Crea una chiave del progetto

Accedi con la CLI. Crea un progetto e salva la sua chiave di ingestione in un file leggibile solo dal proprietario.
La CLI non stampa la chiave. In produzione, usa il gestore dei segreti della tua piattaforma.
2

Installa l'SDK

Attiva l’ambiente virtuale dell’applicazione. Poi installa il pacchetto. Richiede Python 3.10 o versioni successive.
3

Imposta la chiave e l'identità del deploy

Il client aggiunge servizio, ambiente e release a ogni evento.
4

Aggiungi l'handler

Salva questo file come worker.py. Chiama logging.basicConfig() prima di creare il client. Il client aggiunge un handler al logger root, e basicConfig() non fa nulla quando il logger root ha già un handler.
HttpTransport() invia gli eventi in background, 1 secondo dopo il primo evento o al raggiungimento di 50 eventi. client.shutdown() invia gli eventi rimanenti e chiude il client.
5

Esegui il programma

L’output della console non cambia. LogBrew riceve 1 evento di log per ogni record. Questo è il primo evento, senza il contesto di runtime condiviso.
I valori primitivi di extra={...} diventano metadati. Il secondo evento ha exceptionName KeyError e exceptionMessage 'seats'. Per inviare il testo completo del traceback, crea l’handler con include_exception_text=True.
6

Rileggi i log

Una lettura con risultati conferma che LogBrew ha salvato i log. Per leggere da CI o da un agente di codifica, usa una chiave di lettura del progetto. Vedi Verifica la configurazione.

Scegli quali record vanno a LogBrew

Dai all’handler un livello proprio per inviare meno record. La console riceve ancora INFO e superiori.
I livelli Python diventano livelli LogBrew. Il nome e il numero originali del livello restano nei metadati.

Segnala i crash Python come problemi

install_process_error_capture(client) segnala le eccezioni non catturate in script, worker, codice di avvio e thread. Ogni crash diventa 1 problema con il tipo di eccezione, il messaggio, i frame dello stack e le cause concatenate. Python stampa ancora il traceback ed esce come prima. Salva questo file come startup.py ed eseguilo.
LogBrew riceve un problema con il titolo FileNotFoundError, il livello critical e il meccanismo python.excepthook. I suoi frame contengono il nome del file, la riga e la funzione, ma non il percorso completo. Un crash in un thread ha il livello error. Prima che Python esca, l’SDK attende al massimo 2 secondi per la consegna.
Il problema include il messaggio dell’eccezione. Non inserire credenziali o dati personali nei messaggi di eccezione o di log. Vedi Controlla i dati acquisiti.

Risoluzione degli errori

Per le app web, vedi Logging in Flask. Per scegliere un formato di log, vedi Logging strutturato. Per altri runtime, vedi Integrazione SDK.