Melakukan instrumentasi library klien Python Google Cloud

Panduan ini menunjukkan cara mengonfigurasi dan menggunakan pelacakan terdistribusi OpenTelemetry di library klien Python Google Cloud .

Ringkasan

Library klien PythonGoogle Cloud menyediakan pelacakan terdistribusi OpenTelemetry bawaan. Instrumentasi ini menawarkan visibilitas mendalam ke dalam operasi klien, pemanggilan RPC, perilaku percobaan ulang, latensi jaringan, dan respons layanan tanpa memerlukan monkey-patching manual.

Karakteristik utama:

  • Backend Agnostic: Memancarkan span OpenTelemetry standar. Anda dapat mengekspor trace langsung ke Cloud Trace, OpenTelemetry Collector lokal, atau platform kemampuan observasi pihak ketiga.
  • Keikutsertaan: Pelacakan terdistribusi dinonaktifkan secara default untuk menghindari overhead runtime bagi aplikasi yang tidak memerlukan telemetri.
  • Penerapan Konteks: Span otomatis terikat ke konteks trace OpenTelemetry yang aktif menggunakan contextvars bawaan Python, yang menghubungkan panggilan klien dengan permintaan HTTP/gRPC yang masuk.

Cara Kerja Pelacakan (Hierarki Span)

Jika diaktifkan, library klien Python Google Cloud akan memunculkan arsitektur span dua tingkat hierarkis yang dengan jelas memisahkan eksekusi metode yang ditampilkan kepada pengguna dari upaya wire yang mendasarinya:

[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. Span Metode Klien Logis (Induk)

  • Cakupan: Merangkum seluruh siklus proses panggilan metode library klien, mulai dari pemanggilan hingga penyelesaian.
  • Durasi: Mencakup semua upaya percobaan ulang, jeda backoff eksponensial, dan kebijakan waktu tunggu.
  • Identity: Dinamai sesuai dengan metode RPC yang sepenuhnya memenuhi syarat (misalnya, google.cloud.secretmanager.v1.SecretManagerService/GetSecretVersion).
  • Atribut: Menangkap metadata RPC logis, layanan tujuan, dan hasil akhir tingkat tinggi.

2. Rentang Percobaan Jaringan (Turunan)

  • Cakupan: Dibuat sebagai span turunan dari span metode logis, yang mewakili upaya jaringan fisik HTTP/REST atau gRPC individual.
  • Siklus proses: Span baru dibuat untuk setiap upaya jaringan. Jika operasi berhasil pada percobaan pertama, tepat satu span turunan akan dicatat. Jika operasi mengalami error sementara dan mencoba ulang, setiap upaya akan dicatat sebagai span turunan independen dengan pengaturan waktu dan statusnya sendiri.
  • Atribut: Menangkap kode status wire tingkat rendah, alamat server tujuan, dan detail transpor.

Prasyarat & Penginstalan

Pelacakan library klien PythonGoogle Cloud mengandalkan paket Python OpenTelemetry standar.

1. Menginstal Paket

  • Instrumentasi transportasi gRPC & library klien:

    • opentelemetry-api diinstal secara otomatis dengan google-api-core untuk mendukung span metode logis dan span transport HTTP/REST (rest).
    • Untuk juga mencatat span transport gRPC tingkat rendah, instal library klien Anda bersama dengan google-api-core[tracing] (yang menginstal opentelemetry-instrumentation-grpc):
    pip install google-cloud-secret-manager "google-api-core[tracing]"

  • OpenTelemetry SDK (untuk aplikasi mandiri dan contoh kode):

    • Library klien tidak memerlukan opentelemetry-sdk jika lingkungan Anda sudah menyediakan TracerProvider.
    • Namun, untuk mengonfigurasi TracerProvider dan mengekspor span dalam kode Anda sendiri (termasuk contoh di halaman ini), instal opentelemetry-sdk:
    pip install opentelemetry-sdk

Untuk mengetahui petunjuk cara mengonfigurasi pengekspor OpenTelemetry untuk mengirim span ke Cloud Trace atau OpenTelemetry Collector dalam produksi, lihat Menyiapkan Python dengan OpenTelemetry dan Memilih pendekatan instrumentasi.

Mengaktifkan Pelacakan

Pelacakan terdistribusi dapat diaktifkan secara global menggunakan variabel lingkungan atau secara terprogram per klien. Konfigurasi per klien yang diteruskan menggunakan ClientOptions lebih diutamakan daripada setelan variabel lingkungan.

Opsi 1: Konfigurasi global (Variabel lingkungan)

Untuk mengaktifkan pelacakan di semua library klien Python Google Cloud yang didukung di lingkungan Anda, tetapkan variabel lingkungan berikut sebelum memulai aplikasi:

export GOOGLE_SDK_PYTHON_TRACING_ENABLED=true

Jika ditetapkan ke true, library klien akan otomatis mendeteksi OpenTelemetry TracerProvider yang terdaftar secara global dan memunculkan span untuk semua pemanggilan klien.

Opsi 2: Konfigurasi per klien (Kode)

Untuk kontrol yang mendetail atau aplikasi multi-tenant, konfigurasikan instance klien tertentu dengan meneruskan tracer_provider menggunakan 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)

Contoh Kode

Library klien dapat menggunakan Kredensial Default Aplikasi untuk dengan mudah melakukan autentikasi dengan Google API dan mengirim permintaan ke API tersebut. Dengan Kredensial Default Aplikasi, Anda dapat menguji aplikasi secara lokal dan men-deploy aplikasi tanpa mengubah kode yang mendasarinya. Untuk mengetahui informasi selengkapnya, lihat Melakukan autentikasi untuk menggunakan library klien.

1. Contoh Panduan Memulai (SecretManagerServiceClient)

Contoh mandiri berikut menunjukkan cara mengonfigurasi OpenTelemetry standar, mengaktifkan pelacakan library klien menggunakan variabel lingkungan, dan mencetak span yang dikeluarkan langsung ke terminal sebagai JSON menggunakan 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. Konfigurasi Terprogram (ClientOptions)

Jika Anda memilih untuk tidak menggunakan variabel lingkungan atau perlu meneruskan instance TracerProvider yang berbeda ke klien yang berbeda, konfigurasikan klien secara terprogram dengan meneruskan tracer_provider menggunakan 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. Contoh Klien Asinkron (SecretManagerServiceAsyncClient)

Contoh berikut menentukan coroutine asinkron (async def get_secret_version_with_tracing_async) menggunakan SecretManagerServiceAsyncClient. Karena klien ini asinkron, pastikan Anda menjalankannya dalam loop peristiwa asyncio yang aktif.

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

Referensi Atribut Semantik

Span yang dikeluarkan oleh library klien Python Google Cloud mematuhi Konvensi Semantik OpenTelemetry untuk Span RPC standar, yang mencatat metadata standar untuk protokol transpor, identitas metode RPC, alamat server tujuan, kode status respons, dan detail error. Anda dapat menggunakan atribut ini untuk memfilter, menggabungkan, dan membuat kebijakan pemberitahuan di dasbor kemampuan observasi atau Cloud Trace.

Keamanan & Data Sensitif

Google Cloud Instrumentasi library klien Python dirancang dengan mengikuti standar keamanan dan privasi yang ketat:

  • Perlindungan Payload: Library klien tidak pernah mencatat data payload permintaan atau respons (seperti konten file, nilai rahasia, atau hasil kueri database) pada span trace.
  • Visibilitas ID: Nama resource (seperti project ID, ID set data, dan nama secret) muncul dalam parameter metode dan atribut endpoint URL. Jika ID resource berisi informasi bisnis yang sensitif, pastikan penyimpanan trace Anda mematuhi kebijakan kepatuhan internal.
  • Eksportir Pihak Ketiga: Saat mengekspor trace ke layanan kemampuan observasi pihak ketiga atau vendor SaaS, tinjau perjanjian perlindungan data organisasi Anda dan konfigurasikan pemfilteran atribut pengekspor jika diperlukan.