TraceCapture-Richtlinie

Erweiterbare Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Vorschau

Dieses Produkt oder Feature unterliegt den „Bedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Produkte und -Features sind "im Ist-Zustand" verfügbar und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Startphase.

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>

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.

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>

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>

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>

Hinweis:

• Sie können die Variablen private und policy.secret nicht verfolgen.
• Apigee empfiehlt, dass Sie maximal 15 Variablen für Cloud Trace und maximal 25 Variablen für Jaeger konfigurieren.

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

Hinweis: Sie können einen optionalen Standardwert für eine Variable angeben. Wenn die in ref angegebene Variable in einer Anfrage oder Antwort nicht definiert ist, haben die Trace-Daten den Standardwert für die Variable.

<IgnoreUnresolvedVariables>

Bestimmt, ob die Verarbeitung beendet wird, wenn eine nicht aufgelöste Variable erkannt wird.

Standardwert	–
Erforderlich?	Optional
Typ	Boolescher Wert
Ü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>

Hinweis: Der Standardwert des Elements ist false.

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

Hinweis: Der Standardwert des Elements ist false.

Standardwert	–
Erforderlich?	Optional
Typ	Boolescher Wert
Übergeordnetes Element	<TraceCapture>
Untergeordnete Elemente	Keine

Das Element <ThrowExceptionOnLimit> verwendet die folgende Syntax:

Syntax

<ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>

Beispiel

Im folgenden Beispiel wird <ThrowExceptionOnLimit> auf 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: 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.