Trace-Tool verwenden

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

Was ist das Trace-Tool?

Trace ist ein Tool zur Fehlerbehebung und zum Monitoring von API-Proxys, die auf Apigee Edge ausgeführt werden. Mit Trace lassen sich die Details der einzelnen Schritte über einen API-Proxy-Ablauf abrufen.

Trace verwenden

Trace ist einfach zu verwenden. Sie starten eine Trace-Sitzung, führen dann einen API-Aufruf an die Edge-Plattform aus und lesen die Ergebnisse.

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

   Edge

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

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

   Classic Edge (Private Cloud)

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

   1. Melden Sie sich bei http://ms-ip:9000 an, wobei ms-ip die IP-Adresse oder der DNS-Name des Management Server-Knotens ist.
   2. Wählen Sie in der oberen Navigationsleiste APIs > API-Proxys 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-Überarbeitung 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 ausgeführt wird, 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 zum Senden der Anfrage ein beliebiges Tool verwenden, z. B. curl, Postman oder ein anderes Tool, mit dem Sie vertraut sind. Alternativ können Sie die Anfrage direkt über das Trace-Tool 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 Message Processors, 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 Anfragen/Antworten 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:

• Die Transaktionskarte verwendet Symbole, um jeden wichtigen Schritt zu markieren, der während einer API-Proxy-Transaktion auftritt, einschließlich Richtlinienausführung, bedingte Schritte und Übergänge. 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. Beachten Sie, dass einige Bedingungen von Edge generiert werden. Folgendes ist beispielsweise ein 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. Beachten Sie, dass einige Bedingungen von Edge generiert werden. Folgendes ist beispielsweise ein 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. Ordnungsgemäß ausgeführte Richtlinien sind klar an den Häkchen zu erkennen. Bei Fehlern wird ein rotes Ausrufezeichen auf dem Symbol angezeigt. Tipp: Achten Sie auf die Kurzinfo oder die Zeitleiste, um zu sehen, ob eine der Richtlinien 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. Erscheint bei einem Richtliniensymbol, wenn die Bedingung des Richtlinienschritts als falsch ausgewertet wird (siehe Ablaufvariablen und -bedingungen) oder das BoostFault-Richtliniensymbol, wenn eine BoostFault-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 verfeinern

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 herausfiltern, die möglicherweise Probleme verursachen. Möglicherweise müssen Sie sich beispielsweise 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: Es werden nur Aufrufe mit einem bestimmten Wert eines Parameters aufgezeichnet.

Wichtige Informationen zur Filterfunktion

• Sie müssen Ihre Trace-Sitzung neu starten, nachdem Sie Filterparameter in den Filterfeldern angegeben haben.
• Filterparameter werden durch „AND“ miteinander 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 links oben 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 Sie filtern möchten. 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 ist jedoch nicht möglich:

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.
• In den Phasendetails sehen Sie unter anderem die an das Back-End gesendeten Header prüfen, die von Richtlinien festgelegten Variablen ansehen 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 unverarbeiteten Trace-Ergebnissen herunterladen, um sie offline in einem Texteditor anzusehen und darin zu suchen. Die Datei enthält die vollständigen Details der Hörsitzung, einschließlich des Inhalts aller Header, Variablen und Richtlinien.

Klicken Sie zum Herunterladen auf Trace-Sitzung herunterladen.

Anzeigen von Anfragen als curl

Nachdem Sie einen API-Aufruf an einen Zielserver nachverfolgt 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 Nachrichtennutzlasten können Sie mit „curl“ die HTTP-Header und den Nachrichteninhalte an einem Ort sehen. Derzeit gilt eine Beschränkung von etwa 1.000 Zeichen. Einen Tipp, wie Sie dieses Limit umgehen können, finden Sie in diesem Community-Beitrag.)

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 Diagramm „Transaktionskarte“ 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.