Python et OpenTelementry

Cette page est conçue pour les développeurs d'applications qui souhaitent collecter des données Cloud Trace pour les applications Python à l'aide d'OpenTelemetry. OpenTelemetry est un framework d'instrumentation neutre du fournisseur que vous pouvez utiliser pour collecter des données de trace et de métriques. Pour en savoir plus sur l'instrumentation de votre code, consultez la page Instrumentation et observabilité.

  • Installez les packages OpenTelementry.
  • Configurez votre application pour exporter les délais vers Cloud Trace.
  • Configurez votre plate-forme.

Pour en savoir plus sur les versions, consultez les articles suivants :

Pour accéder au contenu de référence d'OpenTelemetry, consultez les pages suivantes:

Pour obtenir les dernières informations sur OpenTelemetry pour Python, ainsi que de la documentation supplémentaire et des exemples, consultez la section OpenTelemetry.

Avant de commencer

  • Vous devez utiliser Python 3.6 ou version ultérieure.

  • Dans le panneau de navigation de la console Google Cloud, sélectionnez API et services, cliquez sur Activer les API et les services, puis activez l'API Cloud Trace:

    Accéder aux paramètres de l'API Cloud Trace

  • Si API activée s'affiche, l'API est déjà activée. Sinon, cliquez sur le bouton Activer.

Installer les packages OpenTelementry

Pour installer les packages OpenTelemetry requis, procédez comme suit :

  1. (Facultatif) Mettez à jour pip vers la dernière version :

    pip install --upgrade pip

  2. Installez les packages OpenTelementry suivants à l'aide de pip :

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

Importer des packages de traces

Mettez à jour votre application pour importer les packages et classes suivants :

L'exemple suivant illustre ces instructions d'importation :


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

Configurer l'exportation des délais vers Cloud Trace

Pour envoyer des délais à Cloud Trace, modifiez votre application afin d'utiliser l'exportateur CloudTraceSpanExporter. L'exemple suivant illustre les étapes requises :


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

Ajouter des attributs à un délai

Pour ajouter un attribut à un délai, appelez la méthode set_attribute du délai. Par exemple, le code suivant ajoute plusieurs attributs au délai nommé 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)

Ajouter des événements à un délai

Pour ajouter un événement à un délai, appelez la méthode add_event du délai. Par exemple, le code suivant ajoute un événement au délai nommé 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")

Pour associer deux délais, importez la classe Link, puis utilisez le champ links dans start_as_current_span. Lorsque vous associez deux délais, vous pouvez inclure des attributs dans le champ links.

Le code suivant illustre deux manières différentes d'associer un délai au délai nommé 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()

Exemple d'application Flask

L'instrumentation Flask d'OpenTelemetry est conçue pour simplifier la capture du contenu des traces associé aux requêtes HTTP. Cela signifie qu'il n'est pas nécessaire d'ajouter une instrumentation spécifique à vos routes pour ces requêtes :

  • Flask utilise l'outil de propagation configuré pour extraire le contexte de délai des requêtes HTTP entrantes.
  • Flask crée automatiquement des délais avec des attributs qui décrivent la requête et la réponse.

Pour obtenir un exemple de bout en bout avec Flask et OpenTelementry, consultez la page flask_e2e. Le fichier README de Git contient des informations sur l'installation, la configuration et l'exécution de l'exemple.

Cette section met en évidence les étapes de configuration spécifiques à Flask incluses dans le fichier server.py de l'exemple. Le fichier client client.py utilise l'instrumentation Requests pour permettre le traçage des requêtes HTTP effectuées par la bibliothèque de requêtes.

Importation et configuration

Pour utiliser l'instrumentation Flask d'OpenTelemetry, vous devez importer FlaskInstrumentor.

Lorsque vous souhaitez vous assurer que les délais créés par différents produits Google Cloud sont associés à la même trace, vous devez configurer l'outil de propagation avec l'outil de propagation Cloud Trace. Cet outil de propagation spécifie l'utilisation de l'en-tête X-Cloud-Trace-Context. Si vous ne configurez pas d'outil de propagation, OpenTelemetry utilise l'outil de propagation par défaut. Dans ce cas, les délais créés par différents produits Google Cloud, tels que Cloud Run et App Engine, se trouvent dans des traces distinctes.

L'exemple suivant illustre les instructions d'importation et de configuration requises, ainsi que la configuration de l'outil de propagation 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())

Vous n'avez pas besoin d'ajouter d'instructions spécifiques à Flask lorsque vous configurez l'exportateur CloudTraceSpanExporter ; la configuration indiquée dans la section Configurer l'exportation des délais vers Cloud Trace est suffisante.

Initialiser Flask

Configurez FlaskInstrumentor pour instrumenter votre application. L'exemple suivant montre comment effectuer cette étape :


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

Configurer votre plate-forme

Vous pouvez utiliser Cloud Trace sur Google Cloud et d'autres plates-formes.

Exécuter des applications sur Google Cloud

Lorsque votre application s'exécute sur Google Cloud, vous n'avez pas besoin de fournir des identifiants d'authentification sous la forme d'un compte de service à la bibliothèque cliente. Cependant, vous devez vous assurer que le niveau d'accès de l'API Cloud Trace est activé sur votre plate-forme Google Cloud.

Pour obtenir la liste des environnements Google Cloud compatibles, consultez la page Environnements compatibles.

Pour les configurations suivantes, les paramètres de niveau d'accès par défaut activent l'API Cloud Trace :

Si vous utilisez des niveaux d'accès personnalisés, assurez-vous que le niveau d'accès de l'API Cloud Trace est activé :

  • Pour en savoir plus sur la configuration des niveaux d'accès pour votre environnement à l'aide de la console Google Cloud, consultez la page Configurer votre projet Google Cloud.

  • Pour les utilisateurs gcloud, spécifiez les niveaux d'accès à l'aide de l'indicateur --scopes et incluez le niveau d'accès à l'API Cloud Trace trace.append. Par exemple, pour créer un cluster GKE avec uniquement l'API Cloud Trace activée, procédez comme suit :

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

Exécuter en local et depuis un autre emplacement

Si votre application s'exécute en dehors de Google Cloud, vous devez fournir les identifiants d'authentification sous la forme d'un compte de service à la bibliothèque cliente. Le compte de service doit contenir le rôle d'agent Cloud Trace. Pour savoir comment faire, consultez la page Créer un compte de service.

Les bibliothèques clientes Google Cloud utilisent les identifiants par défaut de l'application (ADC) pour trouver les identifiants de votre application.

Vous pouvez fournir ces identifiants de l'une des trois manières suivantes:

  • Exécuter gcloud auth application-default login

  • Placez le compte de service dans un chemin d'accès par défaut pour votre système d'exploitation. Voici la liste des chemins d'accès par défaut pour Windows et Linux:

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

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

  • Définissez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS pour qu'elle indique le chemin d'accès à votre compte de service:

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"

Afficher les traces

Dans le panneau de navigation de la console Google Cloud, sélectionnez Trace, puis Explorateur Trace:

Accéder à Explorateur Trace

Dépannage

Pour en savoir plus sur la résolution des problèmes liés à Cloud Trace, consultez la page Dépannage.

Ressources