Trace-Tool verwenden

Sie lesen gerade die Dokumentation zu Apigee Edge.
Apigee X-Dokumentation aufrufen. info

Was ist das Tool „Trace“?

Trace ist ein Tool zur Fehlerbehebung und zum Monitoring von API-Proxys, die auf Apigee Edge ausgeführt werden. Mit Trace können Sie die Details jedes Schritts eines API-Proxy-Ablaufs prüfen.

Trace verwenden

Trace ist einfach zu verwenden. Sie starten eine Trace-Sitzung, rufen dann die Edge-Plattform über die API auf und lesen die Ergebnisse.

1. Greifen Sie wie unten beschrieben auf die Seite "API-Proxies" zu.
   

   Edge

   So rufen Sie die Seite „API-Proxys“ über die Edge-Benutzeroberfläche auf:

   1. Melden Sie sich unter apigee.com/edge an.
   2. Wählen Sie in der linken Navigationsleiste Develop > API Proxies aus.

   Neue Edge-UI (Private Cloud)

   So rufen Sie die Seite „API-Proxys“ über die New Edge-Benutzeroberfläche auf:

   1. Melden Sie sich in der New Edge-Benutzeroberfläche unter http://host:3001/edge an. Dabei ist host die IP-Adresse oder der DNS-Name des Hosts, auf dem die New Edge-Benutzeroberfläche ausgeführt wird.
   2. Wählen Sie in der linken Navigationsleiste Develop > API Proxies aus.
2. Wählen Sie auf der Seite „API-Proxys“ einen API-Proxy aus.
3. Achten Sie darauf, dass die API, die Sie verfolgen möchten, bereitgestellt wird.
4. Klicken Sie auf Trace, um die Ansicht des Trace-Tools aufzurufen.
5. Wählen Sie im Drop-down-Menü Bereitstellung für Trace die Bereitstellungsumgebung und die Proxy-Revision aus, die Sie verfolgen möchten.
6. Klicken Sie auf Trace-Sitzung starten. Wenn die Trace-Sitzung aktiv ist, werden im API-Proxy Details zu jedem Schritt in der Verarbeitungspipeline aufgezeichnet. Während die Trace-Sitzung läuft, werden Nachrichten und Kontextdaten aus dem Live-Traffic erfasst.
   

   

7. Wenn kein Live-Traffic über Ihren Proxy läuft, senden Sie einfach eine Anfrage an die API. Sie können ein beliebiges Tool zum Senden der Anfrage verwenden, z. B. curl, Postman oder ein anderes Tool, mit dem Sie vertraut sind. Alternativ können Sie die Anfrage direkt über das Tool „Trace“ senden. Geben Sie einfach die URL ein und klicken Sie auf Senden. Hinweis:Sie können nur eine GET-Anfrage über das Tool „Trace“ senden, aber keine POST-Anfrage.
   
   Hinweis: Eine Trace-Sitzung kann über den ausgewählten API-Proxy 10 Anfrage-/Antworttransaktionen pro Message Processor unterstützen. In der Edge-Cloud werden mit zwei Nachrichtenprozessoren, die den Traffic verarbeiten, 20 Anfrage-/Antworttransaktionen unterstützt. Eine Trace-Sitzung wird nach 10 Minuten automatisch beendet, wenn Sie sie nicht manuell beenden.
   
8. Wenn Sie genügend Anfragen erfasst haben, klicken Sie auf Trace-Sitzung beenden.
9. Im Menü auf der linken Seite wird eine Liste der erfassten Anfrage-/Antworttransaktionen angezeigt. Klicken Sie auf eine der Transaktionen, um detaillierte Ergebnisse aufzurufen.

Traces richtig lesen

Das Trace-Tool besteht aus zwei Hauptteilen: der Transaktionskarte und den Phasendetails:

• Auf der Transaktionsübersicht werden Symbole verwendet, um jeden wichtigen Schritt zu kennzeichnen, der während einer API-Proxy-Transaktion erfolgt, einschließlich der Ausführung von Richtlinien, bedingten Schritten und Übergängen. Bewegen Sie den Mauszeiger auf ein beliebiges Symbol, um eine Zusammenfassung der Informationen zu sehen. Die Schritte des Anfrageflusses werden im oberen Bereich der Transaktionszuordnung und der Schritte des Antwortflusses unten angezeigt.
• Der Abschnitt Phasendetails des Tools enthält Informationen zur internen Verarbeitung des Proxys, einschließlich Variablen, die festgelegt oder gelesen wurden, Anfrage- und Antwortheader und vieles mehr. Klicken Sie auf ein beliebiges Symbol, um die Phasendetails für diesen Schritt aufzurufen.

Hier ist ein Beispiel einer Trace-Tool-Zuordnung mit Labels der wichtigsten Proxy-Verarbeitungssegmenten:

Transaktionskarte des Trace-Tools

Legende für die Transaktionskarte

In der folgenden Tabelle wird der Intent der Symbole beschrieben, die in der Transaktionszuordnung angezeigt werden. Diese Symbole markieren jeden der wichtigsten Verarbeitungsschritte während des Proxyablauf.

Symbol für Transaktionskarte

	Die Clientanwendung, die eine Anfrage an den ProxyEndpoint des API-Proxys sendet.
	Die Kreise kennzeichnen Übergangsendpunkte im Proxy-Ablauf. Sie werden angezeigt, wenn eine Anfrage vom Client eingeht, wenn die Anfrage beim Ziel eingeht, wenn die Antwort vom Ziel eingeht und wenn die Antwort an den Client zurückgegeben wird.
	Die hohen Balken kennzeichnen den Beginn eines Ablaufsegments im API-Proxy-Ablauf. Ablaufsegmente: ProxyEndpoint-Anfrage, TargetEndpoint-Anfrage, TargetEndpoint-Antwort und ProxyEndpoint-Antwort. Ein Segment enthält den PreFlow, ConditionalFlows und PostFlow. Weitere Informationen finden Sie unter Abläufe konfigurieren.
	Gibt an, dass Analytics-Aktionen im Hintergrund ausgeführt wurden.
	Ein bedingter Ablauf, der mit „true“ ausgewertet wird. Eine Einführung in bedingte Abläufe finden Sie unter Abläufe konfigurieren. Einige Bedingungen werden von Edge generiert. Das folgende Beispiel zeigt einen Ausdruck, mit dem Edge prüft, ob im ProxyEndpoint ein Fehler aufgetreten ist: ((error.state equals PROXY_REQ_FLOW) or (error.state equals PROXY_RESP_FLOW))
	Ein bedingter Ablauf, der mit „false“ ausgewertet wird Eine Einführung zu bedingten Abläufen finden Sie unter Abläufe konfigurieren. Einige Bedingungen werden von Edge generiert. Das folgende Beispiel zeigt einen Ausdruck, mit dem Edge prüft, ob im TargetEndpoint ein Fehler aufgetreten ist: (((error.state equals TARGET_REQ_FLOW) or (error.state equals TARGET_RESP_FLOW)) or ((error.state equals REQ_SENT) or (error.state equals RESP_START)))
	Richtlinien Jeder Richtlinientyp hat ein eindeutiges Symbol. Dieses ist für die Richtlinie „AssignMessage“. Mit diesen Symbolen können Sie nachvollziehen, wo Richtlinien in der richtigen Reihenfolge ausgeführt werden und ob sie erfolgreich sind. Sie können auf ein Richtliniensymbol klicken, um die Ergebnisse der Ausführung aufzurufen und zu sehen, ob sie erwartet werden oder nicht. Sie können beispielsweise sehen, ob die Nachricht richtig umgewandelt wurde oder ob sie im Cache gespeichert wird. Die ordnungsgemäße Ausführung von Richtlinien wird durch Häkchen deutlich angezeigt. Im Fehlerfall wird auf dem Symbol ein rotes Ausrufezeichen angezeigt. Tipp: Achten Sie auf den Kurzinfo-Text oder die Zeitachse, um zu sehen, ob die Anwendung einer Richtlinie länger als erwartet dauert.
	Wird angezeigt, wenn das Backend-Ziel eine Node.js-Anwendung ist. Weitere Informationen finden Sie unter Übersicht über Node.js in Apigee Edge.
	Das vom API-Proxy aufgerufene Backend-Ziel.
	Die Zeitangabe gibt an, wie lange die Verarbeitungszeit in Millisekunden dauert. Durch den Vergleich der verstrichenen Zeitsegmente können Sie die Richtlinien ermitteln, deren Ausführung am längsten dauert und die API-Aufrufe verlangsamen.
	Das Epsilon ist ein Zeitraum, der kleiner als eine Millisekunde ist.
	Deaktiviert. Erscheint bei einem Richtliniensymbol, wenn eine Richtlinie deaktiviert ist. Richtlinien können mit der öffentlichen API deaktiviert werden. Siehe API-Proxy-Konfigurationsreferenz.
	Fehler. Wird auf einem Richtliniensymbol angezeigt, wenn die Schrittbedingung des Richtlinienschritts als „false“ ausgewertet wird (siehe Ablaufvariablen und -bedingungen), oder auf dem RaiseFault-Richtliniensymbol, wenn eine RaiseFault-Richtlinie ausgeführt wird.
	Übersprungen. Erscheint in einem Richtliniensymbol, wenn die Richtlinie nicht ausgeführt wurde, da die Schrittbedingung als „false“ ausgewertet wurde. Weitere Informationen finden Sie unter Ablaufvariablen und Bedingungen.

Phasendetails verstehen

Der Teil Phasendetails des Tools teilt Ihnen mit jedem Verarbeitungsschritt viel über den Status Ihres Proxys mit. Im Folgenden finden Sie einige Details, die in den Phasendetails angegeben werden. Klicken Sie auf ein beliebiges Symbol im Trace-Tool, um Details für den ausgewählten Schritt anzuzeigen. Mit den Schaltflächen Weiter und Zurück können Sie von einem Schritt zu einem anderen wechseln.

Erfassung von Nachrichten mit Filtern optimieren

Sie können filtern, welche Anfragen im Trace-Tool angezeigt werden, indem Sie Header- und/oder Abfrageparameterwerte angeben. Mit Filtern können Sie bestimmte Aufrufe eingrenzen, die möglicherweise Probleme verursachen. Beispielsweise müssen Sie sich möglicherweise auf Anfragen mit bestimmten Inhalten oder Anfragen von bestimmten Partnern oder Apps konzentrieren. Sie können nach folgenden Kriterien filtern:

• HTTP-Header: Beschränken Sie den Trace auf Aufrufe, die einen bestimmten Header enthalten. So können Sie Probleme leichter beheben. Sie können einen Header an Ihren App-Entwickler senden und ihn bitten, ihn in den Aufruf einzufügen, der Probleme verursacht. Apigee Edge zeichnet dann nur Aufrufe mit diesem bestimmten Header auf, damit Sie die Ergebnisse prüfen können.
• Abfrageparameter: Nur Aufrufe mit einem bestimmten Wert eines Parameters werden aufgezeichnet.

Wichtige Informationen zur Filterfunktion

• Sie müssen die Trace-Sitzung neu starten, nachdem Sie Filterparameter in den Filterfeldern angegeben haben.
• Filterparameter werden mit AND verknüpft. Alle angegebenen Name/Wert-Paare für Abfrage und/oder Header müssen in der Anfrage vorhanden sein, damit ein Abgleich erfolgreich ist.
• Mustervergleich wird im Tool „Filter“ nicht unterstützt.
• Bei Filterparametern und ‑werten wird die Groß-/Kleinschreibung beachtet.

Trace-Filter erstellen

1. Wenn eine Trace-Sitzung ausgeführt wird, beenden Sie sie, indem Sie auf Trace-Sitzung beenden klicken.
2. Klicken Sie oben links im Tool „Trace“ auf Filter, um das Feld „Filter“ zu maximieren.
   
   
   
3. Geben Sie im Feld „Filter“ den Abfrageparameter und/oder die Header-Werte an, nach denen gefiltert werden soll. In diesem Beispiel geben wir zwei Abfrageparameter an, nach denen gefiltert werden soll. Beide Parameter müssen in der Anfrage vorhanden sein, damit eine Übereinstimmung erzielt werden kann.
   
   
   
4. Starten Sie die Trace-Sitzung.
5. Rufen Sie Ihre APIs auf. Nur Anfragen, die alle angegebenen Header und/oder Abfrageparameter enthalten, führen zu einer erfolgreichen Übereinstimmung.

Im obigen Beispiel wird dieser API-Aufruf im Trace so angezeigt:

http://docs-test.apigee.net/cats?name=Penny&breed=Calico

Folgendes passiert jedoch nicht:

http://docs-test.apigee.net/cats?name=Penny

Fehlerbehebung mit Trace

Mit Trace können Sie viele interne Details zu einem API-Proxy sehen. Beispiel:

• Sie können auf einen Blick sehen, welche Richtlinien ordnungsgemäß ausgeführt werden oder fehlschlagen.
• Angenommen, Sie haben in einem der Analytics-Dashboards festgestellt, dass die Leistung einer Ihrer APIs ungewöhnlich zurückgegangen ist. Jetzt können Sie mithilfe von Trace ermitteln, wo der Engpass auftritt. Trace gibt die Zeit in Millisekunden an, die jede einzelne Verarbeitungszeit benötigt. Wenn die Ausführung eines Schritts zu lange dauert, können Sie entsprechende Korrekturen vornehmen.
• Anhand der Phasendetails können Sie Header überprüfen, die an das Backend gesendet werden, Variablen ansehen, die von Richtlinien festgelegt wurden, usw.
• Anhand des Basispfads können Sie prüfen, ob eine Richtlinie die Nachricht an den richtigen Server weiterleitet.

Ansichtsoptionen auswählen

Wählen Sie die Ansichtsoptionen für die Trace-Sitzung aus.

Trace-Ergebnisse herunterladen

Sie können eine XML-Datei mit den Rohdaten der Trace-Ergebnisse herunterladen, um sie offline in einem Texteditor anzusehen und zu durchsuchen. Die Datei enthält alle Details der Listening-Sitzung, einschließlich des Inhalts aller Header, Variablen und Richtlinien.

Klicken Sie auf Trace-Sitzung herunterladen, um die Sitzung herunterzuladen.

Anzeigen von Anfragen als curl

Nachdem Sie einen API-Aufruf an einen Zielserver nachvollzogen haben, können Sie die Anfrage als curl-Befehl ansehen. Das ist aus mehreren Gründen besonders nützlich für die Fehlerbehebung:

• Der API-Proxy kann die Anfrage ändern. Daher ist es hilfreich zu sehen, wie sich die Anfrage vom Proxy an den Zielserver von der ursprünglichen Anfrage unterscheidet. Das curl-Kommando stellt die geänderte Anfrage dar.
• Bei größeren Nutzlasten können Sie mit dem curl die HTTP-Header und den Nachrichteninhalte an einem Ort ansehen. Derzeit gilt ein Limit von etwa 1.000 Zeichen. Einen Tipp, wie Sie dieses Limit umgehen können, finden Sie in diesem Communitybeitrag.)

Aus Sicherheitsgründen wird der HTTP-Autorisierungsheader durch die curl-Funktion maskiert.

Wenn Sie Anfragen als „curl“ sehen möchten, nachdem ein API-Aufruf in Trace eingegangen ist, wählen Sie im Transaktionsdiagramm die Phase „Anfrage an Zielserver gesendet“ aus und klicken Sie dann im Bereich „Phasendetails“ in der Spalte „Anfrage an Zielserver gesendet“ auf die Schaltfläche curl anzeigen.

Verwendung des Apigee-Supports von Trace

Mit Apigee Edge kann der Apigee-Support standardmäßig das Trace-Tool auf Ihren API-Proxys verwenden, um Support zu bieten. Sie können diese Option jederzeit deaktivieren. Wenn Sie diese Option jedoch deaktivieren, ist der Support des Apigee-Supports eingeschränkt.

So deaktivieren Sie den Apigee-Support daran, das Trace-Tool zu verwenden:

1. Melden Sie sich unter https://apigee.com/edge an.
2. Wählen Sie in der linken Navigationsleiste Verwaltung > Datenschutz aus.
3. Klicken Sie auf die Ein-/Aus-Schaltfläche Apigee-Support aktivieren , um die Verwendung des Trace-Tools durch den Apigee-Support zu deaktivieren.