Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Lihat dokumentasi
Apigee Edge.
Halaman ini menunjukkan langkah-langkah yang diperlukan untuk mengonfigurasi pelacakan terdistribusi untuk runtime Apigee Anda. Jika Anda baru menggunakan sistem pelacakan terdistribusi dan ingin mengetahui informasi selengkapnya, lihat Memahami Pelacakan Terdistribusi.
Pengantar
Sistem pelacakan terdistribusi memungkinkan Anda melacak permintaan dalam sistem software yang didistribusikan di beberapa aplikasi, layanan, dan database, serta perantara seperti proxy. Sistem pelacakan ini membuat laporan yang menunjukkan waktu yang diperlukan oleh permintaan di setiap langkah. Laporan pelacakan juga dapat memberikan tampilan terperinci dari berbagai layanan yang dipanggil selama permintaan, sehingga memungkinkan pemahaman yang lebih mendalam tentang apa yang terjadi di setiap langkah dalam sistem software Anda.
Alat pelacakan di Apigee Edge dan alat debug di Apigee berguna untuk memecahkan masalah dan memantau proxy API Anda. Namun, alat ini tidak mengirim data apa pun ke server pelacakan terdistribusi seperti Cloud Trace atau Jaeger. Untuk melihat data runtime Apigee dalam laporan pelacakan terdistribusi, Anda harus mengaktifkan pelacakan terdistribusi secara eksplisit di runtime Apigee. Setelah pelacakan diaktifkan, runtime dapat mengirim data rekaman aktivitas ke server pelacakan terdistribusi dan berpartisipasi dalam rekaman aktivitas yang ada. Dengan demikian, Anda dapat melihat data dari dalam dan luar ekosistem Apigee dari satu lokasi.
Anda dapat melihat informasi berikut dalam laporan pelacakan terdistribusi:
- Waktu eksekusi seluruh alur.
- Waktu saat permintaan diterima.
- Waktu saat permintaan dikirim ke target.
- Waktu saat respons diterima dari target.
- Waktu eksekusi setiap kebijakan dalam alur.
- Waktu eksekusi panggilan layanan dan alur target.
- Waktu saat respons dikirim ke klien.
Dalam laporan pelacakan terdistribusi, Anda dapat melihat detail eksekusi alur sebagai rentang. Rentang mengacu pada waktu yang diperlukan oleh alur dalam rekaman aktivitas. Waktu yang diperlukan untuk mengeksekusi alur ditampilkan sebagai gabungan waktu yang diperlukan untuk mengeksekusi setiap kebijakan dalam alur. Anda dapat melihat setiap alur berikut sebagai rentang terpisah:
- Permintaan
- Proxy
- Preflow
- PostFlow
- Target
- Preflow
- PostFlow
- Proxy
- Respons
- Proxy
- Preflow
- PostFlow
- Target
- Preflow
- PostFlow
- Proxy
Setelah Anda mengaktifkan pelacakan terdistribusi, runtime Apigee akan melacak serangkaian variabel yang telah ditentukan sebelumnya secara default. Untuk mengetahui informasi selengkapnya, lihat Variabel rekaman aktivitas default dalam laporan rekaman aktivitas. Anda dapat menggunakan kebijakan TraceCapture untuk memperluas perilaku runtime default dan melacak alur, kebijakan, atau variabel kustom tambahan. Untuk mengetahui informasi selengkapnya, lihat kebijakan TraceCapture.
Variabel rekaman aktivitas default dalam laporan rekaman aktivitas
Setelah distributed tracing diaktifkan, Anda dapat melihat kumpulan variabel standar berikut dalam laporan rekaman aktivitas. Variabel terlihat dalam rentang berikut:
- POST_RESP_SENT: Rentang ini ditambahkan setelah respons diterima dari server target.
- POST_CLIENT_RESP_SENT: Rentang ini ditambahkan setelah respons proxy dikirim ke klien.
Variabel dalam rentang POST_RESP_SENT
Variabel berikut terlihat dalam rentangPOST_RESP_SENT
:
- REQUEST_URL (request.url)
- REQUEST_VERB (request.verb)
- RESPONSE_STATUS_CODE (response.status.code)
- ROUTE_NAME (route.name)
- ROUTE_TARGET (route.target)
- TARGET_BASE_PATH (target.basepath)
- TARGET_HOST (target.host)
- TARGET_IP (target.ip)
- TARGET_NAME (target.name)
- TARGET_PORT (target.port)
- TARGET_RECEIVED_END_TIMESTAMP (target.received.end.timestamp)
- TARGET_RECEIVED_START_TIMESTAMP (target.received.start.timestamp)
- TARGET_SENT_END_TIMESTAMP (target.sent.end.timestamp)
- TARGET_SENT_START_TIMESTAMP (target.sent.start.timestamp)
- TARGET_SSL_ENABLED (target.ssl.enabled)
- TARGET_URL (target.url)
Variabel dalam rentang POST_CLIENT_RESP_SENT
Variabel berikut terlihat dalam rentangPOST_CLIENT_RESP_SENT
:
- API_PROXY_REVISION (apiproxy.revision)
- APIPROXY_NAME (apiproxy.name)
- CLIENT_RECEIVED_END_TIMESTAMP (client.received.end.timestamp)
- CLIENT_RECEIVED_START_TIMESTAMP (client.received.start.timestamp)
- CLIENT_SENT_END_TIMESTAMP (client.sent.end.timestamp)
- CLIENT_SENT_START_TIMESTAMP (client.sent.start.timestamp)
- ENVIRONMENT_NAME (environment.name)
- FAULT_SOURCE (message.header + InternalHeaders.FAULT_SOURCE)
- IS_ERROR (is.error)
- MESSAGE_ID (message.id)
- MESSAGE_STATUS_CODE (message.status.code)
- PROXY_BASE_PATH (proxy.basepath)
- PROXY_CLIENT_IP (proxy.client.ip)
- PROXY_NAME (proxy.name)
- PROXY_PATH_SUFFIX (proxy.pathsuffix)
- PROXY_URL (proxy.url)
Sistem pelacakan terdistribusi yang didukung
Runtime Apigee mendukung sistem pelacakan terdistribusi berikut:
- Cloud Trace
- Jaeger
Anda dapat mengonfigurasi runtime Apigee untuk mengirim data rekaman aktivitas ke sistem Cloud Trace atau Jaeger.
Karena melacak semua panggilan API di runtime Apigee akan memengaruhi performa, Apigee memungkinkan Anda mengonfigurasi rasio pengambilan sampel probabilistik.
Dengan menggunakan rasio pengambilan sampel, Anda dapat menentukan jumlah panggilan API yang dikirim untuk pelacakan terdistribusi. Misalnya, jika
Anda menentukan frekuensi pengambilan sampel sebagai 0.4
, artinya 40% panggilan API dikirim untuk pelacakan. Untuk mengetahui informasi selengkapnya, lihat Pertimbangan performa.
Mengonfigurasi runtime Apigee untuk Cloud Trace
Runtime Apigee dan runtime hybrid Apigee mendukung distributed tracing menggunakan Cloud Trace. Jika Anda menggunakan Jaeger, Anda dapat melewati bagian ini dan melanjutkan ke Mengaktifkan pelacakan terdistribusi untuk Jaeger.
Mengonfigurasi runtime Apigee untuk Cloud Trace
Untuk menggunakan Cloud Trace dengan runtime Apigee, project Google Cloud Anda harus mengaktifkan Cloud Trace API. Setelan ini memungkinkan project Google Cloud Anda menerima data rekaman aktivitas dari sumber yang diautentikasi.
Untuk memastikan bahwa Cloud Trace API diaktifkan, lakukan hal berikut:
- Dari Konsol Google Cloud, buka APIs and Services:
- Klik Aktifkan API dan Layanan.
- Di kotak penelusuran, masukkan Trace API.
- Jika API diaktifkan ditampilkan, API ini sudah diaktifkan dan Anda tidak perlu melakukan apa pun. Jika tidak, klik Aktifkan.
Mengonfigurasi runtime Apigee hybrid untuk Cloud Trace
Cloud Trace API harus diaktifkan untuk menggunakan Cloud Trace dengan runtime hybrid Apigee. Untuk mengonfirmasi bahwa Cloud Trace API diaktifkan, ikuti langkah-langkah di Mengonfigurasi runtime Apigee untuk Cloud Trace.
Selain mengaktifkan Cloud Trace API, Anda harus menambahkan akun layanan iam.gserviceaccount.com
untuk menggunakan Cloud Trace dengan runtime hybrid. Untuk menambahkan akun layanan, beserta peran dan kunci yang diperlukan, lakukan langkah-langkah berikut:
- Buat akun layanan baru:
gcloud iam service-accounts create \ apigee-runtime --display-name "Service Account Apigee hybrid runtime" \ --project PROJECT_ID
- Tambahkan binding kebijakan IAM ke akun layanan:
gcloud projects add-iam-policy-binding \ PROJECT_ID --member "serviceAccount:apigee-runtime@PROJECT_ID.iam.gserviceaccount.com" \ --role=roles/cloudtrace.agent --project PROJECT_ID
- Membuat kunci akun layanan:
gcloud iam service-accounts keys \ create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com
- Tambahkan akun layanan ke file
overrides.yaml
. - Terapkan perubahan ke runtime menggunakan
Helm:
helm upgrade ENV_NAME apigee-env/ \ --namespace APIGEE_NAMESPACE \ --set env=ENV_NAME \ --atomic \ -f overrides.yaml
envs: - name: ENV_NAME serviceAccountPaths: runtime: apigee-runtime.json synchronizer: apigee-sync.json udca: apigee-udca.json
Mengaktifkan tracing terdistribusi
Sebelum mengaktifkan pelacakan terdistribusi untuk Cloud Trace atau Jaeger, buat variabel lingkungan berikut:
TOKEN
="Authorization: Bearer $(gcloud auth print-access-token)
"
ENV_NAME
=YOUR_ENVIRONMENT_NAME
PROJECT_ID
=YOUR_GOOGLE_CLOUD_PROJECT_ID
Dengan:
TOKEN
menentukan header Authentication dengan token pemilik. Anda menggunakan header ini saat memanggil Apigee API. Untuk mengetahui informasi selengkapnya, lihat halaman referensi untuk perintah print-access-token.ENV_NAME
adalah nama lingkungan di organisasi Anda.PROJECT_ID
adalah ID project Google Cloud Anda.
Mengaktifkan pelacakan terdistribusi untuk Cloud Trace
Contoh berikut menunjukkan cara mengaktifkan pelacakan terdistribusi untuk Cloud Trace:
- Jalankan panggilan Apigee API ini:
curl -H "$TOKEN" \ -H "Content-Type: application/json" \ https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \ -X PATCH \ -d '{"exporter":"CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'", "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}}'
Contoh isi permintaan terdiri dari elemen berikut:
samplingRate
disetel ke 0,1. Artinya, sekitar 10% panggilan API dikirim ke rekaman aktivitas terdistribusi. Untuk mengetahui informasi selengkapnya tentang menyetelsamplingRate
untuk lingkungan runtime Anda, lihat Pertimbangan performa.- Parameter
exporter
disetel keCLOUD_TRACE
. - Endpoint ditetapkan ke project Google Cloud tempat Anda ingin mengirimkan rekaman aktivitas. CATATAN: Ini harus cocok dengan akun layanan yang dilakukan di langkah konfigurasi.
Respons yang berhasil akan terlihat mirip dengan berikut ini:
{ "exporter": "CLOUD_TRACE", "endpoint": "staging", "samplingConfig": { "sampler": "PROBABILITY", "samplingRate": 0.1 } }
Mengaktifkan pelacakan terdistribusi untuk Jaeger
Contoh berikut menunjukkan cara mengaktifkan distributed tracing untuk Jaeger:
curl -s -H "$TOKEN" \ 'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig' \ -X PATCH \ -H "content-type:application/json" -d '{ "samplingConfig": { "samplingRate": 0.4, "sampler": "PROBABILITY"}, "endpoint": "http://DOMAIN:9411/api/v2/spans", "exporter": "JAEGER" }'
Dalam contoh ini:
samplingRate
disetel ke 0,4. Artinya, sekitar 40% panggilan API dikirim ke pelacakan terdistribusi.- Parameter
exporter
disetel keJAEGER
. - Endpoint ditetapkan ke tempat Jaeger diinstal dan dikonfigurasi.
Saat menjalankan perintah, Anda dapat melihat respons yang mirip dengan berikut:
{ "exporter": "JAEGER", "endpoint": "staging", "samplingConfig": { "sampler": "PROBABILITY", "samplingRate": 0.4 } }
Melihat konfigurasi tracing terdistribusi
Untuk melihat konfigurasi pelacakan terdistribusi yang ada di runtime Anda, login ke runtime Anda, lalu jalankan perintah berikut:
curl -H "$TOKEN" \ -H "Content-Type: application/json" \ https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig
Saat menjalankan perintah, Anda dapat melihat respons yang mirip dengan berikut:
{ "exporter": "CLOUD_TRACE", "endpoint": "staging", "samplingConfig": { "sampler": "PROBABILITY", "samplingRate": 0.1 } }
Memperbarui konfigurasi pelacakan terdistribusi
Perintah berikut menunjukkan cara memperbarui konfigurasi pelacakan terdistribusi yang ada untuk Cloud Trace:
curl -s \ -H "$TOKEN" \ 'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig?updateMask=endpoint,samplingConfig,exporter' \ -X PATCH -H "content-type:application/json" \ -d '{"samplingConfig": {"samplingRate": 0.05, "sampler":"PROBABILITY"}, "endpoint":"staging", exporter:"CLOUD_TRACE"}'
Saat menjalankan perintah, Anda dapat melihat respons yang mirip dengan berikut:
{ "exporter": "CLOUD_TRACE", "endpoint": "staging", "samplingConfig": { "sampler": "PROBABILITY", "samplingRate": 0.05 } }
0.05
.
Menonaktifkan konfigurasi pelacakan terdistribusi
Contoh berikut menunjukkan cara menonaktifkan pelacakan terdistribusi yang dikonfigurasi untuk Cloud Trace:
curl -H "$TOKEN" \ -H "Content-Type: application/json" \ https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \ -X PATCH -d '{"exporter": "CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'","samplingConfig": {"sampler": "OFF","samplingRate": 0.1}}'
Saat menjalankan perintah, Anda dapat melihat respons yang mirip dengan berikut:
{ "exporter": "CLOUD_TRACE", "endpoint": "staging", "samplingConfig": { "sampler": "OFF", "samplingRate": 0.1 } }
Mengganti setelan rekaman aktivitas untuk proxy API
Saat Anda mengaktifkan pelacakan terdistribusi di runtime Apigee, semua proxy API di runtime menggunakan konfigurasi yang sama untuk pelacakan. Namun, Anda dapat mengganti konfigurasi pelacakan terdistribusi untuk proxy API atau grup proxy API. Hal ini memberi Anda kontrol yang lebih terperinci atas konfigurasi pelacakan.
Contoh berikut menggantikan konfigurasi pelacakan terdistribusi untuk
proxy API hello-world
:
curl -s -H "$TOKEN" \ 'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV_NAME/traceConfig/overrides' \ -X POST \ -H "content-type:application/json" \ -d '{"apiProxy": "hello-world","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}}'
Anda dapat mengganti konfigurasi untuk memecahkan masalah khusus pada proxy API tanpa harus mengubah konfigurasi semua proxy API.
Memperbarui penggantian setelan rekaman aktivitas
Untuk memperbarui penggantian konfigurasi pelacakan untuk proxy API atau grup proxy API, gunakan langkah-langkah berikut:
- Gunakan perintah berikut untuk mengambil penggantian konfigurasi pelacakan yang ada:
curl -s -H "$TOKEN" \ 'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \ -X GET
Perintah ini akan menampilkan respons yang mirip dengan berikut, yang berisi kolom "name" yang mengidentifikasi proxy yang diatur oleh penggantian:
{ "traceConfigOverrides": [ { "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1", "apiProxy": "proxy1", "samplingConfig": { "sampler": "PROBABILITY", "samplingRate": 0.25 } } ] }
- Untuk memperbarui proxy, gunakan nilai kolom "name" untuk mengirim permintaan POST ke konfigurasi penggantian untuk
proxy tersebut,beserta nilai kolom yang diperbarui. Contoh:
curl -s -H "$TOKEN" \ 'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \ -X POST \ -H "content-type:application/json" \ -d '{"apiProxy": "proxy1","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05}}'
Menghapus penggantian setelan rekaman aktivitas
Untuk menghapus penggantian konfigurasi pelacakan untuk proxy API atau grup proxy API, gunakan langkah-langkah berikut:
- Gunakan perintah berikut untuk mengambil penggantian konfigurasi pelacakan yang ada:
curl -s -H "$TOKEN" \ 'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \ -X GET
Perintah ini akan menampilkan respons yang mirip dengan berikut, yang berisi kolom "name" yang mengidentifikasi proxy yang diatur oleh penggantian:
{ "traceConfigOverrides": [ { "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1", "apiProxy": "proxy1", "samplingConfig": { "sampler": "PROBABILITY", "samplingRate": 0.25 } } ] }
- Untuk menghapus proxy, gunakan nilai kolom "name" untuk mengirim permintaan DELETE ke konfigurasi penggantian untuk
proxy tersebut,beserta nilai kolom yang diperbarui. Contoh:
curl -s -H "$TOKEN" \ 'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \ -X DELETE \
Pertimbangan performa
Dampak performa diperkirakan terjadi saat Anda mengaktifkan pelacakan terdistribusi untuk lingkungan runtime Apigee. Dampaknya
dapat menyebabkan peningkatan penggunaan memori, peningkatan persyaratan CPU, dan peningkatan latensi.
Besarnya dampak akan bergantung sebagian pada kompleksitas proxy API (misalnya, jumlah kebijakan) dan rasio pengambilan sampel probabilistik (ditetapkan sebagai samplingRate
). Semakin tinggi rasio pengambilan sampel, semakin tinggi dampak pada performa.
Meskipun dampak pada performa bergantung pada sejumlah faktor, Anda dapat memperkirakan penurunan performa sebesar 10-20% saat
menggunakan pelacakan terdistribusi.
Untuk lingkungan dengan persyaratan traffic tinggi dan latensi rendah, tingkat pengambilan sampel probabilistik yang direkomendasikan adalah kurang dari atau sama dengan 10%. Jika Anda ingin menggunakan pelacakan terdistribusi untuk memecahkan masalah,
pertimbangkan untuk meningkatkan pengambilan sampel probabilistik (samplingRate
) hanya untuk proxy API tertentu.