Questo documento descrive come modificare un'app Python per raccogliere dati di traccia e metriche utilizzando il framework OpenTelemetry open source e come scrivere log JSON strutturati con lo standard out. Questo documento fornisce inoltre informazioni su un'app Python di esempio che puoi installare ed eseguire. L'app utilizza il framework web Flask ed è configurata per generare metriche, tracce e log.
Per saperne di più sulla strumentazione, consulta i seguenti documenti:
Informazioni sulla strumentazione manuale e automatica
Per questo linguaggio, OpenTelemetry definisce la strumentazione automatica come la pratica di raccogliere dati di telemetria da librerie e framework senza apportare modifiche al codice. Tuttavia, hai dei moduli di installazione e imposti le variabili di ambiente.
Questo documento non descrive la strumentazione automatica. Per informazioni su questo argomento, consulta Strumentazione automatica per Python.
Per informazioni generali, consulta OpenTelemetry Instrumentation per Python.
Prima di iniziare
Abilita le API Cloud Logging, Cloud Monitoring, and Cloud Trace.
Instrumenta la tua app per raccogliere tracce, metriche e log
Per consentire all'app di raccogliere dati di traccia e metriche e scrivere un file JSON strutturato in formato standard, esegui i passaggi riportati di seguito, come descritto nelle sezioni successive di questo documento:
Configura OpenTelemetry
Questa app di esempio è configurata in modo da utilizzare l'SDK Python OpenTelemetry per esportare tracce e metriche tramite il protocollo OTLP. Per impostazione predefinita, l'SDK OpenTelemetry Python utilizza il formato Contesto traccia W3C per propagare il contesto della traccia, che garantisce che gli intervalli abbiano la corretta relazione padre-figlio all'interno di una traccia.
Il seguente esempio di codice illustra un modulo Python per configurare OpenTelemetry. Per visualizzare l'esempio completo, fai clic su more_vert Altro, quindi seleziona Visualizza su GitHub.
L'app Flask si basa su Gunicorn per gestire le richieste HTTP seguendo i suggerimenti nella guida Deploying to Production di Flask.
Gunicorn avvia più copie della tua app in esecuzione in processi worker indipendenti per aumentare la velocità effettiva. Per garantire che le metriche dei processi worker non siano in conflitto
tra loro, consigliamo che ogni processo worker imposti un valore univoco per
l'attributo della risorsa service.instance.id
. Un modo per farlo è includere
l'ID di processo in service.instance.id
. Per ulteriori informazioni, consulta la sezione
Collisioni tra serie temporali.
Per ulteriori informazioni e opzioni di configurazione, consulta la pagina relativa alla strumentazione Python di OpenTelemetry.
Configura il logging strutturato
Per scrivere log strutturati collegati alle tracce, configura l'app in modo che restituisca log in formato JSON in modalità standard con chiavi contenenti informazioni di traccia. Il seguente esempio di codice illustra come configurare la libreria logging
standard per generare log strutturati JSON utilizzando la libreria python-json-logger
e come utilizzare il pacchetto opentelemetry-instrumentation-logging
per includere le informazioni di traccia.
La configurazione precedente estrae le informazioni sull'intervallo attivo dal messaggio di log e poi le aggiunge come attributi al log strutturato JSON. Questi attributi possono quindi essere utilizzati per correlare un log a una traccia:
logging.googleapis.com/trace
: nome risorsa della traccia associata alla voce di log.logging.googleapis.com/spanId
: l'ID intervallo con la traccia associata alla voce di log.logging.googleapis.com/trace_sampled
: il valore di questo campo deve esseretrue
ofalse
.
Per ulteriori informazioni su questi campi, consulta la struttura di LogEntry
.
Esegui un'app di esempio configurata per raccogliere dati di telemetria
L'app di esempio utilizza formati indipendenti dal fornitore, tra cui JSON per i log e OTLP per metriche e tracce. La telemetria dell'app viene instradata a Google Cloud utilizzando
OpenTelemetry Collector
configurato con gli esportatori Google. Utilizza Flask per gestire le richieste HTTP e la libreria requests per effettuare le richieste HTTP. Per generare metriche e tracce per il client e il server HTTP, l'app di esempio installa le librerie di strumentazione opentelemetry-instrumentation-flask
e opentelemetry-instrumentation-requests
:
L'app ha due endpoint:
L'endpoint
/multi
è gestito dalla funzionemulti
. Il generatore di carico nell'app invia richieste all'endpoint/multi
. Quando questo endpoint riceve una richiesta, invia da tre a sette richieste all'endpoint/single
sul server locale.L'endpoint
/single
è gestito dalla funzionesingle
. Quando questo endpoint riceve una richiesta, dorme per un breve ritardo e risponde con una stringa.
Scarica ed esegui il deployment dell'app
Per eseguire l'esempio, segui questi passaggi:
-
Nella console Google Cloud, attiva Cloud Shell.
Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.
Clona il repository:
git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python
Vai alla directory di esempio:
cd opentelemetry-operations-python/samples/instrumentation-quickstart
Crea ed esegui l'esempio:
docker compose up --abort-on-container-exit
Se non è in esecuzione su Cloud Shell, esegui l'applicazione con la variabile di ambiente
GOOGLE_APPLICATION_CREDENTIALS
che punta a un file delle credenziali. Credenziali predefinite dell'applicazione fornisce un file di credenziali all'indirizzo$HOME/.config/gcloud/application_default_credentials.json
.# Set environment variables export GOOGLE_CLOUD_PROJECT="PROJECT_ID" export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json" export USERID="$(id -u)" # Run docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit
Visualizzare le metriche
La strumentazione OpenTelemetry nell'app di esempio genera metriche Prometheus che puoi visualizzare utilizzando Metrics Explorer:
Prometheus/http_server_duration_milliseconds/histogram
registra la durata delle richieste del server e archivia i risultati in un istogramma.Prometheus/http_client_duration_milliseconds/histogram
registra la durata delle richieste del client e archivia i risultati in un istogramma.
-
Nella console Google Cloud, vai alla pagina leaderboard Esplora metriche:
Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.
- Nell'elemento Metrica, espandi il menu Seleziona una metrica,
inserisci
http_server
nella barra dei filtri e utilizza i sottomenu per selezionare un tipo di risorsa e una metrica specifici:- Nel menu Risorse attive, seleziona Target Prometheus.
- Nel menu Categorie di metriche attive, seleziona Http.
- Seleziona una metrica nel menu Metriche attive.
- Fai clic su Applica.
- Configura la modalità di visualizzazione dei dati.
Quando le misurazioni di una metrica sono cumulative, Metrics Explorer normalizza automaticamente i dati misurati in base al periodo di allineamento, il che genera la visualizzazione del grafico nel grafico. Per ulteriori informazioni, consulta Tipi, tipi e conversioni.
Quando vengono misurati valori interi o doppi, ad esempio con le due metriche
counter
, Metrics Explorer somma automaticamente tutte le serie temporali. Per visualizzare i dati relativi alle route HTTP/multi
e/single
, imposta il primo menu della voce Aggregazione su Nessuna.Per saperne di più sulla configurazione di un grafico, consulta Selezionare le metriche quando si utilizza Esplora metriche.
Visualizza le tue tracce
Per visualizzare i dati di traccia, segui questi passaggi:
-
Nella console Google Cloud, vai alla pagina Esplora tracce.
Puoi trovare questa pagina anche utilizzando la barra di ricerca.
- Nel grafico a dispersione, seleziona una traccia con URI
/multi
. Nel grafico di Gantt nel riquadro Dettagli traccia, seleziona l'intervallo con l'etichetta
/multi
.Si apre un riquadro che mostra informazioni sulla richiesta HTTP. Questi dettagli includono il metodo, il codice di stato, il numero di byte e lo user agent del chiamante.
Per visualizzare i log associati a questa traccia, seleziona la scheda Log ed eventi.
La scheda mostra i singoli log. Per visualizzare i dettagli della voce di log, espandila. Puoi anche fare clic su Visualizza log e visualizzare il log utilizzando Esplora log.
Per ulteriori informazioni sull'utilizzo di Explorer di Cloud Trace, consulta Trovare ed esplorare le tracce.
visualizza i log
Da Esplora log puoi esaminare i log e puoi anche visualizzare le tracce associate, se presenti.
-
Nella console Google Cloud, vai alla pagina Esplora log:
Se usi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.
Individua un log con la descrizione di
handle /multi request
.Per visualizzare i dettagli del log, espandi la voce di log.
Fai clic su Tracce in una voce di log con il messaggio "handle /multi-richiesta", quindi seleziona Visualizza dettagli traccia.
Si apre un riquadro Dettagli traccia che mostra la traccia selezionata.
Per ulteriori informazioni sull'utilizzo di Esplora log, consulta Visualizzare i log con Esplora log.
Passaggi successivi
- OpenTelemetry
- Specifiche OTLP
- Logging strutturato
- Risoluzione dei problemi di Managed Service per Prometheus
- Risolvi i problemi di Cloud Trace