Halaman ini diterjemahkan oleh Cloud Translation API.

Mengaktifkan pelacakan terdistribusi

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Baca 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 menginginkan informasi selengkapnya, lihat Memahami Pelacakan Terdistribusi.

Pengantar

Sistem pelacakan terdistribusi memungkinkan Anda melacak permintaan dalam sistem software yang didistribusikan ke beberapa aplikasi, layanan, dan database, serta perantara seperti proxy. Sistem pelacakan ini menghasilkan laporan yang menunjukkan waktu yang dibutuhkan oleh permintaan di setiap langkah. Laporan pelacakan juga dapat memberikan gambaran terperinci tentang berbagai layanan yang dipanggil selama permintaan, sehingga memungkinkan pemahaman yang lebih mendalam tentang apa yang terjadi pada setiap langkah dalam sistem software 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 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 dalam runtime Apigee. Setelah perekaman aktivitas diaktifkan, runtime dapat mengirim data rekaman aktivitas ke server pelacakan terdistribusi dan berpartisipasi dalam pelacakan yang ada. Oleh karena itu, 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 flow.
Waktu saat permintaan diterima.
Waktu saat permintaan dikirim ke target.
Waktu saat respons diterima dari target.
Waktu eksekusi setiap kebijakan dalam satu alur.
Waktu eksekusi pemanggilan layanan dan alur target.
Waktu saat respons dikirim ke klien.

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

Minta
- Proxy
  - Alur awal
  - PostFlow
- Target
  - Alur awal
  - PostFlow
Respons
- Proxy
  - Alur awal
  - PostFlow
- Target
  - Alur awal
  - PostFlow

Setelah Anda mengaktifkan pelacakan terdistribusi, runtime Apigee akan melacak kumpulan variabel yang telah ditetapkan secara default. Untuk mengetahui informasi selengkapnya, lihat Variabel pelacakan default dalam laporan pelacakan. 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 yang masuk ke Apigee mungkin berisi header rekaman aktivitas karena panggilan tersebut adalah bagian dari rekaman aktivitas 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, parser dapat mengenali header x-b3-traceid, x-b3-spanid, dan x-b3-sampled saat berpartisipasi dalam rekaman aktivitas yang ada. Namun, jika tidak ada header trace dalam panggilan API yang masuk, Apigee akan menambahkan header trace-nya dan menyebarkannya ke panggilan API keluar. Layanan lain dapat mengakses header dan berpartisipasi dalam perekaman aktivitas jika diperlukan.

Variabel rekaman aktivitas default dalam laporan rekaman aktivitas

Setelah pelacakan terdistribusi diaktifkan, Anda dapat melihat kumpulan variabel standar berikut dalam laporan pelacakan. Variabel ini dapat dilihat 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 dapat dilihat 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.acceptd.end.timestamp)
TARGET_RECEIVED_START_TIMESTAMP (target.acceptd.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 dapat dilihat dalam span POST_CLIENT_RESP_SENT:

API_PROXY_REVISION (apiproxy.revision)
APIPROXY_NAME (apiproxy.name)
CLIENT_RECEIVED_END_TIMESTAMP (client.acceptd.end.timestamp)
CLIENT_RECEIVED_START_TIMESTAMP (client.acceptd.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 rekaman aktivitas ke sistem Cloud Trace atau Jaeger.

Karena melacak semua panggilan API dalam runtime Apigee akan memengaruhi performa, Apigee memungkinkan Anda mengonfigurasi frekuensi sampling probabilistik. Dengan menggunakan frekuensi sampling, Anda dapat menentukan jumlah panggilan API yang dikirimkan untuk pelacakan terdistribusi. Misalnya, jika Anda menentukan frekuensi sampling sebagai 0.4, berarti 40% panggilan API dikirim untuk perekaman aktivitas. 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 mengonfirmasi bahwa Cloud Trace API telah diaktifkan, lakukan hal berikut:

Dari konsol Google Cloud, buka APIs and Services:
Buka API dan Layanan
Klik Aktifkan API dan Layanan.
Di kotak penelusuran, masukkan Trace API.
Jika API diaktifkan ditampilkan, berarti API ini sudah diaktifkan dan tidak ada yang perlu Anda lakukan. Jika tidak, klik Enable.

Mengonfigurasi runtime hybrid Apigee untuk Cloud Trace

Cloud Trace API harus diaktifkan untuk menggunakan Cloud Trace dengan runtime hybrid Apigee. Untuk memastikan bahwa Cloud Trace API telah diaktifkan, ikuti langkah-langkah dalam 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

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

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

Menerapkan perubahan pada runtime

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

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 Authentication dengan token pemilik. Gunakan header ini ketika 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:

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 mengetahui informasi selengkapnya tentang cara menetapkan samplingRate untuk lingkungan runtime Anda, lihat Pertimbangan performa.
- Parameter exporter disetel ke CLOUD_TRACE.
- Endpoint ditetapkan ke project Google Cloud tempat Anda ingin mengirim pelacakan. 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
  }
}
```

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

Guna memperbarui konfigurasi untuk 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 dalam runtime Apigee, semua proxy API dalam runtime akan menggunakan konfigurasi yang sama untuk pelacakan. Namun, Anda dapat mengganti konfigurasi pelacakan terdistribusi untuk proxy API atau sekelompok 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:

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 serupa dengan berikut ini, 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
      }
    }
  ]
}

Untuk mengupdate proxy, gunakan nilai kolom "name" untuk mengirim permintaan POST ke konfigurasi penggantian untuk proxy tersebut,bersama dengan 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}}'

Hapus penggantian setelan rekaman aktivitas

Untuk menghapus penggantian konfigurasi pelacakan bagi 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 serupa dengan berikut ini, 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
      }
    }
  ]
}

Untuk menghapus proxy, gunakan nilai kolom "name" untuk mengirim permintaan DELETE ke konfigurasi penggantian untuk proxy tersebut,bersama dengan nilai kolom yang diupdate. 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 mengakibatkan 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 pada performa bergantung pada sejumlah faktor, tetapi Anda dapat memperkirakan penurunan performa sebesar 10-20% jika menggunakan pelacakan terdistribusi.

Untuk lingkungan dengan persyaratan traffic tinggi dan 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.