Kebijakan TraceCapture

Kebijakan yang dapat diperluas

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.

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 Kebijakan yang dapat diperluas 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>

Elemen ini memiliki atribut berikut yang umum 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. Secara opsional, gunakan elemen <DisplayName> untuk memberi label pada kebijakan di editor proxy UI pengelolaan dengan nama bahasa alami yang berbeda.
continueOnError	false	Opsional	Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Perilaku ini wajar terjadi untuk sebagian besar kebijakan. Tetapkan ke true agar eksekusi alur berlanjut meskipun setelah kebijakan gagal. Lihat juga: Aturan error HANYA dipicu dalam status error (tentang continueOnError) Menangani error dalam alur saat ini
enabled	benar	Opsional	Tetapkan ke true untuk menerapkan kebijakan. Tetapkan ke false untuk menonaktifkan kebijakan. Kebijakan tidak akan diterapkan meskipun tetap terlampir ke alur.
async	false	Tidak digunakan lagi	Atribut ini tidak digunakan lagi.

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

Catatan:

• Anda tidak dapat melacak variabel private dan policy.secret.
• Apigee merekomendasikan Anda untuk mengonfigurasi maksimum 15 variabel untuk Cloud Trace dan maksimum 25 variabel untuk Jaeger.

<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 rekaman aktivitas 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 datanya Anda kumpulkan. Variabel ini dapat berupa variabel alur yang telah ditentukan sebelumnya oleh Apigee atau variabel kustom di proxy API Anda.

Catatan: Anda dapat menentukan nilai default opsional untuk variabel. Jika variabel yang ditentukan dalam ref tidak ditentukan dalam permintaan atau respons, data rekaman aktivitas akan memiliki nilai default untuk variabel tersebut.

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

Catatan: Nilai default elemen adalah false.

<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 ke ukuran batas.

Catatan: Nilai default elemen adalah false.

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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
steps.tracecapture.UnresolvedVariable	500	This error occurs if a variable specified in the TraceCapture policy is either: Out of scope (not available in the specific flow where the policy is being executed) or Can't be resolved (is not defined)
steps.tracecapture.VariableValueLimitExceeded	500	This error occurs if the <ThrowExceptionOnLimit> element is set to true and the size of any variable exceeds 256 bytes.

Fault variables

Whenever there are execution errors in a policy, Apigee generates error messages. You can view these error messages in the error response. Many a time, system generated error messages might not be relevant in the context of your product. You might want to customize the error messages based on the type of error to make the messages more meaningful.

To customize the error messages, you can use either fault rules or the RaiseFault policy. For information about differences between fault rules and the RaiseFault policy, see FaultRules vs. the RaiseFault policy. You must check for conditions using the Condition element in both the fault rules and the RaiseFault policy. Apigee provides fault variables unique to each policy and the values of the fault variables are set when a policy triggers runtime errors. By using these variables, you can check for specific error conditions and take appropriate actions. For more information about checking error conditions, see Building conditions.

The following table describes the fault variables specific to this policy.

Variables	Where	Example
fault.name	The fault.name can match to any of the faults listed in the Runtime errors table. The fault name is the last part of the fault code.	fault.name Matches "UnresolvedVariable"
tracecapture.POLICY_NAME.failed	POLICY_NAME is the user-specified name of the policy that threw the fault.	tracecapture.trace-capture-1.failed = true

For more information about policy errors, see What you need to know about policy errors.