TraceCapture policy

This page applies to Apigeeand Apigee hybrid.

View Apigee Edge documentation.

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.

This policy is an Extensible policy and use of this policy might have cost or utilization implications, depending on your Apigee license. For information on policy types and usage implications, see Policy types .

<TraceCapture>

Defines the TraceCapture policy.

The <TraceCapture> element uses the following 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>

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

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

Child element reference

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

The <DisplayName> element uses the following syntax:

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

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

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

<Variables>

Specifies the list of variables to trace.

The <Variables> element uses the following 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>

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

The <Variable> element uses the following syntax:

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

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

The following table describes the attributes of <Variable> :

<IgnoreUnresolvedVariables>

Determines whether processing stops when an unresolved variable is encountered.

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:

<IgnoreUnresolvedVariables> BOOLEAN_VALUE 
</IgnoreUnresolvedVariables>

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

The <ThrowExceptionOnLimit> element uses the following syntax:

<ThrowExceptionOnLimit> BOOLEAN_VALUE 
</ThrowExceptionOnLimit>

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