TraceCapture policy

You're viewing Apigee X documentation.
View Apigee Edge documentation.

policy icon

Overview

The TraceCapture policy lets you add additional variables to your Apigee runtime's trace data. If you have enabled distributed tracing for the Apigee runtime, the runtime, by default, traces a set of pre-defined variables. For more information, see Default trace variables in tracing report. However, if you want the Apigee runtime to trace additional flow, policy, or custom variables, use the TraceCapture policy. You can use this policy either in the request or the response flow. In your distributed tracing report, you can view the variables added by TraceCapture policy in the TraceCaptureExecution span.

<TraceCapture>

Defines the TraceCapture policy.

Default Value N/A
Required? Required
Type Complex type
Parent Element N/A
Child Elements <DisplayName>
<IgnoreUnresolvedVariables>
<ThrowExceptionOnLimit>
<Variables>

The <TraceCapture> element uses the following syntax:

Syntax

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

Example

The following example shows the TraceCapture policy definition:

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

This element has the following attributes that are common to all policies:

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

continueOnError false Optional Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also:
enabled true Optional Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.

The following table provides a high-level description of the child elements of <TraceCapture>:

Child Element Required? Description
<DisplayName> Optional Specifies a custom name for the policy.
<Variables> Optional Specifies the list of variables to trace.
<IgnoreUnresolvedVariables> Optional Specifies whether processing stops when an unresolved variable is encountered.
<ThrowExceptionOnLimit> Optional Specifies whether a variable must be truncated if the size of the variable exceeds the limit of 256 bytes.
Other child elements
<MergeBehavior> Optional Specifies the merge behavior for the response messages.

Child element reference

This section describes the child elements of <TraceCapture>.

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value N/A
Required? Optional. If you omit <DisplayName>, the value of the policy's name attribute is used.
Type String
Parent Element <PolicyElement>
Child Elements None

The <DisplayName> element uses the following syntax:

Syntax

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

Example

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

The <DisplayName> element has no attributes or child elements.

<Variables>

Specifies the list of variables to trace.

Default Value N/A
Required? Required
Type Complex type
Parent Element <TraceCapture>
Child Elements <Variable>

The <Variables> element uses the following syntax:

Syntax

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

Example

The following example traces the flow-variable-1 and flow-variable-2 flow variables:

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

Specifies the variables to be added in the trace data.

Default Value N/A
Required? Required
Type Complex type
Parent Element <Variables>
Child Elements None

The <Variable> element uses the following syntax:

Syntax
<Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
Example

The following example sets the trace-variable-1 trace variable to the value of the flow-variable-1 flow variable:

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

If the flow-variable-1 flow variable is not available, trace-variable-1 is set to the default value default-val-1.

The following table describes the attributes of <Variable>:

Attribute Required? Type Description
name Required String A name for referencing the data collected for the specified variable. This name will be visible in your distributed tracing report.
ref Required String The variable for which you are collecting the trace data. This variable can be a flow variable predefined by Apigee or a custom variable in your API proxy.

<IgnoreUnresolvedVariables>

Determines whether processing stops when an unresolved variable is encountered.

Default Value N/A
Required? Optional
Type Boolean
Parent Element <TraceCapture>
Child Elements None

Set to true to ignore unresolved variables and continue processing; otherwise false. The default value is true.

Setting <IgnoreUnresolvedVariables> to true is different from setting the <TraceCapture>'s continueOnError to true. If you set continueOnError to true, Apigee ignores all errors, not only errors in variables.

The <IgnoreUnresolvedVariables> element uses the following syntax:

Syntax

<IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>

Example

The following example sets <IgnoreUnresolvedVariables> to false:

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

<ThrowExceptionOnLimit>

Specifies the behavior of the policy when the size of the variable exceeds the limit of 256 bytes.

  • If set to true, the policy throws an error if a variable size exceeds the limit.
  • If set to false, the policy truncates the variable that exceeds the limit. The variable is truncated to the size of the limit.
Default Value N/A
Required? Optional
Type Boolean
Parent Element <TraceCapture>
Child Elements None

The <ThrowExceptionOnLimit> element uses the following syntax:

Syntax

<ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>

Example

The following example sets the <ThrowExceptionOnLimit> value to true.

<ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>

Error codes

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.