Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

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 agente di raccolta OpenTelemetry. Descrive inoltre 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 agente di raccolta OpenTelemetry, strumenta l'applicazione con l'SDK e l'esportatore OTLP in-process dell'SDK. Questa strumentazione è neutrale rispetto al fornitore. Inoltre, implementi un raccoglitore OpenTelemetry che riceve la telemetria dall'esportatore in-process e poi la esporta nel tuo Google Cloud progetto. Per scoprire di più sugli agenti di raccolta, consulta Raccoglitore OpenTelemetry creato da Google.

Ti consigliamo di utilizzare un agente di raccolta OpenTelemetry per esportare i dati di telemetria quando il tuo ambiente supporta l'utilizzo dell'agente di raccolta. Per alcuni ambienti, devi utilizzare un esportatore in-process che invia direttamente i dati al tuo progettoGoogle Cloud . Per scoprire di più sull'instrumentazione in-process, consulta Eseguire la migrazione dall'esportatore di Trace all'endpoint OTLP.

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

Informazioni sull'instrumentazione manuale e zero-code

Per questo linguaggio, 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 Python.

Per informazioni generali, consulta Instrumentazione OpenTelemetry per Python.

Prima di iniziare

Installa Google Cloud CLI.
Configura gcloud CLI per utilizzare la tua identità federata.

Per ulteriori informazioni, vedi Accedi 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.
Nota: se non prevedi di conservare le risorse che crei in questa procedura, crea un progetto invece di selezionarne uno già esistente. Una volta completata questa procedura, puoi eliminare il progetto e tutte le relative risorse.
- 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 attivata 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 dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.
```
gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com
```

Per ottenere le autorizzazioni necessarie per consentire all'applicazione di esempio di scrivere dati di log, metriche e tracce, chiedi all'amministratore di concederti i seguenti ruoli IAM:
- Logs Writer (roles/logging.logWriter) sul tuo progetto
- Monitoring Metric Writer (roles/monitoring.metricWriter) sul tuo progetto
- Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter) sul tuo progetto
- Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) sul progetto quota
Queste autorizzazioni sono sufficienti se esegui l'esempio in Cloud Shell, sulle risorse Google Cloud o in un ambiente di sviluppo locale. Per scoprire come configurare un progetto quota, vedi Imposta il progetto quota.

Importante: le applicazioni di produzione in genere si basano su un account di servizio per fornire le credenziali necessarie per scrivere log, metriche e dati di traccia. In questi scenari, concedi i ruoli precedenti al service account.

Per ottenere le autorizzazioni necessarie per visualizzare i dati di log, metriche e tracce, 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.

Strumenta 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:

Configurare OpenTelemetry
Configura il logging strutturato

Configura 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 span abbiano la corretta relazione elemento principale-secondario all'interno di una traccia.

Il seguente esempio di codice illustra un modulo Python per configurare OpenTelemetry. Per visualizzare l'esempio completo, seleziona il logo GitHub nella barra degli strumenti dell'esempio.

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