Mengaktifkan pelacakan terdistribusi

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Pratinjau

Produk atau fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Produk dan fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

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
• Respons
  • Proxy
    • Preflow
    • PostFlow
  • Target
    • Preflow
    • PostFlow

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.

Panggilan API masuk ke Apigee mungkin berisi header rekaman aktivitas karena panggilan tersebut merupakan bagian dari rekaman aktivitas yang ada. Dalam hal ini, Apigee berpartisipasi dalam rekaman aktivitas yang ada dan menyebarkan header ke panggilan API keluar. Runtime Apigee memahami format header Zipkin B3. Oleh karena itu, header x-b3-traceid, x-b3-spanid, dan x-b3-sampled dikenali saat berpartisipasi dalam rekaman aktivitas yang ada. Namun, jika tidak ada header rekaman aktivitas dalam panggilan API masuk, Apigee akan menambahkan header rekaman aktivitasnya dan menyebarkannya ke panggilan API keluar. Layanan lain dapat mengakses header dan berpartisipasi dalam pelacakan jika diperlukan.

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 rentang POST_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 rentang POST_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.

Frekuensi sampling maksimum yang dapat dikonfigurasi adalah 0.5.

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:

1. Dari Konsol Google Cloud, buka APIs and Services:

   Buka API dan Layanan

2. Klik Aktifkan API dan Layanan.
3. Di kotak penelusuran, masukkan Trace API.
4. 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:

1. Buat akun layanan baru:

   gcloud iam service-accounts create \
       apigee-runtime --display-name "Service Account Apigee hybrid runtime" \
       --project PROJECT_ID

2. 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

3. Membuat kunci akun layanan:

   gcloud iam service-accounts keys \
       create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com

   Kunci akun layanan akan berisiko keamanan jika tidak dikelola dengan benar. Anda bertanggung jawab atas keamanan kunci pribadi dan atas operasi lain yang dijelaskan dalam Praktik terbaik untuk mengelola kunci akun layanan. Jika Anda tidak dapat membuat kunci akun layanan, pembuatan kunci akun layanan mungkin dinonaktifkan untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat Mengelola resource organisasi yang aman secara default.

   Jika Anda mendapatkan kunci akun layanan dari sumber eksternal, Anda harus memvalidasinya sebelum digunakan. Untuk mengetahui informasi selengkapnya, lihat Persyaratan keamanan untuk kredensial yang bersumber dari eksternal".

4. Tambahkan akun layanan ke file overrides.yaml.

envs:
 - name: ENV_NAME
   serviceAccountPaths:
   runtime: apigee-runtime.json
   synchronizer: apigee-sync.json
   udca: apigee-udca.json

5. Terapkan perubahan ke runtime menggunakan Helm:

   helm upgrade ENV_NAME apigee-env/ \
       --namespace APIGEE_NAMESPACE \
       --set env=ENV_NAME \
       --atomic \
       -f overrides.yaml

Di lingkungan hybrid Apigee, Anda dapat menggunakan Anthos Service Mesh, dengan Cloud Trace. Untuk mengetahui informasi selengkapnya tentang cara mengaktifkan Cloud Trace di mesh layanan, lihat Mengakses rekaman aktivitas di Cloud Trace.

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:

1. 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 menyetel samplingRate untuk lingkungan runtime Anda, lihat Pertimbangan performa.
   • Parameter exporter disetel ke CLOUD_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 ke JAEGER.
• 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
  }
}

Dalam contoh ini, frekuensi pengambilan sampel diperbarui menjadi 0.05.

Untuk memperbarui konfigurasi Jaeger, tetapkan kolom exporter dalam permintaan ke JAEGER.

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:

1. 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
         }
       }
     ]
   }

2. 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:

1. 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
         }
       }
     ]
   }

2. 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.