TraceCapture 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

概览

通过 TraceCapture 政策，您可以向 Apigee 运行时的跟踪记录数据添加其他变量。如果您为 Apigee 运行时启用了分布式跟踪，则默认情况下，运行时会跟踪一组预定义的变量。如需了解详情，请参阅跟踪报告中的默认跟踪变量。但是，如果您希望 Apigee 运行时跟踪其他流、政策或自定义变量，请使用 TraceCapture 政策。您可以在请求或响应流中使用此政策。在分布式跟踪报告中，您可以在 TraceCaptureExecution span 中查看 TraceCapture 政策添加的变量。

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

<TraceCapture>

定义 TraceCapture 政策。

默认值 不适用
是否必需？ 需要
类型 复杂类型
父元素 不适用
子元素 <DisplayName>
<IgnoreUnresolvedVariables>
<ThrowExceptionOnLimit>
<Variables>

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

语法

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

示例

以下示例展示了 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 已弃用 此属性已弃用。

下表提供了 <TraceCapture> 的子元素的简要说明：

子元素 是否必需？ 说明
<DisplayName> 可选 指定政策的自定义名称。
<Variables> 可选 指定要跟踪的变量列表。
<IgnoreUnresolvedVariables> 可选 指定在遇到无法解析的变量时处理是否停止。
<ThrowExceptionOnLimit> 可选 指定系统在变量的大小超过 256 字节的限制时是否必须截断变量。
其他子元素
<MergeBehavior> 可选 指定响应消息的合并行为。

子元素参考

本部分介绍 <TraceCapture> 的子元素。

<DisplayName>

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

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

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

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

语法

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

示例

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

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

<Variables>

指定要跟踪的变量列表。

默认值 不适用
是否必需？ 需要
类型 复杂类型
父元素 <TraceCapture>
子元素 <Variable>

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

语法

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

示例

以下示例跟踪 flow-variable-1 和 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>

指定要在跟踪记录数据中添加的变量。

默认值 不适用
是否必需？ 需要
类型 复杂类型
父元素 <Variables>
子元素 无

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

语法
<Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
示例

以下示例将 trace-variable-1 跟踪记录变量设置为 flow-variable-1 流变量的值：

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

如果 flow-variable-1 流变量不可用，则 trace-variable-1 设置为默认值 default-val-1。

下表介绍 <Variable> 的特性：

属性 是否必需？ 类型 说明
name 需要 字符串 引用为指定变量收集的数据的名称。此名称将显示在分布式跟踪报告中。
ref 需要 字符串 要为其收集跟踪记录数据的变量。此变量可以是 Apigee 预定义的流变量或 API 代理中的自定义变量。

<IgnoreUnresolvedVariables>

确定在遇到无法解析的变量时处理是否停止。

默认值 不适用
是否必需？ 可选
类型 布尔值
父元素 <TraceCapture>
子元素 无

设置为 true 可忽略无法解析的变量并继续处理；否则设置为 false。默认值为 true。

将 <IgnoreUnresolvedVariables> 设置为 true 与将 <TraceCapture> 的 continueOnError 设置为 true 不同。如果将 continueOnError 设置为 true，Apigee 会忽略所有错误，而不仅仅是变量中的错误。

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

语法

<IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>

示例

以下示例将 <IgnoreUnresolvedVariables> 设置为 false：

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

<ThrowExceptionOnLimit>

指定变量大小超过 256 字节限制时政策的行为。

  • 如果设置为 true，则在变量大小超出限制时，政策会抛出错误。
  • 如果设置为 false，则政策会截断超出该限制的变量。该变量被截断为限制的大小。
默认值 不适用
是否必需？ 可选
类型 布尔值
父元素 <TraceCapture>
子元素 无

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

语法

<ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>

示例

以下示例将 <ThrowExceptionOnLimit> 值设置为 true。

<ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>

错误代码

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.