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 framework de instrumentación independiente del proveedor que puedes usar para recopilar datos de seguimiento y de métricas. Para obtener información sobre cómo instrumentar tu código, consulta Instrumentación y observabilidad.

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

Para obtener información de la versión, consulta lo siguiente:

Para obtener contenido de referencia de OpenTelemetry, consulta lo siguiente:

Si quieres obtener los detalles más recientes sobre OpenTelemetry para Python, junto con documentación y ejemplos adicionales, consulta OpenTelemetry.

Antes de comenzar

  • Debes usar Python 3.6 o una versión posterior.

  • En el panel de navegación de la consola de Google Cloud, selecciona APIs y servicios, haz clic en Habilitar APIs y servicios y, luego, habilita la API de Cloud Trace:

    Ir a la configuración de la API de Cloud Trace

  • Si aparece API habilitada, la API ya está habilitada. De lo contrario, haz clic en el botón Habilitar.

Instala los paquetes de OpenTelemetry

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

  1. (Opcional) Actualiza a la versión más reciente 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

Cómo importar paquetes de seguimiento

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

En el siguiente ejemplo, se ilustran estas sentencias 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 tu aplicación para usar el exportador CloudTraceSpanExporter. En el siguiente ejemplo, se muestran 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 la clase Link y, luego, usa el campo links en el método start_as_current_span. Cuando vinculas dos intervalos, puedes incluir atributos en el campo links.

En el siguiente código, se muestran dos formas diferentes de vincular un 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 OpenTelemetry está diseñada para simplificar la captura de contenido de seguimiento relacionado con 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 automáticamente intervalos con atributos que describen la solicitud y la respuesta.

Para ver un ejemplo de extremo a extremo con Flask y OpenTelemetry, consulta flask_e2e. El archivo README de Git incluye información para 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 de ejemplo. El archivo cliente, client.py, usa la instrumentación Requests para habilitar el seguimiento de las solicitudes HTTP realizadas por la biblioteca de solicitudes.

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 propagador especifica el uso del encabezado X-Cloud-Trace-Context. Si no configuras un propagador, OpenTelemetry usa el predeterminado. En este caso, los intervalos creados por diferentes productos de Google Cloud, como Cloud Run y App Engine, se encuentran en seguimientos separados.

En el siguiente ejemplo, se ilustran las declaraciones necesarias de importación y configuración, y la configuración del propagador de 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())

No es necesario agregar ninguna declaració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.

Inicializa 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!"

Cómo configurar 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 obtener una lista de los entornos de Google Cloud compatibles, consulta Compatibilidad de entornos.

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

Si usas permisos de acceso personalizados, debes asegurarte de que el permiso de acceso a la API de Cloud Trace esté habilitado:

  • Si quieres obtener información para configurar los permisos de acceso de tu entorno mediante la consola de Google Cloud, consulta Configura tu proyecto de Google Cloud.

  • 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.

Puedes proporcionar estas credenciales de una de estas tres maneras:

  • Ejecución gcloud auth application-default login

  • Coloca la cuenta de servicio en una ruta predeterminada para tu sistema operativo. A continuación, se enumeran las rutas de acceso predeterminadas para Windows y Linux:

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

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

  • Establece la variable de entorno GOOGLE_APPLICATION_CREDENTIALS como la ruta a tu cuenta de servicio:

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"

Ver seguimientos

En el panel de navegación de la consola de Google Cloud, selecciona Trace y, luego, Explorador de seguimiento:

Ve al Explorador 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