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 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，即使在政策失败后，仍可以继续执行流。另请参阅： 故障规则仅在错误状态下触发（关于 continueOnError） 处理当前流中的故障
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>

除了用于 name 属性之外，还可用于在管理界面代理编辑器中使用其他更加自然的名称标记政策。

<DisplayName> 元素适用于所有政策。

默认值	不适用
是否必需？	可选。如果省略 <DisplayName>，则会使用政策的 name 属性的值
类型	字符串
父元素	<PolicyElement>
子元素	无

<DisplayName> 元素使用以下语法：

语法

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

示例

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

<DisplayName> 元素没有属性或子元素。

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

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

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

政策执行时可能会发生这些错误。

故障代码	HTTP 状态	原因
steps.tracecapture.UnresolvedVariable	500	如果 TraceCapture 政策中指定的变量为以下任一情况，就会出现此错误： 超出范围（在执行政策的特定流中不可用） 或 无法解析（未定义）
steps.tracecapture.VariableValueLimitExceeded	500	如果 <ThrowExceptionOnLimit> 元素设为 true 且所有变量的大小都超过 256 字节，则会出现此错误。

故障变量

只要政策中存在执行错误，Apigee 就会生成错误消息。您可以在错误响应中查看这些错误消息。很多时候，系统生成的错误消息可能与您的产品上下文无关。您可能希望根据错误类型自定义错误消息，以使消息更有意义。

如需自定义错误消息，可以使用故障规则或 RaiseFault 政策。如需了解故障规则与 RaiseFault 政策之间的差异，请参阅 FaultRule 与 RaiseFault 政策。您必须使用故障规则和 RaiseFault 政策中的 Condition 元素来检查条件。Apigee 提供每个政策独有的故障变量，并在政策触发运行时错误时设置故障变量的值。通过使用这些变量，您可以检查特定的错误情况并采取适当的操作。如需详细了解如何检查错误条件，请参阅构建条件。

下表介绍了特定于此政策的故障变量。

变量	其中	示例
fault.name	fault.name 可以匹配运行时错误表中列出的任何故障。故障名称是故障代码的最后一部分。	fault.name Matches "UnresolvedVariable"
tracecapture.POLICY_NAME.failed	POLICY_NAME 是抛出故障的政策的用户指定名称。	tracecapture.trace-capture-1.failed = true

如需详细了解政策错误，请参阅您需要了解的政策错误相关信息。