このページは Apigee と Apigee ハイブリッドに適用されます。
Apigee Edge のドキュメントはこちらをご覧ください。
概要
TraceCapture ポリシーを使用すると、Apigee ランタイムのトレースデータに変数を追加できます。Apigee ランタイムの分散トレースを有効にしている場合、ランタイムはデフォルトで一連の事前定義変数をトレースします。詳細については、トレース レポートのデフォルトのトレース変数をご覧ください。ただし、Apigee ランタイムで追加のフロー、ポリシー、またはカスタム変数をトレースする場合は、TraceCapture ポリシーを使用します。このポリシーは、リクエスト フローまたはレスポンス フローで使用できます。分散トレース レポートでは、TraceCaptureExecution スパンの 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 |
なし | 必須 |
ポリシーの内部名。 管理 UI プロキシ エディタで |
continueOnError |
false | 省略可 | ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連情報:
|
enabled |
true | 省略可 | ポリシーを適用するには、true に設定します。ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。 |
async |
false | 非推奨 | この属性は非推奨となりました。 |
次の表は、<TraceCapture> の子要素の概要をまとめたものです。
| 子要素 | 必須かどうか | 説明 |
|---|---|---|
<DisplayName> |
省略可 | ポリシーのカスタム名を指定します。 |
<Variables> |
省略可 | トレースする変数のリストを指定します。 |
<IgnoreUnresolvedVariables> |
省略可 | 未解決の変数に突き当たった場合に、処理を停止するかどうかを指定します。 |
<ThrowExceptionOnLimit> |
省略可 | 変数のサイズが上限の 256 バイトを超えた場合に、変数を切り捨てるかどうかを指定します。 |
| その他の子要素 | ||
<MergeBehavior> |
省略可 | レスポンス メッセージのマージ動作を指定します。 |
子要素のリファレンス
このセクションでは、<TraceCapture> の子要素について説明します。
<DisplayName>
name 属性に加えて、管理 UI プロキシ エディタでポリシーを別の、より自然な響きの名前でラベル付けするために使います。
<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 に設定すると、変数のエラーだけでなく、すべてのエラーが無視されます。
<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:
|
steps.tracecapture.VariableValueLimitExceeded |
500 |
This error occurs if the |
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 |