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 di 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 guna mengonfigurasi pelacakan terdistribusi untuk runtime Apigee Anda. Jika Anda baru menggunakan sistem pelacakan terdistribusi dan menginginkan informasi lebih lanjut, lihat Memahami Pelacakan Terdistribusi.

Pengantar

Sistem pelacakan terdistribusi memungkinkan Anda melacak permintaan dalam sistem software yang didistribusikan di banyak aplikasi, layanan, dan {i>database<i}, serta perantara seperti {i>proxy<i}. Pelacakan ini sistem menghasilkan laporan yang menunjukkan waktu yang dibutuhkan oleh permintaan di setiap langkah. Laporan pelacakan juga dapat memberikan tampilan terperinci tentang berbagai layanan yang dipanggil selama permintaan, sehingga memungkinkan pemahaman yang lebih dalam tentang apa terjadi di setiap langkah dalam sistem perangkat lunak Anda.

Alat rekaman aktivitas di Apigee Edge dan alat debug di Apigee berguna untuk memecahkan masalah dan memantau proxy API Anda. Namun, alat ini tidak mengirim data ke server pelacakan seperti Cloud Trace atau Jaeger. Untuk melihat data runtime Apigee dalam laporan pelacakan terdistribusi, Anda harus secara eksplisit mengaktifkan pelacakan terdistribusi dalam runtime Apigee Anda. Setelah perekaman aktivitas diaktifkan, runtime dapat mengirim data pelacakan ke server pelacakan terdistribusi dan berpartisipasi dalam pelacakan yang ada. Hasilnya, Anda dapat melihat data dari dalam dan luar ekosistem Apigee Anda dari satu lokasi.

Anda dapat melihat informasi berikut dalam laporan pelacakan terdistribusi:

• Waktu eksekusi di 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 info layanan dan alur target.
• Waktu saat respons dikirim ke klien.

Dalam laporan pelacakan terdistribusi, Anda dapat melihat detail eksekusi alur sebagai span. Span mengacu pada waktu yang dibutuhkan oleh flow dalam trace. Waktu yang diperlukan untuk menjalankan alur ditampilkan sebagai gabungan waktu yang diperlukan untuk menjalankan setiap kebijakan dalam alur. Anda dapat melihat setiap alur berikut sebagai span individual:

• Minta
  • {i>proxy<i}
    • Pra-alur
    • PostFlow
  • Target
    • Pra-alur
    • PostFlow
• Respons
  • {i>proxy<i}
    • Pra-alur
    • PostFlow
  • Target
    • Pra-alur
    • PostFlow

Setelah Anda mengaktifkan pelacakan terdistribusi, runtime Apigee akan melacak serangkaian variabel yang telah ditentukan secara default. Untuk informasi selengkapnya, lihat Variabel rekaman aktivitas default dalam laporan pelacakan. Anda dapat menggunakan kebijakan TraceCapture untuk memperluas perilaku runtime default dan melacak alur, kebijakan, atau variabel kustom tambahan. Untuk informasi selengkapnya, lihat kebijakan TraceCapture.

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

Variabel rekaman aktivitas default dalam laporan pelacakan

Setelah pelacakan terdistribusi diaktifkan, Anda dapat melihat kumpulan variabel standar berikut dalam laporan pelacakan. Variabel terlihat dalam span berikut:

• POST_RESP_SENT: Span ini ditambahkan setelah respons diterima dari server target.
• POST_CLIENT_RESP_SENT: Span ini ditambahkan setelah respons proxy dikirim ke klien.

Variabel dalam rentang POST_RESP_SENT

Variabel berikut terlihat dalam span POST_RESP_SENT:

• REQUEST_URL (request.url)
• REQUEST_VERB (request.verb)
• RESPONSE_STATUS_CODE (response.status.code)
• ROUTE_NAME (nama.rute)
• ROUTE_TARGET (route.target)
• TARGET_BASE_PATH (target.basepath)
• TARGET_HOST (target.host)
• TARGET_IP (target.ip)
• TARGET_NAME (nama.target)
• 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 span 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 (nama.proxy)
• 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 trace ke Cloud Trace atau Sistem Jaeger.

Karena melacak semua panggilan API di runtime Apigee akan memengaruhi performa, Apigee memungkinkan Anda mengonfigurasi frekuensi sampling probabilistik. Dengan frekuensi sampling, Anda dapat menentukan jumlah panggilan API yang dikirim untuk pelacakan terdistribusi. Misalnya, jika jika Anda menetapkan frekuensi sampling sebagai 0.4, berarti 40% panggilan API tersebut dikirim untuk pelacakan. Untuk 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 pelacakan terdistribusi 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 memiliki Cloud Trace API diaktifkan. Setelan ini memungkinkan project Google Cloud Anda menerima data trace dari sumber yang diautentikasi.

Untuk mengonfirmasi bahwa Cloud Trace API telah aktif, 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 enabled ditampilkan, berarti API ini sudah diaktifkan dan tidak ada yang perlu Anda lakukan. Atau, klik Aktifkan.

Mengonfigurasi runtime hybrid Apigee untuk Cloud Trace

Cloud Trace API harus diaktifkan agar dapat menggunakan Cloud Trace dengan runtime hybrid Apigee. Untuk mengonfirmasi bahwa {i>Cloud<i} Trace API diaktifkan, ikuti langkah-langkah di Mengonfigurasi runtime Apigee untuk Cloud Trace.

Selain mengaktifkan Cloud Trace API, Anda harus menambahkan akun layanan untuk menggunakan Cloud Trace dengan runtime hybrid. Untuk menambahkan 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." \
       --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.

   Kunci akun layanan merupakan risiko keamanan jika tidak dikelola dengan benar. Anda bertanggung jawab atas keamanan kunci pribadi dan untuk operasi lain yang dijelaskan oleh Praktik terbaik untuk mengelola kunci akun layanan. Jika Anda tidak dapat membuat kunci akun layanan, pembuatan kunci akun layanan dapat dinonaktifkan untuk organisasi Anda. Untuk informasi selengkapnya, lihat Mengelola resource organisasi yang aman secara default.
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. Menerapkan perubahan pada runtime

apigeectl apply -f overrides.yaml --env=ENV_NAME

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 trace di Cloud Trace.

Aktifkan pelacakan 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 keterangan:

• TOKEN menentukan header Autentikasi dengan token pemilik. Anda menggunakan header ini saat memanggil Apigee API. Untuk informasi selengkapnya, lihat halaman referensi untuk 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 API Apigee 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. Ini berarti sekitar 10% panggilan API dikirim ke pelacakan terdistribusi. Untuk informasi selengkapnya tentang cara menyetel samplingRate untuk lingkungan runtime, lihat Pertimbangan performa.
   • Parameter exporter disetel ke CLOUD_TRACE.
   • Endpoint ditetapkan ke project Google Cloud tempat Anda ingin mengirimkan trace. CATATAN: Ini harus cocok dengan layanan akun yang dilakukan di langkah konfigurasi.

   Respons yang berhasil akan terlihat seperti berikut:

   {
     "exporter": "CLOUD_TRACE",
     "endpoint": "staging",
     "samplingConfig": {
       "sampler": "PROBABILITY",
       "samplingRate": 0.1
     }
   }

Aktifkan pelacakan terdistribusi untuk Jaeger

Contoh berikut menunjukkan cara mengaktifkan pelacakan terdistribusi 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. Ini berarti sekitar 40% panggilan API dikirim ke pelacakan terdistribusi.
• Parameter exporter disetel ke JAEGER.
• Endpoint disetel ke tempat Jaeger diinstal dan dikonfigurasi.

Saat menjalankan perintah, Anda dapat melihat respons yang mirip dengan berikut ini:

{
  "exporter": "JAEGER",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.4
  }
}

Melihat konfigurasi pelacakan terdistribusi

Untuk melihat konfigurasi pelacakan terdistribusi yang ada dalam runtime Anda, login ke runtime, 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 ini:

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}

Mengupdate konfigurasi pelacakan terdistribusi

Perintah berikut menunjukkan cara mengupdate konfigurasi pelacakan terdistribusi yang sudah 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 ini:

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  }
}

Dalam contoh ini, frekuensi sampling diperbarui menjadi 0.05.

Untuk memperbarui konfigurasi untuk Jaeger, setel kolom exporter di 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 ini:

{
  "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 dalam penggunaan runtime 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 aktivitas.

Contoh berikut mengganti 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 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 ini, yang berisi "name" bidang yang mengidentifikasi proxy atau proxy yang diatur oleh penggantian:

   {
     "traceConfigOverrides": [
       {
         "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
         "apiProxy": "proxy1",
         "samplingConfig": {
           "sampler": "PROBABILITY",
           "samplingRate": 0.25
         }
       }
     ]
   }

2. Untuk mengupdate proxy, gunakan nilai "name" bidang isian untuk mengirim permintaan POST ke konfigurasi penggantian untuk {i>proxy<i} itu,beserta nilai-nilai {i>field <i}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}}'

Hapus penggantian setelan rekaman aktivitas

Guna 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 ini, yang berisi "name" bidang yang mengidentifikasi proxy atau 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 "nama" untuk mengirim permintaan DELETE ke konfigurasi penggantian untuk {i>proxy<i} itu,beserta nilai-nilai {i>field <i}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 diharapkan akan muncul saat Anda mengaktifkan pelacakan terdistribusi untuk lingkungan runtime Apigee. Dampak mengakibatkan peningkatan penggunaan memori, peningkatan kebutuhan CPU, dan peningkatan latensi. Besarnya dampaknya akan bergantung sebagian pada kompleksitas proxy API (misalnya, jumlah kebijakan) dan frekuensi sampling probabilistik (ditetapkan sebagai samplingRate). Makin tinggi frekuensi sampling, makin tinggi dampaknya pada performa. Meskipun dampaknya terhadap kinerja bergantung pada sejumlah faktor, tetapi Anda dapat memperkirakan penurunan kinerja sebesar 10-20% saat menggunakan pelacakan terdistribusi.

Untuk lingkungan dengan persyaratan traffic tinggi dan latensi rendah, rekomendasi probabilistik frekuensi sampling kurang dari atau sama dengan 10%. Jika Anda ingin menggunakan pelacakan terdistribusi untuk memecahkan masalah, sebaiknya tingkatkan sampling probabilistik (samplingRate) hanya untuk proxy API tertentu.