Kebijakan TraceCapture

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat Dokumentasi Apigee Edge.

ikon kebijakan

Ringkasan

Kebijakan TraceCapture memungkinkan Anda menambahkan variabel tambahan ke runtime Apigee data pelacakan. Jika Anda telah mengaktifkan pelacakan terdistribusi untuk runtime Apigee, secara default, runtime akan melacak sekumpulan variabel yang telah ditentukan. Untuk informasi selengkapnya, lihat Variabel rekaman aktivitas default dalam laporan pelacakan. Namun, jika Anda ingin runtime Apigee melacak alur, kebijakan, atau variabel kustom tambahan, gunakan TraceCapture lebih lanjut. Anda dapat menggunakan kebijakan ini dalam alur permintaan atau respons. Di laporan pelacakan, Anda dapat melihat variabel yang ditambahkan oleh kebijakan TraceCapture dalam span TraceCaptureExecution.

Kebijakan ini merupakan Kebijakan yang dapat diperluas dan penggunaan kebijakan ini mungkin menimbulkan biaya atau implikasi penggunaan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaan, lihat Jenis kebijakan.

<TraceCapture>

Menentukan kebijakan TraceCapture.

Nilai Default T/A
Wajib? Wajib
Jenis Jenis kompleks
Elemen Induk T/A
Elemen Turunan <DisplayName>
<IgnoreUnresolvedVariables>
<ThrowExceptionOnLimit>
<Variables>

Elemen <TraceCapture> menggunakan sintaksis berikut:

Sintaks

<?xml version="1.0" encoding="UTF-8"?>
<TraceCapture continueOnError="true" enabled="true" name="DistributedTraceCapture-1">
    <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
    <Variables>
        <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
        <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
    </Variables>
    <IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>
    <ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>
</TraceCapture>

Contoh

Contoh berikut menunjukkan definisi kebijakan TraceCapture:

<?xml version="1.0" encoding="UTF-8"?>
<TraceCapture continueOnError="true" enabled="true" name="DistributedTraceCapture-1">
    <DisplayName>Distributed-Trace-Capture-Policy-1</DisplayName>
    <Variables>
        <Variable name="trace-variable-1" ref="flow-variable-1">default-val-1</Variable>
        <Variable name="trace-variable-2" ref="flow-variable-2">default-val-2</Variable>
    </Variables>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>
</TraceCapture>

Elemen ini memiliki atribut berikut yang sama untuk semua kebijakan:

Atribut Default Wajib? Deskripsi
name T/A Wajib

Nama internal kebijakan. Nilai atribut name dapat berisi huruf, angka, spasi, tanda hubung, garis bawah, dan titik. Nilai ini tidak boleh melebihi 255 karakter.

Atau, gunakan elemen <DisplayName> untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama natural-language yang berbeda.

continueOnError false Opsional Setel ke false untuk menampilkan error jika kebijakan gagal. Ini adalah perilaku yang wajar untuk sebagian besar kebijakan. Setel ke true agar eksekusi alur tetap berlanjut bahkan setelah kebijakan gagal. Lihat juga:
enabled true Opsional Setel ke true untuk menerapkan kebijakan. Setel ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap melekat pada alur.
async   false Tidak digunakan lagi Atribut ini sudah tidak digunakan lagi.

Tabel berikut memberikan deskripsi tingkat tinggi untuk elemen turunan <TraceCapture>:

Elemen Turunan Wajib? Deskripsi
<DisplayName> Opsional Menentukan nama kustom untuk kebijakan.
<Variables> Opsional Menentukan daftar variabel yang akan dilacak.
<IgnoreUnresolvedVariables> Opsional Menentukan apakah pemrosesan berhenti saat variabel yang belum terselesaikan ditemukan.
<ThrowExceptionOnLimit> Opsional Menentukan apakah variabel harus dipotong jika ukuran variabel melebihi batas 256 byte.
Elemen turunan lainnya
<MergeBehavior> Opsional Menentukan perilaku penggabungan untuk pesan respons.

Referensi elemen turunan

Bagian ini menjelaskan elemen turunan dari <TraceCapture>.

<DisplayName>

Gunakan selain atribut name untuk memberi label kebijakan di editor proxy UI pengelolaan dengan nama yang berbeda dan lebih alami.

Elemen <DisplayName> bersifat umum untuk semua kebijakan.

Nilai Default T/A
Wajib? Opsional. Jika Anda menghilangkan <DisplayName>, nilai atribut name kebijakan akan digunakan.
Jenis String
Elemen Induk <PolicyElement>
Elemen Turunan Tidak ada

Elemen <DisplayName> menggunakan sintaksis berikut:

Sintaksis

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Contoh

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

Elemen <DisplayName> tidak memiliki atribut atau elemen turunan.

<Variables>

Menentukan daftar variabel yang akan dilacak.

Nilai Default T/A
Wajib? Wajib
Jenis Jenis kompleks
Elemen Induk <TraceCapture>
Elemen Turunan <Variable>

Elemen <Variables> menggunakan sintaksis berikut:

Sintaks

<Variables>
    <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
    <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
</Variables>

Contoh

Contoh berikut merekam aktivitas variabel alur flow-variable-1 dan flow-variable-2:

<Variables>
    <Variable name="trace-variable-1" ref="flow-variable-1">default-val-1</Variable>
    <Variable name="trace-variable-2" ref="flow-variable-2">default-val-2</Variable>
</Variables>

<Variable>

Menentukan variabel yang akan ditambahkan dalam data rekaman aktivitas.

Nilai Default T/A
Wajib? Wajib
Jenis Jenis kompleks
Elemen Induk <Variables>
Elemen Turunan Tidak ada

Elemen <Variable> menggunakan sintaksis berikut:

Sintaks
<Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
Contoh

Contoh berikut menetapkan variabel rekaman aktivitas trace-variable-1 ke nilai variabel flow flow-variable-1:

<Variable name="trace-variable-1" ref="flow-variable-1">default-val-1</Variable>

Jika variabel alur flow-variable-1 tidak tersedia, trace-variable-1 ditetapkan ke nilai default default-val-1.

Tabel berikut menjelaskan atribut <Variable>:

Atribut Wajib? Jenis Deskripsi
name Wajib String Nama untuk mereferensikan data yang dikumpulkan untuk variabel yang ditentukan. Nama ini akan menjadi terlihat dalam laporan pelacakan terdistribusi Anda.
ref Wajib String Variabel yang Anda gunakan untuk mengumpulkan data trace. Variabel ini dapat berupa alur variabel yang telah ditentukan sebelumnya oleh Apigee atau variabel kustom di proxy API Anda.

<IgnoreUnresolvedVariables>

Menentukan apakah pemrosesan berhenti saat variabel yang belum terselesaikan ditemukan.

Nilai Default T/A
Wajib? Opsional
Jenis Boolean
Elemen Induk <TraceCapture>
Elemen Turunan Tidak ada

Tetapkan ke true untuk mengabaikan variabel yang belum terselesaikan dan melanjutkan pemrosesan; jika tidak, false. Tujuan nilai defaultnya adalah true.

Menyetel <IgnoreUnresolvedVariables> ke true berbeda dengan menyetel <TraceCapture> continueOnError hingga true. Jika Anda menetapkan continueOnError ke true, Apigee akan mengabaikan semua error, bukan hanya {i>error <i} dalam variabel.

Elemen <IgnoreUnresolvedVariables> menggunakan sintaksis berikut:

Sintaks

<IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>

Contoh

Contoh berikut menetapkan <IgnoreUnresolvedVariables> ke false:

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

<ThrowExceptionOnLimit>

Menentukan perilaku kebijakan saat ukuran variabel melebihi batas 256 byte.

  • Jika disetel ke true, kebijakan akan menampilkan error jika ukuran variabel melebihi batas.
  • Jika disetel ke false, kebijakan akan memotong variabel yang melebihi batas. Tujuan variabel terpotong ke ukuran batas.
Nilai Default T/A
Wajib? Opsional
Jenis Boolean
Elemen Induk <TraceCapture>
Elemen Turunan Tidak ada

Elemen <ThrowExceptionOnLimit> menggunakan sintaksis berikut:

Sintaks

<ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>

Contoh

Contoh berikut menetapkan nilai <ThrowExceptionOnLimit> ke true.

<ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>

Kode error

Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan dan variabel kesalahan yang disetel oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui apakah Anda mengembangkan aturan kesalahan untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.

Error runtime

Error ini dapat terjadi saat kebijakan dieksekusi.

Kode kesalahan Status HTTP Penyebab
steps.tracecapture.UnresolvedVariable 500

Error ini terjadi jika variabel yang ditentukan dalam kebijakan TraceCapture:

  • Di luar cakupan (tidak tersedia di alur spesifik tempat kebijakan sedang dijalankan)
  • atau
  • Tidak dapat diselesaikan (tidak ditentukan)
steps.tracecapture.VariableValueLimitExceeded 500

Error ini terjadi jika elemen <ThrowExceptionOnLimit> disetel ke true dan ukuran variabel apa pun melebihi 256 byte.

Variabel kesalahan

Setiap kali terjadi error eksekusi dalam kebijakan, Apigee akan menghasilkan pesan error. Anda dapat melihat pesan error ini dalam respons error. Sering kali, pesan error yang dihasilkan sistem mungkin tidak relevan dalam konteks produk Anda. Anda mungkin ingin menyesuaikan pesan error berdasarkan jenis error agar pesan menjadi lebih bermakna.

Untuk menyesuaikan pesan error, Anda dapat menggunakan aturan kesalahan atau kebijakan RaiseFault. Untuk mengetahui informasi tentang perbedaan antara aturan fault dan kebijakan RaiseFault, lihat kebijakan FaultRules vs. RaiseFault. Anda harus memeriksa kondisi menggunakan elemen Condition di aturan fault dan kebijakan RaiseFault. Apigee menyediakan variabel kesalahan yang unik untuk setiap kebijakan dan nilai variabel kesalahan ditetapkan saat kebijakan memicu error runtime. Dengan menggunakan variabel ini, Anda dapat memeriksa kondisi error tertentu dan mengambil tindakan yang sesuai. Untuk mengetahui informasi selengkapnya tentang cara memeriksa kondisi error, lihat Mem-build kondisi.

Tabel berikut menjelaskan variabel kesalahan khusus untuk kebijakan ini.

Variabel Dari mana Contoh
fault.name fault.name dapat cocok dengan kesalahan mana pun yang tercantum dalam tabel Error runtime. Nama kesalahan adalah bagian terakhir dari kode kesalahan. fault.name Matches "UnresolvedVariable"
tracecapture.POLICY_NAME.failed POLICY_NAME adalah nama kebijakan yang ditentukan pengguna yang menampilkan kesalahan. tracecapture.trace-capture-1.failed = true
Untuk informasi selengkapnya tentang error kebijakan, lihat Yang perlu Anda ketahui tentang error kebijakan.