TraceCapture ポリシー

このページの内容は Apigee と Apigee ハイブリッドに該当します。

Apigee Edge のドキュメントを表示する。

概要

TraceCapture ポリシーを使用すると、Apigee ランタイムのトレースデータに変数を追加できます。Apigee ランタイムの分散トレースを有効にしている場合、ランタイムはデフォルトで一連の事前定義変数をトレースします。詳細については、トレース レポートのデフォルトのトレース変数をご覧ください。ただし、Apigee ランタイムで追加のフロー、ポリシー、またはカスタム変数をトレースする場合は、TraceCapture ポリシーを使用します。このポリシーは、リクエスト フローまたはレスポンス フローで使用できます。分散トレース レポートでは、TraceCaptureExecution スパンの TraceCapture ポリシーによって追加された変数を表示できます。

このポリシーは拡張可能なポリシーであり、Apigee ライセンスによっては、このポリシーの使用によって費用や使用率に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

<TraceCapture>

TraceCapture ポリシーを定義します。

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

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

この要素には、すべてのポリシーに共通する次の属性があります。

次の表は、<TraceCapture> の子要素の概要をまとめたものです。

子要素のリファレンス

<DisplayName>

name 属性に加えて、管理 UI プロキシ エディタでポリシーを別の、より自然な響きの名前でラベル付けするために使います。

<DisplayName> 要素はすべてのポリシーに共通です。

<DisplayName> 要素の構文は次のとおりです。

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

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

<DisplayName> 要素に属性や子要素はありません。

<Variables>

トレースする変数のリストを指定します。

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

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

トレースデータに追加する変数を指定します。

<Variable> 要素の構文は次のとおりです。

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

次の表に、<Variable> の属性を示します。

<IgnoreUnresolvedVariables>

未解決の変数を検出したときに処理を停止するかどうかを決定します。

true を設定すると、未解決の変数を無視して処理を続行できます。それ以外の場合は false を設定します。デフォルト値は true です。

<IgnoreUnresolvedVariables> を true に設定することは、<TraceCapture> の continueOnError を true に設定することとは異なります。continueOnError を true に設定すると、変数のエラーだけでなく、すべてのエラーが無視されます。

<IgnoreUnresolvedVariables> 要素の構文は次のとおりです。

<IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

<ThrowExceptionOnLimit>

変数のサイズが上限の 256 バイトを超えた場合のポリシーの動作を指定します。

• true に設定すると、変数のサイズが上限を超えた場合にエラーがスローされます。
• false に設定した場合、ポリシーは上限を超える変数を切り捨てます。変数は上限のサイズに切り詰められます。

<ThrowExceptionOnLimit> 要素の構文は次のとおりです。

<ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>

<ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>

エラーコード

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

障害変数

ポリシーで実行エラーが発生すると、Apigee によってエラー メッセージが生成されます。これらのエラー メッセージはエラー レスポンスで確認できます。多くの場合、システムによって生成されたエラー メッセージは、製品のコンテキストとは関係ありません。エラーのタイプに基づいてエラー メッセージをカスタマイズして、より有用なメッセージにすることができます。

エラー メッセージをカスタマイズするには、障害ルールまたは RaiseFault ポリシーを使用します。障害ルールと RaiseFault ポリシーの違いについては、FaultRule ポリシーと RaiseFault ポリシーをご覧ください。障害ルールと RaiseFault ポリシーの両方で Condition 要素を使用して条件を確認する必要があります。Apigee では、各ポリシーに固有の障害変数が用意されています。障害変数の値は、ポリシーがランタイム エラーをトリガーするときに設定されます。これらの変数を使用することで、特定のエラー条件を確認し、適切なアクションを実行できます。エラー条件の確認について詳しくは、条件の作成をご覧ください。

次の表に、このポリシーに固有の障害変数を示します。