Diese Seite gilt für Apigee und Apigee Hybrid.
Apigee Edge-Dokumentation aufrufen
Übersicht
Mit der TraceCapture-Richtlinie können Sie den Trace-Daten Ihrer Apigee-Laufzeit zusätzliche Variablen hinzufügen. Wenn Sie das verteilte Tracing für die Apigee-Laufzeit aktiviert haben, verfolgt die Laufzeit standardmäßig eine Reihe vordefinierter Variablen. Weitere Informationen finden Sie unter Standard-Trace-Variablen im Tracing-Bericht.
Wenn Sie jedoch möchten, dass die Apigee-Laufzeit zusätzliche Ablauf-, Richtlinien- oder benutzerdefinierte Variablen verfolgt, verwenden Sie die TraceCapture-Richtlinie. Sie können diese Richtlinie entweder im Anfrage- oder im Antwortablauf verwenden. Im Bericht zum verteilten Tracing können Sie die Variablen anzeigen lassen, die von der TraceCapture-Richtlinie im Span TraceCaptureExecution
hinzugefügt wurden.
Diese Richtlinie ist eine erweiterbare Richtlinie und die Verwendung dieser Richtlinie kann je nach Apigee-Lizenz Auswirkungen auf die Kosten oder die Nutzung haben. Informationen zu Richtlinientypen und Auswirkungen auf die Nutzung finden Sie unter Richtlinientypen.
<TraceCapture>
Definiert die TraceCapture-Richtlinie
Standardwert | – |
Erforderlich? | Erforderlich |
Typ | Komplexer Typ |
Übergeordnetes Element | – |
Untergeordnete Elemente |
<DisplayName> <IgnoreUnresolvedVariables> <ThrowExceptionOnLimit> <Variables> |
Das <TraceCapture>
-Element verwendet die folgende 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>
Beispiel
Das folgende Beispiel zeigt die TraceCapture-Richtliniendefinition:
<?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>
Dieses Element hat folgende Attribute, die allen Richtlinien gemeinsam sind:
Attribut | Standard | Erforderlich? | Beschreibung |
---|---|---|---|
name |
- | Erforderlich |
Der interne Name der Richtlinie. Der Wert des Attributs Optional können Sie das Element |
continueOnError |
false | Optional | Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten. Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird. Weitere Informationen:
|
enabled |
wahr | Optional | Setzen Sie den Wert auf true , um die Richtlinie zu erzwingen. Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht durchgesetzt, selbst wenn sie mit einem Ablauf verknüpft ist. |
async |
false | Verworfen | Dieses Attribut wurde verworfen. |
Die folgende Tabelle enthält eine allgemeine Beschreibung der untergeordneten Elemente von <TraceCapture>
:
Untergeordnetes Element | Erforderlich? | Beschreibung |
---|---|---|
<DisplayName> |
Optional | Gibt einen benutzerdefinierten Namen für die Richtlinie an. |
<Variables> |
Optional | Gibt die Liste der zu verfolgenden Variablen an. |
<IgnoreUnresolvedVariables> |
Optional | Legt fest, ob die Verarbeitung beendet wird, wenn eine nicht aufgelöste Variable vorhanden ist. |
<ThrowExceptionOnLimit> |
Optional | Gibt an, ob eine Variable gekürzt werden muss, wenn die Größe der Variablen das Limit von 256 Byte überschreitet. |
Weitere untergeordnete Elemente | ||
<MergeBehavior> |
Optional | Legt das Verhalten der Zusammenführung für die Antwortnachrichten fest. |
Verweis auf untergeordnetes Element
In diesem Abschnitt werden die untergeordneten Elemente von<TraceCapture>
beschrieben.
<DisplayName>
Wird zusätzlich zum Attribut name
verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen, natürlicher klingenden Namen zu versehen.
Das Element <DisplayName>
ist für alle Richtlinien gleich.
Standardwert | – |
Erforderlich? | Optional. Wenn Sie <DisplayName> weglassen, wird der Wert des Attributs name der Richtlinie verwendet. |
Typ | String |
Übergeordnetes Element | <PolicyElement> |
Untergeordnete Elemente | Keine |
Das <DisplayName>
-Element verwendet die folgende Syntax:
Syntax
<PolicyElement> <DisplayName>POLICY_DISPLAY_NAME</DisplayName> ... </PolicyElement>
Beispiel
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
Das <DisplayName>
-Element hat keine Attribute oder untergeordneten Elemente.
<Variables>
Gibt die Liste der zu verfolgenden Variablen an.
Standardwert | – |
Erforderlich? | Erforderlich |
Typ | Komplexer Typ |
Übergeordnetes Element |
<TraceCapture> |
Untergeordnete Elemente |
<Variable> |
Das <Variables>
-Element verwendet die folgende 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>
Beispiel
Im folgenden Beispiel werden die Ablaufvariablen flow-variable-1
und flow-variable-2
verfolgt:
<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>
Gibt die Variablen an, die in die Trace-Daten eingefügt werden sollen.
Standardwert | – |
Erforderlich? | Erforderlich |
Typ | Komplexer Typ |
Übergeordnetes Element |
<Variables> |
Untergeordnete Elemente | Keine |
Das <Variable>
-Element verwendet die folgende Syntax:
Syntax
<Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
Beispiel
Im folgenden Beispiel wird die Trace-Variable trace-variable-1
auf den Wert der Ablaufvariablen flow-variable-1
gesetzt:
<Variable name="trace-variable-1" ref="flow-variable-1">default-val-1</Variable>
Wenn die Ablaufvariable flow-variable-1
nicht verfügbar ist, wird trace-variable-1
auf den Standardwert default-val-1
gesetzt.
In der folgenden Tabelle werden die Attribute von <Variable>
beschrieben:
Attribut | Erforderlich? | Typ | Beschreibung |
---|---|---|---|
name |
Erforderlich | String | Ein Name für die Referenz auf die für die angegebene Variable erfassten Daten. Dieser Name ist im Bericht zum verteilten Tracing sichtbar. |
ref |
Erforderlich | String | Die Variable, für die Sie die Trace-Daten erfassen. Diese Variable kann eine von Apigee vordefinierte Ablaufvariable oder eine benutzerdefinierte Variable in Ihrem API-Proxy sein. |
<IgnoreUnresolvedVariables>
Bestimmt, ob die Verarbeitung beendet wird, wenn eine nicht aufgelöste Variable erkannt wird.
Standardwert | – |
Erforderlich? | Optional |
Typ | Boolesch |
Übergeordnetes Element |
<TraceCapture> |
Untergeordnete Elemente | Keine |
Auf true
festlegen, um nicht aufgelöste Variablen zu ignorieren und die Verarbeitung fortzusetzen. Andernfalls false
. Der Standardwert ist true
.
Das Festlegen von true
für <IgnoreUnresolvedVariables>
unterscheidet sich vom Festlegen von continueOnError
auf true
für <TraceCapture>
. Wenn Sie true
für continueOnError
angeben, ignoriert Apigee alle Fehler, also nicht nur Fehler in Variablen.
Das <IgnoreUnresolvedVariables>
-Element verwendet die folgende Syntax:
Syntax
<IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>
Beispiel
Im folgenden Beispiel wird für <IgnoreUnresolvedVariables>
der Wert false
festgelegt:
<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
<ThrowExceptionOnLimit>
Gibt das Verhalten der Richtlinie an, wenn die Größe der Variablen das Limit von 256 Byte überschreitet.
- Ist
true
festgelegt, gibt die Richtlinie einen Fehler aus, wenn eine Variablengröße das Limit überschreitet. - Ist
false
festgelegt, wird die Variable, die das Limit überschreitet, von der Richtlinie gekürzt. Die Variable wird auf die Größe des Limits gekürzt.
Standardwert | – |
Erforderlich? | Optional |
Typ | Boolesch |
Übergeordnetes Element |
<TraceCapture> |
Untergeordnete Elemente | Keine |
Das <ThrowExceptionOnLimit>
-Element verwendet die folgende Syntax:
Syntax
<ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>
Beispiel
Im folgenden Beispiel wird
auf <ThrowExceptionOnLimit>
true
festgelegt.
<ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>
Fehlercodes
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 |