Halaman ini diterjemahkan oleh Cloud Translation API.

Membuat trace dan metrik dengan Python

Dokumen ini menjelaskan cara memodifikasi aplikasi Python untuk mengumpulkan data trace dan metrik menggunakan framework OpenTelemetry open source, dan cara menulis log JSON terstruktur ke standard out. Dokumen ini juga memberikan informasi tentang contoh aplikasi Python yang dapat Anda instal dan jalankan. Aplikasi ini menggunakan framework web Flask dan dikonfigurasi untuk membuat metrik, trace, dan log.

Untuk mempelajari instrumentasi lebih lanjut, lihat dokumen berikut:

Tentang instrumentasi manual dan otomatis

Untuk bahasa ini, OpenTelemetry mendefinisikan instrumentasi otomatis sebagai praktik mengumpulkan telemetri dari library dan framework tanpa mengubah kode. Namun, Anda telah menginstal modul dan menetapkan variabel lingkungan.

Dokumen ini tidak menjelaskan instrumentasi otomatis. Untuk mengetahui informasi tentang topik tersebut, lihat Instrumentasi Otomatis untuk Python.

Untuk informasi umum, lihat Instrumentasi OpenTelemetry untuk Python.

Sebelum memulai

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

Melengkapi aplikasi untuk mengumpulkan trace, metrik, dan log

Untuk menginstrumentasikan aplikasi Anda untuk mengumpulkan data trace dan metrik serta menulis JSON terstruktur ke standard out, lakukan langkah-langkah berikut seperti yang dijelaskan di bagian selanjutnya dalam dokumen ini:

Mengonfigurasi OpenTelemetry
Mengonfigurasi logging terstruktur

Mengonfigurasi OpenTelemetry

Aplikasi contoh ini dikonfigurasi untuk menggunakan OpenTelemetry Python SDK guna mengekspor trace dan metrik menggunakan protokol OTLP. Secara default, OpenTelemetry Python SDK menggunakan format W3C Trace Context untuk menyebarkan konteks rekaman aktivitas, yang memastikan bahwa span memiliki hubungan induk-turunan yang benar dalam sebuah rekaman aktivitas.

Contoh kode berikut mengilustrasikan modul Python untuk menyiapkan OpenTelemetry. Untuk melihat contoh lengkap, klik More, lalu pilih View on GitHub.

resource = Resource.create(attributes={
    # Use the PID as the service.instance.id to avoid duplicate timeseries
    # from different Gunicorn worker processes.
    SERVICE_INSTANCE_ID: f"worker-{os.getpid()}",
})

traceProvider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(OTLPSpanExporter())
traceProvider.add_span_processor(processor)
trace.set_tracer_provider(traceProvider)

reader = PeriodicExportingMetricReader(
    OTLPMetricExporter()
)
meterProvider = MeterProvider(metric_readers=[reader], resource=resource)
metrics.set_meter_provider(meterProvider)

Aplikasi Flask mengandalkan Gunicorn untuk melayani permintaan HTTP dengan mengikuti rekomendasi dalam panduan Deploying to Production Flask. Gunicorn memulai beberapa salinan aplikasi Anda yang berjalan dalam proses pekerja independen untuk meningkatkan throughput. Untuk memastikan metrik dari proses pekerja tidak bertentangan satu sama lain, sebaiknya setiap proses pekerja menetapkan nilai unik untuk atribut resource service.instance.id. Salah satu cara untuk melakukannya adalah dengan menyertakan ID proses dalam service.instance.id. Untuk mengetahui informasi selengkapnya, lihat Tabrakan deret waktu.

Untuk informasi selengkapnya dan opsi konfigurasi, lihat instrumentasi OpenTelemetry Python.

Mengonfigurasi logging terstruktur

Untuk menulis log terstruktur yang tertaut ke rekaman aktivitas, konfigurasi aplikasi Anda untuk menghasilkan log berformat JSON ke standard out dengan kunci yang berisi informasi rekaman aktivitas. Contoh kode berikut mengilustrasikan cara mengonfigurasi library logging standar untuk menghasilkan log terstruktur JSON menggunakan library python-json-logger, dan cara menggunakan paket opentelemetry-instrumentation-logging untuk menyertakan informasi rekaman aktivitas.

LoggingInstrumentor().instrument()

logHandler = logging.StreamHandler()
formatter = jsonlogger.JsonFormatter(
    "%(asctime)s %(levelname)s %(message)s %(otelTraceID)s %(otelSpanID)s %(otelTraceSampled)s",
    rename_fields={
        "levelname": "severity",
        "asctime": "timestamp",
        "otelTraceID": "logging.googleapis.com/trace",
        "otelSpanID": "logging.googleapis.com/spanId",
        "otelTraceSampled": "logging.googleapis.com/trace_sampled",
        },
    datefmt="%Y-%m-%dT%H:%M:%SZ",
)
logHandler.setFormatter(formatter)
logging.basicConfig(
    level=logging.INFO,
    handlers=[logHandler],
)

Konfigurasi sebelumnya mengekstrak informasi tentang span aktif dari pesan log, lalu menambahkan informasi tersebut sebagai atribut ke log terstruktur JSON. Atribut ini kemudian dapat digunakan untuk menghubungkan log dengan trace:

logging.googleapis.com/trace: Nama resource trace yang terkait dengan entri log.
logging.googleapis.com/spanId: ID span dengan rekaman aktivitas yang terkait dengan entri log.
logging.googleapis.com/trace_sampled: Nilai kolom ini harus true atau false.

Untuk mengetahui informasi selengkapnya tentang kolom ini, lihat struktur LogEntry.

Menjalankan aplikasi contoh yang dikonfigurasi untuk mengumpulkan telemetri

Aplikasi contoh menggunakan format yang tidak terikat dengan vendor, termasuk JSON untuk log dan OTLP untuk metrik dan trace. Telemetri dari aplikasi dirutekan ke Google Cloud menggunakan Collector OpenTelemetry yang dikonfigurasi dengan pengekspor Google. Library ini menggunakan Flask untuk menyalurkan permintaan HTTP, dan library permintaan untuk membuat permintaan HTTP. Untuk membuat metrik dan rekaman aktivitas bagi klien dan server HTTP, aplikasi contoh akan menginstal library instrumentasi opentelemetry-instrumentation-flask dan opentelemetry-instrumentation-requests:

logger = logging.getLogger(__name__)

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

Aplikasi ini memiliki dua endpoint:

Endpoint /multi ditangani oleh fungsi multi. Generator beban di aplikasi mengeluarkan permintaan ke endpoint /multi. Saat menerima permintaan, endpoint ini akan mengirimkan antara tiga hingga tujuh permintaan ke endpoint /single di server lokal.

@app.route('/multi')
def multi():
    """Handle an http request by making 3-7 http requests to the /single endpoint."""
    subRequests = randint(3, 7)
    logger.info("handle /multi request", extra={'subRequests': subRequests})
    for _ in range(subRequests):
        requests.get(url_for('single', _external=True))
    return 'ok'

Endpoint /single ditangani oleh fungsi single. Saat menerima permintaan, endpoint ini akan tidur untuk penundaan singkat, lalu merespons dengan string.

@app.route('/single')
def single():
    """Handle an http request by sleeping for 100-200 ms, and write the number of seconds slept as the response."""
    duration = uniform(0.1, 0.2)
    time.sleep(duration)
    return f'slept {duration} seconds'

Mendownload dan men-deploy aplikasi

Untuk menjalankan contoh, lakukan hal berikut:

Di konsol Google Cloud, aktifkan Cloud Shell.

Aktifkan Cloud Shell

Di bagian bawah Google Cloud Console, Cloud Shell sesi akan terbuka dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi sesi.

Meng-cloning repository

git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python

Buka direktori contoh:

cd opentelemetry-operations-python/samples/instrumentation-quickstart

Buat dan jalankan contoh:

docker compose up --abort-on-container-exit

Jika Anda tidak berjalan di Cloud Shell, jalankan aplikasi dengan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS yang mengarah ke file kredensial. Kredensial Default Aplikasi menyediakan file kredensial di $HOME/.config/gcloud/application_default_credentials.json.

# Set environment variables
export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
export USERID="$(id -u)"

# Run
docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit

Melihat metrik Anda

Instrumentasi OpenTelemetry di aplikasi contoh menghasilkan metrik Prometheus yang dapat Anda tampilkan menggunakan Metrics Explorer:

Prometheus/http_server_duration_milliseconds/histogram mencatat durasi permintaan server dan menyimpan hasilnya dalam histogram.
Prometheus/http_client_duration_milliseconds/histogram mencatat durasi permintaan klien dan menyimpan hasilnya dalam histogram.

Untuk melihat metrik yang dihasilkan oleh aplikasi contoh, lakukan langkah berikut:

Di konsol Google Cloud, buka halaman Metrics Explorer:
Buka Metrics Explorer

Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Monitoring.
Di elemen Metric, luaskan menu Select a metric, masukkan http_server di panel filter, lalu gunakan submenu untuk memilih jenis resource dan metrik tertentu:
1. Di menu Active resources, pilih Prometheus Target.
2. Pada menu Active metric categories, pilih Http.
3. Di menu Metrik aktif, pilih metrik.
4. Klik Apply.
Konfigurasi cara data ditampilkan.
Jika pengukuran untuk sebuah metrik bersifat kumulatif, Metrics Explorer akan otomatis menormalisasi data terukur berdasarkan periode penyelarasan, sehingga diagram menampilkan tarif. Untuk informasi selengkapnya, lihat Jenis, jenis, dan konversi.

Saat nilai bilangan bulat atau ganda diukur, misalnya dengan dua metrik counter, Metrics Explorer akan otomatis menjumlahkan semua deret waktu secara otomatis. Guna melihat data untuk rute HTTP /multi dan /single, tetapkan menu pertama entri Agregasi ke None.

Untuk informasi selengkapnya tentang cara mengonfigurasi diagram, lihat Memilih metrik saat menggunakan Metrics Explorer.

Melihat trace Anda

Untuk melihat data trace Anda, lakukan tindakan berikut:

Di konsol Google Cloud, buka halaman Trace explorer:
Buka Trace Explorer

Anda juga dapat menemukan halaman ini menggunakan kotak penelusuran.
Di diagram sebar, pilih rekaman aktivitas dengan URI /multi.
Pada diagram Gantt di panel Trace details, pilih span dengan label /multi.

Sebuah panel yang menampilkan informasi tentang permintaan HTTP akan terbuka. Detail ini mencakup metode, kode status, jumlah byte, dan agen pengguna pemanggil.
Untuk melihat log yang terkait dengan rekaman aktivitas ini, pilih tab Logs & Events.

Tab ini menampilkan log individual. Untuk melihat detail entri log, luaskan entri log. Anda juga dapat mengklik View Logs dan melihat log menggunakan Logs Explorer.

Untuk informasi lebih lanjut tentang cara menggunakan penjelajah Cloud Trace, lihat Menemukan dan menjelajahi rekaman aktivitas.

Melihat log

Dari Logs Explorer, Anda dapat memeriksa log, dan juga dapat melihat trace terkait, saat ada.

Di konsol Google Cloud, buka halaman Logs Explorer:
Buka Logs Explorer

Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Logging.
Cari log dengan deskripsi handle /multi request.

Untuk melihat detail log, luaskan entri log.
Klik Traces pada entri log yang berisi pesan "handle /multi request", lalu pilih View trace details.

Panel Trace details akan terbuka dan menampilkan rekaman aktivitas yang dipilih.

Untuk mengetahui informasi lebih lanjut tentang cara menggunakan Logs Explorer, baca Melihat log menggunakan Logs Explorer.