Google Cloud Python-Clientbibliotheken instrumentieren

In diesem Leitfaden wird beschrieben, wie Sie die verteilte OpenTelemetry-Ablaufverfolgung in Python-Clientbibliotheken von Google Cloud konfigurieren und verwenden.

Übersicht

Google Cloud Python-Clientbibliotheken bieten integriertes verteiltes Tracing von OpenTelemetry. Diese Instrumentierung bietet tiefe Einblicke in Clientvorgänge, RPC-Aufrufe, Wiederholungsverhalten, Netzwerklatenz und Dienstantworten, ohne dass manuelles Monkey-Patching erforderlich ist.

Wichtige Merkmale:

• Backend-unabhängig: Gibt Standard-OpenTelemetry-Spans aus. Sie können Traces direkt in Cloud Trace, einen lokalen OpenTelemetry Collector oder Beobachtbarkeitsplattformen von Drittanbietern exportieren.
• Opt-In: Verteiltes Tracing ist standardmäßig deaktiviert, um Laufzeit-Overhead für Anwendungen zu vermeiden, die keine Telemetrie erfordern.
• Kontextweitergabe: Spans werden automatisch an den aktiven OpenTelemetry-Trace-Kontext gebunden, wobei das integrierte contextvars von Python verwendet wird. Dadurch werden Clientaufrufe mit eingehenden HTTP-/gRPC-Anfragen korreliert.

Funktionsweise des Tracing (Span-Hierarchie)

Wenn diese Option aktiviert ist, geben die Python-Clientbibliotheken von Google Cloud eine hierarchische, zweistufige Span-Architektur aus, die die für Nutzer sichtbare Ausführung von Methoden klar von den zugrunde liegenden Wire-Versuchen trennt:

[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. Logische Clientmethoden-Spans (übergeordnet)

• Bereich: Kapselt den gesamten Lebenszyklus des Methodenaufrufs der Clientbibliothek von der Aufrufung bis zum Abschluss.
• Dauer: Umfasst alle Wiederholungsversuche, Pausen für exponentiellen Backoff und Zeitüberschreitungsrichtlinien.
• Identität: Benannt nach der vollständig qualifizierten RPC-Methode (z. B. google.cloud.secretmanager.v1.SecretManagerService/GetSecretVersion).
• Attribute: Erfasst logische RPC-Metadaten, den Zieldienst und das endgültige Ergebnis auf übergeordneter Ebene.

2. Versuchs-Spans des Netzwerks (untergeordnet)

• Umfang: Werden als untergeordnete Spans des logischen Methoden-Spans erstellt und stellen einzelne physische HTTP/REST- oder gRPC-Netzwerkversuche dar.
• Lebenszyklus: Für jeden Netzwerkversuch wird ein neuer Span generiert. Wenn ein Vorgang beim ersten Versuch erfolgreich ist, wird genau ein untergeordneter Span aufgezeichnet. Wenn bei einem Vorgang vorübergehende Fehler auftreten und er wiederholt wird, wird jeder Versuch als unabhängiger untergeordneter Span mit eigener Zeit und eigenem Status aufgezeichnet.
• Attribute: Erfasst Low-Level-Wire-Statuscodes, die Adresse des Zielservers und Transportdetails.

Voraussetzungen und Installation

Google Cloud Das Tracing der Python-Clientbibliothek basiert auf standardmäßigen OpenTelemetry-Python-Paketen.

1. Pakete installieren

• Instrumentierung von Clientbibliothek und gRPC-Transport:

  • opentelemetry-api wird automatisch mit google-api-core installiert, um logische Methoden-Spans und HTTP/REST-Transport-Spans (rest) zu unterstützen.
  • Wenn Sie auch Low-Level-gRPC-Transportspans aufzeichnen möchten, installieren Sie die Clientbibliothek zusammen mit google-api-core[tracing] (wodurch opentelemetry-instrumentation-grpc installiert wird):

  pip install google-cloud-secret-manager "google-api-core[tracing]"
  

• OpenTelemetry SDK (für eigenständige Anwendungen und Codebeispiele):

  • Clientbibliotheken benötigen opentelemetry-sdk nicht, wenn Ihre Umgebung bereits ein TracerProvider bereitstellt.
  • Wenn Sie jedoch einen TracerProvider konfigurieren und Spans in Ihrem eigenen Code exportieren möchten (einschließlich der Beispiele auf dieser Seite), installieren Sie opentelemetry-sdk:

  pip install opentelemetry-sdk
  

Hinweis: Das Paket opentelemetry-instrumentation-grpc ist nur für Low-Level-gRPC-Transportspans erforderlich. Logische Client-Methoden-Spans und HTTP/REST-Transport-Spans (rest) funktionieren auch ohne.

Eine Anleitung zum Konfigurieren von OpenTelemetry-Exportern, um Spans an Cloud Trace oder einen OpenTelemetry Collector in der Produktion zu senden, finden Sie unter Python mit OpenTelemetry einrichten und Instrumentierungsansatz auswählen.

Tracing aktivieren

Verteiltes Tracing kann entweder global über eine Umgebungsvariable oder programmatisch pro Client aktiviert werden. Die mit ClientOptions übergebene client-spezifische Konfiguration hat Vorrang vor den Einstellungen der Umgebungsvariablen.

Option 1: Globale Konfiguration (Umgebungsvariablen)

Wenn Sie das Tracing für alle unterstützten Google Cloud Python-Clientbibliotheken in Ihrer Umgebung aktivieren möchten, legen Sie vor dem Starten Ihrer Anwendung die folgende Umgebungsvariable fest:

export GOOGLE_SDK_PYTHON_TRACING_ENABLED=true

Wenn der Wert auf true gesetzt ist, erkennen Clientbibliotheken automatisch die global registrierte OpenTelemetry-TracerProvider und geben Spans für alle Clientaufrufe aus.

Option 2: Konfiguration pro Client (Code)

Wenn Sie eine detaillierte Kontrolle oder mandantenfähige Anwendungen benötigen, konfigurieren Sie eine bestimmte Clientinstanz, indem Sie mit ClientOptions eine tracer_provider übergeben:

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)

Codebeispiele

Clientbibliotheken können Standardanmeldedaten für Anwendungen verwenden, um sich einfach bei Google APIs zu authentifizieren und Anfragen an diese APIs zu senden. Mit den Standardanmeldedaten für Anwendungen können Sie Ihre Anwendung lokal testen und bereitstellen, ohne den zugrunde liegenden Code zu ändern. Weitere Informationen finden Sie unter Für die Verwendung von Clientbibliotheken authentifizieren.

1. Beispiel für eine Kurzanleitung (SecretManagerServiceClient)

Das folgende eigenständige Beispiel zeigt, wie Sie OpenTelemetry konfigurieren, das Tracing der Clientbibliothek mithilfe einer Umgebungsvariablen aktivieren und ausgegebene Spans mithilfe von ConsoleSpanExporter direkt als JSON im Terminal ausgeben.

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

get_secret_version_trace.py

2. Programmatische Konfiguration (ClientOptions)

Wenn Sie keine Umgebungsvariablen verwenden möchten oder unterschiedliche TracerProvider-Instanzen an verschiedene Clients übergeben müssen, konfigurieren Sie einen Client programmatisch, indem Sie tracer_provider mit ClientOptions übergeben:

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

get_secret_version_trace_client_options.py

3. Beispiel für einen asynchronen Client (SecretManagerServiceAsyncClient)

Im folgenden Beispiel wird eine asynchrone Koroutine (async def get_secret_version_with_tracing_async) mit SecretManagerServiceAsyncClient definiert. Da dieser Client asynchron ist, müssen Sie ihn in einer aktiven asyncio-Ereignisschleife ausführen.

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

get_secret_version_trace_async.py

Kontextweitergabe in asynchronem Code: OpenTelemetry Python gibt den Trace-Kontext automatisch über await-Punkte und gleichzeitige Aufgaben hinweg weiter. Dazu wird das in Python integrierte contextvars verwendet. Selbst wenn mehrere Koroutinen gleichzeitig ausgeführt und fortgesetzt werden, behält jeder Clientaufruf seinen aktiven übergeordneten Span und Trace-Kontext korrekt bei.

Referenz zu semantischen Attributen

Spans, die von Google Cloud Python-Clientbibliotheken ausgegeben werden, entsprechen den standardmäßigen semantischen OpenTelemetry-Konventionen für RPC-Spans. Dabei werden Standardmetadaten für das Transportprotokoll, die RPC-Methodenidentität, die Zielserveradresse, die Antwortstatuscodes und Fehlerdetails aufgezeichnet. Sie können diese Attribute verwenden, um in Ihrem Observability- oder Cloud Trace-Dashboard Benachrichtigungsrichtlinien zu filtern, zu aggregieren und zu erstellen.

Sicherheit und sensible Daten

Google Cloud Die Instrumentierung der Python-Clientbibliothek wurde nach strengen Sicherheits- und Datenschutzstandards entwickelt:

• Nutzlastschutz: Clientbibliotheken zeichnen niemals Anfrage- oder Antwortnutzlastdaten (z. B. Dateiinhalte, geheime Werte oder Datenbankabfrageergebnisse) in Trace-Spans auf.
• Sichtbarkeit von Kennungen: Ressourcennamen (z. B. Projekt-IDs, Dataset-IDs und Secret-Namen) werden in Methodenparametern und URL-Endpunktattributen angezeigt. Wenn Ressourcenkennungen vertrauliche Geschäftsinformationen enthalten, achten Sie darauf, dass Ihr Trace-Speicher Ihren internen Compliance-Richtlinien entspricht.
• Drittanbieter-Exporter: Wenn Sie Traces in Beobachtbarkeitsdienste oder SaaS-Anbieter von Drittanbietern exportieren, prüfen Sie die Datenschutzvereinbarungen Ihrer Organisation und konfigurieren Sie bei Bedarf die Attributfilterung für Exporter.