本页面适用于 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 |
无 | 必需 |
政策的内部名称。 （可选）使用 |
continueOnError |
否 | 可选 | 设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 true，即使在政策失败后，仍可以继续执行流。另请参阅：
|
enabled |
true | 可选 | 设置为 true 可实施政策。 设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。 |
async |
否 | 已弃用 | 此属性已弃用。 |
下表提供了 <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>
错误代码
本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。
运行时错误
政策执行时可能会发生这些错误。
| 故障代码 | HTTP 状态 | 原因 |
|---|---|---|
steps.tracecapture.UnresolvedVariable |
500 |
如果 TraceCapture 政策中指定的变量为以下任一情况，就会出现此错误：
|
steps.tracecapture.VariableValueLimitExceeded |
500 |
如果 |
故障变量
只要政策中存在执行错误，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 |