Como instrumentar bibliotecas de cliente Python do Cloud de Confiance by S3NS

Neste guia, demonstramos como configurar e usar o rastreamento distribuído do OpenTelemetry nas bibliotecas de cliente do Python do Cloud de Confiance by S3NS .

Visão geral

Cloud de Confiance by S3NS As bibliotecas de cliente do Python oferecem rastreamento distribuído integrado do OpenTelemetry. Essa instrumentação oferece visibilidade profunda das operações do cliente, invocações de RPC, comportamento de repetição, latência de rede e respostas de serviço sem exigir monkey-patching manual.

Principais características:

  • Independente de back-end: emite períodos padrão do OpenTelemetry. É possível exportar traces diretamente para o Cloud Trace, um coletor do OpenTelemetry no local ou plataformas de observabilidade de terceiros.
  • Ativação: o rastreamento distribuído é desativado por padrão para evitar sobrecarga de ambiente de execução em aplicativos que não exigem telemetria.
  • Propagação de contexto: os períodos se vinculam automaticamente ao contexto de trace ativo do OpenTelemetry usando o contextvars integrado do Python, correlacionando chamadas de cliente com solicitações HTTP/gRPC recebidas.

Como o rastreamento funciona (hierarquia de períodos)

Quando ativadas, as bibliotecas de cliente do Python do Cloud de Confiance by S3NS emitem uma arquitetura de período hierárquica de dois níveis que separa claramente a execução do método voltado ao usuário das tentativas de conexão subjacentes:

[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. Períodos de método de cliente lógico (pai)

  • Escopo: encapsula todo o ciclo de vida da chamada de método da biblioteca de cliente, da invocação à conclusão.
  • Duração: abrange todas as tentativas de repetição, pausas de espera exponencial e políticas de tempo limite.
  • Identidade: nomeado de acordo com o método RPC totalmente qualificado (por exemplo, google.cloud.secretmanager.v1.SecretManagerService/GetSecretVersion).
  • Atributos: captura metadados lógicos de RPC, o serviço de destino e o resultado final de alto nível.

2. Períodos de tentativa de rede (secundários)

  • Escopo: criados como períodos filhos do período do método lógico, representando tentativas individuais de rede física HTTP/REST ou gRPC.
  • Ciclo de vida: um novo período é gerado para cada tentativa de rede. Se uma operação for bem-sucedida na primeira tentativa, exatamente um período filho será registrado. Se uma operação encontrar erros temporários e tentar novamente, cada tentativa será registrada como um período filho independente com o próprio tempo e status.
  • Atributos: captura códigos de status de conexão de baixo nível, endereço do servidor de destino e detalhes de transporte.

Pré-requisitos e instalação

Cloud de Confiance by S3NS O trace da biblioteca de cliente do Python depende de pacotes padrão do OpenTelemetry para Python.

1. Instalar pacotes

  • Biblioteca de cliente e instrumentação de transporte gRPC:

    • O opentelemetry-api é instalado automaticamente com o google-api-core para oferecer suporte a períodos de método lógico e períodos de transporte HTTP/REST (rest).
    • Para também registrar períodos de transporte gRPC de baixo nível, instale a biblioteca de cliente com google-api-core[tracing] (que instala opentelemetry-instrumentation-grpc):
    pip install google-cloud-secret-manager "google-api-core[tracing]"

  • SDK do OpenTelemetry (para apps independentes e exemplos de código):

    • As bibliotecas de cliente não exigem opentelemetry-sdk se o ambiente já fornece um TracerProvider.
    • No entanto, para configurar um TracerProvider e exportar períodos no seu próprio código (incluindo os exemplos nesta página), instale opentelemetry-sdk:
    pip install opentelemetry-sdk

Para instruções sobre como configurar exportadores do OpenTelemetry para enviar períodos ao Cloud Trace ou a um coletor do OpenTelemetry em produção, consulte Configurar o Python com o OpenTelemetry e Escolher uma abordagem de instrumentação.

Como ativar o rastreamento

O rastreamento distribuído pode ser ativado globalmente usando uma variável de ambiente ou programaticamente por cliente. A configuração por cliente transmitida usando ClientOptions tem precedência sobre as configurações variável de ambiente.

Opção 1: configuração global (variáveis de ambiente)

Para ativar o trace em todas as bibliotecas de cliente do Python Cloud de Confiance by S3NS compatíveis no seu ambiente, defina a seguinte variável de ambiente antes de iniciar o aplicativo:

export GOOGLE_SDK_PYTHON_TRACING_ENABLED=true

Quando definido como true, as bibliotecas de cliente detectam automaticamente o TracerProvider do OpenTelemetry registrado globalmente e emitem períodos para todas as invocações de cliente.

Opção 2: configuração por cliente (código)

Para controle refinado ou aplicativos multilocatários, configure uma instância de cliente específica transmitindo um tracer_provider usando 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)

Exemplos de código

As bibliotecas de cliente podem usar o Application Default Credentials para se autenticar facilmente nas APIs do Google e enviar solicitações para elas. Com o Application Default Credentials, é possível testar seu aplicativo localmente e implantá-lo sem alterar o código. Para mais informações, consulte Autenticação para usar bibliotecas de cliente.

1. Exemplo de início rápido (SecretManagerServiceClient)

O exemplo independente a seguir demonstra como configurar o OpenTelemetry padrão, ativar o rastreamento da biblioteca de cliente usando uma variável de ambiente e imprimir períodos emitidos diretamente no terminal como JSON usando 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. Configuração programática (ClientOptions)

Se você preferir não usar variáveis de ambiente ou precisar transmitir instâncias TracerProvider diferentes para clientes diferentes, configure um cliente de maneira programática transmitindo tracer_provider usando 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. Exemplo de cliente assíncrono (SecretManagerServiceAsyncClient)

O exemplo a seguir define uma corrotina assíncrona (async def get_secret_version_with_tracing_async) usando SecretManagerServiceAsyncClient. Como esse cliente é assíncrono, execute-o em um loop de eventos asyncio ativo.

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

Referência de atributos semânticos

Os períodos emitidos pelas bibliotecas de cliente do Python do Cloud de Confiance by S3NS seguem as convenções semânticas do OpenTelemetry para períodos de RPC, registrando metadados padrão para o protocolo de transporte, a identidade do método RPC, o endereço do servidor de destino, os códigos de status de resposta e os detalhes do erro. Use esses atributos para filtrar, agregar e criar políticas de alerta no painel de observabilidade ou do Cloud Trace.

Segurança e dados sensíveis

Cloud de Confiance by S3NS A instrumentação da biblioteca de cliente do Python foi projetada de acordo com padrões rígidos de segurança e privacidade:

  • Proteção de payload: as bibliotecas de cliente nunca registram dados de payload de solicitação ou resposta (como conteúdo de arquivos, valores secretos ou resultados de consultas de banco de dados) em períodos de trace.
  • Visibilidade do identificador: os nomes dos recursos (como IDs de projetos, IDs de conjuntos de dados e nomes de secrets) aparecem nos parâmetros de método e nos atributos de endpoint de URL. Se os identificadores de recursos contiverem informações comerciais sensíveis, verifique se o armazenamento de traces está em conformidade com as políticas de compliance internas.
  • Exportadores de terceiros: ao exportar traces para serviços de observabilidade de terceiros ou fornecedores de SaaS, analise os contratos de proteção de dados da sua organização e configure a filtragem de atributos do exportador, se necessário.