Se usó la API de Cloud Translation para traducir esta página.
Switch to English

Python y OpenTelemetry

Esta página está diseñada para desarrolladores de aplicaciones que deseen recopilar datos de Cloud Trace para aplicaciones de Python mediante OpenTelemetry. OpenTelemetry es un conjunto de bibliotecas de instrumentación para recopilar datos de seguimiento y métricas. Estas bibliotecas funcionan con varios backends. Para recopilar seguimientos con OpenTelemetry y Python, puedes hacer lo siguiente, como se describe en esta página:

  • Instala los paquetes de OpenTelemetry.
  • Configura tu aplicación para exportar intervalos a Cloud Trace.
  • Configura tu plataforma.

A fin de obtener los últimos detalles sobre OpenTelemetry para Python, junto con documentación y ejemplos adicionales, consulta OpenTelemetry.

Antes de comenzar

  1. Debes usar Python 3.6 o una versión superior.
  2. Verifica que la API de Cloud Trace esté habilitada para tu proyecto de Google Cloud:

    1. Haz clic en el siguiente botón o, en Google Cloud Console, selecciona API y servicios y, luego, API de Cloud Trace:

      Ir a la API de Trace

    2. En la página API de Cloud Trace, si se muestra un botón con la etiqueta Habilitar, haz clic en él. Si no se muestra este botón, la API de Cloud Trace se habilita para el proyecto seleccionado.

Instala los paquetes de OpenTelemetry

Para instalar los paquetes de OpenTelemetry necesarios, haz lo siguiente:

  1. (Opcional) Actualiza a la última versión de pip:

    pip install --upgrade pip
    
  2. Instala los siguientes paquetes de OpenTelemetry con pip:

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

Importar paquetes de seguimiento

Actualiza tu aplicación para importar los siguientes paquetes y clases:

  • trace
  • CloudTraceSpanExporter
  • TracerProvider
  • Un procesador de intervalo de exportación:

    • Para enviar intervalos con un proceso en segundo plano, usa el procesador BatchSpanProcessor. Te recomendamos que uses este procesador a menos que uses Cloud Run. Cloud Run no admite procesos en segundo plano.

    • Para enviar intervalos con un proceso en primer plano, usa el procesador SimpleSpanProcessor. Si usas Cloud Run, debes usar este procesador. Este procesador puede ralentizar tu aplicación.

  • (Opcional) Si deseas vincular intervalos, importa la clase Link.

En el siguiente ejemplo, se muestran estas instrucciones de importación:


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 la exportación de intervalos a Cloud Trace

Si deseas enviar intervalos a Cloud Trace, modifica la aplicación para que use el exportador CloudTraceSpanExporter. El siguiente ejemplo ilustra los pasos necesarios:


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__)

Cómo agregar atributos a un intervalo

Para agregar un atributo a un intervalo, llama al método set_attribute del intervalo. Por ejemplo, el siguiente código agrega varios atributos al intervalo llamado 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)

Cómo agregar eventos a un intervalo

Para agregar un evento a un intervalo, llama al método add_event del intervalo. Por ejemplo, el siguiente código agrega un evento al intervalo llamado 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")

Para vincular dos intervalos, importa laLink de la clase y, luego, usar lalinks campo en elstart_as_current_span. Cuando vinculas dos intervalos, puedes incluir atributos en el campo links.

El siguiente código ilustra dos maneras diferentes de vincular un intervalo al intervalo llamado 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()

Aplicación de muestra de Flask

La instrumentación de Flask de Telemetry está diseñada para simplificar la captura del contenido de seguimiento relacionado con las solicitudes HTTP. Esto significa que no necesitas agregar instrumentación específica a tus rutas para estas solicitudes:

  • Flask usa el propagador configurado para extraer el contexto de intervalo de las solicitudes HTTP entrantes.
  • Flask crea intervalos automáticamente con atributos que describen la solicitud y la respuesta.

Para obtener un ejemplo de extremo a extremo con Flask y OpenTelemetry, consulta flask_e2e. El archivo README de Git incluye información sobre cómo instalar, configurar y ejecutar el ejemplo.

En esta sección, se destacan los pasos de configuración específicos de Flask que se incluyen en el archivo server.py del ejemplo. El archivo de cliente, client.py, usa la instrumentación Requests para habilitar el seguimiento de las solicitudes HTTP que realiza la biblioteca requests.

Importación y configuración

Para usar la instrumentación de Flask de OpenTelemetry, debes importar el FlaskInstrumentor.

Cuando quieras asegurarte de que los intervalos creados por diferentes productos de Google Cloud estén asociados con el mismo seguimiento, debes configurar el propagador con el propagador de Cloud Trace. Este propagación especifica el uso del encabezado X-Cloud-Trace-Context. Si no configuras un propagador, OpenTelemetry usa el propagador predeterminado. En este caso, los intervalos creados por diferentes productos de Google Cloud, como Cloud Run y App Engine, se encuentran en seguimientos diferentes.

En el siguiente ejemplo, se muestran las instrucciones de importación y configuración obligatorias, así como la configuración del propagador de Cloud Trace:


import time

from flask import Flask
from opentelemetry import trace
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.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

set_global_textmap(CloudTraceFormatPropagator())

No es necesario agregar ninguna instrucción específica de Flask cuando configuras el exportador CloudTraceSpanExporter. la configuración que se muestra en Configura la exportación de intervalos a Cloud Trace es suficiente.

Cómo inicializar Flask

Configura el FlaskInstrumentor para instrumentar tu aplicación. En el siguiente ejemplo, se muestra cómo realizar este paso:


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 tu plataforma

Puedes usar Cloud Trace en Google Cloud y otras plataformas.

Ejecuta en Google Cloud

Cuando tu aplicación se ejecuta en Google Cloud, no necesitas proporcionar credenciales de autenticación en el formato de una cuenta de servicio a la biblioteca cliente. Sin embargo, debes asegurarte de que tu plataforma de Google Cloud tenga habilitado el permiso de acceso a la API de Cloud Trace.

Para las siguientes opciones de configuración, la configuración predeterminada del permiso de acceso habilita la API de Cloud Trace:

  • Entorno flexible de App Engine
  • Entorno estándar de App Engine

  • Google Kubernetes Engine (GKE)

  • Compute Engine

Si usas niveles de acceso personalizados, debes asegurarte de que el nivel de acceso a la API de Cloud Trace esté habilitado. Para los usuarios de gcloud, especifica los niveles de acceso con la marca --scopes y, también, incluye el permiso de acceso a la API de Cloud Trace trace.append. Por ejemplo, para crear un clúster de GKE solo con la API de Cloud Trace habilitada, sigue estos pasos:

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

Ejecuta de forma local y en otros lugares

Si tu aplicación se ejecuta fuera de Google Cloud, debes proporcionar credenciales de autenticación en forma de una cuenta de servicio a la biblioteca cliente. La cuenta de servicio debe contener la función de agente de Cloud Trace. Para obtener más instrucciones, consulta Cómo crear una cuenta de servicio.

Las bibliotecas cliente de Google Cloud usan las credenciales predeterminadas de la aplicación (ADC) para encontrar las credenciales de tu aplicación. Estas credenciales se proporcionan mediante la configuración de la variable de entorno GOOGLE_APPLICATION_CREDENTIALS:

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"

Cómo ver los seguimientos

Después de la implementación, puedes ver los seguimientos en el visor de seguimientos de Cloud Console.

Ir a la página del Lector de seguimiento

Soluciona problemas

Para obtener información sobre cómo solucionar problemas con Cloud Trace, ve a la página de solución de problemas.

Recursos