Instrumenta las bibliotecas cliente de Python de Cloud de Confiance by S3NS

En esta guía, se muestra cómo configurar y usar el seguimiento distribuido de OpenTelemetry en las bibliotecas cliente de Python de Cloud de Confiance by S3NS .

Descripción general

Cloud de Confiance by S3NS Las bibliotecas cliente de Python proporcionan seguimiento distribuido integrado de OpenTelemetry. Esta instrumentación ofrece una visibilidad profunda de las operaciones del cliente, las invocaciones de RPC, el comportamiento de reintento, la latencia de red y las respuestas del servicio sin necesidad de realizar parches manuales.

Características clave:

  • Independiente del backend: Emite intervalos estándar de OpenTelemetry. Puedes exportar seguimientos directamente a Cloud Trace, un recopilador de OpenTelemetry local o plataformas de observabilidad de terceros.
  • Habilitación: El seguimiento distribuido está inhabilitado de forma predeterminada para evitar la sobrecarga del entorno de ejecución en las aplicaciones que no requieren telemetría.
  • Propagación de contexto: Los intervalos se vinculan automáticamente al contexto de seguimiento activo de OpenTelemetry con el contextvars integrado de Python, lo que correlaciona las llamadas de cliente con las solicitudes HTTP/gRPC entrantes.

Cómo funciona el seguimiento (jerarquía de intervalos)

Cuando están habilitadas, las bibliotecas cliente de Python de Cloud de Confiance by S3NS emiten una arquitectura de intervalos jerárquica de dos niveles que separa claramente la ejecución de métodos para el usuario de los intentos de conexión subyacentes:

[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. Intervalos de métodos lógicos del cliente (superior)

  • Alcance: Encapsula todo el ciclo de vida de la llamada de método de la biblioteca cliente, desde la invocación hasta la finalización.
  • Duración: Abarca todos los intentos de reintento, las pausas de retirada exponencial y las políticas de tiempo de espera.
  • Identidad: Se nombra según el método de RPC completamente calificado (por ejemplo, google.cloud.secretmanager.v1.SecretManagerService/GetSecretVersion).
  • Atributos: Captura metadatos lógicos de RPC, el servicio de destino y el resultado final de alto nivel.

2. Intervalos de intentos de red (secundarios)

  • Alcance: Se crean como intervalos secundarios del intervalo del método lógico, que representan intentos de red física HTTP/REST o gRPC individuales.
  • Ciclo de vida: Se genera un intervalo nuevo para cada intento de red. Si una operación se realiza correctamente en el primer intento, se registra exactamente un intervalo secundario. Si una operación encuentra errores transitorios y reintentos, cada intento se registra como un intervalo secundario independiente con su propio tiempo y estado.
  • Atributos: Captura códigos de estado de conexión de bajo nivel, la dirección del servidor de destino y los detalles del transporte.

Requisitos previos y configuración

Cloud de Confiance by S3NS La biblioteca cliente de Python para el seguimiento se basa en los paquetes estándar de OpenTelemetry para Python.

1. Instalar paquetes

  • Instrumentación de transporte de gRPC y biblioteca cliente:

    • opentelemetry-api se instala automáticamente con google-api-core para admitir intervalos de métodos lógicos y de transporte HTTP/REST (rest).
    • Para registrar también intervalos de transporte gRPC de bajo nivel, instala la biblioteca cliente junto con google-api-core[tracing] (que instala opentelemetry-instrumentation-grpc):
    pip install google-cloud-secret-manager "google-api-core[tracing]"

  • SDK de OpenTelemetry (para apps independientes y muestras de código):

    • Las bibliotecas cliente no requieren opentelemetry-sdk si tu entorno ya proporciona un TracerProvider.
    • Sin embargo, para configurar un TracerProvider y exportar intervalos en tu propio código (incluidas las muestras de esta página), instala opentelemetry-sdk:
    pip install opentelemetry-sdk

Para obtener instrucciones sobre cómo configurar los exportadores de OpenTelemetry para enviar intervalos a Cloud Trace o a un recopilador de OpenTelemetry en producción, consulta Configura Python con OpenTelemetry y Elige un enfoque de instrumentación.

Habilita el seguimiento

El seguimiento distribuido se puede habilitar de forma global con una variable de entorno o de manera programática por cliente. La configuración por cliente que se pasa con ClientOptions tiene prioridad sobre la configuración de variable de entorno.

Opción 1: Configuración global (variables de entorno)

Para habilitar el seguimiento en todas las bibliotecas cliente de Python Cloud de Confiance by S3NS compatibles en tu entorno, establece la siguiente variable de entorno antes de iniciar la aplicación:

export GOOGLE_SDK_PYTHON_TRACING_ENABLED=true

Cuando se establece en true, las bibliotecas cliente detectan automáticamente el TracerProvider de OpenTelemetry registrado de forma global y emiten intervalos para todas las invocaciones de clientes.

Opción 2: Configuración por cliente (código)

Para un control detallado o aplicaciones de múltiples usuarios, configura una instancia de cliente específica pasando un tracer_provider con 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)

Ejemplos de código

Las bibliotecas cliente pueden usar credenciales predeterminadas de la aplicación para autenticarse de manera sencilla con las APIs de Google y enviarles solicitudes. Con las credenciales predeterminadas de la aplicación, puedes probar tu aplicación de forma local y, luego, implementarla sin cambiar el código subyacente. Para obtener más información, consulta Autentícate para usar las bibliotecas cliente.

1. Ejemplo de guía de inicio rápido (SecretManagerServiceClient)

En el siguiente ejemplo independiente, se muestra cómo configurar OpenTelemetry estándar, habilitar el seguimiento de la biblioteca cliente con una variable de entorno y mostrar los intervalos emitidos directamente en la terminal como JSON con 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. Configuración programática (ClientOptions)

Si prefieres no usar variables de entorno o necesitas pasar diferentes instancias de TracerProvider a diferentes clientes, configura un cliente de manera programática pasando tracer_provider con 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. Ejemplo de cliente asíncrono (SecretManagerServiceAsyncClient)

En el siguiente ejemplo, se define una corrutina asíncrona (async def get_secret_version_with_tracing_async) con SecretManagerServiceAsyncClient. Debido a que este cliente es asíncrono, asegúrate de ejecutarlo dentro de un bucle de eventos asyncio activo.

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

Referencia de atributos semánticos

Los intervalos que emiten las bibliotecas cliente de Python para Cloud de Confiance by S3NS cumplen con las convenciones semánticas de OpenTelemetry para intervalos de RPC estándar, lo que registra metadatos estándar para el protocolo de transporte, la identidad del método de RPC, la dirección del servidor de destino, los códigos de estado de respuesta y los detalles de los errores. Puedes usar estos atributos para filtrar, agregar y crear políticas de alertas en tu panel de observabilidad o de Cloud Trace.

Seguridad y datos sensibles

Cloud de Confiance by S3NS La instrumentación de la biblioteca cliente de Python se diseñó siguiendo estrictos estándares de seguridad y privacidad:

  • Protección de la carga útil: Las bibliotecas cliente nunca registran datos de carga útil de solicitud o respuesta (como contenido de archivos, valores de secretos o resultados de consultas de bases de datos) en intervalos de seguimiento.
  • Visibilidad de identificadores: Los nombres de los recursos (como los IDs de proyectos, los IDs de conjuntos de datos y los nombres de secretos) aparecen en los parámetros de métodos y los atributos de extremos de URLs. Si los identificadores de recursos contienen información empresarial sensible, asegúrate de que el almacenamiento de seguimientos cumpla con tus políticas de cumplimiento internas.
  • Exportadores de terceros: Cuando exportes seguimientos a servicios de observabilidad de terceros o proveedores de SaaS, revisa los acuerdos de protección de datos de tu organización y configura el filtrado de atributos del exportador si es necesario.