このページは 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>
エラーコード
このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、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 |