Python e OpenTelemetry

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Questa pagina è progettata per gli sviluppatori di applicazioni che vogliono raccogliere i dati Cloud Trace per le applicazioni Python utilizzando OpenTelemetry. OpenTelemetry è un set di librerie di strumentazione per la raccolta di dati di tracce e metriche; queste librerie funzionano con più backend. Per raccogliere le tracce con OpenTelemetry e Python, procedi come segue, come descritto in questa pagina:

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

Per informazioni sulla versione, consulta quanto segue:

Per i dettagli più recenti su OpenTelemetry per Python, oltre a documentazione ed esempi aggiuntivi, consulta OpenTelemetry.

Prima di iniziare

  • È necessario utilizzare Python 3.6 o versioni successive.
  • Verifica che lCloud Trace API sia abilitata per il tuo progetto Google Cloud:

    1. Fai clic sul pulsante seguente o, in Google Cloud Console, seleziona API e servizi, quindi seleziona API Cloud Trace:

      Vai all'API Trace

    2. Nella pagina dell'API Cloud Trace, se viene visualizzato un pulsante con l'etichetta Abilita, fai clic su di esso. Se questo pulsante non è visualizzato, significa che l'Cloud Trace API è abilitata per il progetto selezionato.

Installa i pacchetti OpenTelemetry

Per installare i pacchetti OpenTelemetry richiesti:

  1. (Facoltativo) Esegui l'upgrade all'ultima versione 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 traccia

Aggiorna la tua applicazione per importare i seguenti pacchetti e classi:

  • trace
  • CloudTraceSpanExporter
  • TracerProvider
  • Un processore di intervallo di esportazione:

    • Per inviare intervalli con un processo in background, utilizza il processore BatchSpanProcessor. Ti consigliamo di utilizzare questo processore a meno che non utilizzi Cloud Run. Cloud Run non supporta i processi in background.

    • Per inviare intervalli con un processo in primo piano, utilizza il processore SimpleSpanProcessor. Se utilizzi Cloud Run, devi utilizzare questo processore. Questo processore potrebbe rallentare l'applicazione.

  • (Facoltativo) Se vuoi collegare gli intervalli, importa la classe Link.

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

Configurare l'esportazione degli intervalli in Cloud Trace

Per inviare intervalli a Cloud Trace, modifica la tua applicazione per utilizzare CloudTraceSpanExporter Exporter. 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 uno span, chiama il metodo set_attribute dello span. 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 uno span, chiama il metodo add_event dello span. 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, quindi utilizza il campo links nel metodo start_as_current_span. Quando colleghi due intervalli, puoi includere attributi nel campo links.

Il seguente codice illustra due diversi modi per collegare uno span a uno 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 di traccia relativi alle richieste HTTP. Non è necessario aggiungere strumentazione specifica ai percorsi per queste richieste:

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

Per un esempio end-to-end che utilizza Flask e OpenTelemetry, consulta flask_e2e. Il Git README 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 dell'esempio. Il file client, client.py, utilizza la strumentazione Requests per consentire il tracciamento delle richieste HTTP effettuate dalla libreria requests.

Importazione e configurazione

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

Se vuoi assicurarti che gli intervalli creati da prodotti Google Cloud diversi 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 il propagatore predefinito. In questo caso, gli intervalli creati da diversi prodotti Google Cloud, come Cloud Run e App Engine, sono in tracce separate.

Il seguente esempio illustra le istruzioni di importazione e configurazione richieste e la configurazione del propagatore di 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 di Flask quando configuri l'esportatore CloudTraceSpanExporter; la configurazione mostrata nella sezione Configura l'esportazione di intervalli in Cloud Trace è sufficiente.

Contenitore iniziale

Configura FlaskInstrumentor per gestire la tua 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.

Esecuzione in Google Cloud

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

Per un elenco degli ambienti Google Cloud supportati, consulta la pagina Assistenza per l'ambiente.

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

  • Ambiente flessibile di App Engine
  • Ambiente standard di App Engine

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

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 Google Cloud Console, 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 Cloud Trace API trace.append. Ad esempio, per creare un cluster GKE con solo l'Cloud Trace API abilitata, segui questi passaggi:

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

Esecuzione locale e altrove

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

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

Per fornire queste credenziali, puoi utilizzare uno dei tre metodi seguenti:

  • Esegui gcloud auth application-default login

  • Posiziona 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 del 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"

Visualizzazione delle tracce

Dopo il deployment, puoi visualizzare le tracce in Visualizzatore Trace di Google Cloud Console.

Vai alla pagina Visualizzatore tracce

Risolvere i problemi

Per informazioni sulla risoluzione dei problemi con Cloud Trace, consulta la pagina per la risoluzione dei problemi.

Risorse