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 dalam 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 menghasilkan laporan yang menunjukkan waktu yang diperlukan oleh permintaan di setiap langkah. Laporan pelacakan juga dapat memberikan tampilan terperinci tentang 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 info layanan dan alur target.
• Waktu respons dikirim ke klien.

Dalam laporan pelacakan terdistribusi, Anda dapat melihat detail eksekusi alur sebagai span. Rentang mengacu pada waktu yang diperlukan oleh alur dalam rekaman aktivitas. Waktu yang diperlukan untuk mengeksekusi alur ditampilkan sebagai agregat waktu yang diperlukan untuk mengeksekusi setiap kebijakan dalam alur. Anda dapat melihat setiap alur berikut sebagai span individual:

• Minta
  • Proxy
    • Pra-alur
    • PostFlow
  • Target
    • Pra-alur
    • PostFlow
• Respons
  • Proxy
    • Pra-alur
    • PostFlow
  • Target
    • Pra-alur
    • PostFlow

Setelah Anda mengaktifkan pelacakan terdistribusi, runtime Apigee akan melacak kumpulan variabel yang telah ditentukan secara default. Untuk informasi selengkapnya, lihat Variabel rekaman aktivitas default dalam laporan perekaman aktivitas. Anda dapat menggunakan kebijakan TraceCapture untuk memperluas perilaku runtime default dan melacak variabel alur, kebijakan, atau kustom tambahan. Untuk 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, ia mengenali header x-b3-traceid, x-b3-spanid, dan x-b3-sampled 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 perekaman aktivitas

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 span POST_RESP_SENT

Variabel berikut terlihat di span 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 span POST_CLIENT_RESP_SENT

Variabel berikut terlihat di 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 (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 Cloud Trace atau sistem Jaeger.

Karena melacak semua panggilan API di runtime Apigee akan memengaruhi performa, Apigee memungkinkan Anda mengonfigurasi frekuensi sampling probabilistik. Dengan menggunakan frekuensi sampling, 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 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 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 enabled ditampilkan, API ini sudah diaktifkan dan Anda tidak perlu melakukan apa pun. Jika tidak, klik Enable.

Mengonfigurasi runtime Apigee hybrid untuk Cloud Trace

Cloud Trace API harus diaktifkan untuk menggunakan Cloud Trace dengan runtime campuran 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 campuran. Untuk menambahkan akun layanan, bersama dengan 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 lainnya yang dijelaskan oleh 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 memperoleh kunci akun layanan dari sumber eksternal, Anda harus memvalidasinya sebelum digunakan. Untuk mengetahui informasi selengkapnya, lihat Persyaratan keamanan untuk kredensial yang bersumber secara 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 informasi selengkapnya tentang cara mengaktifkan Cloud Trace di mesh layanan, lihat Mengakses trace di Cloud Trace.

Mengaktifkan 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 Authentication dengan token pemilik. Anda menggunakan header ini saat memanggil Apigee API. Untuk 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 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. Artinya, sekitar 10% panggilan API dikirim ke rekaman aktivitas terdistribusi. Untuk informasi selengkapnya tentang cara menetapkan samplingRate untuk lingkungan runtime, lihat Pertimbangan performa.
   • Parameter exporter disetel ke CLOUD_TRACE.
   • Endpoint ditetapkan ke project Google Cloud tempat Anda ingin pelacakan dikirim. CATATAN: Akun ini harus cocok dengan akun layanan yang dilakukan pada 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 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. 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 ini:

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

Melihat konfigurasi pelacakan terdistribusi

Untuk melihat konfigurasi pelacakan terdistribusi yang ada di runtime, 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
  }
}

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

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

Dalam contoh ini, frekuensi sampling 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 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 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 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, yang berisi kolom "name" 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 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 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 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 akan 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 frekuensi sampling probabilistik (ditetapkan sebagai samplingRate). Makin tinggi frekuensi sampling, makin tinggi dampaknya terhadap performa. Meskipun dampaknya terhadap performa bergantung pada sejumlah faktor, Anda dapat mengalami penurunan performa sebesar 10-20% saat menggunakan pelacakan terdistribusi.

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