Melacak API Anda

OpenAPI   |  gRPC

Setelah Anda men-deploy Extensible Service Proxy (ESP) atau Extensible Service Proxy V2 (ESPv2) dan kode backend API Anda, proxy akan mencegat semua permintaan dan melakukan pemeriksaan yang diperlukan sebelum meneruskan permintaan ke backend API. Saat backend merespons, proxy mengumpulkan dan melaporkan telemetri. Salah satu data telemetri yang diambil oleh proxy adalah tracing, dengan menggunakan Cloud Trace.

Halaman ini menjelaskan cara:

• Melihat rekaman aktivitas di konsol Google Cloud
• Perkirakan biaya Anda untuk Trace.
• Konfigurasi proxy untuk menonaktifkan pengambilan sampel rekaman aktivitas.

Melihat trace

Rekaman aktivitas melacak permintaan masuk ke API Anda dan berbagai peristiwa (seperti panggilan RPC atau bagian kode yang diinstrumentasikan), beserta waktu yang tepat untuk setiap peristiwa. Peristiwa ini direpresentasikan sebagai rentang dalam rekaman aktivitas.

Untuk melihat rekaman aktivitas project Anda, buka halaman Cloud Trace di Google Cloud console:

Buka Trace

Di halaman Trace explorer, Anda dapat melihat perincian untuk melihat setiap rekaman aktivitas dan melihat rentang yang dibuat ESP dalam rekaman aktivitas. Anda dapat menggunakan filter untuk melihat rekaman aktivitas untuk satu API atau operasi.

Rekaman aktivitas dan rentang yang dibuat untuk API Anda akan berbeda, bergantung pada apakah API Anda menggunakan ESPv2 atau ESP. Ringkasan format rekaman aktivitas untuk setiap penerapan tercantum di bawah.

Untuk mengetahui informasi selengkapnya tentang halaman Trace explorer, lihat Menemukan dan menjelajahi rekaman aktivitas.

Rentang yang dibuat oleh ESPv2

ESPv2 membuat rekaman aktivitas dalam format berikut:

Setidaknya, ESPv2 membuat 2 rentang per rekaman aktivitas:

• Rentang ingress OPERATION_NAME untuk seluruh permintaan dan respons.
• Rentang router BACKEND egress untuk waktu ESPv2 menunggu backend memproses permintaan dan merespons kembali. Hal ini mencakup hop jaringan antara ESPv2 dan backend.

Bergantung pada konfigurasi API Anda, ESPv2 dapat membuat rentang tambahan:

• Jika API Anda memerlukan autentikasi, ESPv2 akan meng-cache kunci publik yang diperlukan untuk autentikasi selama 5 menit. Jika kunci publik tidak ada di cache, ESPv2 akan mengambil dan menyimpan kunci publik dalam cache, serta membuat rentang JWT Remote PubKey Fetch.
• Jika API Anda memerlukan kunci API, ESPv2 akan meng-cache informasi yang diperlukan untuk memvalidasi kunci API. Jika informasi tidak ada dalam cache, ESPv2 akan memanggil Kontrol Layanan dan membuat rentang Service Control remote call: Check.

Secara umum, ESPv2 hanya membuat rentang untuk panggilan jaringan yang memblokir permintaan masuk. Permintaan yang tidak memblokir tidak akan dilacak. Pemrosesan lokal akan membuat peristiwa waktu, bukan rentang. Contoh:

• Penerapan kuota memerlukan panggilan jarak jauh, tetapi panggilan tidak terjadi di jalur permintaan API dan tidak akan memiliki rentang yang terkait dengannya dalam rekaman aktivitas.
• Kunci API di-cache oleh ESPv2 untuk jangka waktu singkat. Setiap permintaan yang menggunakan cache akan memiliki peristiwa waktu yang terkait dalam rekaman aktivitas.

Rentang yang dibuat oleh ESP

Peringatan: ESP tidak memberikan informasi mendetail untuk rentang. Hal ini juga membuat rentang tambahan yang tidak bermakna. Harap bermigrasi ke ESPv2 untuk melihat rekaman aktivitas mendetail yang mengikuti praktik terbaik pelacakan.

ESP membuat rekaman aktivitas dalam format berikut:

Setidaknya, ESP membuat 4 rentang per rekaman aktivitas:

• Rentang untuk seluruh permintaan dan respons.
• Rentang CheckServiceControl untuk panggilan ke metode Service Control services.check untuk mendapatkan konfigurasi API Anda.
• Rentang QuotaControl untuk memeriksa apakah ada kuota yang dikonfigurasi di API Anda.
• Rentang Backend yang melacak waktu yang dihabiskan dalam kode backend API Anda.

Bergantung pada konfigurasi untuk API Anda, ESP membuat rentang tambahan:

• Jika API Anda memerlukan autentikasi, ESP akan membuat rentang CheckAuth di setiap rekaman aktivitas. Untuk mengautentikasi permintaan, ESP menyimpan dalam cache kunci publik yang perlu diautentikasi selama 5 menit. Jika kunci publik tidak ada di cache, ESP akan mengambil dan menyimpan kunci publik dalam cache, lalu membuat rentang HttpFetch.
• Jika API Anda memerlukan kunci API, ESP akan membuat rentang CheckServiceControlCache di setiap rekaman aktivitas. ESP menyimpan dalam cache informasi yang diperlukan untuk memvalidasi kunci API. Jika informasi tidak ada dalam cache, ESP akan memanggil Kontrol Layanan dan membuat rentang Call ServiceControl server.
• Jika Anda telah menetapkan kuota untuk API, ESP akan membuat rentang QuotaServiceControlCache di setiap rekaman aktivitas. ESP menyimpan dalam cache informasi yang diperlukan untuk memeriksa kuota. Jika informasi tidak ada dalam cache, ESP akan memanggil Kontrol Layanan dan membuat rentang Call ServiceControl server.

Kecepatan pengambilan sampel trace

ESP mengambil sampel sejumlah kecil permintaan ke API Anda untuk mendapatkan data rekaman aktivitas. Untuk mengontrol rasio pengambilan sampel, ESP mempertahankan penghitung permintaan dan timer. Jumlah permintaan per detik ke API Anda menentukan rasio pengambilan sampel. Jika tidak ada permintaan dalam satu detik, ESP tidak akan mengirimkan rekaman aktivitas.

Jika jumlah permintaan dalam satu detik adalah:

• Kurang dari atau sama dengan 999, ESP mengirim 1 rekaman aktivitas.
• Antara 1000 dan 1999, ESP mengirim 2 rekaman aktivitas.
• Antara 2000 dan 2999, ESP mengirim 3 rekaman aktivitas.
• Dan seterusnya.

Singkatnya, Anda dapat memperkirakan rasio pengambilan sampel dengan fungsi ceiling: ceiling(requests per second/1000)

Memperkirakan biaya Trace

Untuk memperkirakan biaya Trace, Anda perlu memperkirakan jumlah rentang yang dikirim ESP ke Trace dalam sebulan.

Untuk memperkirakan jumlah rentang per bulan:

1. Perkirakan jumlah permintaan per detik ke API Anda. Untuk mendapatkan perkiraan ini, Anda dapat menggunakan grafik Requests di halaman Endpoints > Services atau Cloud Logging. Lihat Memantau API untuk mengetahui informasi selengkapnya.
2. Hitung jumlah rekaman aktivitas yang dikirim ESP ke Trace per detik: ceiling(requests per second/1000)
3. Perkirakan jumlah rentang dalam rekaman aktivitas. Untuk mendapatkan perkiraan ini, Anda dapat menggunakan informasi di Rentang yang dibuat oleh ESP atau melihat halaman Daftar Pelacakan untuk melihat pelacakan untuk API Anda.
4. Perkirakan jumlah detik dalam sebulan saat API Anda mendapatkan traffic. Misalnya, beberapa API hanya menerima permintaan selama waktu tertentu dalam sehari, dan API lainnya menerima permintaan secara sporadis.
5. Kalikan jumlah detik dalam sebulan dengan jumlah rentang.

Contoh:

1. Asumsikan bahwa jumlah maksimum permintaan per detik untuk API adalah 5.
2. Frekuensi pengambilan sampel rekaman aktivitas adalah ceiling (5/1000) = 1
3. API tidak memiliki kuota yang dikonfigurasi, tidak memerlukan kunci API, dan tidak memerlukan autentikasi. Oleh karena itu, jumlah span yang dibuat ESP per rekaman aktivitas adalah 4.
4. API ini hanya menerima permintaan selama jam kerja, Senin hingga Jumat. Jumlah detik dalam sebulan saat API mendapatkan traffic adalah sekitar: 3.600 X 8 X 20 = 576.000
5. Jumlah rentang per bulan adalah sekitar 576.000 x 4 = 2.304.000

Setelah mengetahui perkiraan jumlah rentang dalam sebulan, lihat halaman Harga Trace untuk mengetahui informasi harga mendetail.

Menonaktifkan pengambilan sampel trace

Jika ingin menghentikan ESP mengambil sampel permintaan dan mengirimkan rekaman aktivitas, Anda dapat menyetel opsi mulai ESP dan memulai ulang ESP. Trace yang dikirim ESP ke Cloud Trace tidak bergantung pada grafik yang ditampilkan di halaman Endpoints > Services. Grafik akan terus tersedia jika Anda menonaktifkan pengambilan sampel rekaman aktivitas.

Bagian berikut mengasumsikan bahwa Anda telah men-deploy API dan ESP, atau Anda memahami proses deployment. Untuk mengetahui informasi selengkapnya, lihat Men-deploy backend API.

App Engine

Untuk menonaktifkan pengambilan sampel rekaman aktivitas ESP di lingkungan fleksibel App Engine:

1. Edit file app.yaml. Di bagian endpoints_api_service, tambahkan opsi trace_sampling dan tetapkan nilainya ke false. Contoh:

   endpoints_api_service:
     name: example-project-12345.appspot.com
     rollout_strategy: managed
     trace_sampling: false

   Jika aplikasi Anda berbasis microservice, Anda harus menyertakan trace_sampling: false di setiap file app.yaml.

2. Jika Anda belum mengupdate Google Cloud CLI baru-baru ini, jalankan perintah berikut:

   gcloud components update

3. Simpan file app.yaml (atau file).
4. Deploy kode backend dan ESP ke App Engine:

   gcloud app deploy

Untuk mengaktifkan kembali pengambilan sampel rekaman aktivitas:

1. Menghapus opsi trace_sampling dari app.yaml.
2. Deploy kode backend dan ESP ke App Engine:

   gcloud app deploy

Compute Engine

Untuk menonaktifkan pengambilan sampel rekaman aktivitas ESP di Compute Engine dengan Docker:

1. Menghubungkan ke instance VM:

   gcloud compute ssh [INSTANCE_NAME]

2. Di flag ESP untuk perintah docker run, tambahkan opsi --disable_cloud_trace_auto_sampling:

   sudo docker run \
       --name=esp \
       --detach \
       --publish=80:8080 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:1 \
       --service=[SERVICE_NAME] \
       --rollout_strategy=managed \
       --backend=[YOUR_API_CONTAINER_NAME]:8080 \
       --disable_cloud_trace_auto_sampling

3. Berikan perintah docker run untuk memulai ulang ESP.

Untuk mengaktifkan kembali pengambilan sampel rekaman aktivitas:

1. Hapus --disable_cloud_trace_auto_sampling.
2. Berikan perintah docker run untuk memulai ulang ESP.

GKE

Untuk menonaktifkan pengambilan sampel rekaman aktivitas ESP di GKE:

1. Buka file manifes deployment Anda, yang disebut sebagai deployment.yaml, dan tambahkan berikut ini ke bagian containers:

   containers:
   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:1
     args: [
       "--http_port=8081",
       "--backend=127.0.0.1:8080",
       "--service=[SERVICE_NAME]",
       "--rollout_strategy=managed",
       "--disable_cloud_trace_auto_sampling"
     ]

2. Mulai layanan Kubernetes menggunakan perintah kubectl create:

   kubectl create -f deployment.yaml

Untuk mengaktifkan kembali pengambilan sampel rekaman aktivitas:

1. Hapus opsi --disable_cloud_trace_auto_sampling.
2. Mulai layanan Kubernetes:

   kubectl create -f deployment.yaml

Jika Anda menjalankan ESP di instance VM Compute Engine tanpa container Docker, tidak ada pasangan nilai kunci metadata instance VM yang setara untuk opsi --disable_cloud_trace_auto_sampling. Jika Anda ingin menonaktifkan pengambilan sampel rekaman aktivitas, Anda harus menjalankan ESP di container.

Klien dapat memaksa permintaan untuk dilacak dengan menambahkan header X-Cloud-Trace-Context ke permintaan, seperti yang dijelaskan dalam Memaksa permintaan untuk dilacak. Jika permintaan berisi header X-Cloud-Trace-Context, ESP akan mengirimkan data rekaman aktivitas ke Trace meskipun Anda telah menonaktifkan pengambilan sampel rekaman aktivitas.

Penerapan Konteks Trace

Untuk pelacakan terdistribusi, header permintaan dapat berisi konteks rekaman aktivitas yang menentukan ID rekaman aktivitas. ID rekaman aktivitas digunakan saat ESPv2 membuat rentang rekaman aktivitas baru dan mengirimkannya ke Cloud Trace. ID rekaman aktivitas digunakan untuk menelusuri semua rekaman aktivitas dan menggabungkan rentang untuk satu permintaan. Jika tidak ada konteks rekaman aktivitas yang ditentukan dalam permintaan, dan rekaman aktivitas diaktifkan, ID rekaman aktivitas acak akan dibuat untuk semua rentang rekaman aktivitas.

Dalam contoh berikut, Cloud Trace mengorelasikan rentang yang dibuat oleh ESPv2 (1) dengan rentang yang dibuat oleh backend (2) untuk satu permintaan. Hal ini membantu men-debug masalah latensi di seluruh sistem:

Untuk mengetahui detail selengkapnya, baca Konsep Inti OpenTelemetry: Propagasi Konteks

Catatan: Distributed tracing mengharuskan klien dan/atau backend Anda mendukung pelacakan. Hal ini berada di luar cakupan dokumentasi ini. Sebaiknya gunakan OpenTelemetry.

Header yang Didukung

ESPv2 mendukung header propagasi konteks rekaman aktivitas berikut:

• traceparent: Header propagasi konteks trace W3C standar. Didukung oleh sebagian besar framework pelacakan modern.
• x-cloud-trace-context: Header propagasi konteks rekaman aktivitas GCP. Didukung oleh framework pelacakan lama dan library Google, tetapi khusus vendor.
• grpc-trace-bin: Header penerapan konteks rekaman aktivitas yang digunakan oleh backend gRPC dengan library rekaman aktivitas OpenCensus.

Jika Anda membuat aplikasi baru, sebaiknya gunakan propagasi konteks rekaman aktivitas traceparent. ESPv2 akan mengekstrak dan menyebarkan header ini secara default. Lihat Opsi startup perekaman aktivitas ESPv2 untuk mengetahui detail tentang cara mengubah perilaku default.

Catatan: Tidak seperti ESPv2, propagasi konteks rekaman aktivitas di ESP harus diaktifkan secara manual melalui opsi startup. ESP tidak mendukung header traceparent.