TraceCapture policy

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

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.

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: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow
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>

Note:

• You cannot trace private and policy.secret variables.
• Apigee recommends you to configure a maximum of 15 variables for Cloud Trace and a maximum of 25 variables for Jaeger.

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

Note: You can specify an optional default value for a variable. If the variable specified in ref is undefined in a request or a response, the trace data will have the default value for the variable.

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

Note: The default value of the element is false.

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

Note: The default value of the element is false.

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.