Kebijakan TraceCapture

Kebijakan yang dapat diperluas

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

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

Kebijakan ini adalah Extensible policy dan penggunaan kebijakan ini mungkin memiliki implikasi biaya atau penggunaan, bergantung pada lisensi Apigee Anda. Untuk mengetahui informasi tentang jenis kebijakan dan implikasi penggunaannya, 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:

Sintaksis

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

此元素具有所有政策中常见的以下属性:

属性 默认 是否必需? 说明
name 不适用 必需

政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。

(可选)使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

continueOnError false 可选 设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 true,即使在政策失败后,仍可以继续执行流。另请参阅:
enabled true 可选 设置为 true 可实施政策。 设为 false 可关闭政策。即使政策仍附加到某个流,也不会强制执行该政策。
async   false 已弃用 此属性已弃用。

Tabel berikut memberikan deskripsi umum tentang 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 dipangkas 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 <TraceCapture>.

<DisplayName>

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

Elemen <DisplayName> 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:

Sintaks

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

Sintaksis

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

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

Contoh berikut menetapkan variabel pelacakan trace-variable-1 ke nilai variabel alur 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 disetel 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 terlihat dalam laporan pelacakan terdistribusi Anda.
ref Wajib String Variabel yang digunakan untuk mengumpulkan data rekaman aktivitas. Variabel ini dapat berupa variabel alur yang telah ditentukan sebelumnya oleh Apigee atau variabel kustom di proxy API Anda.

<IgnoreUnresolvedVariables>

Menentukan apakah pemrosesan berhenti saat variabel yang belum diselesaikan ditemukan.

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

Setel ke true untuk mengabaikan variabel yang belum diselesaikan dan melanjutkan pemrosesan; jika tidak, setel ke false. Nilai default-nya adalah true.

Menetapkan <IgnoreUnresolvedVariables> ke true berbeda dengan menetapkan continueOnError <TraceCapture> ke true. Jika Anda menetapkan continueOnError ke true, Apigee akan mengabaikan semua error, bukan hanya error dalam variabel.

Elemen <IgnoreUnresolvedVariables> menggunakan sintaksis berikut:

Sintaksis

<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 memangkas variabel yang melebihi batas. Variabel dipangkas hingga ukuran batas.
Nilai Default T/A
Wajib? Opsional
Jenis Boolean
Elemen Induk <TraceCapture>
Elemen Turunan Tidak ada

Elemen <ThrowExceptionOnLimit> menggunakan sintaksis berikut:

Sintaksis

<ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>

Contoh

Contoh berikut menetapkan nilai <ThrowExceptionOnLimit> ke true.

<ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>

Kode error

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

Error runtime

Error ini dapat terjadi saat kebijakan dijalankan.

Kode kerusakan Status HTTP Penyebab
steps.tracecapture.UnresolvedVariable 500

Error ini terjadi jika variabel yang ditentukan dalam kebijakan TraceCapture adalah:

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

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

Variabel error

Setiap kali ada 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 untuk membuat pesan lebih bermakna.

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

Tabel berikut menjelaskan variabel error khusus untuk kebijakan ini.

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