Instrumenter les bibliothèques clientes Python Google Cloud

Ce guide explique comment configurer et utiliser le traçage distribué OpenTelemetry dans les bibliothèques clientes Google Cloud Python.

Présentation

Google Cloud Les bibliothèques clientes Python fournissent un traçage distribué OpenTelemetry intégré. Cette instrumentation offre une visibilité approfondie sur les opérations client, les appels RPC, le comportement des nouvelles tentatives, la latence du réseau et les réponses du service, sans nécessiter de monkey-patching manuel.

Principales caractéristiques :

  • Indépendant du backend : émet des segments OpenTelemetry standards. Vous pouvez exporter des traces directement vers Cloud Trace, un collecteur OpenTelemetry sur site ou des plates-formes d'observabilité tierces.
  • Activation : le traçage distribué est désactivé par défaut pour éviter une surcharge d'exécution pour les applications qui ne nécessitent pas de télémétrie.
  • Propagation du contexte : les segments se lient automatiquement au contexte de trace OpenTelemetry actif à l'aide de la fonction contextvars intégrée de Python, ce qui permet de mettre en corrélation les appels client avec les requêtes HTTP/gRPC entrantes.

Fonctionnement du traçage (hiérarchie des segments)

Lorsqu'elles sont activées, les bibliothèques clientes Google Cloud Python émettent une architecture de segment hiérarchique à deux niveaux qui sépare clairement l'exécution des méthodes visibles par l'utilisateur des tentatives de connexion sous-jacentes :

[Logical Client Method Span] (Parent: covers full method duration, retries, and backoff)
 │
 ├── [Network Attempt Span #1] (Child: First wire call; e.g. transient 503 UNAVAILABLE)
 └── [Network Attempt Span #2] (Child: Retry wire call; succeeds 200 OK)

1. Segments de méthode client logique (parent)

  • Champ d'application : encapsule l'intégralité du cycle de vie de l'appel de méthode de la bibliothèque cliente, de l'appel à l'achèvement.
  • Durée : couvre toutes les tentatives, les pauses d'intervalle exponentiel entre les tentatives et les règles de délai avant expiration.
  • Identité : nommée d'après la méthode RPC complète (par exemple, google.cloud.secretmanager.v1.SecretManagerService/GetSecretVersion).
  • Attributs : capture les métadonnées RPC logiques, le service de destination et le résultat final de haut niveau.

2. Segments de tentative réseau (enfant)

  • Champ d'application : créés en tant que segments enfants du segment de méthode logique, représentant des tentatives de réseau physique HTTP/REST ou gRPC individuelles.
  • Cycle de vie : un nouveau segment est généré pour chaque tentative de connexion au réseau. Si une opération réussit du premier coup, un seul segment enfant est enregistré. Si une opération rencontre des erreurs temporaires et effectue de nouvelles tentatives, chaque tentative est enregistrée en tant que segment enfant indépendant avec sa propre durée et son propre état.
  • Attributs : capture les codes d'état de connexion de bas niveau, l'adresse du serveur de destination et les détails du transport.

Prérequis et installation

Google Cloud Le traçage de la bibliothèque cliente Python repose sur les packages Python OpenTelemetry standards.

1. Installer les packages

  • Instrumentation de la bibliothèque cliente et du transport gRPC :

    • opentelemetry-api est installé automatiquement avec google-api-core pour prendre en charge les segments de méthode logique et les segments de transport HTTP/REST (rest).
    • Pour enregistrer également les segments de transport gRPC de bas niveau, installez votre bibliothèque cliente avec google-api-core[tracing] (qui installe opentelemetry-instrumentation-grpc) :
    pip install google-cloud-secret-manager "google-api-core[tracing]"

  • SDK OpenTelemetry (pour les applications autonomes et les exemples de code) :

    • Les bibliothèques clientes ne nécessitent pas opentelemetry-sdk si votre environnement fournit déjà un TracerProvider.
    • Toutefois, pour configurer un TracerProvider et exporter des segments dans votre propre code (y compris les exemples de cette page), installez opentelemetry-sdk :
    pip install opentelemetry-sdk

Pour savoir comment configurer les exportateurs OpenTelemetry afin d'envoyer des segments à Cloud Trace ou à un collecteur OpenTelemetry en production, consultez Configurer Python avec OpenTelemetry et Choisir une approche d'instrumentation.

Activer le traçage

Le traçage distribué peut être activé de manière globale à l'aide d'une variable d'environnement ou de manière programmatique pour chaque client. La configuration par client transmise à l'aide de ClientOptions prévaut sur les paramètres des variable d'environnement.

Option 1 : Configuration globale (variables d'environnement)

Pour activer le traçage sur toutes les bibliothèques clientes Google Cloud Python compatibles de votre environnement, définissez la variable d'environnement suivante avant de démarrer votre application :

export GOOGLE_SDK_PYTHON_TRACING_ENABLED=true

Lorsqu'elles sont définies sur true, les bibliothèques clientes détectent automatiquement l'TracerProvider OpenTelemetry enregistré de manière globale et émettent des segments pour tous les appels client.

Option 2 : Configuration par client (code)

Pour un contrôle précis ou des applications mutualisées, configurez une instance de client spécifique en transmettant un tracer_provider à l'aide de ClientOptions :

from google.api_core.client_options import ClientOptions
from google.cloud import secretmanager

options = ClientOptions(tracer_provider=my_tracer_provider)
client = secretmanager.SecretManagerServiceClient(client_options=options)

Exemples de code

Les bibliothèques clientes peuvent utiliser les identifiants par défaut de l'application pour s'authentifier facilement auprès des API Google et envoyer des requêtes à ces API. Avec les identifiants par défaut de l'application, vous pouvez tester votre application localement et la déployer sans modifier le code sous-jacent. Pour en savoir plus, consultez la section S'authentifier à l'aide des bibliothèques clientes.

1. Exemple de démarrage rapide (SecretManagerServiceClient)

L'exemple autonome suivant montre comment configurer OpenTelemetry standard, activer le traçage de la bibliothèque cliente à l'aide d'une variable d'environnement et imprimer les segments émis directement dans le terminal au format JSON à l'aide de ConsoleSpanExporter.

import os

from google.cloud import secretmanager
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor


def get_secret_version_with_tracing(
    project_id: str,
    secret_id: str,
    version_id: str = "latest",
) -> secretmanager.SecretVersion:
    """Get a secret version in Secret Manager with OpenTelemetry tracing enabled.

    Args:
        project_id: Google Cloud project ID.
        secret_id: ID of the secret.
        version_id: ID of the secret version (defaults to "latest").

    Returns:
        The SecretVersion metadata object.
    """
    # NOTE: In standalone scripts or CLI tools, initialize and shut down the
    # TracerProvider within the script workflow. In long-running production
    # applications (e.g., web servers), configure the TracerProvider once at
    # application startup.
    #
    # Initialize the OpenTelemetry TracerProvider with a Console exporter
    provider = TracerProvider()
    provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
    trace.set_tracer_provider(provider)

    # Enable Google Cloud client library tracing
    os.environ["GOOGLE_SDK_PYTHON_TRACING_ENABLED"] = "true"

    # Instantiate the client (automatically discovers the active TracerProvider)
    client = secretmanager.SecretManagerServiceClient()

    # Construct the resource name and invoke the RPC
    name = f"projects/{project_id}/secrets/{secret_id}/versions/{version_id}"

    try:
        print("--- OpenTelemetry Trace Spans (JSON) ---")
        response = client.get_secret_version(request={"name": name})
        state_name = response.state.name
        print(
            f"\nAPI Result: Retrieved secret version {response.name} (state: {state_name})"
        )
        return response
    finally:
        # Flush buffered spans before program completion
        provider.shutdown()

2. Configuration programmatique (ClientOptions)

Si vous préférez ne pas utiliser de variables d'environnement ou si vous devez transmettre différentes instances TracerProvider à différents clients, configurez un client de manière programmatique en transmettant tracer_provider à l'aide de ClientOptions :

from google.api_core.client_options import ClientOptions
from google.cloud import secretmanager
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor


def get_secret_version_with_client_options(
    project_id: str,
    secret_id: str,
    version_id: str = "latest",
) -> secretmanager.SecretVersion:
    """Get a secret version configuring tracing programmatically via ClientOptions.

    Args:
        project_id: Google Cloud project ID.
        secret_id: ID of the secret.
        version_id: ID of the secret version (defaults to "latest").

    Returns:
        The SecretVersion metadata object.
    """
    # Initialize an independent TracerProvider (no global registration required)
    provider = TracerProvider()
    provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))

    # Pass the TracerProvider directly via ClientOptions
    # Tracing is activated specifically for this client instance, even without
    # setting the GOOGLE_SDK_PYTHON_TRACING_ENABLED environment variable.
    options = ClientOptions(tracer_provider=provider)
    client = secretmanager.SecretManagerServiceClient(client_options=options)

    # Construct resource name and invoke RPC
    name = f"projects/{project_id}/secrets/{secret_id}/versions/{version_id}"

    try:
        print("--- OpenTelemetry Trace Spans (JSON) ---")
        response = client.get_secret_version(request={"name": name})
        state_name = response.state.name
        print(
            f"\nAPI Result: Retrieved secret version {response.name} (state: {state_name})"
        )
        return response
    finally:
        # Flush buffered spans before program completion
        provider.shutdown()

3. Exemple de client asynchrone (SecretManagerServiceAsyncClient)

L'exemple suivant définit une coroutine asynchrone (async def get_secret_version_with_tracing_async) à l'aide de SecretManagerServiceAsyncClient. Comme ce client est asynchrone, veillez à l'exécuter dans une boucle d'événements asyncio active.

import asyncio
import os

from google.cloud import secretmanager
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor


async def get_secret_version_with_tracing_async(
    project_id: str,
    secret_id: str,
    version_id: str = "latest",
) -> secretmanager.SecretVersion:
    """Get a secret version using SecretManagerServiceAsyncClient with OpenTelemetry tracing.

    Args:
        project_id: Google Cloud project ID.
        secret_id: ID of the secret.
        version_id: ID of the secret version (defaults to "latest").

    Returns:
        The SecretVersion metadata object.
    """
    # NOTE: In standalone scripts or CLI tools, initialize and shut down the
    # TracerProvider within the script workflow. In long-running production
    # applications (e.g., web servers), configure the TracerProvider once at
    # application startup.
    #
    # Initialize the OpenTelemetry TracerProvider with a Console exporter
    provider = TracerProvider()
    provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
    trace.set_tracer_provider(provider)

    # Enable Google Cloud client library tracing
    os.environ["GOOGLE_SDK_PYTHON_TRACING_ENABLED"] = "true"

    # Instantiate the async client
    client = secretmanager.SecretManagerServiceAsyncClient()

    # Construct resource name and invoke the async RPC
    name = f"projects/{project_id}/secrets/{secret_id}/versions/{version_id}"

    try:
        print("--- OpenTelemetry Trace Spans (JSON) ---")
        response = await client.get_secret_version(request={"name": name})
        state_name = response.state.name
        print(
            f"\nAPI Result: Retrieved secret version {response.name} (state: {state_name})"
        )
        return response
    finally:
        # Flush buffered spans before program completion
        provider.shutdown()

Référence des attributs sémantiques

Les délais émis par les bibliothèques clientes Python Google Cloud respectent les conventions sémantiques OpenTelemetry standards pour les délais RPC, en enregistrant les métadonnées standards pour le protocole de transport, l'identité de la méthode RPC, l'adresse du serveur de destination, les codes d'état de réponse et les détails des erreurs. Vous pouvez utiliser ces attributs pour filtrer, agréger et créer des règles d'alerte dans votre tableau de bord d'observabilité ou Cloud Trace.

Sécurité et données sensibles

Google Cloud L'instrumentation de la bibliothèque cliente Python est conçue selon des normes de sécurité et de confidentialité strictes :

  • Protection de la charge utile : les bibliothèques clientes n'enregistrent jamais les données de charge utile de requête ou de réponse (telles que le contenu des fichiers, les valeurs secrètes ou les résultats de requêtes de base de données) sur les segments de trace.
  • Visibilité des identifiants : les noms de ressources (tels que les ID de projet, les ID d'ensemble de données et les noms de secrets) apparaissent dans les paramètres de méthode et les attributs de point de terminaison d'URL. Si les identifiants de ressources contiennent des informations commerciales sensibles, assurez-vous que votre stockage de traces est conforme à vos règles de conformité internes.
  • Exportateurs tiers : lorsque vous exportez des traces vers des services d'observabilité tiers ou des fournisseurs SaaS, consultez les accords de protection des données de votre organisation et configurez le filtrage des attributs de l'exportateur si nécessaire.