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 tersebut ke backend API. Saat backend merespons, proxy akan mengumpulkan dan melaporkan telemetri. Salah satu bagian data telemetri yang ditangkap proxy adalah pelacakan, dengan menggunakan Cloud Trace.

Halaman ini menjelaskan cara:

• Melihat trace di konsol Google Cloud.
• Perkirakan biaya untuk Trace.
• Mengonfigurasi 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 berinstrumen), beserta waktu yang akurat untuk setiap peristiwa. Peristiwa ini direpresentasikan sebagai span dalam rekaman aktivitas.

Untuk melihat trace project Anda, buka halaman Cloud Trace di Konsol Google Cloud:

Buka Trace

Di halaman Trace explorer, Anda dapat melihat perincian untuk melihat trace individual dan melihat span yang dibuat ESP dalam suatu trace. Anda dapat menggunakan filter untuk melihat trace untuk satu API atau operasi.

Trace dan span yang dibuat untuk API Anda akan berbeda, bergantung pada apakah API Anda menggunakan ESPv2 atau ESP. Berikut ini ringkasan format rekaman aktivitas untuk setiap penerapan.

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:

Setidaknya, ESPv2 membuat 2 span per trace:

• Span ingress OPERATION_NAME untuk seluruh permintaan dan respons.
• Span 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 span tambahan:

• Jika API Anda memerlukan autentikasi, ESPv2 akan menyimpan kunci publik yang diperlukan untuk melakukan autentikasi selama 5 menit. Jika kunci publik tidak ada dalam cache, ESPv2 akan mengambil dan men-cache kunci publik dan membuat span JWT Remote PubKey Fetch.
• Jika API Anda memerlukan kunci API, ESPv2 akan menyimpan informasi yang diperlukan untuk memvalidasi kunci API. Jika informasi tersebut 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 span. Contoh:

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

Span yang dibuat oleh ESP

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

ESP membuat rekaman aktivitas dalam format berikut:

Setidaknya, ESP membuat 4 span per trace:

• Span untuk seluruh permintaan dan respons.
• Span CheckServiceControl untuk panggilan ke metode services.check Service Control untuk mendapatkan konfigurasi untuk API Anda.
• Span QuotaControl untuk memeriksa apakah ada kuota yang dikonfigurasi pada API Anda.
• Span 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 trace. Untuk mengautentikasi permintaan, ESP meng-cache kunci publik yang diperlukan untuk melakukan autentikasi selama 5 menit. Jika kunci publik tidak ada dalam cache, ESP akan mengambil dan meng-cache kunci publik dan membuat span HttpFetch.
• Jika API Anda memerlukan kunci API, ESP akan membuat span CheckServiceControlCache di setiap trace. ESP menyimpan informasi yang diperlukan untuk memvalidasi kunci API ke dalam cache. Jika informasi tersebut tidak ada dalam cache, ESP akan memanggil Kontrol Layanan dan membuat span Call ServiceControl server.
• Jika Anda memiliki kuota yang ditetapkan untuk API, ESP akan membuat span QuotaServiceControlCache di setiap trace. ESP menyimpan informasi yang diperlukan untuk memeriksa kuota ke dalam cache. Jika informasi tersebut tidak ada dalam cache, ESP akan memanggil Kontrol Layanan dan membuat span Call ServiceControl server.

Kecepatan pengambilan sampel trace

ESP mengambil sampel sejumlah kecil permintaan ke API Anda untuk mendapatkan data rekaman aktivitas. Untuk mengontrol frekuensi sampling, ESP menyimpan penghitung permintaan dan timer. Jumlah permintaan per detik ke API Anda menentukan frekuensi sampling. 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 trace.
• Antara tahun 1000 dan 1999, ESP mengirim 2 pelacakan.
• Antara tahun 2000 dan 2999, ESP mengirim 3 pelacakan.
• Dan seterusnya.

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

Memperkirakan biaya Trace

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

Untuk memperkirakan jumlah durasi per bulan:

1. Perkirakan jumlah permintaan per detik ke API Anda. Untuk mendapatkan estimasi ini, Anda dapat menggunakan grafik Requests di halaman Endpoint > Services atau Cloud Logging. Lihat Memantau API Anda untuk informasi selengkapnya.
2. Menghitung jumlah rekaman aktivitas yang dikirim ESP ke Trace per detik: ceiling(requests per second/1000)
3. Memperkirakan jumlah span dalam rekaman aktivitas. Untuk mendapatkan estimasi ini, Anda dapat menggunakan informasi dalam Span yang dibuat oleh ESP atau melihat halaman Trace List guna melihat trace untuk API Anda.
4. Perkirakan jumlah detik dalam sebulan saat API Anda mendapatkan traffic. Misalnya, beberapa API hanya mendapatkan permintaan pada waktu tertentu, dan API lainnya mendapatkan permintaan secara sporadis.
5. Kalikan jumlah detik dalam bulan dengan jumlah durasi.

Contoh:

1. Asumsikan bahwa jumlah maksimum permintaan per detik untuk API adalah 5.
2. Frekuensi sampling trace adalah batas atas (5/1.000) = 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 trace adalah 4.
4. API ini hanya mendapatkan permintaan selama jam kerja, Senin hingga Jumat. Jumlah detik traffic yang didapatkan API dalam sebulan adalah sekitar: 3.600 X 8 X 20 = 576.000
5. Jumlah durasi per bulan adalah sekitar 576.000 x 4 = 2.304.000

Setelah Anda mengetahui perkiraan jumlah durasi dalam sebulan, lihat halaman Harga trace untuk mengetahui informasi harga mendetail.

Menonaktifkan pengambilan sampel rekaman aktivitas

Jika ingin menghentikan ESP agar tidak mengambil sampel permintaan dan mengirim rekaman aktivitas, Anda dapat menetapkan opsi startup ESP dan memulai ulang ESP. Trace yang dikirimkan ESP ke Cloud Trace tidak bergantung pada grafik yang ditampilkan di halaman Endpoint > Services. Grafik akan terus tersedia jika Anda menonaktifkan pengambilan sampel rekaman aktivitas.

Bagian berikut mengasumsikan bahwa Anda telah men-deploy API dan ESP, atau 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 dalam 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 beberapa file).
4. Deploy kode backend dan ESP Anda ke App Engine:

   gcloud app deploy
   

Untuk mengaktifkan kembali pengambilan sampel trace:

1. Hapus opsi trace_sampling dari app.yaml.
2. Deploy kode backend dan ESP Anda 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 trace:

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 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 trace:

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

   kubectl create -f deployment.yaml

Jika Anda menjalankan ESP pada 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 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 tersebut, seperti yang dijelaskan dalam Memaksa permintaan untuk dilacak. Jika permintaan berisi header X-Cloud-Trace-Context, ESP akan mengirim data rekaman aktivitas ke Rekaman aktivitas 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 span rekaman aktivitas baru dan mengirimkannya ke Cloud Trace. ID trace digunakan untuk menelusuri semua trace dan menggabungkan span untuk satu permintaan. Jika tidak ada konteks rekaman aktivitas yang ditentukan dalam permintaan, dan perekaman aktivitas diaktifkan, ID rekaman aktivitas acak akan dibuat untuk semua span rekaman aktivitas.

Pada contoh berikut, Cloud Trace menghubungkan span yang dibuat oleh ESPv2 (1) dengan span yang dibuat oleh backend (2) untuk satu permintaan. Cara ini membantu men-debug masalah latensi di seluruh sistem:

Untuk mengetahui detail selengkapnya, baca OpenTelemetry Core Concepts: Context Propagation

Catatan: Pelacakan terdistribusi memerlukan klien dan/atau backend Anda untuk 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 rekaman aktivitas W3C standar. Didukung oleh sebagian besar framework pelacakan modern.
• x-cloud-trace-context: Header propagasi konteks rekaman aktivitas GCP. Didukung oleh framework pelacakan yang lebih lama dan library Google, tetapi khusus vendor.
• grpc-trace-bin: Header propagasi konteks rekaman aktivitas yang digunakan oleh backend gRPC dengan library pelacakan OpenCensus.

Jika Anda membangun aplikasi baru, sebaiknya gunakan propagasi konteks rekaman aktivitas 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, propagasi konteks rekaman aktivitas di ESP perlu diaktifkan secara manual melalui opsi startup. ESP tidak mendukung header traceparent.