Melacak API Anda

OpenAPI   |  gRPC

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

Halaman ini menjelaskan cara:

• Lihat rekaman aktivitas di konsol Google Cloud.
• Memperkirakan biaya Anda untuk Trace.
• Konfigurasikan 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 dari setiap peristiwa. Peristiwa ini direpresentasikan sebagai span dalam rekaman aktivitas.

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

Buka Trace

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

Jejak dan span yang dibuat untuk API Anda akan berbeda-beda, bergantung pada apakah API Anda menggunakan ESPv2 atau ESP. Ringkasan format trace untuk setiap implementasi dapat dilihat di bawah.

Untuk mengetahui informasi selengkapnya tentang halaman Trace Explorer, lihat Menemukan dan menjelajahi trace.

Span yang dibuat oleh ESPv2

ESPv2 membuat rekaman aktivitas dalam format berikut:

Minimal, ESPv2 membuat 2 span 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 lompatan jaringan antara ESPv2 dan backend.

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

• Jika API Anda memerlukan autentikasi, ESPv2 akan meng-cache kunci publik yang diperlukan untuk mengautentikasi selama 5 menit. Jika kunci publik tidak ada dalam cache, ESPv2 akan mengambil dan meng-cache kunci publik serta membuat span 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 span Service Control remote call: Check.

Secara umum, ESPv2 hanya membuat span untuk panggilan jaringan yang memblokir permintaan masuk. Permintaan non-pemblokiran tidak akan dilacak. Setiap 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 span yang terkait dengannya dalam rekaman aktivitas.
• Kunci API disimpan dalam cache oleh ESPv2 untuk jangka waktu yang singkat. Setiap permintaan yang menggunakan cache akan memiliki peristiwa waktu yang terkait dalam rekaman aktivitas.

Span yang dibuat oleh ESP

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

ESP membuat rekaman aktivitas dalam format berikut:

Minimal, ESP membuat 4 span per rekaman aktivitas:

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

Bergantung pada konfigurasi untuk API Anda, ESP akan membuat span tambahan:

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

Kecepatan pengambilan sampel trace

ESP mengambil sampel sejumlah kecil permintaan ke API Anda untuk mendapatkan data trace. Untuk mengontrol frekuensi sampling, ESP mempertahankan penghitung permintaan dan timer. Jumlah permintaan per detik ke API Anda menentukan sampling rate. Jika tidak ada permintaan dalam satu detik, ESP tidak akan mengirim 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 mengirimkan 2 rekaman aktivitas.
• Antara 2000 dan 2999, ESP mengirim 3 rekaman aktivitas.
• Dan seterusnya.

Singkatnya, Anda dapat memperkirakan frekuensi sampling dengan fungsi ceiling: ceiling(requests per second/1000)

Memperkirakan biaya Pelacakan

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

Untuk memperkirakan jumlah span per bulan:

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

Contoh:

1. Asumsikan bahwa jumlah maksimum permintaan per detik untuk API adalah 5.
2. Kecepatan 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 span per bulan adalah sekitar 576.000 x 4 = 2.304.000

Setelah mengetahui perkiraan jumlah span dalam sebulan, lihat halaman Harga rekaman aktivitas untuk mengetahui informasi harga mendetail.

Menonaktifkan pengambilan sampel trace

Jika ingin menghentikan ESP mengambil sampel permintaan dan mengirim rekaman aktivitas, Anda dapat menetapkan opsi startup ESP dan memulai ulang ESP. Pelacakan 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 sudah 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 didasarkan pada 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. Hapus 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. Dalam 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, yang disebut sebagai deployment.yaml, dan tambahkan kode berikut 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 penampung Docker, tidak ada pasangan nilai kunci metadata instance VM yang setara untuk opsi --disable_cloud_trace_auto_sampling. Jika ingin menonaktifkan pengambilan sampel rekaman aktivitas, Anda harus menjalankan ESP dalam penampung.

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 mengirim data rekaman aktivitas ke Trace meskipun Anda telah menonaktifkan pengambilan sampel rekaman aktivitas.

Penerapan Konteks Rekaman Aktivitas

Untuk pelacakan terdistribusi, header permintaan dapat berisi konteks rekaman aktivitas yang menentukan ID rekaman aktivitas. ID rekaman aktivitas digunakan saat ESPv2 membuat span rekaman aktivitas baru dan mengirimnya ke Cloud Trace. ID rekaman aktivitas digunakan untuk menelusuri semua rekaman aktivitas dan menggabungkan span 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 span rekaman aktivitas.

Pada contoh berikut, Cloud Trace mengaitkan span yang dibuat oleh ESPv2 (1) dengan span 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: Penyebaran Konteks

Catatan: Pelacakan terdistribusi 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 penyebaran konteks rekaman aktivitas berikut:

• traceparent: Header penerapan konteks trace W3C standar. Didukung oleh sebagian besar framework pelacakan modern.
• x-cloud-trace-context: Header penyebaran 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 pelacakan OpenCensus.

Jika Anda mem-build aplikasi baru, sebaiknya gunakan penyebaran konteks trace traceparent. ESPv2 akan mengekstrak dan menyebarkan header ini secara default. Lihat Opsi startup pelacakan ESPv2 untuk mengetahui detail tentang cara mengubah perilaku default.

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