Python e OpenTelemetry

Questa pagina è rivolta agli sviluppatori di applicazioni che vogliono raccogliere dati di Cloud Trace per le applicazioni Python utilizzando OpenTelemetry. OpenTelemetry è un framework di strumentazione indipendente dal fornitore che puoi usare per raccogliere dati di tracce e metriche. Per informazioni sulla strumentazione del tuo codice, consulta Strumentazione e osservabilità.

  • Installare i pacchetti OpenTelemetry.
  • Configura la tua applicazione per esportare gli intervalli in Cloud Trace.
  • Configura la tua piattaforma.

Per informazioni sulla release, consulta le pagine seguenti:

Per i contenuti di riferimento di OpenTelemetry, vedi quanto segue:

Per i dettagli più recenti su OpenTelemetry per Python, insieme alla documentazione e agli esempi aggiuntivi, consulta OpenTelemetry.

Prima di iniziare

  • Devi utilizzare Python 3.6 o versioni successive.

  • Nel pannello di navigazione della console Google Cloud, seleziona API e servizi, fai clic su Abilita API e servizi e poi abilita l'Cloud Trace API:

    Vai alle impostazioni dell'API Cloud Trace

  • Se viene visualizzato API abilitata, significa che l'API è già abilitata. In caso contrario, fai clic sul pulsante Attiva.

Installare i pacchetti OpenTelemetry

Per installare i pacchetti OpenTelemetry richiesti, segui questi passaggi:

  1. (Facoltativo) Esegui l'upgrade alla versione più recente di pip:

    pip install --upgrade pip

  2. Installa i seguenti pacchetti OpenTelemetry utilizzando pip:

    pip install opentelemetry-api \
  opentelemetry-sdk \
  opentelemetry-exporter-gcp-trace

Importa pacchetti di tracce

Aggiorna l'applicazione per importare i pacchetti e le classi seguenti:

L'esempio seguente illustra queste istruzioni di importazione:


from opentelemetry import trace
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.trace import Link

Configura l'esportazione di intervalli in Cloud Trace

Per inviare intervalli a Cloud Trace, modifica l'applicazione in modo da utilizzare l'utilità di esportazione CloudTraceSpanExporter. L'esempio seguente illustra i passaggi richiesti:


tracer_provider = TracerProvider()
cloud_trace_exporter = CloudTraceSpanExporter()
tracer_provider.add_span_processor(
    # BatchSpanProcessor buffers spans and sends them in batches in a
    # background thread. The default parameters are sensible, but can be
    # tweaked to optimize your performance
    BatchSpanProcessor(cloud_trace_exporter)
)
trace.set_tracer_provider(tracer_provider)

tracer = trace.get_tracer(__name__)

Aggiungere attributi a un intervallo

Per aggiungere un attributo a un intervallo, chiama il metodo set_attribute dell'intervallo. Ad esempio, il seguente codice aggiunge più attributi all'intervallo denominato foo_with_attribute:


with tracer.start_span("foo_with_attribute") as current_span:
    do_work()

    # Add attributes to the spans of various types
    current_span.set_attribute("string_attribute", "str")
    current_span.set_attribute("bool_attribute", False)
    current_span.set_attribute("int_attribute", 3)
    current_span.set_attribute("float_attribute", 3.14)

Aggiungere eventi a un intervallo

Per aggiungere un evento a un intervallo, chiama il metodo add_event dell'intervallo. Ad esempio, il seguente codice aggiunge un evento all'intervallo denominato foo_with_event:


# Adding events to spans
with tracer.start_as_current_span("foo_with_event") as current_span:
    do_work()
    current_span.add_event(name="event_name")

Per collegare due intervalli, importa la classe Link e utilizza il campo links nel metodo start_as_current_span. Quando colleghi due sezioni, puoi includere attributi nel campo links.

Il seguente codice illustra due diversi modi per collegare un intervallo all'intervallo denominato link_target:


# Adding links to spans
with tracer.start_as_current_span("link_target") as link_target:
    # Using start_as_current_span() instead of start_span() will make spans
    # created within this scope children of foo_with_attribute

    # Creates a span "span_with_link" and a link from
    # "span_with_link" -> "link_target"
    with tracer.start_as_current_span(
        "span_with_link", links=[Link(link_target.context)]
    ):
        do_work()

    # Creates a span "span_with_link" and a link from
    # "span_with_link" -> "link_target". This link also has the attribute
    # {"link_attr": "string"}
    with tracer.start_as_current_span(
        "span_with_link_and_link_attributes",
        links=[Link(link_target.context, attributes={"link_attr": "string"})],
    ):
        do_work()

Applicazione Flask di esempio

La strumentazione Flask di OpenTelemetry è progettata per semplificare l'acquisizione dei contenuti delle tracce relativi alle richieste HTTP. Ciò significa che non devi aggiungere una strumentazione specifica alle tue route per queste richieste:

  • Flask utilizza il propagatore configurato per estrarre il contesto di intervallo dalle richieste HTTP in entrata.
  • Flask crea automaticamente intervalli con attributi che descrivono la richiesta e la risposta.

Per un esempio end-to-end utilizzando Flask e OpenTelemetry, vedi flask_e2e. Il file README di Git include informazioni su come installare, configurare ed eseguire l'esempio.

Questa sezione evidenzia i passaggi di configurazione specifici di Flask inclusi nel file server.py di esempio. Il file client, client.py, utilizza la strumentazione Requests per attivare il tracciamento delle richieste HTTP effettuate dalla libreria delle richieste.

Importazione e configurazione

Per utilizzare la strumentazione Flask di OpenTelemetry, devi importare FlaskInstrumentor.

Se vuoi assicurarti che gli intervalli creati da diversi prodotti Google Cloud siano associati alla stessa traccia, devi configurare il propagatore con il propagatore di Cloud Trace. Questo propagatore specifica l'utilizzo dell'intestazione X-Cloud-Trace-Context. Se non configuri un propagatore, OpenTelemetry utilizza quello predefinito. In questo caso, gli intervalli creati da diversi prodotti Google Cloud, come Cloud Run e App Engine, sono in tracce separate.

L'esempio seguente illustra le istruzioni di importazione e configurazione necessarie e la configurazione del propagatore Cloud Trace:


import time

from flask import Flask
from opentelemetry import metrics, trace
from opentelemetry.exporter.cloud_monitoring import (
    CloudMonitoringMetricsExporter,
)
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
from opentelemetry.instrumentation.flask import FlaskInstrumentor
from opentelemetry.propagate import set_global_textmap
from opentelemetry.propagators.cloud_trace_propagator import (
    CloudTraceFormatPropagator,
)
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor


set_global_textmap(CloudTraceFormatPropagator())

Non è necessario aggiungere istruzioni specifiche per Flask quando configuri l'utilità di esportazione CloudTraceSpanExporter; la configurazione mostrata in Configurare l'esportazione di intervalli in Cloud Trace è sufficiente.

Inizializza Flask

Configura FlaskInstrumentor per la strumentazione dell'applicazione. Il seguente esempio illustra come eseguire questo passaggio:


app = Flask(__name__)
FlaskInstrumentor().instrument_app(app)

@app.route("/")
def hello_world():
    # You can still use the OpenTelemetry API as usual to create custom spans
    # within your trace
    with tracer.start_as_current_span("do_work"):
        time.sleep(0.1)

    return "Hello, World!"

Configura la tua piattaforma

Puoi utilizzare Cloud Trace su Google Cloud e altre piattaforme.

In esecuzione su Google Cloud

Quando la tua applicazione è in esecuzione su Google Cloud, non è necessario fornire alla libreria client le credenziali di autenticazione sotto forma di account di servizio. Tuttavia, devi assicurarti che per la tua piattaforma Google Cloud sia abilitato l'ambito di accesso all'API Cloud Trace.

Per un elenco degli ambienti Google Cloud supportati, consulta la pagina relativa all'assistenza per gli ambienti.

Per le seguenti configurazioni, le impostazioni predefinite dell'ambito di accesso abilitano l'Cloud Trace API:

Se utilizzi ambiti di accesso personalizzati, devi assicurarti che l'ambito di accesso all'API Cloud Trace sia abilitato:

  • Per informazioni su come configurare gli ambiti di accesso per il tuo ambiente utilizzando la console Google Cloud, consulta Configurazione del progetto Google Cloud.

  • Per gli utenti gcloud, specifica gli ambiti di accesso utilizzando il flag --scopes e includi l'ambito di accesso all'Cloud Trace API trace.append. Ad esempio, per creare un cluster GKE in cui è abilitata solo l'Cloud Trace API:

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

Esecuzione in locale e altrove

Se la tua applicazione viene eseguita al di fuori di Google Cloud, devi fornire alla libreria client le credenziali di autenticazione sotto forma di account di servizio. L'account di servizio deve contenere il ruolo agente Cloud Trace. Per le istruzioni, vedi Creazione di un account di servizio.

Le librerie client di Google Cloud utilizzano le Credenziali predefinite dell'applicazione (ADC) per trovare le credenziali della tua applicazione.

Puoi fornire queste credenziali in uno dei tre modi seguenti:

  • Esegui gcloud auth application-default login

  • Inserisci l'account di servizio in un percorso predefinito per il tuo sistema operativo. Di seguito sono elencati i percorsi predefiniti per Windows e Linux:

    • Windows: %APPDATA%/gcloud/application_default_credentials.json

    • Linux: $HOME/.config/gcloud/application_default_credentials.json

  • Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso al tuo account di servizio:

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

Visualizza tracce

Nel pannello di navigazione della console Google Cloud, seleziona Trace e poi Trace Explorer:

Vai a Trace Explorer

Risoluzione dei problemi

Per informazioni sulla risoluzione dei problemi relativi a Cloud Trace, vai alla pagina Risoluzione dei problemi.

Risorse