TraceCapture-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Ü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 name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten. Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.
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: Fehlerregeln werden NUR im Fehlerzustand ausgelöst (über continueOnError) Umgang mit Fehlern im aktuellen Ablauf
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>

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

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

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	Boolesch
Übergeordnetes Element	<TraceCapture>
Untergeordnete Elemente	Keine

Das <ThrowExceptionOnLimit>-Element verwendet die folgende Syntax:

Syntax

<ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>

Beispiel

Im folgenden Beispiel wird <ThrowExceptionOnLimit> auf true festgelegt.

<ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>

Fehlercodes

In diesem Abschnitt werden die zurückgegebenen Fehlercodes und Fehlermeldungen beschrieben, die von Apigee festgelegt werden, wenn die Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Laufzeitfehler

Diese Fehler können bei Ausführung der Richtlinie auftreten.

Fehlercode	HTTP-Status	Ursache
steps.tracecapture.UnresolvedVariable	500	Dieser Fehler tritt auf, wenn für eine Variable, die in der TraceCapture-Richtlinie angegeben ist, Folgendes gilt: Wert liegt außerhalb des Bereichs (nicht in dem spezifischen Ablauf verfügbar, in dem die Richtlinie ausgeführt wird) oder kann nicht gelöst werden (ist nicht definiert)
steps.tracecapture.VariableValueLimitExceeded	500	Dieser Fehler tritt auf, wenn das Element <ThrowExceptionOnLimit> auf true gesetzt ist und die Größe einer Variablen 256 Byte überschreitet.

Fehlervariablen

Wenn in einer Richtlinie Ausführungsfehler auftreten, generiert Apigee Fehlermeldungen. Sie können sich diese Fehlermeldungen in der Fehlerantwort ansehen. Häufig sind vom System generierte Fehlermeldungen im Kontext Ihres Produkts möglicherweise nicht relevant. Sie können die Fehlermeldungen basierend auf dem Fehlertyp anpassen, um die Nachrichten aussagekräftiger zu machen.

Zum Anpassen der Fehlermeldungen können Sie entweder Fehlerregeln oder die RaiseFault-Richtlinie verwenden. Informationen zu Unterschieden zwischen Fehlerregeln und der RaiseFault-Richtlinie finden Sie unter FaultRules-Richtlinie im Vergleich zur RaiseFault-Richtlinie. Prüfen Sie, ob Bedingungen mit dem Element Condition in den Fehlerregeln und in der RaiseFault-Richtlinie verwendet werden. Apigee stellt Fehlervariablen bereit, die für jede Richtlinie eindeutig sind. Die Werte der Fehlervariablen werden festgelegt, wenn eine Richtlinie Laufzeitfehler auslöst. Mit diesen Variablen können Sie nach bestimmten Fehlerbedingungen suchen und entsprechende Maßnahmen ergreifen. Weitere Informationen zum Prüfen von Fehlerbedingungen finden Sie unter Bedingungen erstellen.

In der folgenden Tabelle werden die für diese Richtlinie spezifischen Fehlervariablen beschrieben.

Variablen	Wo	Beispiel
fault.name	Der fault.name kann mit einem der Fehler übereinstimmen, die in der Tabelle Laufzeitfehler aufgeführt sind. Der Fehlername ist der letzte Teil des Fehlercodes.	fault.name Matches "UnresolvedVariable"
tracecapture.POLICY_NAME.failed	POLICY_NAME ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat.	tracecapture.trace-capture-1.failed = true

Weitere Informationen zu Richtlinienfehlern finden Sie unter Was Sie über Richtlinienfehler wissen müssen.