Esempio di strumentazione Python

Questo documento descrive come instrumentare un'app Python per raccogliere dati di traccia e metriche utilizzando l'SDK OpenTelemetry e un collettore OpenTelemetry. Descrive anche come scrivere log JSON strutturati nell'output standard. Per sperimentare l'instrumentazione, scarica ed esegui l'app di esempio. Questa app utilizza il framework web Flask e genera dati di log, metriche e traccia.

Quando utilizzi un collettore OpenTelemetry, strumenta l'applicazione con l'SDK e l'esportatore in-process OTLP dell'SDK. Questa strumentazione è neutrale rispetto al fornitore. Devi anche implementare un raccoglitore OpenTelemetry che riceve la telemetria dall'esportatore in-process e poi la esporta nel tuo Google Cloud progetto. Per scoprire di più sui raccoglitori, consulta Raccoglitore OpenTelemetry creato da Google.

Ti consigliamo di utilizzare un raccoglitore OpenTelemetry per esportare i dati di telemetria quando l'ambiente supporta l'utilizzo del raccoglitore. Per alcuni ambienti, devi utilizzare un esportatore in-process che invia direttamente i dati al tuo progettoGoogle Cloud . Per informazioni sull'instrumentazione in-process, consulta Migrazione dall'esportatore di Trace all'endpoint OTLP.

Per saperne di più sull'instrumentazione, consulta i seguenti documenti:

Informazioni sull'instrumentazione manuale e senza codice

Per questa lingua, OpenTelemetry definisce l'instrumentazione zero-code come la pratica di raccolta della telemetria da librerie e framework senza apportare modifiche al codice. Tuttavia, devi installare i moduli e impostare le variabili di ambiente.

Questo documento non descrive l'instrumentazione zero-code. Per informazioni su questo argomento, consulta Strumentazione zero-code di Python.

Per informazioni generali, vedi OpenTelemetry Instrumentation for Python.

Prima di iniziare

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

Installa Google Cloud CLI.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Crea o seleziona un Google Cloud progetto.

Ruoli richiesti per selezionare o creare un progetto

Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

Creare un progetto Google Cloud :
```
gcloud projects create PROJECT_ID
```
Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.
Seleziona il progetto Google Cloud che hai creato:
```
gcloud config set project PROJECT_ID
```
Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

Verifica che la fatturazione sia abilitata per il tuo progetto Google Cloud .

Abilita le API Cloud Logging, Cloud Monitoring, Cloud Trace e Telemetry:

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

Installa Google Cloud CLI.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Crea o seleziona un Google Cloud progetto.

Ruoli richiesti per selezionare o creare un progetto

Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

Creare un progetto Google Cloud :
```
gcloud projects create PROJECT_ID
```
Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.
Seleziona il progetto Google Cloud che hai creato:
```
gcloud config set project PROJECT_ID
```
Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

Verifica che la fatturazione sia abilitata per il tuo progetto Google Cloud .

Abilita le API Cloud Logging, Cloud Monitoring, Cloud Trace e Telemetry:

Ruoli richiesti per abilitare le API

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

Se esegui l'esempio in Cloud Shell, sulle risorse Google Cloud o in un ambiente di sviluppo locale, le autorizzazioni elencate in questa sezione sono sufficienti. Per le applicazioni di produzione, in genere un account di servizio fornisce le credenziali per scrivere dati di log, metriche e traccia.

Per ottenere le autorizzazioni necessarie per consentire all'applicazione di esempio di scrivere dati di log, metriche e traccia, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:
- Logs Writer (roles/logging.logWriter)
- Monitoring Metric Writer (roles/monitoring.metricWriter)
- Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)
Per ottenere le autorizzazioni necessarie per visualizzare i dati di log, metriche e traccia, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:
- Visualizzatore log (roles/logging.viewer)
- Monitoring Viewer (roles/monitoring.viewer)
- Utente Cloud Trace (roles/cloudtrace.user)
Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Instrumenta la tua app per raccogliere tracce, metriche e log

Per instrumentare l'app in modo da raccogliere dati di traccia e metriche e scrivere JSON strutturato in standard out, segui questi passaggi come descritto nelle sezioni successive di questo documento:

Configura OpenTelemetry
Configura il logging strutturato

Configurare OpenTelemetry

Questa app di esempio è configurata per utilizzare l'SDK OpenTelemetry Python per esportare tracce e metriche utilizzando il protocollo OTLP. Per impostazione predefinita, l'SDK Python di OpenTelemetry utilizza il formato W3C Trace Context per la propagazione del contesto di traccia, il 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 Altro e poi seleziona Visualizza su GitHub.

def setup_opentelemetry() -> None:
    resource = Resource.create(
        attributes={
            # Use the PID as the service.instance.id to avoid duplicate timeseries
            # from different Gunicorn worker processes.
            SERVICE_INSTANCE_ID: f"worker-{os.getpid()}",
        }
    )
    # Set up OpenTelemetry Python SDK
    tracer_provider = TracerProvider(resource=resource)
    tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
    trace.set_tracer_provider(tracer_provider)

    logger_provider = LoggerProvider(resource=resource)
    logger_provider.add_log_record_processor(BatchLogRecordProcessor(OTLPLogExporter()))
    logs.set_logger_provider(logger_provider)

    reader = PeriodicExportingMetricReader(OTLPMetricExporter())
    meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
    metrics.set_meter_provider(meter_provider)

L'app Flask si basa su Gunicorn per gestire le richieste HTTP seguendo i consigli della guida Deploying to Production di Flask. Gunicorn avvia più copie della tua app in esecuzione in processi di lavoro indipendenti per aumentare la velocità effettiva. Per garantire che le metriche dei processi di lavoro non siano in conflitto tra loro, ti consigliamo di impostare un valore univoco per l'attributo risorsa service.instance.id per ogni processo di lavoro. Un modo per farlo è includere l'ID processo in service.instance.id. Per saperne di più, vedi Collisioni delle serie temporali.

Per ulteriori informazioni e opzioni di configurazione, consulta OpenTelemetry Python instrumentation.

Configura il logging strutturato

Per scrivere log strutturati collegati alle tracce, configura la tua app in modo che restituisca log in formato JSON a standard out con chiavi contenenti informazioni sulle tracce. Il seguente esempio di codice mostra come configurare la libreria standard logging per generare log strutturati in formato JSON utilizzando la libreria python-json-logger e come utilizzare il pacchetto opentelemetry-instrumentation-logging per includere le informazioni di tracciamento.

class JsonFormatter(jsonlogger.JsonFormatter):
    def formatTime(self, record: logging.LogRecord, datefmt: Optional[str] = None):
        # Format the timestamp as RFC 3339 with microsecond precision
        isoformat = datetime.fromtimestamp(record.created).isoformat()
        return f"{isoformat}Z"


def setup_structured_logging() -> None:
    LoggingInstrumentor().instrument()

    log_handler = logging.StreamHandler()
    formatter = JsonFormatter(
        "%(asctime)s %(levelname)s %(message)s %(otelTraceID)s %(otelSpanID)s %(otelTraceSampled)s",
        rename_fields={
            "levelname": "severity",
            "asctime": "timestamp",
            "otelTraceID": "logging.googleapis.com/trace",
            "otelSpanID": "logging.googleapis.com/spanId",
            "otelTraceSampled": "logging.googleapis.com/trace_sampled",
        },
    )
    log_handler.setFormatter(formatter)
    logging.basicConfig(
        level=logging.INFO,
        handlers=[log_handler],
    )

La configurazione precedente estrae le informazioni sullo span attivo dal messaggio di log e le aggiunge come attributi al log strutturato JSON. Questi attributi possono essere utilizzati per correlare un log a una traccia:

logging.googleapis.com/trace: il nome della 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 essere true o false.

Per saperne di più su questi campi, consulta la struttura LogEntry.

Esegui un'app di esempio configurata per raccogliere dati di telemetria

La strumentazione nell'app di esempio utilizza formati indipendenti dal fornitore, come JSON per i dati di log e OTLP per i dati di metrica e traccia. L'app di esempio utilizza anche Flask per gestire le richieste HTTP e la libreria requests per effettuare richieste HTTP. Collector OpenTelemetry invia dati di log e metriche al tuo progetto utilizzando gli esportatori Google. Invia i dati di traccia al tuo progetto utilizzando l'API Telemetry, che utilizza OTLP.

Per generare metriche e tracce per il client HTTP e il server, l'app di esempio installa le librerie di strumentazione opentelemetry-instrumentation-flask e opentelemetry-instrumentation-requests:

logger = logging.getLogger(__name__)

# Initialize OpenTelemetry Python SDK and structured logging
setup_opentelemetry()
setup_structured_logging()

app = Flask(__name__)

# Add instrumentation
FlaskInstrumentor().instrument_app(app)
RequestsInstrumentor().instrument()

L'app ha due endpoint:

L'endpoint /multi viene gestito dalla funzione multi. 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.

@app.route("/multi")
def multi():
    """Handle an http request by making 3-7 http requests to the /single endpoint."""
    sub_requests = randint(3, 7)
    logger.info("handle /multi request", extra={"subRequests": sub_requests})
    for _ in range(sub_requests):
        requests.get(url_for("single", _external=True))
    return "ok"

L'endpoint /single viene gestito dalla funzione single. Quando questo endpoint riceve una richiesta, rimane inattivo per un breve periodo e poi risponde con una stringa.

@app.route("/single")
def single():
    """Handle an http request by sleeping for 100-200 ms, and write the number of seconds slept as the response."""
    duration = uniform(0.1, 0.2)
    logger.info("handle /single request", extra={"duration": duration})
    time.sleep(duration)
    return f"slept {duration} seconds"

Scaricare ed eseguire il deployment dell'app

Per eseguire l'esempio:

Nella console Google Cloud , attiva Cloud Shell.

Attiva Cloud Shell

Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. 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 esegui l'applicazione 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 in $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

L'instrumentazione OpenTelemetry nell'app di esempio genera metriche Prometheus che puoi visualizzare utilizzando Esplora metriche:

Prometheus/http_server_duration_milliseconds/histogram registra la durata delle richieste del server e memorizza i risultati in un istogramma.
Prometheus/http_client_duration_milliseconds/histogram registra la durata delle richieste client e memorizza i risultati in un istogramma.

Per visualizzare le metriche generate dall'app di esempio, segui questi passaggi:

Nella console Google Cloud , vai alla pagina Esplora metriche:
Vai a Esplora metriche

Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.
Nella barra degli strumenti della console Google Cloud , seleziona il tuo progetto Google Cloud . Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
Nell'elemento Metrica, espandi il menu Seleziona una metrica, digita http_server nella barra dei filtri e poi utilizza i sottomenu per selezionare un tipo di risorsa e una metrica specifici:
1. Nel menu Risorse attive, seleziona Target Prometheus.
2. Nel menu Categorie di metriche attive, seleziona Http.
3. Nel menu Metriche attive, seleziona una metrica.
4. Fai clic su Applica.
Per aggiungere filtri, che rimuovono le serie temporali dai risultati della query, utilizza l'elemento Filtro.
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 comporta la visualizzazione di una frequenza nel grafico. Per maggiori 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 per le route HTTP /multi e /single, imposta il primo menu della voce Aggregazione su Nessuna.

Per ulteriori informazioni sulla configurazione di un grafico, consulta Seleziona le metriche durante l'utilizzo di Esplora metriche.

Visualizza le tracce

Potrebbero essere necessari diversi minuti prima che i dati di tracciamento siano disponibili. Ad esempio, quando i dati di traccia vengono ricevuti dal tuo progetto, Google Cloud Observability potrebbe dover creare un database per archiviarli. La creazione del database può richiedere alcuni minuti e durante questo periodo non sono disponibili dati di traccia da visualizzare.

Per visualizzare i dati di traccia:

Nella console Google Cloud , vai alla pagina Esplora tracce:
Vai a Esplora tracce

Puoi trovare questa pagina anche utilizzando la barra di ricerca.
Nella sezione della tabella della pagina, seleziona una riga con il nome dello span /multi.
Nel grafico di Gantt nel riquadro Dettagli su Trace, seleziona l'intervallo etichettato /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 Esplora tracce, consulta Trovare ed esplorare le tracce.

Visualizza i log

Da Esplora log puoi esaminare i log e visualizzare le tracce associate, se esistenti.

Nella console Google Cloud , vai alla pagina Esplora log:
Vai a Esplora log

Se utilizzi 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 Trace in una voce di log con il messaggio "handle /multi request", quindi seleziona Visualizza dettagli trace.

Si apre un riquadro Dettagli su Trace che mostra la traccia selezionata.

I dati di log potrebbero essere disponibili diversi minuti prima dei dati di traccia. Se si verifica un errore durante la visualizzazione dei dati di traccia cercando una traccia per ID o seguendo i passaggi descritti in questa attività, attendi un minuto o due e riprova.

Per ulteriori informazioni sull'utilizzo di Esplora log, vedi Visualizza i log utilizzando Esplora log.