Halaman ini diterjemahkan oleh Cloud Translation API.

Membuat trace dan metrik dengan Python

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

Untuk mempelajari instrumentasi lebih lanjut, lihat dokumen berikut:

Tentang instrumentasi manual dan otomatis

Untuk bahasa ini, OpenTelemetry mendefinisikan instrumentasi otomatis sebagai praktik pengumpulan telemetri dari library dan framework tanpa mengubah kode. Namun, Anda memiliki menginstal modul dan mengatur 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

Aktifkan API Cloud Logging, Cloud Monitoring, and Cloud Trace.

Mengaktifkan API

Melengkapi aplikasi untuk mengumpulkan trace, metrik, dan log

Untuk melengkapi aplikasi Anda guna mengumpulkan data metrik dan trace serta untuk menulis JSON terstruktur ke standard out, lakukan langkah-langkah berikut di bagian selanjutnya dari dokumen ini:

Mengonfigurasi OpenTelemetry
Mengonfigurasi logging terstruktur

Mengonfigurasi OpenTelemetry

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

Contoh kode berikut mengilustrasikan modul Python untuk menyiapkan OpenTelemetry. Untuk melihat sampel lengkap, klik Lainnya, 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 setelah rekomendasi dalam panduan Deploying to Production Flask. Gunicorn memulai beberapa salinan aplikasi Anda yang berjalan dalam proses pekerja independen untuk meningkatkan throughput. Untuk memastikan bahwa metrik dari proses pekerja tidak mengalami konflik satu sama lain, kami menyarankan agar setiap proses pekerja menetapkan nilai unik untuk Atribut resource service.instance.id. Salah satu cara untuk melakukannya adalah dengan menyertakan ID proses di service.instance.id. Untuk informasi selengkapnya, lihat Tabrakan deret waktu.

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

Mengonfigurasi logging terstruktur

Untuk menulis log terstruktur yang ditautkan ke trace, konfigurasi aplikasi Anda agar menghasilkan log berformat JSON ke standard out dengan kunci yang berisi trace tidak akurat atau tidak sesuai. Contoh kode berikut mengilustrasikan cara mengonfigurasi Library logging untuk menghasilkan log terstruktur JSON menggunakan library python-json-logger, dan cara menggunakan Paket opentelemetry-instrumentation-logging untuk menyertakan rekaman aktivitas tidak akurat atau tidak sesuai.

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 durasi aktif dari pesan log tersebut, lalu menambahkan informasi tersebut sebagai atribut ke JSON log. Atribut ini kemudian dapat digunakan untuk menghubungkan log dengan rekaman aktivitas:

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

Untuk informasi selengkapnya tentang kolom ini, lihat LogEntry karena ada berbagai struktur penetapan harga.

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. Model ini menggunakan Flask untuk menyalurkan permintaan HTTP, dan library permintaan untuk membuat permintaan HTTP. Untuk menghasilkan metrik dan trace untuk klien HTTP dan server, aplikasi contoh menginstal opentelemetry-instrumentation-flask dan opentelemetry-instrumentation-requests library instrumentasi:

logger = logging.getLogger(__name__)

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

Aplikasi ini memiliki dua endpoint:

Endpoint /multi ditangani oleh fungsi multi. Beban generator di aplikasi mengeluarkan permintaan ke endpoint /multi. Jika endpoint menerima permintaan, 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. Jika endpoint menerima permintaan, akan tidur sebentar, lalu merespons dengan sebuah {i>string.<i}

@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 menjalankan Cloud Shell, jalankan aplikasi dengan Variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS yang mengarah ke kredensial. Default Aplikasi Kredensial 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 Prometheus yang dapat Anda tampilkan menggunakan Metrics Explorer:

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

Untuk melihat metrik yang dihasilkan oleh aplikasi contoh, lakukan hal 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 Metrik, luaskan menu Pilih metrik, masukkan http_server di panel filter, lalu gunakan submenu untuk memilih metrik dan jenis resource 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 Terapkan.
Konfigurasikan cara data dilihat.
Saat pengukuran untuk suatu metrik kumulatif, Metrics Explorer akan otomatis menormalisasi data terukur dengan periode perataan, sehingga diagram menampilkan tarif. Sebagai informasi selengkapnya, lihat Jenis, jenis, dan konversi.

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

Untuk informasi selengkapnya tentang cara mengonfigurasi diagram, lihat Pilih 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.
Dalam bagan Gantt pada panel Detail pelacakan, pilih span yang berlabel /multi.

Sebuah panel yang menampilkan informasi tentang permintaan HTTP akan terbuka. Ini detailnya meliputi metode, kode status, jumlah byte, dan agen pengguna pemanggil.
Untuk melihat log yang terkait dengan trace ini, pilih opsi Log & Peristiwa.

Tab ini menampilkan log individual. Untuk melihat detail entri log, perluas entri log. Anda juga dapat mengklik Lihat Log dan melihat log menggunakan Logs Explorer.

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

Melihat log

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

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

Jika Anda menggunakan bilah pencarian untuk menemukan halaman ini, kemudian pilih hasil yang sub judulnya Logging.
Cari log dengan deskripsi handle /multi request.

Untuk melihat detail log, luaskan entri log.
Klik Traces pada entri log dengan "menangani /multipermintaan" pesan, lalu pilih View trace details.

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

Untuk informasi selengkapnya tentang penggunaan Logs Explorer, lihat Lihat log menggunakan Logs Explorer.