Python dan OpenTelemetry

Halaman ini ditujukan bagi developer aplikasi yang ingin mengumpulkan data Cloud Trace untuk aplikasi Python menggunakan OpenTelemetry. OpenTelemetry adalah framework instrumentasi yang tidak bergantung pada vendor yang dapat Anda gunakan untuk mengumpulkan data trace dan metrik. Untuk mengetahui informasi tentang cara menginstrumentasikan kode, lihat Instrumentasi dan kemampuan observasi.

Halaman ini akan memandu Anda melakukan langkah-langkah berikut:

  • Instal paket OpenTelemetry.
  • Konfigurasi aplikasi Anda untuk mengekspor span ke Cloud Trace.
  • Konfigurasi platform Anda.

Untuk informasi rilis, lihat referensi berikut:

Untuk konten referensi OpenTelemetry, lihat hal berikut:

Untuk detail terbaru tentang OpenTelemetry untuk Python, beserta dokumentasi dan contoh tambahan, lihat OpenTelemetry.

Sebelum memulai

  • Anda harus menggunakan Python 3.6 atau yang lebih baru.

  • Di panel navigasi Konsol Google Cloud, pilih APIs & Services, klik Enable APIs and Services, lalu aktifkan Cloud Trace API:

    Buka setelan Cloud Trace API

  • Jika API enabled ditampilkan, berarti API sudah diaktifkan. Jika belum, klik tombol Enable.

Menginstal paket OpenTelemetry

Untuk menginstal paket OpenTelemetry yang diperlukan, lakukan hal berikut:

  1. (Opsional) Upgrade ke versi terbaru pip:

    pip install --upgrade pip

  2. Instal paket OpenTelemetry berikut menggunakan pip:

    pip install opentelemetry-api \
  opentelemetry-sdk \
  opentelemetry-exporter-gcp-trace

Mengimpor paket rekaman aktivitas

Update aplikasi Anda untuk mengimpor paket dan class berikut:

  • trace
  • CloudTraceSpanExporter
  • TracerProvider

  • BatchSpanProcessor, yang merupakan pemroses span ekspor yang mengirimkan span menggunakan proses latar belakang.

  • (Opsional) Jika Anda ingin menautkan span, impor class Link.

Contoh berikut mengilustrasikan pernyataan impor ini:


from opentelemetry import trace
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.trace import Link

Mengonfigurasi ekspor span ke Cloud Trace

Untuk mengirim span ke Cloud Trace, ubah aplikasi Anda agar menggunakan pengekspor CloudTraceSpanExporter. Contoh berikut menggambarkan langkah-langkah yang diperlukan:


tracer_provider = TracerProvider()
cloud_trace_exporter = CloudTraceSpanExporter()
tracer_provider.add_span_processor(
    # BatchSpanProcessor buffers spans and sends them in batches in a
    # background thread. The default parameters are sensible, but can be
    # tweaked to optimize your performance
    BatchSpanProcessor(cloud_trace_exporter)
)
trace.set_tracer_provider(tracer_provider)

tracer = trace.get_tracer(__name__)

Menambahkan atribut ke span

Untuk menambahkan atribut ke span, panggil metode set_attribute span. Misalnya, kode berikut menambahkan beberapa atribut ke span bernama foo_with_attribute:


with tracer.start_span("foo_with_attribute") as current_span:
    do_work()

    # Add attributes to the spans of various types
    current_span.set_attribute("string_attribute", "str")
    current_span.set_attribute("bool_attribute", False)
    current_span.set_attribute("int_attribute", 3)
    current_span.set_attribute("float_attribute", 3.14)

Menambahkan peristiwa ke span

Untuk menambahkan peristiwa ke span, panggil metode add_event span. Misalnya, kode berikut menambahkan peristiwa ke span bernama foo_with_event:


# Adding events to spans
with tracer.start_as_current_span("foo_with_event") as current_span:
    do_work()
    current_span.add_event(name="event_name")

Untuk menautkan dua span, impor class Link, lalu gunakan kolom links dalam metode start_as_current_span. Saat menautkan dua span, Anda dapat menyertakan atribut dalam kolom links.

Kode berikut mengilustrasikan dua cara berbeda untuk menautkan span ke span bernama link_target:


# Adding links to spans
with tracer.start_as_current_span("link_target") as link_target:
    # Using start_as_current_span() instead of start_span() will make spans
    # created within this scope children of foo_with_attribute

    # Creates a span "span_with_link" and a link from
    # "span_with_link" -> "link_target"
    with tracer.start_as_current_span(
        "span_with_link", links=[Link(link_target.context)]
    ):
        do_work()

    # Creates a span "span_with_link" and a link from
    # "span_with_link" -> "link_target". This link also has the attribute
    # {"link_attr": "string"}
    with tracer.start_as_current_span(
        "span_with_link_and_link_attributes",
        links=[Link(link_target.context, attributes={"link_attr": "string"})],
    ):
        do_work()

Aplikasi Flask Contoh

Instrumentasi Flask OpenTelemetry dirancang untuk menyederhanakan pengambilan konten rekaman aktivitas yang terkait dengan permintaan HTTP. Artinya, Anda tidak perlu menambahkan instrumentasi tertentu ke rute untuk permintaan ini:

  • Flask menggunakan propagator yang dikonfigurasi untuk mengekstrak konteks span dari permintaan HTTP yang masuk.
  • Flask secara otomatis membuat span dengan atribut yang menjelaskan permintaan dan respons.

Untuk contoh menyeluruh yang menggunakan Flask dan OpenTelemetry, lihat flask_e2e. README Git menyertakan informasi tentang cara menginstal, mengonfigurasi, dan menjalankan contoh tersebut.

Bagian ini menandai langkah-langkah konfigurasi khusus Flask yang disertakan dalam file server.py contoh. File klien, client.py, menggunakan instrumentasi Requests untuk mengaktifkan pelacakan permintaan HTTP yang dibuat oleh library requests.

Impor dan konfigurasi

Untuk menggunakan instrumentasi Flask OpenTelemetry, Anda harus mengimpor FlaskInstrumentor.

Jika ingin memastikan bahwa span yang dibuat oleh produk Google Cloud yang berbeda dikaitkan dengan trace yang sama, Anda harus mengonfigurasi propagator dengan propagator Cloud Trace. Propagator ini menentukan penggunaan header X-Cloud-Trace-Context. Jika Anda tidak mengonfigurasi propagator, OpenTelemetry akan menggunakan propagator default. Dalam hal ini, span yang dibuat oleh berbagai produk Google Cloud, seperti Cloud Run dan App Engine, berada dalam trace terpisah.

Contoh berikut mengilustrasikan pernyataan impor dan konfigurasi yang diperlukan, serta konfigurasi propagator Cloud Trace:


import time

from flask import Flask
from opentelemetry import metrics, trace
from opentelemetry.exporter.cloud_monitoring import (
    CloudMonitoringMetricsExporter,
)
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
from opentelemetry.instrumentation.flask import FlaskInstrumentor
from opentelemetry.propagate import set_global_textmap
from opentelemetry.propagators.cloud_trace_propagator import (
    CloudTraceFormatPropagator,
)
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor


set_global_textmap(CloudTraceFormatPropagator())

Anda tidak perlu menambahkan pernyataan khusus Flask saat mengonfigurasi pengekspor CloudTraceSpanExporter. Konfigurasi yang ditampilkan di bagian Mengonfigurasi ekspor span ke Cloud Trace sudah cukup.

Melakukan inisialisasi Flask

Mengonfigurasi FlaskInstrumentor untuk melengkapi aplikasi Anda. Contoh berikut mengilustrasikan cara melakukan langkah ini:


app = Flask(__name__)
FlaskInstrumentor().instrument_app(app)

@app.route("/")
def hello_world():
    # You can still use the OpenTelemetry API as usual to create custom spans
    # within your trace
    with tracer.start_as_current_span("do_work"):
        time.sleep(0.1)

    return "Hello, World!"

Konfigurasi platform Anda

Anda dapat menggunakan Cloud Trace di Google Cloud dan platform lainnya.

Berjalan di Google Cloud

Saat aplikasi Anda berjalan di Google Cloud, Anda tidak perlu memberikan kredensial autentikasi dalam bentuk akun layanan ke library klien. Namun, Anda harus memastikan bahwa platform Google Cloud Anda telah mengaktifkan cakupan akses Cloud Trace API.

Untuk mengetahui daftar lingkungan Google Cloud yang didukung, lihat Dukungan lingkungan.

Untuk konfigurasi berikut, setelan cakupan akses default akan mengaktifkan Cloud Trace API:

Jika menggunakan cakupan akses kustom, Anda harus memastikan cakupan akses API Cloud Trace diaktifkan:

  • Untuk mengetahui informasi cara mengonfigurasi cakupan akses untuk lingkungan Anda menggunakan Konsol Google Cloud, lihat Mengonfigurasi project Google Cloud.

  • Untuk pengguna gcloud, tentukan cakupan akses menggunakan flag --scopes dan sertakan cakupan akses Cloud Trace API trace.append. Misalnya, untuk membuat cluster GKE dengan hanya Cloud Trace API yang diaktifkan, lakukan hal berikut:

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

Berjalan secara lokal dan di tempat lain

Jika aplikasi Anda berjalan di luar Google Cloud, Anda harus memberikan kredensial autentikasi dalam bentuk akun layanan ke library klien. Akun layanan harus berisi peran agen Cloud Trace. Untuk mengetahui petunjuknya, lihat Membuat akun layanan.

Library klien Google Cloud menggunakan Kredensial Default Aplikasi (ADC) untuk menemukan kredensial aplikasi Anda.

Anda dapat memberikan kredensial ini dengan salah satu dari tiga cara:

  • Jalankan gcloud auth application-default login

  • Tempatkan akun layanan di jalur default untuk sistem operasi Anda. Berikut ini daftar jalur default untuk Windows dan Linux:

    • Windows: %APPDATA%/gcloud/application_default_credentials.json

    • Linux: $HOME/.config/gcloud/application_default_credentials.json

  • Tetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke jalur ke akun layanan Anda:

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

Lihat pelacakan

Di panel navigasi konsol Google Cloud, pilih Trace, lalu pilih Trace explorer:

Buka Trace explorer

Pemecahan masalah

Untuk mengetahui informasi tentang cara memecahkan masalah terkait Cloud Trace, buka halaman Pemecahan masalah.

Referensi