aws x-ray - entwicklerhandbuch€¦ · aws x-ray entwicklerhandbuch was ist aws x-ray? aws x-ray...
TRANSCRIPT
AWS X-RayEntwicklerhandbuch
AWS X-Ray Entwicklerhandbuch
AWS X-Ray: EntwicklerhandbuchCopyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any mannerthat is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks notowned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored byAmazon.
AWS X-Ray Entwicklerhandbuch
Table of ContentsWas ist AWS X-Ray? .......................................................................................................................... 1Anwendungsfälle ................................................................................................................................ 3
Unterstützte Sprachen und Frameworks ......................................................................................... 4Unterstützte AWS-Services .......................................................................................................... 6Code- und Konfigurationsänderungen ............................................................................................ 7
Erste Schritte ..................................................................................................................................... 8Voraussetzungen ........................................................................................................................ 9Bereitstellen der Anwendung in Elastic Beanstalk und Generieren von Ablaufverfolgungsdaten .............. 10Anzeigen der Service-Übersicht in der X-Ray-Konsole .................................................................... 11Konfigurations-Amazon SNS-Benachrichtigungen ........................................................................... 13Erkunden der Beispielanwendung ................................................................................................ 15Bereinigen ............................................................................................................................... 18Nächste Schritte ....................................................................................................................... 19
Konzepte ......................................................................................................................................... 20Segmente ................................................................................................................................ 20Untersegmente ......................................................................................................................... 21Service-Grafik ........................................................................................................................... 23Ablaufverfolgungen .................................................................................................................... 25Sampling ................................................................................................................................. 26Ablaufverfolgungs-Header .......................................................................................................... 26Filterausdrücke ......................................................................................................................... 27Anmerkungen und Metadaten ..................................................................................................... 27Fehler und Ausnahmen .............................................................................................................. 28
X-Ray-Konsole ................................................................................................................................. 29Anzeigen der Service-Übersicht .................................................................................................. 29Anzeigen von Ablaufverfolgungen ................................................................................................ 32Anzeigen von Segmentdetails ..................................................................................................... 35Anzeigen von Untersegmentdetails .............................................................................................. 37Filterausdrücke ......................................................................................................................... 39
Syntax für Filterausdrücke .................................................................................................. 41Boolesche Schlüsselwörter ................................................................................................. 42Anzahl von Schlüsselwörtern .............................................................................................. 42Schlüsselwörter für Zeichenfolge ......................................................................................... 43Komplexe Schlüsselwörter .................................................................................................. 44Die ID-Funktion ................................................................................................................ 45
Erstellen von Deep-Links ........................................................................................................... 47Ablaufverfolgungen ............................................................................................................ 47Filterausdrücke ................................................................................................................. 47Zeitraum .......................................................................................................................... 47Region ............................................................................................................................ 48Kombiniert ....................................................................................................................... 48
Histogramme ............................................................................................................................ 48Verschlüsselung ........................................................................................................................ 50
X-Ray-API ........................................................................................................................................ 52Praktische Anleitung .................................................................................................................. 52
Voraussetzungen .............................................................................................................. 52Generieren von Ablaufverfolgungsdaten ............................................................................... 53Verwenden der X-Ray-API ................................................................................................. 53Bereinigen ....................................................................................................................... 55
Senden von Daten .................................................................................................................... 55Erzeugen von Ablaufverfolgungs-IDs .................................................................................... 57Verwendung von PutTraceSegments ................................................................................... 58Senden von Segmentdokumenten an den X-Ray-Daemon ....................................................... 58
Abrufen von Daten .................................................................................................................... 59
iii
AWS X-Ray Entwicklerhandbuch
Abrufen der Service-Grafik ................................................................................................. 59Abrufen von Ablaufverfolgungen .......................................................................................... 64
Konfiguration ............................................................................................................................ 67CloudTrail ................................................................................................................................ 68AWS Config ............................................................................................................................. 69
Erstellen eines Lambda-Funktionsauslösers .......................................................................... 70Erstellen einer benutzerdefinierten AWS Config-Regel für X-Ray .............................................. 71Beispielergebnisse ............................................................................................................ 72Amazon SNS-Benachrichtigungen ....................................................................................... 72
Segmentdokumente ................................................................................................................... 72Segmentfelder .................................................................................................................. 73Untersegmente ................................................................................................................. 75HTTP-Anfragedaten ........................................................................................................... 78Anmerkungen ................................................................................................................... 80Metadata ......................................................................................................................... 80AWS-Ressourcendaten ...................................................................................................... 81Fehler und Ausnahmen ...................................................................................................... 83SQL-Abfragen ................................................................................................................... 84
Berechtigungen ................................................................................................................................. 86Verwaltete IAM-Richtlinien für X-Ray ............................................................................................ 86Lokale Ausführung Ihrer Anwendung ........................................................................................... 87Ausführung Ihrer Anwendung in AWS .......................................................................................... 88
Beispielanwendung ............................................................................................................................ 89AWS SDK-Clients ..................................................................................................................... 93Benutzerdefinierte Untersegmente ............................................................................................... 93Anmerkungen und Metadaten ..................................................................................................... 94HTTP-Clients ............................................................................................................................ 95SQL-Clients .............................................................................................................................. 95AWS Lambda-Funktionen ........................................................................................................... 98
Zufälliger Name ................................................................................................................ 99Worker ........................................................................................................................... 100
Amazon ECS .......................................................................................................................... 102Startup-Code .......................................................................................................................... 103Skripte ................................................................................................................................... 104Client ..................................................................................................................................... 106Auftragnehmer-Threads ............................................................................................................ 109Erstellen von Deep-Links .......................................................................................................... 111
X-Ray-Daemon ............................................................................................................................... 112Herunterladen des Daemons ..................................................................................................... 112Überprüfen der Signatur des Daemon-Archivs ............................................................................. 112Ausführen des Daemons .......................................................................................................... 113Erteilen der Berechtigung zum Senden von Daten an X-Ray für den Daemon ................................... 114Protokolle des X-Ray-Daemons ................................................................................................. 114Konfiguration .......................................................................................................................... 115
Verwendung von Befehlszeilenoptionen .............................................................................. 115Verwendung einer Konfigurationsdatei ................................................................................ 116
Lokales Ausführen des Daemons .............................................................................................. 117Ausführen des X-Ray-Daemons unter Linux ........................................................................ 117Ausführen des X-Ray-Daemons in einem Docker-Container ................................................... 118Ausführen des X-Ray-Daemons unter Windows ................................................................... 119Ausführen des X-Ray-Daemons unter OS X ........................................................................ 119
In Elastic Beanstalk ................................................................................................................. 120Verwenden der Elastic Beanstalk X-Ray-Integration zum Ausführen des X-Ray-Daemons ............ 120Manuelles Herunterladen und Ausführen des X-Ray-Daemons (Erweitert) ................................ 121
In Amazon EC2 ...................................................................................................................... 123In Amazon ECS ...................................................................................................................... 124
Arbeiten mit Java ............................................................................................................................ 127
iv
AWS X-Ray Entwicklerhandbuch
Voraussetzungen ..................................................................................................................... 128Abhängigkeitsmanagement ....................................................................................................... 129Konfiguration .......................................................................................................................... 130
Service-Plugins ............................................................................................................... 130Samplingregeln ............................................................................................................... 132Protokollierung ................................................................................................................ 134Umgebungsvariablen ....................................................................................................... 134Systemeigenschaften ....................................................................................................... 135
Eingehende Anforderungen ....................................................................................................... 135Hinzufügen eines Ablaufverfolgungsfilters zu Ihrer Anwendung (Tomcat) .................................. 136Hinzufügen eines Ablaufverfolgungsfilters zu Ihrer Anwendung (Spring) ................................... 136Konfiguration einer Segmentbenennungsstrategie ................................................................ 137
AWS SDK-Clients .................................................................................................................... 138Ausgehende HTTP-Aufrufe ....................................................................................................... 139SQL-Abfragen ......................................................................................................................... 141Benutzerdefinierte Untersegmente ............................................................................................. 142Anmerkungen und Metadaten ................................................................................................... 144
Aufzeichnung von Anmerkungen mit X-Ray SDK for Java ...................................................... 144Aufzeichnung von Metadaten mit X-Ray SDK for Java .......................................................... 146Aufzeichnung von Benutzer-IDs mit X-Ray SDK for Java ....................................................... 147
Multithreading ......................................................................................................................... 147AOP mit Spring ....................................................................................................................... 148
Konfigurieren von Spring .................................................................................................. 148Kommentieren Ihres Codes oder implementieren einer Schnittstelle ........................................ 149Aktivieren von X-Ray in Ihrer Anwendung ........................................................................... 149Beispiel .......................................................................................................................... 149
Verwenden von Go ......................................................................................................................... 151Voraussetzungen ..................................................................................................................... 152Referenzdokumentation ............................................................................................................ 152Konfiguration .......................................................................................................................... 152
Service-Plugins ............................................................................................................... 153Samplingregeln ............................................................................................................... 154Protokollierung ................................................................................................................ 155Umgebungsvariablen ....................................................................................................... 155Verwenden von "Configure" .............................................................................................. 156
Eingehende Anforderungen ....................................................................................................... 156Konfiguration einer Segmentbenennungsstrategie ................................................................ 157
AWS SDK-Clients .................................................................................................................... 158Ausgehende HTTP-Aufrufe ....................................................................................................... 160SQL-Abfragen ......................................................................................................................... 160Benutzerdefinierte Untersegmente ............................................................................................. 160Anmerkungen und Metadaten ................................................................................................... 161
Aufzeichnen von Anmerkungen mit dem X-Ray SDK für Go ................................................... 161Aufzeichnen von Metadaten mit dem X-Ray SDK für Go ....................................................... 162Aufzeichnen von Benutzer-IDs mit dem X-Ray SDK für Go .................................................... 162
Arbeiten mit Node.js ........................................................................................................................ 163Voraussetzungen ..................................................................................................................... 164Abhängigkeitsmanagement ....................................................................................................... 164Konfiguration .......................................................................................................................... 165
Service-Plugins ............................................................................................................... 165Samplingregeln ............................................................................................................... 166Protokollierung ................................................................................................................ 167X-Ray-Daemon-Adresse ................................................................................................... 167Umgebungsvariablen ....................................................................................................... 168
Eingehende Anforderungen ....................................................................................................... 168Nachverfolgung eingehender Anforderungen mit Express ...................................................... 169Nachverfolgung eingehender Anforderungen mit Restify ........................................................ 169
v
AWS X-Ray Entwicklerhandbuch
Konfiguration einer Segmentbenennungsstrategie ................................................................ 170AWS SDK-Clients .................................................................................................................... 171Ausgehende HTTP-Aufrufe ....................................................................................................... 172SQL-Abfragen ......................................................................................................................... 173Benutzerdefinierte Untersegmente ............................................................................................. 174Anmerkungen und Metadaten ................................................................................................... 175
Aufzeichnen von Anmerkungen mit dem X-Ray SDK for Node.js ............................................. 175Aufzeichnen von Metadaten mit dem X-Ray SDK for Node.js ................................................. 176
Verwenden von Python .................................................................................................................... 178Voraussetzungen ..................................................................................................................... 179Abhängigkeitsmanagement ....................................................................................................... 180Konfiguration .......................................................................................................................... 180
Service-Plugins ............................................................................................................... 180Samplingregeln ............................................................................................................... 182Protokollierung ................................................................................................................ 183Konfiguration des Recorders im Code ................................................................................ 183Konfigurieren des Recorders mit Django ............................................................................. 183Umgebungsvariablen ....................................................................................................... 184
Eingehende Anforderungen ....................................................................................................... 185Hinzufügen der Middleware zu Ihrer Anwendung (Django) ..................................................... 186Hinzufügen der Middleware zu Ihrer Anwendung (Flask) ........................................................ 186Manuelle Instrumentierung von Python-Code ....................................................................... 187Konfiguration einer Segmentbenennungsstrategie ................................................................ 187
Patchen von Bibliotheken ......................................................................................................... 188Ablaufverfolgungskontext für Asynchronous Work ................................................................. 189
AWS SDK-Clients .................................................................................................................... 190Ausgehende HTTP-Aufrufe ....................................................................................................... 191Benutzerdefinierte Untersegmente ............................................................................................. 192Anmerkungen und Metadaten ................................................................................................... 193
Aufzeichnen von Anmerkungen mit dem X-Ray SDK für Python .............................................. 194Aufzeichnen von Metadaten mit dem X-Ray SDK für Python .................................................. 194Aufzeichnen von Benutzer-IDs mit dem X-Ray SDK für Python ............................................... 195
Arbeiten mit Ruby ........................................................................................................................... 197Voraussetzungen ..................................................................................................................... 198Konfiguration .......................................................................................................................... 198
Service-Plugins ............................................................................................................... 198Samplingregeln ............................................................................................................... 200Protokollierung ................................................................................................................ 201Konfiguration des Recorders im Code ................................................................................ 202Konfigurieren des Recorders mit Rails ................................................................................ 202Umgebungsvariablen ....................................................................................................... 203
Eingehende Anforderungen ....................................................................................................... 203Verwenden der Rails-Middleware ....................................................................................... 204Code manuell instrumentieren ........................................................................................... 204Konfiguration einer Segmentbenennungsstrategie ................................................................ 205
Patchen von Bibliotheken ......................................................................................................... 206AWS SDK-Clients .................................................................................................................... 206Benutzerdefinierte Untersegmente ............................................................................................. 207Anmerkungen und Metadaten ................................................................................................... 208
Aufzeichnung von Anmerkungen mit X-Ray SDK für Ruby ..................................................... 208Aufzeichnung von Metadaten mit X-Ray SDK für Ruby .......................................................... 209Aufzeichnen von Benutzer-IDs mit dem X-Ray SDK für Ruby ................................................. 210
Arbeiten mit .NET ............................................................................................................................ 211Voraussetzungen ..................................................................................................................... 212Hinzufügen des X-Ray SDK for .NET zu Ihrer Anwendung ............................................................. 212Konfiguration .......................................................................................................................... 212
Plugins .......................................................................................................................... 213
vi
AWS X-Ray Entwicklerhandbuch
Samplingregeln ............................................................................................................... 214Protokollierung (.NET) ...................................................................................................... 215Protokollierung (.NET Core) .............................................................................................. 215Umgebungsvariablen ....................................................................................................... 216
Eingehende Anforderungen ....................................................................................................... 217Instrumentierung eingehender Anforderungen (.NET) ............................................................ 217Instrumentierung eingehender Anforderungen (.NET Core) .................................................... 218Konfiguration einer Segmentbenennungsstrategie ................................................................ 218
AWS SDK-Clients .................................................................................................................... 219Ausgehende HTTP-Aufrufe ....................................................................................................... 220SQL-Abfragen ......................................................................................................................... 222Benutzerdefinierte Untersegmente ............................................................................................. 223Anmerkungen und Metadaten ................................................................................................... 223
Aufzeichnen von Anmerkungen mit dem X-Ray SDK for .NET ................................................ 224Aufzeichnen von Metadaten mit dem X-Ray SDK for .NET ..................................................... 224
Fehlerbehebung .............................................................................................................................. 226X-Ray SDK for Java ................................................................................................................ 226X-Ray SDK for Node.js ............................................................................................................ 226Der X-Ray-Daemon ................................................................................................................. 227
Arbeiten mit anderen Services .......................................................................................................... 228Elastic Load Balancing ............................................................................................................. 228Lambda ................................................................................................................................. 229API Gateway .......................................................................................................................... 230Amazon EC2 .......................................................................................................................... 230Elastic Beanstalk ..................................................................................................................... 230
vii
AWS X-Ray Entwicklerhandbuch
Was ist AWS X-Ray?AWS X-Ray ist ein Service, der Daten über Anforderungen erfasst, die Ihre Anwendung verarbeitet,und bietet Tools zum Anzeigen, Filtern und Analysieren der Daten, um Probleme und Möglichkeitenzur Optimierung zu identifizieren. Für jede verfolgte Clientanforderung für Ihre Anwendung sehen Siedetaillierte Informationen nicht nur über die Anforderung und Antwort, sondern auch über Aufrufe, die IhreAnwendung an nachgelagerte AWS-Ressourcen, -Mikroservices, -Datenbanken und HTTP-Web-APIssendet.
Das X-Ray-SDK bietet:
• Interceptors, die Sie Ihrem Code hinzufügen können, um eingehende HTTP-Anforderungennachzuverfolgen.
• Client-Handler zur Instrumentierung von AWS SDK-Clients, mit denen Ihre Anwendung andere AWS-Services aufruft.
• Einen HTTP-Client zur Instrumentierung von Aufrufen an andere interne und externe HTTP-Webservices.
Das SDK unterstützt auch Instrumentierungsaufrufe von SQL-Datenbanken, automatische AWS SDK-Client-Instrumentierung und andere Funktionen.
Anstatt Ablaufverfolgungsdaten direkt in X-Ray zu senden, übermittelt das SDK JSON-Segmentdokumentean einen Daemon-Prozess, der auf UDP-Datenverkehr wartet. Der X-Ray-Daemon (p. 112) puffert
1
AWS X-Ray Entwicklerhandbuch
Segmente in eine Warteschlange und lädt sie in Stapeln auf X-Ray hoch. Der Daemon ist verfügbar fürLinux, Windows und macOS und ist auf AWS Elastic Beanstalk und AWS Lambda Plattformen enthalten.
X-Ray verwendet Ablaufverfolgungsdaten von den AWS-Ressourcen, die Ihre Cloudanwendungenunterstützen, um ein detailliertes Servicediagramm zu erstellen. Das Servicediagramm zeigt den Client,Ihren Frontend-Service und die Backend-Services, die Ihr Frontend-Services für die Verarbeitung vonAnforderungen und Persistenzdaten aufruft. Sie können das Servicediagramms zur Ermittlung vonEngpässen, Latenzspitzen und anderen Problemen verwenden, die Sie zur Verbesserung der LeistungIhrer Anwendungen beheben können.
In der Erste Schritte-Anleitung (p. 8) finden Sie Informationen, mit deren Hilfe Sie in wenigen MinutenX-Ray mit einer instrumentierten Beispielanwendung verwenden können. Oder lesen Sie weiter (p. 3),um mehr über die Sprachen, Frameworks und Services zu erfahren, die mit X-Ray funktionieren.
2
AWS X-Ray Entwicklerhandbuch
AWS X-Ray Anwendungsfälle undAnforderungen
Mit der X-Ray-SDK- und AWS-Serviceintegration können Sie Anforderungen an Ihre Anwendungeninstrumentieren, die lokal oder auf AWS-Datenverarbeitungsservices wie Amazon EC2, Elastic Beanstalk,Amazon ECS und AWS Lambda ausgeführt werden.
Zum Instrumentieren Ihres Anwendungscodes können Sie das X-Ray SDK verwenden. Das SDK erfasstDaten über ein- und ausgehende Anforderungen und sendet diese an den X-Ray-Daemon, der dieDaten in Stapeln an X-Ray weiterleitet. Wenn Ihre Anwendung beispielsweise DynamoDB aufruft, umBenutzerinformationen aus einer DynamoDB-Tabelle abzurufen, erfasst das X-Ray SDK Daten sowohl ausder Client-Anforderung als auch aus dem nachgelagerten Aufruf von DynamoDB.
Andere AWS-Services erleichtern das Instrumentieren der Komponenten Ihrer Anwendung durch dieIntegration in X-Ray. Service-Integration kann das Hinzufügen von Ablaufverfolgungs-Headern zueingehenden Anforderungen, Senden von Ablaufverfolgungsdaten an X-Ray oder Ausführen des X-Ray-Daemons umfassen. Beispielsweise kann AWS Lambda Ablaufverfolgungsdaten zu Anfragen an IhreLambda-Funktionen senden und den X-Ray-Daemon für Arbeiter ausführen, um diesen die Verwendungdes X-Ray-SDK zu erleichtern.
3
AWS X-Ray EntwicklerhandbuchUnterstützte Sprachen und Frameworks
Viele Instrumentierungsszenarios erfordern nur Konfigurationsänderungen. Beispielsweise können Siealle eingehenden HTTP-Anforderungen und nachgeordneten Aufrufe an AWS-Services instrumentieren,die die Java-Anwendung durchführt. Dazu fügen Sie den Filter des X-Ray SDK for JavaIhrer Servlet-Konfiguration hinzu und nehmen das AWS SDK for Java Instrumentor-Untermodul als Build-Abhängigkeit.Für die erweiterte Instrumentierung können Sie Ihren Anwendungscode ändern, um die Daten, die das SDKan X-Ray sendet, anzupassen und mit Anmerkungen zu versehen.
Abschnitte• Unterstützte Sprachen und Frameworks (p. 4)• Unterstützte AWS-Services (p. 6)• Code- und Konfigurationsänderungen (p. 7)
Unterstützte Sprachen und FrameworksAWS X-Ray bietet Tools und Integrationen zur Unterstützung verschiedener Sprachen, Frameworks undPlattformen.
C#
Unter Windows Server können Sie das X-Ray SDK for .NET verwenden, um eingehende Anforderungen,AWS SDK-Clients, SQL-Clients und HTTP-Clients zu instrumentieren. Auf AWS Lambda können Sie dieLambda-X-Ray-Integration verwenden, um eingehende Anforderungen zu instrumentieren.
Weitere Informationen finden Sie unter AWS X-Ray-SDK für .NET (p. 211).
• .NET auf Windows Server – Fügen Sie Ihrer HTTP-Konfiguration einen Meldungshandler (p. 217)hinzu, um eingehende Anforderungen zu instrumentieren.
• C# .NET Core auf AWS Lambda – Aktivieren Sie X-Ray auf Ihrer Lambda-Funktionskonfiguration, umeingehende Anforderungen zu instrumentieren.
Go
In einer Go-Anwendung können Sie die X-Ray SDK für Go-Klassen zum Instrumentieren von eingehendenAnforderungen, AWS SDK-Clients, SQL-Clients und HTTP-Clients verwenden. Die Eine automatischeInstrumentierung von Anforderungen ist für Anwendungen verfügbar, die HTTP-Handler verwenden.
Auf AWS Lambda können Sie die Lambda-X-Ray-Integration verwenden, um eingehende Anforderungenzu instrumentieren. Fügen Sie Ihrer Funktion das X-Ray SDK für Go für eine vollständige Instrumentierunghinzu.
Weitere Informationen finden Sie unter AWS X-Ray-SDK für Go (p. 151).
• Go-Webanwendungen – Verwenden Sie den X-Ray SDK für Go HTTP-Handler (p. 156), umeingehende Anforderungen auf Ihren Routen zu verarbeiten.
• Go auf AWS Lambda – Aktivieren Sie X-Ray auf Ihrer Lambda-Funktionskonfiguration, um eingehendeAnforderungen zu instrumentieren. Fügen Sie X-Ray SDK für Go hinzu, um AWS SDK-, HTTP- und SQL-Clients zu instrumentieren.
Java
In einer Java-Anwendung können Sie die X-Ray SDK for Java-Klassen zum Instrumentieren voneingehenden Anforderungen, AWS SDK-Clients, SQL-Clients und HTTP-Clients verwenden. Dieautomatische Anforderungsinstrumentierung ist für Frameworks verfügbar, die Java-Servlets unterstützen.Die automatische SDK-Instrumentierung ist über das Untermodul Instrumentor verfügbar.
4
AWS X-Ray EntwicklerhandbuchUnterstützte Sprachen und Frameworks
Auf AWS Lambda können Sie die Lambda-X-Ray-Integration verwenden, um eingehende Anforderungenzu instrumentieren. Fügen Sie Ihrer Funktion das X-Ray SDK for Java für eine vollständigeInstrumentierung hinzu.
Weitere Informationen finden Sie unter AWS X-Ray SDK für Java (p. 127).
• Tomcat – Fügen Sie einen Servlet-Filter (p. 136) zu Ihrer Bereitstellungsbeschreibung (web.xml)hinzu, um eingehende Anforderungen zu instrumentieren.
• Spring Boot – Fügen Sie einen Servlet-Filter (p. 136) zu Ihrer Ihrer WebConfig-Klasse hinzu, umeingehende Anforderungen zu instrumentieren.
• Java auf AWS Lambda – Aktivieren Sie X-Ray auf Ihrer Lambda-Funktion, um eingehendeAnforderungen zu instrumentieren. Fügen Sie X-Ray SDK for Java hinzu, um AWS SDK-, HTTP- undSQL-Clients zu instrumentieren.
• Andere Frameworks – Fügen Sie einen Servlet-Filter hinzu, wenn Ihr Framework Servlets unterstützt,oder erstellen Sie für jede eingehende Anforderung manuell ein Segment.
Node.js
In einer Node.js-Anwendung können Sie die X-Ray SDK for Node.js-Klassen zum Instrumentierenvon eingehenden Anforderungen, AWS SDK-Clients, SQL-Clients und HTTP-Clients verwenden. Eineautomatische Instrumentierung von Anforderungen ist für Anwendungen verfügbar, die die Express- undRestify-Frameworks verwenden.
Auf AWS Lambda können Sie die Lambda-X-Ray-Integration verwenden, um eingehende Anforderungenzu instrumentieren. Fügen Sie Ihrer Funktion das X-Ray SDK for Node.js für eine vollständigeInstrumentierung hinzu.
Weitere Informationen finden Sie unter Das X-Ray SDK for Node.js (p. 163).
• Express oder Restify – Verwenden Sie die X-Ray SDK for Node.js Middleware (p. 168) zurInstrumentierung von eingehenden Anforderungen.
• Node.js auf AWS Lambda – Aktivieren Sie X-Ray auf Ihrer Lambda-Funktion, um eingehendeAnforderungen zu instrumentieren. Fügen Sie X-Ray SDK for Node.js hinzu, um AWS SDK-, HTTP- undSQL-Clients zu instrumentieren.
• Andere Frameworks – Erstellen Sie manuell ein Segment für jede eingehende Anforderung.
Python
In einer Python-Anwendung können Sie die X-Ray SDK für Python-Klassen zum Instrumentieren voneingehenden Anforderungen, AWS SDK-Clients, SQL-Clients und HTTP-Clients verwenden. Eineautomatische Instrumentierung von Anforderungen ist für Anwendungen verfügbar, die die Django- undFlask-Frameworks verwenden.
Auf AWS Lambda können Sie die Lambda-X-Ray-Integration verwenden, um eingehende Anforderungenzu instrumentieren. Fügen Sie Ihrer Funktion das X-Ray SDK für Python für eine vollständigeInstrumentierung hinzu.
Weitere Informationen finden Sie unter AWS X-Ray-SDK für Python (p. 178).
• Django oder Flask – Verwenden Sie die X-Ray SDK für Python-Middleware (p. 185) zurInstrumentierung eingehender Anforderungen.
• Python auf AWS Lambda – Aktivieren Sie X-Ray auf Ihrer Lambda-Funktionskonfiguration, umeingehende Anforderungen zu instrumentieren. Fügen Sie X-Ray SDK für Python hinzu, um AWS SDK-,HTTP- und SQL-Clients zu instrumentieren.
• Andere Frameworks – Erstellen Sie manuell ein Segment für jede eingehende Anforderung.
5
AWS X-Ray EntwicklerhandbuchUnterstützte AWS-Services
Ruby
In einer Ruby-Anwendung können Sie die X-Ray SDK für Ruby-Klassen zum Instrumentieren voneingehenden Anforderungen, AWS SDK-Clients, SQL-Clients und HTTP-Clients verwenden. Eineautomatische Instrumentierung von Anforderungen ist für Anwendungen verfügbar, die das Rails-Framework verwenden.
• Rails – Fügen Sie Ihrer Gemfile-Datei das X-Ray SDK für Ruby-Gem und railtie hinzu, und konfigurierenSie den Recorder (p. 203) in einem Initialisierer, um eingehende Anforderungen zu instrumentieren.
• Andere Frameworks – Erstellen Sie manuell ein Segment (p. 204) für jede eingehende Anforderung.
Wenn das X-Ray SDK für Ihre Sprache oder Plattform nicht verfügbar ist, können SieAblaufverfolgungsdaten manuell generieren und sie an den X-Ray-Daemon oder direkt an die X-Ray-API (p. 52) senden.
Unterstützte AWS-ServicesMehrere AWS-Services bieten X-Ray-Integration. Integrierte Services (p. 228) bieten verschiedeneEbenen der Integration, die Sampling und Hinzufügen von Headern zu eingehenden Anforderungen,Ausführen des X-Ray-Daemons und automatisches Senden der Ablaufverfolgungsdaten an X-Rayumfassen können.
• Aktive Instrumentierung – Führt Sampling und Instrumentierung von eingehenden Anforderungen durch.• Passive Instrumentierung – Instrumentiert Anforderungen, für die von einem anderen Service ein
Sampling durchgeführt wurde.• Ablaufverfolgung von Anforderungen – Fügt allen eingehenden Anforderungen einen Ablaufverfolgungs-
Header hinzu und verteilt ihn auf nachgelagerte Services.• Tooling – Führt den AWS X-Ray-Daemon aus, um Segmente vom X-Ray SDK zu empfangen.
Services mit X-Ray-Integration umfassen Folgendes:
• AWS Lambda – Aktive und passive Instrumentierung eingehender Anforderungen in allen Laufzeiten.Wenn Sie die Instrumentierung aktivieren, führt AWS Lambda auch den X-Ray-Daemon in denLaufzeiten Java und Node.js zur Verwendung mit dem X-Ray-SDK aus. Weitere Informationen (p. 229).
• Amazon API Gateway – Ablaufverfolgung anfordern. API Gateway übergibt die Ablaufverfolgungs-ID anAWS Lambda und fügt sie dem Anforderungs-Header für andere nachgelagerte Services hinzu. WeitereInformationen (p. 230).
• Elastic Load Balancing – Fordert die Ablaufverfolgung für Application Load Balancer an. Der ApplicationLoad Balancer fügt die Ablaufverfolgungs-ID dem Anforderungs-Header vor dem Senden an eineZielgruppe hinzu. Weitere Informationen (p. 228).
• AWS Elastic Beanstalk – Tooling. Elastic Beanstalk enthält den X-Ray-Daemon auf den folgendenPlattformen:• Java SE – 2.3.0 und neuere Konfigurationen• Tomcat – 2.4.0 und neuere Konfigurationen• Node.js – 3.2.0 und neuere Konfigurationen• Windows Server – Alle Konfigurationen außer Windows Server Core, die seit 9. Dezember 2016
veröffentlicht wurden.
Sie können Elastic Beanstalk in der Elastic Beanstalk-Konsole oder mit der XRayEnabled-Optionim aws:elasticbeanstalk:xray-Namespace anweisen, den Daemon auf diesen Plattformenauszuführen. Weitere Informationen (p. 230).
6
AWS X-Ray EntwicklerhandbuchCode- und Konfigurationsänderungen
Code- und KonfigurationsänderungenDie Ablaufverfolgungsdaten können größtenteils ohne funktionale Änderungen an Ihrem Code generiertwerden. Die detaillierte Ablaufverfolgung von Front-End- und nachgelagerten Aufrufen erfordert nurminimale Änderungen an der Build- und Bereitstellungszeitkonfiguration.
Beispiele für Code- und Konfigurationsänderungen
• AWS-Ressourcenkonfiguration – Ändern Sie die AWS-Ressourceneinstellungen, um Anforderungen aneine Lambda-Funktion zu instrumentieren. Führen Sie den X-Ray-Daemon auf den Instances in IhrerElastic Beanstalk-Umgebung aus, indem Sie eine Optionseinstellung ändern.
• Build-Konfiguration – Verwenden Sie X-Ray SDK for Java-Untermodule alsKompilierungszeitabhängigkeit, um alle nachgelagerten Anforderungen an AWS-Services undRessourcen wie Amazon DynamoDB-Tabellen, Amazon SQS-Warteschlangen und Amazon S3-Bucketszu instrumentieren.
• Anwendungskonfiguration – Fügen Sie zum Instrumentieren eingehender HTTP-Anforderungen einenServlet-Filter zu Ihrer Java-Anwendung hinzu oder verwenden Sie das X-Ray SDK for Node.js alsMiddleware in Ihrer Express-Anwendung. Ändern Sie die Samplingregeln und aktivieren Sie Plugins zumInstrumentieren von Amazon EC2-, Amazon ECS- und AWS Elastic Beanstalk-Ressourcen, die IhreAnwendung ausführen.
• Klassen- oder Objektkonfiguration – Importieren Sie zur Instrumentierung ausgehender HTTP-Aufrufe inJava die X-Ray SDK for Java-Version von HttpClientBuilder anstelle der Apache.org-Version.
• Funktionale Änderungen – Fügen Sie einem AWS SDK-Client einen Anforderungshandler hinzu, umAufrufe zu instrumentieren, die er an die AWS-Services sendet. Erstellen Sie Untersegmente, umnachgelagerte Aufrufe zu gruppieren, und fügen Sie Segmenten mit Anmerkungen und MetadatenDebug-Informationen hinzu.
7
AWS X-Ray Entwicklerhandbuch
Erste Schritte mit AWS X-RayFür die ersten Schritte mit AWS X-Ray starten Sie eine Beispielanwendung in Elastic Beanstalk, die bereitsinstrumentiert (p. 127) ist, um Ablaufverfolgungsdaten zu generieren. In wenigen Minuten können Siedie Beispielanwendung starten, Datenverkehr generieren, Segmente an X-Ray senden und eine Service-Übersicht sowie Ablaufverfolgungen in der AWS Management Console ansehen.
In diesem Tutorial wird eine Java-Beispielanwendung (p. 89) verwendet, um Segmente zu erstellenund an X-Ray zu senden. Die Anwendung verwendet das Spring Framework zur Implementierung einerJSON-Web-API und AWS SDK for Java, um Daten in Amazon DynamoDB beizubehalten. Ein Servlet-Filterin der Anwendung instrumentiert alle eingehenden Anforderungen, die von der Anwendung verarbeitetwerden, und ein Anforderungshandler auf dem AWS SDK Client instrumentiert nachgelagerte Aufrufe vonDynamoDB.
Sie verwenden die X-Ray-Konsole, um die Verbindungen zwischen Clients, Servern und DynamoDB ineiner Service-Übersicht anzuzeigen. Die Service-Übersicht ist eine visuelle Darstellung der Services,aus denen Ihre Webanwendung besteht. Sie wird aus den Ablaufverfolgungsdaten generiert, die bei derVerarbeitung von Anforderungen anfallen.
8
AWS X-Ray EntwicklerhandbuchVoraussetzungen
Mit dem X-Ray SDK for Java können Sie alle primären und nachgelagerten AWS-Ressourcen IhrerAnwendung durch zwei Konfigurationsänderungen verfolgen:
• Fügen Sie den Ablaufverfolgungsfilter des X-Ray SDK for Java zu Ihrer Servlet-Konfiguration in einerWebConfig-Klasse oder in der Datei web.xml hinzu.
• Verwenden Sie die Untermodule des X-Ray SDK for Java als Build-Abhängigkeiten in Ihrer Maven- oderGradle-Build-Konfiguration.
Sie können auch auf die unformatierte Service-Übersicht zugreifen und Daten mithilfe der AWS-Befehlszeilenschnittstelle zum Aufrufen der X-Ray-API verfolgen. Der Service-Übersichts- undAblaufverfolgungsdaten liegen im JSON-Format vor, das Sie abfragen können, um sicherzustellen, dassIhre Anwendung Daten sendet, oder um bestimmte Felder im Rahmen Ihrer Testautomatisierung zuüberprüfen.
Abschnitte• Voraussetzungen (p. 9)• Bereitstellen der Anwendung in Elastic Beanstalk und Generieren von
Ablaufverfolgungsdaten (p. 10)• Anzeigen der Service-Übersicht in der X-Ray-Konsole (p. 11)• Konfigurations-Amazon SNS-Benachrichtigungen (p. 13)• Erkunden der Beispielanwendung (p. 15)• Bereinigen (p. 18)• Nächste Schritte (p. 19)
VoraussetzungenIn diesem Tutorial wird Elastic Beanstalk zum Erstellen und Konfigurieren der Ressourcen verwendet,die die Beispielanwendung und den X-Ray-Daemon ausführen. Wenn Sie einen IAM-Benutzer
9
AWS X-Ray EntwicklerhandbuchBereitstellen der Anwendung in Elastic Beanstalk
und Generieren von Ablaufverfolgungsdaten
mit eingeschränkten Berechtigungen verwenden, fügen Sie die von Elastic Beanstalk verwalteteBenutzerrichtlinie hinzu, um Ihrem IAM-Benutzer die Berechtigung zur Nutzung von Elastic Beanstalk zugewähren. Fügen Sie außerdem die verwaltete AWSXrayReadOnlyAccess-Richtlinie hinzu, um demBenutzer die Berechtigung zum Lesen der Service-Übersicht und der Ablaufverfolgungen in der X-Ray-Konsole zu gewähren.
Erstellen Sie eine Elastic Beanstalk-Umgebung für die Beispielanwendung. Wenn Sie Elastic Beanstalkzum ersten Mal verwenden, wird bei diesem Vorgang auch eine Service-Rolle und ein Instance-Profil fürIhre Anwendung erstellt.
Erstellen Sie eine Elastic Beanstalk-Umgebung wie folgt:
1. Öffnen Sie die Elastic Beanstalk Management Console mit diesem vorkonfiguriertenLink: https://console.aws.amazon.com/elasticbeanstalk/#/newApplication?applicationName=scorekeep&solutionStackName=Java
2. Wählen Sie Create application aus, um eine Anwendung mit einer Umgebung zu erstellen, in der dieJava 8 SE-Plattform ausgeführt wird.
3. Wenn Ihre Umgebung bereit ist, leitet die Konsole Sie zum Dashboard der Umgebung weiter.4. Klicken Sie auf die URL oben auf der Seite, um die Website zu öffnen.
Die Instances in Ihrer Umgebung benötigen eine Berechtigung zum Senden von Daten an den AWS X-Ray-Service. Darüber hinaus verwendet die Beispielanwendung Amazon S3 und DynamoDB. Ändern Sie dasstandardmäßige Elastic Beanstalk-Instance-Profil, um Berechtigungen für diese Services zu integrieren.
So fügen Sie Ihrer Elastic Beanstalk -Umgebung X-Ray-, Amazon S3- und DynamoDB-Berechtigungen hinzu
1. Öffnen Sie das Elastic Beanstalk Instance-Profil in der IAM-Konsole: aws-elasticbeanstalk-ec2-role.2. Wählen Sie Attach Policy aus.3. Fügen Sie der Rolle AWSXrayFullAccess, AmazonS3FullAccess und AmazonDynamoDBFullAccess
zu an.
Bereitstellen der Anwendung in Elastic Beanstalkund Generieren von Ablaufverfolgungsdaten
Stellen Sie die Beispielanwendung in Ihrer Elastic Beanstalk-Umgebung bereit. Die Beispielanwendungnutzt Elastic Beanstalk-Konfigurationsdateien zum Konfigurieren der Umgebung für die Nutzung mit X-Rayund zum Erstellen der DynamoDB, die automatisch verwendet wird.
Stellen Sie den Quellcode wie folgt bereit:
1. Laden Sie die Musteranwendung herunter: eb-java-scorekeep-xray-gettingstarted-v1.3.zip2. Open the Elastic Beanstalk console.3. Navigate to the management console for your environment.4. Klicken Sie auf die Schaltfläche Upload and Deploy.5. Laden Sie eb-java-scorekeep-xray-gettingstarted-v1.3.zip, hoch und wählen Sie dann Deploy aus.
Die Beispielanwendung enthält eine Front-End-Webanwendung. Verwenden Sie die Webanwendung, umDatenverkehr an die API zu generieren und Ablaufverfolgungsdaten an X-Ray zu senden.
10
AWS X-Ray EntwicklerhandbuchAnzeigen der Service-Übersicht in der X-Ray-Konsole
Generieren Sie Ablaufverfolgungsdaten wie folgt:
1. Klicken Sie im Dashboard der Umgebung auf die URL, um die Webanwendung zu öffnen.2. Wählen Sie Create aus, um einen Benutzer und eine Sitzung zu erstellen.3. Geben Sie einen Game Name ein, legen Sie die Rules auf Tic Tac Toe fest und wählen Sie
anschließend Create aus, um ein Spiel zu erstellen.4. Wählen Sie Play, um das Spiel zu starten.5. Wählen Sie eine Kachel, um einen Spielzug zu machen, und ändern Sie den Spielestatus.
Jeder dieser Schritte generiert HTTP-Anforderungen an die API und nachgelagerte Aufrufe von DynamoDBzum Lesen und Schreiben von Benutzer-, Sitzungs-, Spiel-, Spielzug- und Statusdaten.
Anzeigen der Service-Übersicht in der X-Ray-Konsole
Sie können die Service-Übersicht und die Ablaufverfolgungen, die von der Beispielanwendung generiertwurden, in der X-Ray-Konsole anzeigen.
Verwenden Sie die X-Ray-Konsole wie folgt:
1. Öffnen Sie die Service-Übersichtsseite der X-Ray-Konsole.2. Die Konsole zeigt eine Darstellung der Service-Übersicht, die X-Ray aus den von der Anwendung
gesendeten Ablaufverfolgungsdaten generiert.
Die Service-Übersicht zeigt den Web-App-Client, die in Elastic Beanstalk ausgeführte API, den DynamoDB-Service und die einzelnen DynamoDB-Tabellen, die von der Anwendung verwendet werden. JedeAnforderung an die Anwendung, bis zu einer konfigurierbaren Höchstanzahl von Anforderungen proSekunde, wird verfolgt, und zwar wie sie auf die API trifft, Anforderungen an nachgelagerte Servicesgeneriert und abgeschlossen wird.
11
AWS X-Ray EntwicklerhandbuchAnzeigen der Service-Übersicht in der X-Ray-Konsole
Sie können jeden Knoten in der Service-Grafik wählen, um Ablaufverfolgungen für Anforderungenanzusehen, die Datenverkehr zu diesem Knoten generiert haben. Zurzeit ist der Amazon SNS-Knoten rot.Zeigen Sie die Details an, um herauszufinden, warum.
So finden Sie die Ursache des Fehlers
1. Wählen Sie den Knoten mit dem Namen SNS.2. Wählen Sie die Nachverfolgung aus der Trace list. Diese Ablaufverfolgung verfügt über keine Methode
oder URL, da sie während des Startups und nicht als Reaktion auf eine eingehende Anforderungaufgezeichnet wurde.
3. Wählen Sie das rote Statussymbol, um die Seite Exceptions für das SNS-Untersegment zu öffnen.
4. Das X-Ray-SDK erfasst automatisch Ausnahmen, die von instrumentierten AWS-SDK-Clientsausgegeben werden, und zeichnet die Stack-Ablaufverfolgung auf.
12
AWS X-Ray EntwicklerhandbuchKonfigurations-Amazon SNS-Benachrichtigungen
Die Ursache gibt an, dass die E-Mail-Adresse, die in einem Aufruf von createSubscription in derKlasse WebConfig angegeben wurde, ungültig ist. Dies muss behoben werden.
Konfigurations-Amazon SNS-BenachrichtigungenScorekeep verwendet Amazon SNS, um Benachrichtigungen zu senden, wenn Benutzer ein Spielabschließen. Wenn die Anwendung gestartet wird, versucht sie, ein Abonnement für eine E-Mail-Adressezu erstellen, die in einer Umgebungsvariable definiert ist. Dieser Aufruf kann zurzeit nicht ausgeführtwerden, was dazu führt, dass der Amazon SNS-Knoten in der Service-Übersicht rot ist. Konfigurieren Sieeine Benachrichtigungs-E-Mail in einer Umgebungsvariablen, um Benachrichtigungen zu ermöglichen,sodass die Service-Übersicht grün angezeigt wird.
So konfigurieren Sie Amazon SNS-Benachrichtigungen für Scorekeep
1. Open the Elastic Beanstalk console.2. Navigate to the management console for your environment.3. Choose Configuration.4. Wählen Sie Software Configuration.5. Ersetzen Sie unter Environment Properties den Standardwert durch Ihre E-Mail-Adresse.
13
AWS X-Ray EntwicklerhandbuchKonfigurations-Amazon SNS-Benachrichtigungen
Note
Der Standardwert verwendet eine AWS CloudFormation-Funktion, um einen Parameterabzurufen, der in einer Konfigurationsdatei gespeichert ist (in diesem Fall einenPlatzhalterwert).
6. Wählen Sie Apply aus.
Wenn die Aktualisierung abgeschlossen ist, startet Scorekeep neu und erstellt ein Abonnement fürdas SNS-Thema. Überprüfen Sie Ihre E-Mail-Adresse und bestätigen Sie das Abonnement, umAktualisierungen anzuzeigen, wenn Sie ein Spiel abgeschlossen haben.
14
AWS X-Ray EntwicklerhandbuchErkunden der Beispielanwendung
Erkunden der BeispielanwendungDie Beispielanwendung ist eine HTTP-Web-API in Java, die zur Verwendung des X-Ray SDK for Javakonfiguriert ist. Wenn Sie die Anwendung für Elastic Beanstalk bereitstellen, werden die DynamoDB-Tabellen erstellt, die API mit Gradle kompiliert und der nginx-Proxy-Server so konfiguriert, dass dieWebanwendung statisch im Stammpfad verarbeitet wird. Gleichzeitig leitet Elastic Beanstalk Anforderungenan Pfade beginnend mit /api an die API weiter.
Zum Instrumentieren eingehender HTTP-Anforderungen fügt die Anwendung den vom SDK bereitgestelltenTracingFilter hinzu.
Example src/main/java/scorekeep/WebConfig.java – Servlet-Filter
import javax.servlet.Filter;import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;...
@Configurationpublic class WebConfig {
@Bean public Filter TracingFilter() { return new AWSXRayServletFilter("Scorekeep"); }...
Dieser Filter sendet Ablaufverfolgungsdaten über alle eingehenden Anforderungen, die die Anwendungverarbeitet, einschließlich Anforderungs-URL, Methode, Antwortstatus sowie Start- und Endzeit.
15
AWS X-Ray EntwicklerhandbuchErkunden der Beispielanwendung
Die Anwendung nimmt außerdem nachgelagerte Aufrufe der DynamoDB mithilfe von AWS SDK forJava vor. Um diese Aufrufe zu instrumentieren, nutzt die Anwendung die auf das AWS SDK bezogenenUntermodule als Abhängigkeiten, sodass das X-Ray SDK for Java alle AWS SDK-Clients automatischinstrumentiert.
Die Anwendung verwendet eine Buildfile-Datei zur Erstellung des Quellcodes in einer einzelnen Instanzmit Gradle und einer Procfile - Datei, um die ausführbare JAR-Datei auszuführen, die von Gradlegeneriert wird. Die Unterstützung von Buildfile und Procfile ist eine Funktion der Elastic BeanstalkJava SE-Plattform.
Example Buildfile
build: gradle build
Example Procfile
web: java -Dserver.port=5000 -jar build/libs/scorekeep-api-1.0.0.jar
Die build.gradle-Datei lädt die SDK-Untermodule von Maven während der Kompilierung herunter,indem sie zu Abhängigkeiten erklärt werden.
Example build.gradle – Abhängigkeiten
...dependencies { compile("org.springframework.boot:spring-boot-starter-web") testCompile('org.springframework.boot:spring-boot-starter-test') compile('com.amazonaws:aws-java-sdk-dynamodb') compile("com.amazonaws:aws-xray-recorder-sdk-core") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk-instrumentor") ...}dependencyManagement { imports { mavenBom("com.amazonaws:aws-java-sdk-bom:1.11.67") mavenBom("com.amazonaws:aws-xray-recorder-sdk-bom:1.3.1") }
16
AWS X-Ray EntwicklerhandbuchErkunden der Beispielanwendung
}
Zum automatischen Instrumentieren der nachgelagerten Aufrufe, die mit dem AWS SDK vorgenommenwerden, sind lediglich die wichtigsten Untermodule von AWS SDK und AWS SDK Instrumentor erforderlich.
Zum Ausführen des X-Ray-Daemons verwendet die Anwendung eine weitere Funktion von ElasticBeanstalk, und zwar Konfigurationsdateien. Die Konfigurationsdatei weist Elastic Beanstalk an, denDaemon auszuführen und sendet dessen Protokoll auf Anforderung.
Example .ebextensions/xray.config
option_settings: aws:elasticbeanstalk:xray: XRayEnabled: true
files: "/opt/elasticbeanstalk/tasks/taillogs.d/xray-daemon.conf" : mode: "000644" owner: root group: root content: | /var/log/xray/xray.log
Das X-Ray SDK for Java bietet eine Klasse namens AWSXRay, die die globale Aufzeichnung bereitstellt,einen TracingHandler, mit dem Sie Ihren Code instrumentieren können. Sie können die globaleAufzeichnung so konfigurieren, dass der AWSXRayServletFilter, der Segmente für eingehende HTTP-Aufrufe erstellt, angepasst wird. Das Beispiel enthält einen statischen Block in der WebConfig-Klasse, derdie globale Aufzeichnung mit Plugins und Samplingregeln konfiguriert.
Example src/main/java/scorekeep/WebConfig.java – Aufzeichnung
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.AWSXRayRecorderBuilder;import com.amazonaws.xray.plugins.EC2Plugin;import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin;import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
@Configurationpublic class WebConfig {... static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build()); }}
In diesem Beispiel wird der Builder zum Laden von Samplingregeln aus einer Datei namens sampling-rules.json verwendet. Samplingregeln bestimmen die Rate, mit der das SDK Segmente für eingehendeAnforderungen aufzeichnet.
Example src/main/java/resources/sampling-rules.json
{ "version": 1, "rules": [
17
AWS X-Ray EntwicklerhandbuchBereinigen
{ "description": "Resource creation.", "service_name": "*", "http_method": "POST", "url_path": "/api/*", "fixed_target": 1, "rate": 1.0 }, { "description": "Session polling.", "service_name": "*", "http_method": "GET", "url_path": "/api/session/*", "fixed_target": 0, "rate": 0.05 }, { "description": "Game polling.", "service_name": "*", "http_method": "GET", "url_path": "/api/game/*/*", "fixed_target": 0, "rate": 0.05 }, { "description": "State polling.", "service_name": "*", "http_method": "GET", "url_path": "/api/state/*/*/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 }}
Die Samplingregeldatei definiert vier benutzerdefinierte Samplingregeln und die Standardregel. Für jedeeingehende Anforderung wertet das SDK die benutzerdefinierten Regeln in der Reihenfolge aus, in der siedefiniert sind. Das SDK wendet die erste Regel an, die der Methode, dem Pfad und dem Service-Namender Anforderung entspricht. Bei Scorekeep fängt die erste Regel alle POST-Anforderungen (Aufrufe zumErstellen von Ressourcen) ab, indem pro Sekunde ein festes Ziel einer einzelnen Anfrage und eine Ratevon 1.0 angewendet wird bzw. 100 % der Anforderungen nach dem festen Ziel erfüllt sind.
Die übrigen drei benutzerdefinierte Regeln wenden eine Rate von fünf Prozent ohne festes Zielauf Sitzungs-, Spiel- und Statuslesevorgänge (GET-Anfragen) an. Dies minimiert die Anzahl derAblaufverfolgungen für regelmäßige Aufrufe, die das Front-End automatisch alle paar Sekunden ausführt,um sicherzustellen, dass die Inhalte auf dem neuesten Stand sind. Für alle übrigen Anforderungen definiertdie Datei eine Standardrate von einer einzelnen Anfrage pro Sekunde und einer Rate von 10 Prozent.
Die Beispielanwendung zeigt auch, wie Sie erweiterte Funktionen wie die manuelle SDK-Client-Instrumentierung verwenden sowie zusätzliche Untersegmente und ausgehende HTTP-Aufrufe erstellen.Weitere Informationen finden Sie unter AWS X-Ray-Beispielanwendung (p. 89).
BereinigenBeenden Sie Ihre Elastic Beanstalk-Umgebung, um die Amazon EC2 Instances, DynamoDB-Tabellen undandere Ressourcen zu schließen.
18
AWS X-Ray EntwicklerhandbuchNächste Schritte
Beenden Sie Ihre Elastic Beanstalk-Umgebung wie folgt:
1. Open the Elastic Beanstalk console.2. Navigate to the management console for your environment.3. Wählen Sie Actions.4. Wählen Sie Terminate Environment.5. Wähen Sie Terminate.
Die Ablaufverfolgungsdaten werden nach 30 days in X-Ray automatisch gelöscht.
Nächste SchritteWeitere Informationen zu X-Ray erhalten Sie im nächsten Kapitel AWS X-Ray – Begriffe (p. 20).
Weitere Informationen über das X-Ray SDK for Java oder eines der anderen X-Ray SDKs zumInstrumentieren Ihrer eigenen App erhalten Sie in folgenden Abschnitten:
• X-Ray SDK for Java – AWS X-Ray SDK für Java (p. 127)• X-Ray SDK for Node.js – Das X-Ray SDK for Node.js (p. 163)• X-Ray SDK for .NET – AWS X-Ray-SDK für .NET (p. 211)
Informationen, wie Sie den X-Ray-Daemon lokal oder in AWS ausführen, finden Sie unter AWS X-Ray-Daemon (p. 112).
Informationen zum Mitwirken an der Beispielanwendung auf GitHub finden Sie unter eb-java-scorekeep.
19
AWS X-Ray EntwicklerhandbuchSegmente
AWS X-Ray – BegriffeAWS X-Ray erhält Daten von Services als Segmente. X-Ray gruppiert dann Segmente mit einergemeinsamen Anfrage zu Ablaufverfolgungen. X-Ray verarbeitet die Ablaufverfolgungen zur Erstellungeiner Servicegraphik, die eine visuelle Repräsentation Ihrer Anwendung bereitstellt.
Konzepte• Segmente (p. 20)• Untersegmente (p. 21)• Service-Grafik (p. 23)• Ablaufverfolgungen (p. 25)• Sampling (p. 26)• Ablaufverfolgungs-Header (p. 26)• Filterausdrücke (p. 27)• Anmerkungen und Metadaten (p. 27)• Fehler und Ausnahmen (p. 28)
SegmenteDie Datenverarbeitungsressourcen, die Ihre Anwendungslogik ausführen, senden Daten zu ihrer Arbeit alsSegment. Ein Segment enthält den Namen der Ressource, Details zu der Anforderung und Details zu denerledigten Aufgaben. Wenn zum Beispiel eine HTTP-Anforderung Ihre Anwendung erreicht, können Datenüber Folgendes erfasst werden:
• Der Host – Hostname, Alias oder IP-Adresse• Anforderung – Methode, Clientadresse, Pfad, Benutzeragent• Antwort – Status, Inhalt• Erledigte Aufgaben – Start- und Endzeiten, Untersegmente• Auftretende Probleme – Fehler und Ausnahmen (p. 28), einschließlich der automatischen Erfassung
von Ausnahme-Stacks.
20
AWS X-Ray EntwicklerhandbuchUntersegmente
Das X-Ray SDK sammelt Informationen von den Anforderungs- und Antwort-Headern, den Code inIhrer Anwendung und Metadaten über die AWS-Ressourcen, auf denen es ausgeführt wird. Sie könnenauswählen, welche Daten gesammelt werden, indem Sie Ihre Anwendungskonfiguration oder denCode ändern, um eingehende Anforderungen, nachgelagerte Anforderungen und AWS SDK-Clients zuinstrumentieren.
Weitergeleitete Anfragen
Wenn ein Load Balancer oder ein anderer Mittler eine Anforderung an Ihre Anwendungweiterleitet, übernimmt X-Ray die Client-IP aus der X-Forwarded-For-Kopfzeile der Anforderungund nicht aus der Quell-IP im IP-Paket. Die für eine weitergeleitete Anforderung aufgezeichneteClient-IP kann gefälscht sein und ist daher nicht vertrauenswürdig.
Sie können das X-Ray-SDK verwenden, um zusätzliche Informationen wie Anmerkungen und Metadatenaufzuzeichnen. (p. 27) Weitere Details über die Struktur und die Informationen, die in Segmenten undUntersegmenten aufgezeichnet werden, finden Sie unter AWS X-Ray Segmentdokumente (p. 72).Segmentdokumente können eine Größe von bis zu 64 kB haben.
UntersegmenteEin Segment kann die Daten zu der geleisteten Arbeit in Untersegmente unterteilen. Untersegmente bietendetailliertere Zeitinformationen und Einzelheiten zu Downstream-Aufrufen, die Ihre Anwendung getätigthat, um die ursprüngliche Anforderung zu bearbeiten. Ein Untersegment kann zusätzliche Details zu einemAufruf eines AWS-Service, eine externe HTTP-API oder eine SQL-Datenbank enthalten. Sie können sogarbeliebige Untersegmente definieren, um spezifische Funktionen oder Codezeilen in Ihrer Anwendung zuinstrumentieren.
21
AWS X-Ray EntwicklerhandbuchUntersegmente
Für Dienste, die keine eigenen Segmente senden, z. B. Amazon DynamoDB, verwendet X-RayUntersegmente, um abgeleitete Segmente und nachgelagerte Knoten in der Service-Übersicht zugenerieren. Dadurch können Sie alle Ihre nachgelagerten Abhängigkeiten einsehen, auch wenn diesekeine Ablaufverfolgung unterstützen oder externe Ressourcen sind.
Untersegmente geben die Ansicht eines nachgelagerten Aufrufs Ihrer Anwendung als Client wieder.Wenn der nachgelagerte Service ebenfalls instrumentiert ist, ersetzt das von ihm gesendete Segmentdas abgeleitete Segment, das aus dem Untersegment des vorgelagerten Clients generiert wurde. DerKnoten im Service-Diagramm verwendet immer Informationen vom Segment des Services, sofernverfügbar, während die Edge zwischen den beiden Knoten das Untersegment des nachgelagerten Servicesverwendet.
Wenn Sie beispielsweise DynamoDB mit einem instrumentierten AWS SDK-Client aufrufen, zeichnet dasX-Ray-SDK ein Untersegment für diesen Aufruf auf. DynamoDB sendet kein Segment, somit enthalten dasabgeleitete Segment in der Ablaufverfolgung, der DynamoDB-Knoten im Service-Diagramm und die Edgezwischen Ihrem Service und DynamoDB Informationen aus dem Untersegment.
Wenn Sie einen weiteren instrumentierten Service mit einer instrumentierten Anwendung aufrufen, sendetder nachgelagerte Service ein eigenes Segment, um seine Ansicht desselben Aufrufs aufzuzeichnen, dender vorgelagerte Service in einem Untersegment aufgezeichnet hat. Im Service-Diagramm enthalten dieKnoten beider Services Zeit- und Fehlerinformationen aus den Segmenten dieser Services, während dieEdge zwischen ihnen Informationen aus dem Untersegment des vorgelagerten Services enthält.
22
AWS X-Ray EntwicklerhandbuchService-Grafik
Beide Ansichten sind nützlich, da der nachgelagerte Service genau aufzeichnet, wann die Verarbeitungder Anfrage gestartet und beendet wurde, und der vorgelagerten Service zeichnet die Umlauflatenz auf,einschließlich der Zeit für die Übertragung der Latenz zwischen den beiden Services.
Service-GrafikX-Ray verwendet die Daten, die Ihre Anwendung sendet, um eine Service-Grafik zu erstellen. Jede AWS-Ressource, die Daten an X-Ray sendet, wird in der Graphik als Service dargestellt. Edges verbinden dieServices, die gemeinsam Anforderungen bearbeiten. Edges verbinden Clients mit Ihrer Anwendung undIhre Anwendung mit den Downstream-Services sowie den verwendeten Ressourcen.
Service-Namen
Der name eines Segments sollte mit dem Domänennamen oder logischen Namen des Servicesübereinstimmen, der das Segment generiert. Dies wird jedoch nicht erzwungen. Jede Anwendungmit Berechtigung für PutTraceSegments kann Segmente mit beliebigem Namen senden.
Eine Service-Graphik ist ein JSON-Dokument, das Informationen zu den Services und Ressourcen enthält,aus denen Ihre Anwendung besteht. Die X-Ray-Konsole verwendet die Service-Graphik zur Erstellungeiner Visualisierung oder Service-Übersicht.
23
AWS X-Ray EntwicklerhandbuchService-Grafik
Bei einer verteilten Anwendung kombiniert X-Ray Knoten aus allen Services, die Anforderungen mitderselben Ablaufverfolgungs-ID verarbeiten, in einer einzelnen Service-Graphik. Der erste Service, den dieAnforderung findet, fügt einen Nachverfolgungskopf (p. 26) hinzu, der zwischen dem Frontend und dendavon aufgerufenen Services verteilt wird.
Beispielsweise führt Scorekeep (p. 89) eine Web-API aus, die einen Mikroservice (eine AWS Lambda-Funktion) aufruft, die mithilfe einer Node.js-Bibliothek einen zufälligen Namen generiert. Das X-RaySDK for Java generiert die Ablaufverfolgungs-ID und fügt sie in Aufrufe an Lambda ein. Lambda sendetNachverfolgungsdaten und übergibt die Ablaufverfolgungs-ID an die Funktion. Das X-Ray SDK for Node.jsverwendet ebenfalls die Ablaufverfolgungs-ID zum Senden von Daten. Das Ergebnis ist, dass Knoten fürdie API, den Lambda-Service und die Lambda-Funktion sämtlich als separate (jedoch verbundene) Knotenin der Service-Übersicht dargestellt werden.
24
AWS X-Ray EntwicklerhandbuchAblaufverfolgungen
Service-Diagrammdaten werden 30 Tage aufbewahrt.
AblaufverfolgungenEine Ablaufverfolgungs-ID verfolgt den Weg einer Anforderung durch Ihre Anwendung. EineAblaufverfolgung sammelt alle von einer einzelnen Anforderung generierten Segmente. Diese Anforderungist in der Regel eine HTTP GET- oder POST-Anforderung, die durch einen Load Balancer läuft, auf IhrenAnwendungscode trifft und Downstream-Aufrufe an andere AWS-Services oder externe Web-APIs ausgibt.Der erste unterstützte Service, mit dem die HTTP-Anforderungen interagiert, fügt der Anforderung einenAblaufverfolgungs-ID-Kopf hinzu und verteilt ihn nachgeordnet weiter, um Latenz, Disposition und andereDaten der Anforderung nachzuverfolgen.
Service-Diagrammdaten werden 30 days aufbewahrt.
25
AWS X-Ray EntwicklerhandbuchSampling
SamplingUm sicherzustellen, dass die Ablaufverfolgung effizient ist und gleichzeitig ein repräsentatives Samplingder Anfragen, die Ihre Anwendung verarbeitet, erfolgt, wendet das X-Ray-SDK einen Sampling-Algorithmusan, um zu ermitteln, welche Anfragen verfolgt werden. Standardmäßig zeichnet das X-Ray-SDK die ersteAnfragen pro Sekunde und fünf Prozent aller weiteren Anfragen. auf.
Um zu vermeiden, dass bei den ersten Schritten Servicegebühren anfallen, ist die Standard-Samplingratekonservativ. Sie können durch Konfiguration des SDK die Standard-Samplingregeln ändern undverschiedene Samplingraten für verschiedene Routen konfigurieren, die Ihre Anwendung verarbeitet.
Sie können beispielsweise Samplings deaktivieren und alle Anfragen für Aufrufe verfolgen, die den Statusändern oder mit Benutzerkonten oder Transaktionen zu tun haben. Für große, schreibgeschützte Aufrufewie Abfragen im Hintergrund, Zustandsprüfungen oder Anschlusswartung können Sie eine niedrigeSamplingrate einstellen und erhalten dennoch genügend Daten, um auftretende Probleme zu erkennen.
Weitere Informationen zur Sampling-Konfiguration mit einem praktischen Beispiel finden Sie im Tutorial"Erste Schritte" (p. 8).
Ablaufverfolgungs-HeaderAlle Anforderungen werden bis zu einem konfigurierbaren Minimum verfolgt. Wenn dieses Minimumerreicht ist, wird ein Prozentsatz der Anforderungen nachverfolgt, um unnötige Kosten zu vermeiden. DieSamplingentscheidung und die Ablaufverfolgungs-ID werden HTTP-Anforderungen in Ablaufverfolgungs-Headern mit der Bezeichnung X-Amzn-Trace-Id hinzugefügt. Der erste X-Ray-integrierte Service, aufden die Anforderung trifft, fügt einen Nachverfolgungskopf hinzu, der von dem X-Ray-SDK gelesen und indie Antwort aufgenommen wird.
Example Ablaufverfolgungs-Header mit Stammablaufverfolgungs-ID und Samplingentscheidung
X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Sampled=1
Sicherheit des Ablaufverfolgungs-Headers
Ein Ablaufverfolgungs-Header kann vom X-Ray SDK, von einem AWS-Service oder derClient-Anforderung stammen. Ihre Anwendung kann X-Amzn-Trace-Id aus eingehendenAnforderungen entfernen, um Probleme zu vermeiden, die von Benutzern verursacht werden, dieihren Anforderungen Ablaufverfolgungs-IDs oder Samplingentscheidungen hinzufügen.
Der Ablaufverfolgungs-Header kann auch eine übergeordnete Segment-ID enthalten, wenn dieAnforderung von einer instrumentierten Anwendung stammte. Wenn Ihre Anwendung beispielsweise einenachgelagerte HTTP-Web-API mit einem instrumentierten HTTP-Client aufruft, fügt das X-Ray SDK dieID des Segments für die ursprüngliche Anforderung dem Ablaufverfolgungs-Header der nachgelagertenAnforderung hinzu. Eine instrumentierte Anwendung, die die nachgelagerte Anforderung verarbeitet, kanndie übergeordnete Segment-ID erfassen, um die beiden Anforderungen zu verbinden.
Example Ablaufverfolgungs-Header mit Stammablaufverfolgungs-ID, übergeordnete Segment-IDund Samplingentscheidung
X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1
26
AWS X-Ray EntwicklerhandbuchFilterausdrücke
FilterausdrückeSelbst mit Sampling generiert eine komplexe Anwendung eine Fülle von Daten. Die AWS X-Ray-Konsolebietet eine benutzerfreundliche Ansicht der Service-Grafik. Sie zeigt Status- und Leistungsinformationen,mit denen Sie Probleme und Möglichkeiten zur Optimierung Ihrer Anwendung ermitteln können. Fürdie erweiterte Ablaufverfolgung können Sie Details der Ablaufverfolgungen für einzelne Anforderungenanzeigen oder Filterausdrücke verwenden, um Ablaufverfolgungen in Bezug auf bestimmte Pfade oderBenutzer zu suchen.
Anmerkungen und MetadatenWenn Sie Ihre Anwendung instrumentieren, zeichnet das X-Ray-SDK Informationen zu eingehenden undausgehenden Anforderungen, den verwendeten AWS-Ressourcen und der Anwendung selbst auf. Siekönnen dem Segmentdokument weitere Informationen hinzufügen, wie etwa Anmerkungen und Metadaten.
Anmerkungen sind einfache Schlüssel-Wert-Paare, die zur Verwendung mit Filterausdrücken (p. 39)indiziert sind. Berücksichtigen Sie Anmerkungen, um Daten zur Gruppierung von Ablaufverfolgungen in derKonsole zu verwenden, oder wenn Sie die GetTraceSummaries-API aufrufen.
X-Ray indiziert bis zu 50 Anmerkungen pro Ablaufverfolgung.
Metadaten sind Schlüssel-Wert-Paare mit Werten aller Art (darunter Objekte und Listen), jedoch ohneIndizierung. Verwenden Sie Metadaten zum Aufzeichnen von Daten in der Ablaufverfolgung, die nicht zurAblaufsuche erforderlich sind.
Sie können Anmerkungen und Metadaten in den Segment- oder Untersegment-Details in der X-Ray-Konsole anzeigen.
27
AWS X-Ray EntwicklerhandbuchFehler und Ausnahmen
Fehler und AusnahmenX-Ray verfolgt Fehler, die in Ihrem Anwendungscode auftreten, und Fehler, die von nachgelagertenServices zurückgegeben werden. Fehler sind wie folgt kategorisiert.
• Error – Client-Fehler (400er-Fehler)• Fault – Server-Fehler (500er-Fehler)• Throttle – Ablehnungsfehler (Fehler 429 – Zu viele Anfragen)
Wenn eine Ausnahme auftritt, während Ihre Anwendung eine instrumentierte Anfrage verarbeitet, zeichnetdas X-Ray-SDK Details über die Ausnahme auf, einschließlich Stacktrace, sofern verfügbar. Sie könnenAusnahmen unter Segmentdetails (p. 35) in der X-Ray-Konsole anzeigen.
28
AWS X-Ray EntwicklerhandbuchAnzeigen der Service-Übersicht
AWS X-Ray-KonsoleMit der AWS X-Ray-Konsole können Sie Service-Übersichten und Ablaufverfolgungen für Anforderungenanzeigen, die von Ihren Anwendungen verarbeitet werden.
Die Service-Übersicht der Konsole ist eine visuelle Darstellung der JSON-Service-Grafik, die X-Ray ausden Ablaufverfolgungsdaten Ihrer Anwendungen generiert. Die Übersicht besteht aus Service-Knotenfür jede Anwendung in Ihrem Konto, das Anforderungen verarbeitet, aus vorgelagerten Knoten, die dieUrsprünge der Anforderungen repräsentieren, und aus nachgelagerten Service-Knoten, die Web-Servicesund Ressourcen darstellen, die von einer Anwendung während der Verarbeitung einer Anforderungverwendet werden.
Mithilfe von Filtern können Sie eine Service-Übersicht oder Ablaufverfolgungen für eine bestimmteAnforderung, einen Service, eine Verbindung zwischen zwei Services (eine Edge) oder Anforderungenanzeigen, die eine Bedingung erfüllen. X-Ray stellt Filterausdrücke zum Filtern von Anforderungen,Services und Edges basierend auf den Daten in Anforderungs-Headern, im Antwortstatus und in indiziertenFeldern der ursprünglichen Segmente bereit.
Anzeigen der Service-ÜbersichtZeigen Sie die Service-Übersicht in der X-Ray-Konsole an, um fehlerhafte Services, Verbindungen mithoher Latenz oder Ablaufverfolgungen für erfolglose Anforderungen zu identifizieren.
Zeigen Sie die Service-Übersicht wie folgt an:
1. Öffnen Sie die Service-Übersichtsseite der X-Ray-Konsole.
29
AWS X-Ray EntwicklerhandbuchAnzeigen der Service-Übersicht
2. Wählen Sie einen Service-Knoten, um Anforderungen für diesen Knoten anzuzeigen, oder eine Edgezwischen zwei Knoten, um Anforderungen anzuzeigen, die diese Verbindung passiert haben.
3. Verwenden Sie das Histogramm (p. 48), um Ablaufverfolgungen nach Dauer zu filtern, und wählenSie die Statuscodes aus, deren Ablaufverfolgungen Sie anzeigen möchten. Klicken Sie anschließendauf View traces, um die Ablaufverfolgungsliste mit angewendetem Filterausdruck zu öffnen.
Die Service-Karte zeigt den Zustand jedes Knotens an und markiert ihn farblich auf Grundlage desVerhältnisses zwischen erfolgreichen Anrufen und Fehlern:
30
AWS X-Ray EntwicklerhandbuchAnzeigen der Service-Übersicht
• Grün für erfolgreiche Anrufe• Rot für Server-Fehler (500er-Fehler)• Gelb für Client-Fehler (400er-Fehler)• Violett für Ablehnungsfehler („Fehler 429 – Zu viele Anfragen”)
In der Mitte jedes Knotens zeigt die Konsole die durchschnittliche Reaktionszeit und die Anzahl derwährend des ausgewählten Zeitraums pro Minute gesendeten Ablaufverfolgungen an.
Ist die Service-Übersicht groß, zeigt die Konsole standardmäßig eine verkleinerte Ansicht an. VerwendenSie die Steuerelemente auf dem Bildschirm oder die Maus, um das Bild zu vergrößern, zu verkleinern oderzu verschieben.
31
AWS X-Ray EntwicklerhandbuchAnzeigen von Ablaufverfolgungen
Steuerungen
•– Vergrößern und Verkleinern. Sie können auch mit dem Mausrad vergrößern oder
verkleinern.•
– Scrollen in der Service-Übersicht. Klicken und ziehen Sie, um einen Bildlauf mit der Mausdurchzuführen.
• – Fokussieren des ausgewählten Knotens oder der Edge in der Mitte der Übersicht.
Anzeigen von AblaufverfolgungenVerwenden Sie die Ablaufverfolgungsliste in der X-Ray-Konsole, um mithilfe der URL, des Codes oderanderer Daten aus der Ablaufverfolgungsübersicht nach Ablaufverfolgungen zu suchen.
So verwenden Sie die Ablaufverfolgungsliste
1. Öffnen Sie die Seite der Ablaufverfolgungen der X-Ray-Konsole.
32
AWS X-Ray EntwicklerhandbuchAnzeigen von Ablaufverfolgungen
2. Wählen Sie eine URL aus, um die Ablaufverfolgungsliste zu filtern.3. Wählen Sie eine Ablaufverfolgungs-ID aus, um die Timeline für eine Ablaufverfolgung anzuzeigen.
Die Timeline-Ansicht zeigt eine Hierarchie der Segmente und Untersegmente. Der erste Eintrag in der Listeist das Segment, das alle vom Service für eine einzelne Anforderung aufgezeichneten Daten darstellt.
Unter dem Segment befinden sich Untersegmente. In diesem Beispiel werden die von instrumentiertenAmazon DynamoDB-Clients aufgezeichneten Untersegmente sowie ein benutzerdefiniertes Untersegmentgezeigt.
33
AWS X-Ray EntwicklerhandbuchAnzeigen von Ablaufverfolgungen
Das X-Ray-SDK zeichnet Untersegmente bei der Verwendung eines instrumentierten AWS SDK-,HTTP- oder SQL-Clients für das Ausführen von Aufrufen bei externen Ressourcen automatisch auf. Siekönnen das SDK auch anweisen, benutzerdefinierte Untersegmente für alle Funktionen oder Codeblöckeaufzuzeichnen. Zusätzliche Untersegmente, die bei einem geöffneten benutzerdefinierten Untersegmentaufgezeichnet wurden, werden zu untergeordneten Elementen von benutzerdefinierten Untersegmenten.
Von der Timeline-Ansicht aus können Sie auch auf die Ablaufverfolgungsrohdaten zugreifen, die vonder Konsole zum Erstellen der Timeline verwendet werden. Wählen Sie Raw data aus, um das JSON-Dokument anzuzeigen, das alle Segmente und Untersegmente enthält, aus denen die Ablaufverfolgungbesteht.
34
AWS X-Ray EntwicklerhandbuchAnzeigen von Segmentdetails
Anzeigen von SegmentdetailsWählen Sie anhand der Ablaufverfolgungs-Timeline den Namen eines im Detail anzuzeigenden Segmentsaus. Overview zeigt Informationen zu Anforderung und Antwort an.
35
AWS X-Ray EntwicklerhandbuchAnzeigen von Segmentdetails
Die Registerkarte Resources für ein Segment zeigt Informationen zu den AWS-Ressourcen, auf denenIhre Anwendung ausgeführt wird, und zum X-Ray-SDK an. Verwenden Sie das Amazon EC2-, AWS ElasticBeanstalk- oder Amazon ECS-Plugin für das SDK, um Service-spezifische Ressourceninformationenaufzuzeichnen.
Die restlichen Registerkarten zeigen Annotations, Metadata und Exceptions an, die auf dem Segmentaufgezeichnet wurden. Ausnahmen werden automatisch erfasst, wenn sie von einer instrumentiertenAnforderung ausgelöst werden. Anmerkungen und Metadaten enthalten zusätzliche Informationen, die Siemithilfe der im SDK bereitgestellten Methoden aufzeichnen können.
36
AWS X-Ray EntwicklerhandbuchAnzeigen von Untersegmentdetails
Anzeigen von UntersegmentdetailsWählen Sie anhand der Ablaufverfolgungs-Timeline den Namen eines im Detail anzuzeigenden Segmentsaus. Für die mit instrumentierten Clients generierten Untersegmente enthält Overview Informationen zuAnforderung und Antwort aus der Sicht Ihrer Anwendung. Das folgende Beispiel zeigt ein Untersegmentvon einem instrumentierten Aufruf von DynamoDB.
37
AWS X-Ray EntwicklerhandbuchAnzeigen von Untersegmentdetails
Die Registerkarte Ressourcen für das Untersegment mit Details zur DynamoDB-Tabelle, zum aufgerufenenVorgang und zur Anforderungs-ID
Bei benutzerdefinierten Untersegmenten zeigt Overview den Namen des Untersegments an, den Sieangeben können, um den Code-Bereich oder die Funktion anzugeben, der oder die aufgezeichnet wird.
Mit benutzerdefinierten Untersegmenten können Sie Untersegmente von instrumentierten Clientsin Gruppen organisieren. Außerdem können Sie Metadaten und Anmerkungen für Untersegmenteaufzeichnen. Dies kann beim Debuggen von Funktionen hilfreich sein.
38
AWS X-Ray EntwicklerhandbuchFilterausdrücke
In diesem Beispiel zeichnet die Anwendung den Status jedes Game-Objekts auf, das in DynamoDBgespeichert wird, indem das Objekt einfach in die putMetadata-Methode des Untersegments übergebenwird. Das X-Ray-SDK serialisiert das Objekt in JSON und fügt es dem Segmentdokument hinzu.
Suchen nach Ablaufverfolgungen in der AWS X-Ray-Konsole mit Filterausdrücken
Wenn Sie einen Zeitraum auswählen, für den Ablaufverfolgungen in der X-Ray-Konsole angezeigt werdensollen, erhalten Sie möglicherweise mehr Ergebnisse, als die Konsole anzeigen kann. In der rechtenoberen Ecke der Konsole wird die Anzahl der gescannten Ablaufverfolgungen angezeigt und Sie könnenablesen, ob weitere Ablaufverfolgungen verfügbar sind. Um die Ergebnisse auf die Ablaufverfolgungen zubeschränken, die Sie suchen, verwenden Sie einen Filterausdruck.
39
AWS X-Ray EntwicklerhandbuchFilterausdrücke
Wenn Sie einen Knoten in der Service-Übersicht auswählen (p. 29), erzeugt die Konsole einenFilterausdruck basierend auf der Service-Übersicht des Knotens und auf den vorhandenen Fehlertypenbasierend auf Ihrer Auswahl. Um Ablaufverfolgungen zu finden, die Leistungsprobleme zeigen oder zubestimmten Anfragen gehören, können Sie den von der Konsole bereitgestellten Ausdruck anpassen odereinen eigenen erstellen. Wenn Sie mit dem X-Ray-SDK Anmerkungen hinzufügen, können Sie auch nachder Präsenz eines Anmerkungsschlüssels oder nach dem Wert eines Schlüssels filtern.
Note
Wenn Sie einen relativen Zeitraum in der Service-Übersicht auswählen, wandelt die Konsolediesen in eine absolute Start- und Endzeit um, wenn Sie einen Knoten auswählen. Umsicherzustellen, dass die Ablaufverfolgungen für den Knoten in den Suchergebnissen angezeigtwerden, und um das Scannen von Zeiträumen zu vermeiden, in denen der Knoten nicht aktivwar, werden nur Zeiten in den Zeitraum einbezogen, zu denen der Knoten Ablaufverfolgungengesendet hat. Wenn die Suche relativ zur aktuellen Zeit durchgeführt werden soll, können Siewieder zum relativen Zeitraum auf der Seite der Ablaufverfolgungen wechseln und einen erneutenScan durchführen.
Wenn immer noch mehr Ergebnisse vorliegen, als in der Konsole angezeigt werden können, gibtdie Konsole die Anzahl der Ablaufverfolgungen an, die die Kriterien erfüllt haben, sowie die Anzahlder gescannten Ablaufverfolgungen. Der angezeigte Prozentsatz entspricht dem Prozentsatz desausgewählten Zeitraums, der gescannt wurde. Grenzen Sie Ihren Filterausdruck weiter ein oder wählenSie einen kürzeren Zeitraum aus, um sicherzustellen, dass alle passenden Ablaufverfolgungen in denErgebnissen angezeigt werden.
Die Konsole beginnt den Scan am Ende des Zeitraums und arbeitet sich nach vorne durch, um Ihnendie aktuellsten Ergebnisse zuerst anzuzeigen. Wenn viele Ablaufverfolgungen vorliegen, aber nurwenige Ergebnisse, teilt die Konsole den Zeitraum in Abschnitte ein und scannt diese parallel. DerFortschrittsbalken zeigt die Abschnitte des Zeitraums an, die gescannt wurden.
40
AWS X-Ray EntwicklerhandbuchSyntax für Filterausdrücke
Abschnitte• Syntax für Filterausdrücke (p. 41)• Boolesche Schlüsselwörter (p. 42)• Anzahl von Schlüsselwörtern (p. 42)• Schlüsselwörter für Zeichenfolge (p. 43)• Komplexe Schlüsselwörter (p. 44)• Die ID-Funktion (p. 45)
Syntax für FilterausdrückeFilterausdrücke können ein Schlüsselwort, einen unären oder binären Operator und einen Wert für denVergleich enthalten.
keyword operator value
Für verschiedene Arten von Schlüsselwörtern sich unterschiedliche Operatoren erhältlich. Beispielsweiseist responsetime ein Zahlenschlüsselwort, das mit auf Zahlen bezüglichen Operatoren verglichen werdenkann.
Example Anforderungen, bei denen die Reaktionszeit mehr als 5 Sekunden betrug
responsetime > 5
Sie können mehrere Ausdrücke mit den Operatoren AND und OR zu einem zusammengesetzten Ausdruckverbinden.
Example Anfragen, bei denen die gesamte Dauer 5 bis 8 Sekunden betrug
duration >= 5 AND duration <= 8
Einfache Schlüsselwörter und Operatoren finden nur Probleme auf der Ebene der Ablaufverfolgungen.Wenn ein Fehler dahinter auftritt, von Ihrer Anwendung jedoch berücksichtigt und nicht an den Benutzerzurückgegeben wird, findet eine Suche nach error diesen Fehler nicht.
41
AWS X-Ray EntwicklerhandbuchBoolesche Schlüsselwörter
Zum Finden von Ablaufverfolgungen mit nachgeordneten Fehlern können Sie komplexeSchlüsselwörter (p. 44) service() und edge() verwenden. Diese Schlüsselwörter ermöglichen dieAnwendung eines Filterausdrucks auf alle nachgeordneten Knoten, einen einzelnen nachgeordnetenKnoten oder eine Edge zwischen zwei Knoten. Für noch mehr Granularität können Sie Services und Edgesmit der id()-Funktion (p. 45) nach Typ filtern.
Boolesche SchlüsselwörterBoolesche Schlüsselwörter sind entweder „true“ oder „false“. Verwenden Sie diese Schlüsselwörter, umAblaufverfolgungen zu finden, die zu Fehlern geführt haben.
Boolesche Schlüsselwörter
• ok – Der Antwortstatuscode lautete "2XX Success".• error – Der Antwortstatuscode lautete "4XX Client Error".• throttle – Antwortstatuscode: 429 Zu viele Anfragen.• fault – Der Antwortstatuscode lautete "5XX Server Error".• partial – Die Anforderung enthält unvollständige Segmente.
Boolesche Operatoren finden Segmente, bei denen der angegebene Schlüssel true oder false ist.
Boolesche Operatoren
• kein – Der Ausdruck ist wahr, wenn das Schlüsselwort wahr ist.• ! – Der Ausdruck ist wahr, wenn das Schlüsselwort falsch ist.• =,!= – Vergleich des Wertes des Schlüsselworts mit der Zeichenfolge true oder false. Fungiert wie
die anderen Operatoren, jedoch deutlicher.
Example Der Reaktionsstatus ist 2XX OK
ok
Example Der Reaktionsstatus ist nicht 2XX OK
!ok
Example Der Reaktionsstatus ist nicht 2XX OK
ok = false
Anzahl von SchlüsselwörternMit Zahlenschlüsselwörtern können Sie nach Anforderungen mit einem bestimmten Reaktionszeit, Daueroder einem besonderen Reaktionsstatus suchen.
Anzahl von Schlüsselwörtern
• responsetime – Zeit, die der Server benötigte, um eine Antwort zu senden.• duration – Gesamtdauer der Anforderung, einschließlich aller nachgelagerten Aufrufe.
42
AWS X-Ray EntwicklerhandbuchSchlüsselwörter für Zeichenfolge
• http.status – Antwortstatuscode.
Zahlenschlüsselwörter verwenden Standard-Operatoren für Gleichheit und Vergleichsfunktionen.
Zahlenoperatoren
• =,!= – Das Schlüsselwort ist gleich oder nicht gleich einem Zahlenwert.• <,<=, >,>= – Das Schlüsselwort ist kleiner oder größer als ein Zahlenwert.
Example Der Reaktionsstatus ist nicht 200 OK
http.status != 200
Example Anforderungen, bei denen die gesamte Dauer 5 bis 8 Sekunden betrug
duration >= 5 AND duration <= 8
Example Anforderungen, die in weniger als 3 Sekunden erfolgreich abgeschlossen wurden,einschließlich aller nachgelagerten Aufrufe
ok !partial duration <3
Schlüsselwörter für ZeichenfolgeMit Zeichenfolgen-Schlüsselwörtern können Sie Ablaufverfolgungen mit bestimmtem Text in denAnforderungsköpfen bzw. Benutzer-IDs finden.
Schlüsselwörter für Zeichenfolge
• http.url – Anforderungs-URL.• http.method – Anforderungsmethode.• http.useragent – Die Zeichenfolge des Benutzeragent wird angefordert.• http.clientip – IP-Adresse des Anforderers.• user – Wert des Benutzerfelds für jedes Segment in der Ablaufverfolgung.
Zeichenfolgenoperatoren finden Werte, die identisch mit bestimmtem Text sind oder diesen enthalten.Werte müssen stets in Anführungszeichen angegeben werden.
Zeichenfolgen-Operatoren
• =,!= – Das Schlüsselwort ist gleich oder nicht gleich einem Zahlenwert.• CONTAINS – Das Schlüsselwort enthält eine bestimmte Zeichenfolge.• BEGINSWITH ,ENDSWITH – Das Schlüsselwort beginnt oder endet mit einer bestimmten Zeichenfolge.
Example Benutzerfilter
http.url CONTAINS "/api/game/"
43
AWS X-Ray EntwicklerhandbuchKomplexe Schlüsselwörter
Um zu testen, ob ein Feld in einer Ablaufverfolgung vorhanden ist (unabhängig von seinem Wert), prüfenSie, ob es die leere Zeichenfolge enthält.
Example Benutzerfilter
Alle Ablaufverfolgungen mit Benutzer-IDs suchen.
user CONTAINS ""
Komplexe SchlüsselwörterMit komplexen Schlüsselwörtern finden Sie Anfragen basierend auf dem Service-Namen, Edge-Namen oder Anmerkungswert. Für Services und Edges können Sie einen zusätzlichen Filterausdruckangeben, der sich auf den Service oder die Edge bezieht. Für Anmerkungen können Sie nach demWert einer Anmerkung mit einem bestimmten Schlüssel filtern und dafür boolesche Werte, Zahlen oderZeichenfolgenoperatoren verwenden.
Komplexe Schlüsselwörter
• service(name) {filter} – Service mit dem Namen Name. Optionale geschweifte Klammern könneneinen Filterausdruck enthalten, der für vom Service erstellte Segmente gilt.
• edge(name) {filter} – Verbindung zwischen den Services Quelle und Ziel. Optionalegeschweifte Klammern können einen Filterausdruck enthalten, der für Segmente in dieser Verbindunggilt.
• annotation.key – Wert der Anmerkung mit dem Feld Schlüssel. Der Wert einer Anmerkung kannein boolescher Wert, eine Zahl oder eine Zeichenfolge sein, Sie können daher alle Vergleichsoperatorendieser Typen verwenden. Sie können dieses Schlüsselwort in Kombination mit den Schlüsselwörternservice oder edge verwenden.
Verwenden Sie das Service-Schlüsselwort, um Ablaufverfolgungen für Anforderungen zu finden, die aufeinen bestimmten Knoten in Ihrer Service-Übersicht gestoßen sind.
Example Servicefilter
Anforderungen mit einem Aufruf an api.example.com mit einem Fehler (Fehler der Serie 500).
service("api.example.com") { fault }
Sie können den Servicenahmen ausschließen, um einen Filterausdruck auf alle Knoten in Ihrer Service-Übersicht anzuwenden.
Example Servicefilter
Anforderungen, die einen Fehler irgendwo in Ihrer Service-Übersicht verursacht haben.
service() { fault }
Das Edge-Schlüsselwort wendet einen Filterausdruck auf eine Verbindung zwischen zwei Knoten an.
Example Edge-Filter
Anforderung, bei der der Service api.example.com einen Aufruf an backend.example.comvorgenommen hat, der mit einem Fehler fehlgeschlagen ist.
44
AWS X-Ray EntwicklerhandbuchDie ID-Funktion
edge("api.example.com", "backend.example.com") { error }
Sie können auch den !-Operator mit Service- und Edge-Schlüsselwörtern verwenden, um einen Serviceoder eine Edge aus den Ergebnissen eines anderen Filterausdrucks auszuschließen.
Example Service- und Anforderungsfilter
Anforderung, bei der die URL mit http://api.example.com/ beginnt und /v2/ enthält, aber keinService mit dem Namen api.example.com erreicht wird.
http.url BEGINSWITH "http://api.example.com/" AND http.url CONTAINS "/v2/" AND !service("api.example.com")
Verwenden Sie für Anmerkungen die Vergleichsoperatoren, die der Art des Werts entsprechen.
Example Anmerkung mit Zeichenfolgenwert
Anforderungen mit einer Anmerkung mit dem Namen gameid und dem Zeichenfolgenwert "817DL6VO".
annotation.gameid = "817DL6VO"
Example Anmerkung mit Zahlenwert
Anforderungen mit einer Anmerkung mit einem numerischen Wert größer als 29.
annotation.age > 29
Die ID-FunktionWenn Sie einen Service-Namen für die Schlüsselwörter service oder edge bereitstellen, erhalten SieErgebnisse für alle Knoten mit diesem Namen. Für eine präzisere Filterung können Sie mit der id-Funktionzusätzlich zu einem Namen einen Servicetyp angeben, um zwischen Knoten mit demselben Namen zudifferenzieren.
id(name: "service-name", type:"service::type")
Sie können die id-Funktion anstelle eines Service-Namens in Service- und Edge-Filtern verwenden.
service(id(name: "service-name", type:"service::type")) { filter }
edge(id(name: "service-one", type:"service::type"), id(name: "service-two", type:"service::type")) { filter }
Beispielsweise enthält die Scorekeep-Beispielanwendung (p. 89) eine AWS Lambda-Funktion mit derBezeichnung random-name. Dadurch werden zwei Knoten in der Service-Übersicht erstellt, einer für denAufruf der Funktion und einer für den Lambda-Service.
45
AWS X-Ray EntwicklerhandbuchDie ID-Funktion
Die zwei Knoten haben denselben Namen, aber unterschiedliche Arten. Ein Standard-Servicefilter findetAblaufnachverfolgungen für beide.
Example Servicefilter
Anforderungen, die einen Fehler bei einem Service mit dem Namen random-name enthalten.
service("random-name") { error }
Verwenden Sie die id-Funktion zur Eingrenzung der Suche auf Fehler bei der Funktion selbst, unterAusschluss von Fehlern vom Service.
Example Servicefilter mit id-Funktion
Anforderungen, die einen Fehler bei einem Service mit dem Namen random-name und dem TypAWS::Lambda::Function enthalten.
service(id(name: "random-name", type: "AWS::Lambda::Function")) { error }
Sie können den Namen auch vollständig ausschließen, um Knoten nach Typ zu suchen.
Example Servicefilter mit id()-Funktion
Anforderungen, die einen Fehler bei einem Service des Typs AWS::Lambda::Function enthalten.
service(id(type: "AWS::Lambda::Function")) { error }
46
AWS X-Ray EntwicklerhandbuchErstellen von Deep-Links
Erstellen von Deep-LinksSie können mit Routen und Abfragen Deep-Links in bestimmte Ablaufverfolgungen oder gefilterte Ansichtenvon Ablaufverfolgungen und der Service-Übersicht erstellen.
Konsolenseiten
• Begrüßungsseite – xray/home#/welcome• Erste Schritte – xray/home#/getting-started• Service-Übersicht – xray/home#/service-map• Ablaufverfolgungen – xray/home#/traces
AblaufverfolgungenSie können Links für Timeline-, Roh- und Kartenansichten einzelner Ablaufverfolgungen generieren.
Ablaufverfolgungs-Timeline – xray/home#/traces/trace-id
Rohe Ablaufverfolgungsdaten – xray/home#/traces/trace-id/raw
Example Rohe Ablaufverfolgungsdaten
https://console.aws.amazon.com/xray/home#/traces/1-57f5498f-d91047849216d0f2ea3b6442/raw
FilterausdrückeLink zu einer gefilterten Liste von Ablaufverfolgungsdaten.
Gefilterte Ansicht von Ablaufverfolgungsdaten – xray/home#/traces?filter=filter-expression
Example Filterausdruck
https://console.aws.amazon.com/xray/home#/traces?filter=service("api.amazon.com") { fault = true OR responsetime > 2.5 } AND annotation.foo = "bar"
Example Filterausdruck (URL-codiert)
https://console.aws.amazon.com/xray/home#/traces?filter=service(%22api.amazon.com%22)%20%7B%20fault%20%3D%20true%20OR%20responsetime%20%3E%202.5%20%7D%20AND%20annotation.foo%20%3D%20%22bar%22
Weitere Informationen zu Filterausdrücken finden Sie unter Suchen nach Ablaufverfolgungen in der AWSX-Ray-Konsole mit Filterausdrücken (p. 39).
ZeitraumGeben Sie einen Zeitraum oder Start- und Endzeit im ISO8601-Format an. Zeitbereiche werden in UTCangegeben und können bis zu 6 hours lang sein.
Zeitdauer – xray/home#/page?timeRange=range-in-minutes
47
AWS X-Ray EntwicklerhandbuchRegion
Example Servicekarte der letzten Stunde
https://console.aws.amazon.com/xray/home#/service-map?timeRange=PT1H
Start- und Endzeit – xray/home#/page?timeRange=start~end
Example Zeitbereich auf die Sekunde genau
https://console.aws.amazon.com/xray/home#/traces?timeRange=2018-6-01T16:00:00~2018-6-01T22:00:00
Example Zeitbereich auf die Minute genau
https://console.aws.amazon.com/xray/home#/traces?timeRange=2018-6-01T16:00~2018-6-01T22:00
RegionGeben Sie eine Region an, um Seiten in dieser Region zu verknüpfen. Wenn Sie keine Region angeben,führt Sie die Konsole zur zuletzt besuchten Region.
Region – xray/home?region=region#/page
Example Service-Übersicht in Oregon (us-west-2)
https://console.aws.amazon.com/xray/home?region=us-west-2#/service-map
Wenn Sie eine Region mit anderen Abfrageparametern einschließen, steht die Regionenabfrage vor demHash-Zeichen, und die X-Ray-spezifischen Abfragen kommen nach dem Namen der Seite.
Example Service-Übersicht für die letzte Stunde in Oregon (us-west-2)
https://console.aws.amazon.com/xray/home?region=us-west-2#/service-map?timeRange=PT1H
KombiniertExample Neueste Ablaufverfolgungen mit Dauerfilter
https://console.aws.amazon.com/xray/home#/traces?timeRange=PT15M&filter=duration%20%3E%3D%205%20AND%20duration%20%3C%3D%208
Ausgangs-
• Seite – Ablaufverfolgungen• Zeitraum – Letzte 15 Minuten• Filter – Dauer >= 5 UND Dauer <= 8
Verwendung von Latenz-Histogrammen in der AWSX-Ray-Konsole–
Wenn Sie einen Knoten oder eine Edge in einer AWS X-Ray-Service-Übersicht (p. 29) auswählen, zeigtdie X-Ray-Konsole ein Histogramm der Latenzverteilung. Als Latenz wird die Zeit zwischen dem Start und
48
AWS X-Ray EntwicklerhandbuchHistogramme
dem Abschluss einer Anforderung bezeichnet. Ein Histogramm zeigt eine Verteilung von Latenzen. Er zeigtDauer auf der x-Achse und den Prozentsatz der Anforderungen, die jeder Dauer entsprechen, auf der y-Achse.
Dieses Histogramm zeigt einen Service, der die meisten Anfragen in weniger als 300 ms abschließt. Einkleiner Prozentsatz von Anfragen dauert 2 Sekunden, und einige Ausreißer nehmen noch mehr Zeit inAnspruch.
Service-Histogramme und Edge-Histogramme bieten eine visuelle Darstellung der Latenz aus der Sichteines Services oder eines Anforderers.
• Wählen Sie einen Service-Knoten, indem Sie auf den Kreis klicken. X-Ray zeigt ein Histogramm für dieAnforderungen an, die der Service berücksichtigt. Die Latenzen sind die, die der Service aufgezeichnethat; dazu gehört nicht die Netzwerklatenz zwischen dem Service und dem Auftraggeber.
• Wählen Sie eine Edge, indem Sie auf die Zeile oder Pfeilspitze der Edge zwischen zwei Services klicken.X-Ray zeigt ein Histogramm für Anfragen des Auftraggebers, die vom Downstream-Service bearbeitetwurden. Die Latenzen sind die vom Auftraggeber aufgezeichneten; dazu gehört die Latenz in derNetzwerkverbindung zwischen den beiden Services.
Zur Interpretation des Panel-Histogramms mit den Servicedetails können Sie die Werte betrachten, dieam stärksten von den meisten Werten im Histogramm abweichen. Diese Ausreißer sind als Spitzen imHistogramm zu sehen und Sie können die Ablaufverfolgungen für einen bestimmten Bereich untersuchen,um zu sehen, was vor sich geht.
Wählen Sie zur Anzeige nach Latenz gefilterter Ablaufverfolgungen einen Bereich im Histogramm aus.Klicken Sie an die Stelle, an der die Auswahl beginnen soll, und ziehen Sie von links nach rechts, um einenBereich von Latenzen hervorzuheben, der in den Ablaufverfolgungsfilter eingeschlossen werden soll.
Nach Auswahl eines Bereichs können Sie den Zoom wählen, um nur diesen Teil des Histogrammsanzuzeigen, und Ihre Auswahl verfeinern.
49
AWS X-Ray EntwicklerhandbuchVerschlüsselung
Sobald Sie den Fokus auf den interessierenden Bereich gesetzt haben, wählen Sie Ablaufverfolgungenanzeigen.
Konfigurieren von Verschlüsselungseinstellungen inder AWS X-Ray-Konsole
AWS X-Ray verschlüsselt immer Spuren und zugehörige ruhende Daten. Wenn SieVerschlüsselungsschlüssel für die Compliance oder aufgrund interner Anforderungen prüfen unddeaktivieren müssen, können Sie X-Ray so konfigurieren, dass es einen AWS Key ManagementService (AWS KMS)-Kunden-Master-Schlüssels (CMK, Customer Master Key) verwendet, um Daten zuverschlüsseln.
X-Ray stellt einen von AWS verwalteten CMK namens aws/xray bereit. Verwenden Sie diesen Schlüssel,wenn Sie die Schlüsselverwendung in AWS CloudTrail überprüfen möchten, den eigentlichen Schlüsselaber nicht verwalten müssen. Wenn Sie den Zugriff auf den Schlüssel verwalten oder die Schlüsselrotationkonfigurieren müssen, können Sie einen vom Kunden verwalteten CMK erstellen.
So konfigurieren Sie X-Ray für die Verwendung eines CMK für die Verschlüsselung
1. Öffnen Sie die X-Ray-Konsole.2. Wählen Sie Encryption (Verschlüsselung) aus.3. Wählen Sie Use a customer master key (Verwenden eines Kundenmasterschlüssels).4. Wählen Sie einen Schlüssel aus dem Dropdown-Menü:
• aws/xray – Verwendung des von AWS-verwalteten CMK.• key alias (Schlüsselalias) – Verwendung eines benutzerdefinierten verwalteten CMK in Ihrem Konto.• Manually enter a key ARN (Manuelle Eingabe eines Schlüssel-ARN) – Verwendung eines
benutzerdefinierten verwalteten CMK in einem anderen Konto. Geben Sie den vollständigenAmazon-Ressourcennamen (ARN) des Schlüssels in das entsprechende Feld ein.
50
AWS X-Ray EntwicklerhandbuchVerschlüsselung
5. Wählen Sie Apply aus.
Wenn Sie Verschlüsselungseinstellungen ändern, benötigt X-Ray einige Zeit zum Generieren undWeitergeben von Datenschlüsseln. Während der neue Schlüssel verarbeitet wird, kann X-Ray Daten miteiner Kombination aus den neuen und alten Einstellungen verschlüsseln. Vorhandene Daten werden nichterneut verschlüsselt, wenn Sie Verschlüsselungseinstellungen ändern.
Note
AWS KMS verlangt Gebühren, wenn X-Ray einen CMK zum Verschlüsseln oder Entschlüsselnvon Spurdaten verwendet.
• Standardverschlüsselung – Kostenlos.• Von AWS verwalteter CMK – Zahlung für die Schlüsselnutzung.• Vom Kunden verwalteter CMK – Zahlung für die Speicherung und Nutzung des Schlüssels.
Weitere Informationen finden Sie unter AWS Key Management Service – Preise.
Wenn X-Ray nicht auf Ihren Verschlüsselungsschlüssel zugreifen kann, speichert es keine Daten mehr.Dies kann der Fall sein, wenn Ihr Benutzer den Zugriff auf den CMK verliert, oder wenn Sie einen Schlüsseldeaktivieren, der gerade verwendet wird. Wenn dies geschieht, zeigt X-Ray eine Benachrichtigung in derNavigationsleiste an.
Weitere Informationen zum Konfigurieren von Verschlüsselungseinstellungen mit der X-Ray-API finden Sieunter Konfigurieren von AWS X-Ray-Verschlüsselungseinstellungen (p. 67).
51
AWS X-Ray EntwicklerhandbuchPraktische Anleitung
AWS X-Ray-APIDie X-Ray-API bietet Zugriff auf alle X-Ray-Funktionen über das AWS-SDK, AWS Command Line Interfaceoder direkt über HTTPS. Die X-Ray-API-Referenz dokumentiert Eingabeparameter für jede API-Aktionsowie die Felder und Datentypen, die zurückgegeben werden.
Sie können das AWS-SDK für die Entwicklung von Programmen einsetzen, die die X-Ray-API verwenden.Die X-Ray-Konsole und der X-Ray-Daemon verwenden beide das AWS-SDK für die Kommunikation mit X-Ray. Das AWS-SDK verfügt für jede Sprache über ein Referenzdokument für Schulungen und Methoden,die X-Ray-API-Funktionen und -Typen zugeordnet sind.
AWS-SDK-Referenzen
• Java – AWS SDK for Java• JavaScript – AWS SDK for JavaScript• .NET – AWS SDK for .NET• Ruby – AWS SDK for Ruby• Go – AWS SDK for Go• PHP – AWS SDK for PHP• Python – AWS SDK for Python (Boto)
AWS Command Line Interface ist ein Befehlszeilen-Tool, das SDK for Python zum Aufrufen von AWS-APIs verwendet. Zum Kennenlernen der AWS-API bietet AWS CLI eine einfache Möglichkeit, um sich mitden verfügbaren Parametern vertraut zu machen und die Service-Ausgabe im JSON- oder Textformatanzuzeigen.
In der AWS CLI-Befehlsreferenz finden Sie weitere Informationen über aws xray Unterbefehle.
Themen• Verwenden der AWS X-Ray-API mit der AWS CLI (p. 52)• Senden von Ablaufverfolgungsdaten an AWS X-Ray (p. 55)• Abrufen von aus AWS X-Ray (p. 59)• Konfigurieren von AWS X-Ray-Verschlüsselungseinstellungen (p. 67)• Protokollieren von X-Ray-API-Aufrufen mit AWS CloudTrail (p. 68)• Nachverfolgen von Änderungen an der X-Ray-Verschlüsselungskonfiguration mit AWS
Config (p. 69)• AWS X-Ray Segmentdokumente (p. 72)
Verwenden der AWS X-Ray-API mit der AWS CLIMit der AWS CLI können Sie direkt auf die X-Ray-Services zugreifen und die gleichen APIs verwenden, diedie X-Ray-Konsole zum Abrufen des Service-Diagramms und der Raw-Ablaufverfolgungsdaten verwendet.Die Beispielanwendung umfasst Skripts, die veranschaulichen, wie Sie diese APIs mit der AWS CLIverwenden.
VoraussetzungenIn diesem Tutorial werden die Scorekeep-Beispielanwendung und darin enthaltene Skripts verwendet, umAblaufverfolgungsdaten und eine Service-Übersicht zu erstellen. Folgen Sie den Anweisungen im Tutorial"Erste Schritte" (p. 8), um die Anwendung zu starten.
52
AWS X-Ray EntwicklerhandbuchGenerieren von Ablaufverfolgungsdaten
In diesem Tutorial wird die AWS CLI verwendet, um die einfache Nutzung der X-Ray-API zuveranschaulichen. Die AWS CLI, die für Windows, Linux und OS-X verfügbar ist, bietet Befehlszeilenzugriffauf die öffentlichen APIs für alle AWS-Services.
Die enthaltenen Skripts zum Testen der Beispielanwendung verwenden cURL, um Datenverkehr zur API zusenden, und jq zum Analysieren der Ausgabe. Sie können die ausführbare Datei jq von stedolan.github.iound die ausführbare Datei curl von https://curl.haxx.se/download.html herunterladen. Die meisten Linux-und OS X-Installationen umfassen cURL.
Generieren von AblaufverfolgungsdatenDie Web-App generiert weiterhin alle paar Sekunden Datenverkehr zur API, während das Spielfortgesetzt wird, es wird aber nur eine Art der Anforderung generiert. Verwenden Sie das Skript test-api.sh, um End-to-End-Szenarien auszuführen und um während der Prüfung der API vielfältigereAblaufverfolgungsdaten zu generieren.
So verwenden Sie das test-api.sh-Skript
1. Open the Elastic Beanstalk console.2. Navigate to the management console for your environment.3. Kopieren Sie die Umgebungs-URL aus dem Header der Seite.4. Öffnen Sie bin/test-api.sh und ersetzen Sie den Wert für die API mit der URL Ihrer Umgebung.
#!/bin/bashAPI=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com
5. Führen Sie das Skript aus, um Datenverkehr zur API zu generieren.
~/debugger-tutorial$ ./bin/test-api.shCreating users,session,game,configuring game,playing game,ending game,game complete.{"id":"MTBP8BAS","session":"HUF6IT64","name":"tic-tac-toe-test","users":["QFF3HBGM","KL6JR98D"],"rules":"102","startTime":1476314241,"endTime":1476314245,"states":["JQVLEOM2","D67QLPIC","VF9BM9NC","OEAA6GK9","2A705O73","1U2LFTLJ","HUKIDD70","BAN1C8FI","G3UDJTUF","AB70HVEV"],"moves":["BS8F8LQ","4MTTSPKP","463OETES","SVEBCL3N","N7CQ1GHP","O84ONEPD","EG4BPROQ","V4BLIDJ3","9RL3NPMV"]}
Verwenden der X-Ray-APIDie AWS CLI bietet Befehle für alle API-Aktionen, die X-Ray zur Verfügung stellt, einschließlichGetServiceGraph und GetTraceSummaries. Weitere Informationen über alle unterstützten Aktionenund die von ihnen verwendeten Datentypen finden Sie in der AWS X-Ray-API-Referenz.
Example bin/service-graph.sh
EPOCH=$(date +%s)aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
Das Skript ruft ein Service-Diagramm für die letzten 10 Minuten ab.
~/eb-java-scorekeep$ ./bin/service-graph.sh | less{
53
AWS X-Ray EntwicklerhandbuchVerwenden der X-Ray-API
"StartTime": 1479068648.0, "Services": [ { "StartTime": 1479068648.0, "ReferenceId": 0, "State": "unknown", "EndTime": 1479068651.0, "Type": "client", "Edges": [ { "StartTime": 1479068648.0, "ReferenceId": 1, "SummaryStatistics": { "ErrorStatistics": { "ThrottleCount": 0, "TotalCount": 0, "OtherCount": 0 }, "FaultStatistics": { "TotalCount": 0, "OtherCount": 0 }, "TotalCount": 2, "OkCount": 2, "TotalResponseTime": 0.054000139236450195 }, "EndTime": 1479068651.0, "Aliases": [] } ] }, { "StartTime": 1479068648.0, "Names": [ "scorekeep.elasticbeanstalk.com" ], "ReferenceId": 1, "State": "active", "EndTime": 1479068651.0, "Root": true, "Name": "scorekeep.elasticbeanstalk.com",...
Example bin/trace-urls.sh
EPOCH=$(date +%s)aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Http.HttpURL'
Das Skript ruft die URLs der Ablaufverfolgungen ab, die ein bis zwei Minuten zuvor generiert wurden.
~/eb-java-scorekeep$ ./bin/trace-urls.sh[ "http://scorekeep.elasticbeanstalk.com/api/game/6Q0UE1DG/5FGLM9U3/endtime/1479069438", "http://scorekeep.elasticbeanstalk.com/api/session/KH4341QH", "http://scorekeep.elasticbeanstalk.com/api/game/GLQBJ3K5/153AHDIA", "http://scorekeep.elasticbeanstalk.com/api/game/VPDL672J/G2V41HM6/endtime/1479069466"]
Example bin/full-traces.sh
EPOCH=$(date +%s)
54
AWS X-Ray EntwicklerhandbuchBereinigen
TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text)aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]'
Das Skript ruft die vollständigen Ablaufverfolgungsdaten ab, die ein bis zwei Minuten zuvor generiertwurden.
~/eb-java-scorekeep$ ./bin/full-traces.sh | less[ { "Segments": [ { "Id": "3f212bc237bafd5d", "Document": "{\"id\":\"3f212bc237bafd5d\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242459E9,\"end_time\":1.479072242477E9,\"parent_id\":\"72a08dcf87991ca9\",\"http\":{\"response\":{\"content_length\":60,\"status\":200}},\"inferred\":true,\"aws\":{\"consistent_read\":false,\"table_name\":\"scorekeep-session-xray\",\"operation\":\"GetItem\",\"request_id\":\"QAKE0S8DD0LJM245KAOPMA746BVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-session-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}" }, { "Id": "309e355f1148347f", "Document": "{\"id\":\"309e355f1148347f\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242477E9,\"end_time\":1.479072242494E9,\"parent_id\":\"37f14ef837f00022\",\"http\":{\"response\":{\"content_length\":606,\"status\":200}},\"inferred\":true,\"aws\":{\"table_name\":\"scorekeep-game-xray\",\"operation\":\"UpdateItem\",\"request_id\":\"388GEROC4PCA6D59ED3CTI5EEJVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-game-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}" } ], "Id": "1-5828d9f2-a90669393f4343211bc1cf75", "Duration": 0.05099987983703613 }...
BereinigenBeenden Sie Ihre Elastic Beanstalk-Umgebung, um die Amazon EC2 Instances, DynamoDB-Tabellen undandere Ressourcen zu schließen.
Beenden Sie Ihre Elastic Beanstalk-Umgebung wie folgt:
1. Open the Elastic Beanstalk console.2. Navigate to the management console for your environment.3. Wählen Sie Actions.4. Wählen Sie Terminate Environment.5. Wähen Sie Terminate.
Die Ablaufverfolgungsdaten werden nach 30 days in X-Ray automatisch gelöscht.
Senden von Ablaufverfolgungsdaten an AWS X-RaySie können Ablaufverfolgungsdaten in Form von Segmentdokumenten an X-Ray senden. EinSegmentdokument ist eine JSON-formatierte Zeichenfolge mit Informationen über die Arbeit, die Ihre
55
AWS X-Ray EntwicklerhandbuchSenden von Daten
Anwendung im Dienste einer Anforderung verrichtet. Ihre Anwendung kann Daten über die Arbeit, diesie selbst in Segmenten verrichtet, oder über Arbeit, die Downstream-Services und -Ressourcen inUntersegmenten verrichtet, aufzeichnen.
Segmente zeichnen Informationen über die Arbeit auf, die Ihre Anwendung verrichtet. Ein Segmentzeichnet mindestens die für eine Aufgabe aufgewendete zeit, ihren Namen sowie zwei IDs auf. DieNachverfolgungs-ID zeichnet die Anforderung auf Ihrem Weg zwischen den Services auf. Die Segment-IDverfolgt die für die Anforderung durch einen einzelnen Service verrichtete Arbeit.
Example Minimales vollständiges Segment
{ "name" : "Scorekeep", "id" : "70de5b6f19ff9a0a", "start_time" : 1.478293361271E9, "trace_id" : "1-581cf771-a006649127e371903a2de979", "end_time" : 1.478293361449E9}
Wenn eine Anfrage empfangen wird, können Sie eine In-Progress-Segment als Platzhalter senden, bis dieAnforderung abgeschlossen ist.
Example In Bearbeitung befindliches Segment
{ "name" : "Scorekeep", "id" : "70de5b6f19ff9a0b", "start_time" : 1.478293361271E9, "trace_id" : "1-581cf771-a006649127e371903a2de979", “in_progress”: true}
Sie können Segmente an X-Ray direkt, mit PutTraceSegments (p. 58) oder über den X-Ray-Daemon (p. 58) senden.
Die meisten Anwendungen führen den Aufruf anderer Services oder den Zugriff auf Ressourcen mit demAWS-SDK durch. Zeichnen Sie Informationen über Downstream-Aufrufe in Untersegmenten auf. X-Raynutzt Untersegmente, um nachgelagerte Services zu identifizieren, die keine Segmente senden undEinträge für sie im Service-Diagramm erstellen.
Ein Untersegment kann in einem vollständigen Segmentdokument eingebettet oder separat gesendetwerden. Senden Sie Untersegmente separat, um nachgelagerte Aufrufe für lange andauerndeAnforderungen asynchron nachzuverfolgen oder um zu verhindern, dass die maximale Größe desSegmentdokuments (64 kB) überschritten wird.
Example Untersegment
Ein Untersegment hat den type subsegment und eine parent_id, mit der das übergeordnete Segmentidentifiziert wird.
{ "name" : "www2.example.com", "id" : "70de5b6f19ff9a0c", "start_time" : 1.478293361271E9, "trace_id" : "1-581cf771-a006649127e371903a2de979" “end_time” : 1.478293361449E9, “type” : “subsegment”, “parent_id” : “70de5b6f19ff9a0b”
56
AWS X-Ray EntwicklerhandbuchErzeugen von Ablaufverfolgungs-IDs
}
Weitere Informationen über die Felder und Werte, die in Segmente und Untersegmente eingegeben werdenkönnen, finden Sie unter AWS X-Ray Segmentdokumente (p. 72).
Abschnitte• Erzeugen von Ablaufverfolgungs-IDs (p. 57)• Verwendung von PutTraceSegments (p. 58)• Senden von Segmentdokumenten an den X-Ray-Daemon (p. 58)
Erzeugen von Ablaufverfolgungs-IDsUm Daten an X-Ray zu senden, müssen Sie für jede Anfrage eine eindeutige Ablaufverfolgungs-IDerzeugen. Ablaufverfolgungs-ID müssen die folgenden Anforderungen erfüllen.
Format der Ablaufverfolgungs-ID
Eine trace_id besteht aus drei durch Bindestriche getrennte Zahlen. Beispiel, 1-58406520-a006649127e371903a2de979. Dies umfasst:
• Die Versionsnummer 1.• Die Zeit der ursprünglichen Anforderung als Zeit seit Unix-Epoche und in 8 Hexadezimalziffern
ausgedrückt.
Beispiel: 10:00 Uhr 1. Dezember 2016 PST entspricht einer Epoch-Zeit von 1480615200 Sekunden oderin hexadezimalen Ziffern ausgedrückt 58406520.
• Eine 96-Bit-Kennzeichnung für die Ablaufverfolgung, global eindeutig, in 24 Hexadezimalziffern.
Sie können ein Skript schreiben, um Ablaufverfolgungs-IDs zu Testzwecken zu generieren. Nachfolgendfinden Sie zwei Beispiele.
Python
import timeimport osimport binascii
START_TIME = time.time()HEX=hex(int(START_TIME))[2:]TRACE_ID="1-" + HEX + "-" + binascii.b2a_hex(os.urandom(12))
Bash
START_TIME=$(date +%s)HEX_TIME=$(printf '%x\n' $START_TIME)GUID=$(dd if=/dev/random bs=12 count=1 2>/dev/null | od -An -tx1 | tr -d ' \t\n')TRACE_ID="1-$HEX_TIME-$GUID"
In der Scorekeep-Beispielanwendung finden Sie Skripte, die Ablaufverfolgungs-IDs erstellen und Segmentean den X-Ray-Daemon senden.
• Python – xray_start.py• Bash – xray_start.sh
57
AWS X-Ray EntwicklerhandbuchVerwendung von PutTraceSegments
Verwendung von PutTraceSegmentsSie können Segmentdokumente mit der PutTraceSegments-API hochladen. Die API hat einen einzelnenParameter, TraceSegmentDocuments, der eine Liste von JSON-Segmentdokumenten aufnimmt.
Verwenden Sie mit der AWS-CLI den Befehl aws xray put-trace-segments, um Segmentdokumentedirekt an X-Ray zu senden.
$ DOC='{"trace_id": "1-5960082b-ab52431b496add878434aa25", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}'$ aws xray put-trace-segments --trace-segment-documents $DOC{ "UnprocessedTraceSegments": []}
Note
Windows Command Prozessor und Windows PowerShell haben unterschiedliche Anforderungenfür Anführungszeichen und Escapes für Anführungszeichen in JSON-Zeichenfolgen: WeitereDetails finden Sie unter Setzen von Anführungszeichen für Zeichenfolgen im AWS CLI-Benutzerhandbuch.
Die Ausgabe führt alle Segmente auf, deren Verarbeitung fehlgeschlagen ist. Beispiel: Wenn das Datum inder Nachverfolgungs-ID zu weit in der Vergangenheit liegt, sehen Sie eine Fehlermeldung wie die folgende.
{ "UnprocessedTraceSegments": [ { "ErrorCode": "InvalidTraceId", "Message": "Invalid segment. ErrorCode: InvalidTraceId", "Id": "6226467e3f845502" } ]}
Sie können mehrere Segmentdokumente gleichzeitig, durch Leerräume getrennt, weitergeben.
$ aws xray put-trace-segments --trace-segment-documents $DOC1 $DOC2
Senden von Segmentdokumenten an den X-Ray-DaemonAnstatt Segmentdokumente zur X-Ray-API zu senden, können Sie Segmente und Untersegmente an denX-Ray-Daemon senden, der sie puffert und in Stapeln zur X-Ray-API hochlädt. Das X-Ray-SDK sendetSegmentdokumente an den Daemon, um direkte Aufrufe an AWS zu vermeiden.
Note
Informationen zur Ausführung des Daemons finden Sie unter Lokales Ausführen des X-Ray-Daemons (p. 117).
Senden Sie das Segment in JSON über den UDP-Port 2000 mit dem vorangestellten Daemon-Kopf{"format": "json", "version": 1}\n.
{"format": "json", "version": 1}\n{"trace_id": "1-5759e988-bd862e3fe1be46a994272793", "id": "defdfd9912dc5a56", "start_time": 1461096053.37518, "end_time": 1461096053.4042, "name": "test.elasticbeanstalk.com"}
58
AWS X-Ray EntwicklerhandbuchAbrufen von Daten
Unter Linux können Sie Segmentdokumente von einem Bash-Terminal aus an den Daemon senden.Speichern Sie den Kopf und das Segmentdokument in einer Textdatei, und senden Sie sie an /dev/udpmit cat.
$ cat segment.txt > /dev/udp/127.0.0.1/2000
Example segment.txt
{"format": "json", "version": 1}{"trace_id": "1-594aed87-ad72e26896b3f9d3a27054bb", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}
Überprüfen Sie anhand des Daemon-Protokolls (p. 114), dass das Segment an X-Ray gesendet wurde.
2017-07-07T01:57:24Z [Debug] processor: sending partial batch2017-07-07T01:57:24Z [Debug] processor: segment batch size: 1. capacity: 502017-07-07T01:57:24Z [Info] Successfully sent batch of 1 segments (0.020 seconds)
Abrufen von aus AWS X-RayAWS X-Ray verarbeitet die von Ihnen gesendeten Ablaufverfolgungsdaten, um vollständigeAblaufverfolgungen, Ablaufverfolgungsübersichten und Service-Diagramme in JSON zu generieren. Siekönnen die generierten Daten direkt über die API mit der AWS-CLI abrufen.
Abschnitte• Abrufen der Service-Grafik (p. 59)• Abrufen von Ablaufverfolgungen (p. 64)
Abrufen der Service-GrafikSie können die API GetServiceGraph verwenden, um das JSON-Service-Diagramm abzurufen. DieAPI erfordert eine Start- und Endzeit. Sie können diese mit dem date-Befehl an einem Linux-Terminalberechnen.
$ date +%s1499394617
date +%s druckt ein Datum in Sekunden. Verwenden Sie diese Zahl als Endzeit. Ziehen Sie Zeit ab, umeine Startzeit zu erhalten.
Example Script, um ein Service-Diagramm für die letzten 10 Minuten abzurufen
EPOCH=$(date +%s)aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
Das folgende Beispiel zeigt eine Service-Grafik mit 4 Knoten, einschließlich eines Client-Knotens, einerEC2-Instance, einer DynamoDB-Tabelle und eines Amazon SNS-Themas.
Example GetServiceGraph-Ausgabe
{
59
AWS X-Ray EntwicklerhandbuchAbrufen der Service-Grafik
"Services": [ { "ReferenceId": 0, "Name": "xray-sample.elasticbeanstalk.com", "Names": [ "xray-sample.elasticbeanstalk.com" ], "Type": "client", "State": "unknown", "StartTime": 1528317567.0, "EndTime": 1528317589.0, "Edges": [ { "ReferenceId": 2, "StartTime": 1528317567.0, "EndTime": 1528317589.0, "SummaryStatistics": { "OkCount": 3, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 1, "TotalCount": 1 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 4, "TotalResponseTime": 0.273 }, "ResponseTimeHistogram": [ { "Value": 0.005, "Count": 1 }, { "Value": 0.015, "Count": 1 }, { "Value": 0.157, "Count": 1 }, { "Value": 0.096, "Count": 1 } ], "Aliases": [] } ] }, { "ReferenceId": 1, "Name": "awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA", "Names": [ "awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA" ], "Type": "AWS::DynamoDB::Table", "State": "unknown", "StartTime": 1528317583.0, "EndTime": 1528317589.0, "Edges": [], "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": {
60
AWS X-Ray EntwicklerhandbuchAbrufen der Service-Grafik
"ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.12 }, "DurationHistogram": [ { "Value": 0.076, "Count": 1 }, { "Value": 0.044, "Count": 1 } ], "ResponseTimeHistogram": [ { "Value": 0.076, "Count": 1 }, { "Value": 0.044, "Count": 1 } ] }, { "ReferenceId": 2, "Name": "xray-sample.elasticbeanstalk.com", "Names": [ "xray-sample.elasticbeanstalk.com" ], "Root": true, "Type": "AWS::EC2::Instance", "State": "active", "StartTime": 1528317567.0, "EndTime": 1528317589.0, "Edges": [ { "ReferenceId": 1, "StartTime": 1528317567.0, "EndTime": 1528317589.0, "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.12 }, "ResponseTimeHistogram": [ { "Value": 0.076, "Count": 1
61
AWS X-Ray EntwicklerhandbuchAbrufen der Service-Grafik
}, { "Value": 0.044, "Count": 1 } ], "Aliases": [] }, { "ReferenceId": 3, "StartTime": 1528317567.0, "EndTime": 1528317589.0, "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.125 }, "ResponseTimeHistogram": [ { "Value": 0.049, "Count": 1 }, { "Value": 0.076, "Count": 1 } ], "Aliases": [] } ], "SummaryStatistics": { "OkCount": 3, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 1, "TotalCount": 1 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 4, "TotalResponseTime": 0.273 }, "DurationHistogram": [ { "Value": 0.005, "Count": 1 }, { "Value": 0.015, "Count": 1 }, { "Value": 0.157, "Count": 1 },
62
AWS X-Ray EntwicklerhandbuchAbrufen der Service-Grafik
{ "Value": 0.096, "Count": 1 } ], "ResponseTimeHistogram": [ { "Value": 0.005, "Count": 1 }, { "Value": 0.015, "Count": 1 }, { "Value": 0.157, "Count": 1 }, { "Value": 0.096, "Count": 1 } ] }, { "ReferenceId": 3, "Name": "SNS", "Names": [ "SNS" ], "Type": "AWS::SNS", "State": "unknown", "StartTime": 1528317583.0, "EndTime": 1528317589.0, "Edges": [], "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.125 }, "DurationHistogram": [ { "Value": 0.049, "Count": 1 }, { "Value": 0.076, "Count": 1 } ], "ResponseTimeHistogram": [ { "Value": 0.049, "Count": 1 }, { "Value": 0.076,
63
AWS X-Ray EntwicklerhandbuchAbrufen von Ablaufverfolgungen
"Count": 1 } ] } ]}
Abrufen von AblaufverfolgungenSie können die API GetTraceSummaries verwenden, um eine Liste von Ablaufverfolgungsübersichtenabzurufen. Ablaufverfolgungsübersichten enthalten Informationen, mit denen Sie Ablaufverfolgungenidentifizieren können, die Sie vollständig herunterladen möchten, einschließlich Anmerkungen,Informationen zu Anforderung und Reaktion sowie IDs.
Mit dem Befehl aws xray get-trace-summaries können Sie eine Liste vonAblaufverfolgungsübersichten abrufen. Mit den folgenden Befehlen können Sie eine Liste vonAblaufverfolgungsübersichten abrufen, die zwischen 1 und 2 Minuten in der Vergangenheit erstellt wurden.
Example Skript zum Abrufen von Ablaufverfolgungsübersichten
EPOCH=$(date +%s)aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60))
Example GetTraceSummaries-Ausgabe
{ "TraceSummaries": [ { "HasError": false, "Http": { "HttpStatus": 200, "ClientIp": "205.255.255.183", "HttpURL": "http://scorekeep.elasticbeanstalk.com/api/session", "UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36", "HttpMethod": "POST" }, "Users": [], "HasFault": false, "Annotations": {}, "ResponseTime": 0.084, "Duration": 0.084, "Id": "1-59602606-a43a1ac52fc7ee0eea12a82c", "HasThrottle": false }, { "HasError": false, "Http": { "HttpStatus": 200, "ClientIp": "205.255.255.183", "HttpURL": "http://scorekeep.elasticbeanstalk.com/api/user", "UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36", "HttpMethod": "POST" }, "Users": [ { "UserName": "5M388M1E" } ],
64
AWS X-Ray EntwicklerhandbuchAbrufen von Ablaufverfolgungen
"HasFault": false, "Annotations": { "UserID": [ { "AnnotationValue": { "StringValue": "5M388M1E" } } ], "Name": [ { "AnnotationValue": { "StringValue": "Ola" } } ] }, "ResponseTime": 3.232, "Duration": 3.232, "Id": "1-59602603-23fc5b688855d396af79b496", "HasThrottle": false } ], "ApproximateTime": 1499473304.0, "TracesProcessedCount": 2}
Mithilfe der Ablaufverfolgungs-ID aus der Ausgabe können Sie mit der API BatchGetTraces einevollständige Ablaufverfolgung abrufen.
Example Befehl BatchGetTraces
$ aws xray batch-get-traces --trace-ids 1-596025b4-7170afe49f7aa708b1dd4a6b
Example BatchGetTraces-Ausgabe
{ "Traces": [ { "Duration": 3.232, "Segments": [ { "Document": "{\"id\":\"1fb07842d944e714\",\"name\":\"random-name\",\"start_time\":1.499473411677E9,\"end_time\":1.499473414572E9,\"parent_id\":\"0c544c1b1bbff948\",\"http\":{\"response\":{\"status\":200}},\"aws\":{\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda\",\"resource_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}", "Id": "1fb07842d944e714" }, { "Document": "{\"id\":\"194fcc8747581230\",\"name\":\"Scorekeep\",\"start_time\":1.499473411562E9,\"end_time\":1.499473414794E9,\"http\":{\"request\":{\"url\":\"http://scorekeep.elasticbeanstalk.com/api/user\",\"method\":\"POST\",\"user_agent\":\"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36\",\"client_ip\":\"205.251.233.183\"},\"response\":{\"status\":200}},\"aws\":{\"elastic_beanstalk\":{\"version_label\":\"app-abb9-170708_002045\",\"deployment_id\":406,\"environment_name\":\"scorekeep-dev\"},\"ec2\":{\"availability_zone\":\"us-west-2c\",\"instance_id\":\"i-0cd9e448944061b4a\"},\"xray\":{\"sdk_version\":\"1.1.2\",\"sdk\":\"X-Ray for Java\"}},\"service\":{},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"user\":\"5M388M1E\",\"origin\":\"AWS::ElasticBeanstalk::Environment\",\"subsegments\":[{\"id\":
65
AWS X-Ray EntwicklerhandbuchAbrufen von Ablaufverfolgungen
\"0c544c1b1bbff948\",\"name\":\"Lambda\",\"start_time\":1.499473411629E9,\"end_time\":1.499473414572E9,\"http\":{\"response\":{\"status\":200,\"content_length\":14}},\"aws\":{\"log_type\":\"None\",\"status_code\":200,\"function_name\":\"random-name\",\"invocation_type\":\"RequestResponse\",\"operation\":\"Invoke\",\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\",\"resource_names\":[\"random-name\"]},\"namespace\":\"aws\"},{\"id\":\"071684f2e555e571\",\"name\":\"## UserModel.saveUser\",\"start_time\":1.499473414581E9,\"end_time\":1.499473414769E9,\"metadata\":{\"debug\":{\"test\":\"Metadata string from UserModel.saveUser\"}},\"subsegments\":[{\"id\":\"4cd3f10b76c624b4\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"namespace\":\"aws\"}]}]}", "Id": "194fcc8747581230" }, { "Document": "{\"id\":\"00f91aa01f4984fd\",\"name\":\"random-name\",\"start_time\":1.49947341283E9,\"end_time\":1.49947341457E9,\"parent_id\":\"1fb07842d944e714\",\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\",\"resource_names\":[\"random-name\"],\"account_id\":\"123456789012\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda::Function\",\"subsegments\":[{\"id\":\"e6d2fe619f827804\",\"name\":\"annotations\",\"start_time\":1.499473413012E9,\"end_time\":1.499473413069E9,\"annotations\":{\"UserID\":\"5M388M1E\",\"Name\":\"Ola\"}},{\"id\":\"b29b548af4d54a0f\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"namespace\":\"aws\"},{\"id\":\"2279c0030c955e52\",\"name\":\"Initialization\",\"start_time\":1.499473412064E9,\"end_time\":1.499473412819E9,\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}}]}", "Id": "00f91aa01f4984fd" }, { "Document": "{\"id\":\"17ba309b32c7fbaf\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"parent_id\":\"4cd3f10b76c624b4\",\"inferred\":true,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::DynamoDB::Table\"}", "Id": "17ba309b32c7fbaf" }, { "Document": "{\"id\":\"1ee3c4a523f89ca5\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"parent_id\":\"b29b548af4d54a0f\",\"inferred\":true,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::SNS\"}", "Id": "1ee3c4a523f89ca5" } ], "Id": "1-59602603-23fc5b688855d396af79b496" } ], "UnprocessedTraceIds": []}
Die vollständige Nachverfolgung umfasst ein Dokument für jedes Segment, das aus allenSegmentdokumenten kompiliert wurde, die mit der gleichen Ablaufverfolgungs-ID erhalten wurden.Diese Dokumente stellen die Daten nicht so dar, wie sie von Ihrer Anwendung an X-Ray gesendet
66
AWS X-Ray EntwicklerhandbuchKonfiguration
wurden. Stattdessen stellen sie die vom X-Ray-Service erstellten verarbeiteten Dokumente dar. X-Ray erstellt das vollständige Ablaufverfolgungsdokument und kompiliert dazu die von Ihrer Anwendunggesendeten Segmentdokumente und entfernt die Daten, die dem Segmentdokumentschema (p. 72)nicht entsprechen.
X-Ray erstellt außerdem abgeleitete Segmente für nachgelagerte Aufrufe an Services, die selbst keineSegmente senden. Wenn Sie beispielsweise DynamoDB mit einem instrumentierten Client aufrufen,zeichnet das X-Ray-SDK ein Untersegment mit Details zum Aufruf aus dessen Sicht auf. DynamoDBsendet jedoch kein entsprechendes Segment. X-Ray verwendet die Informationen im Untersegment, umein abgeleitetes Segment zu erstellen, das die DynamoDB-Ressource in der Service-Übersicht darstellt,und fügt dieses dem Ablaufverfolgungsdokument hinzu.
Um mehrere Ablaufverfolgungen von der API zu erhalten, benötigen Sie eine Liste der Trace-IDs, die Siemit einer AWS CLI-Abfrage aus der Ausgabe von get-trace-summaries extrahieren können. LeitenSie die Liste zur Eingabe von batch-get-traces um, um vollständige Ablaufverfolgungen für einenbestimmten Zeitraum zu erhalten.
Example Script, um vollständige Ablaufverfolgungen für einen Zeitraum von einer Minute zuerhalten
EPOCH=$(date +%s)TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text)aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]'
Konfigurieren von AWS X-Ray-Verschlüsselungseinstellungen
AWS X-Ray bietet APIs für die Konfiguration von Verschlüsselungseinstellungen (p. 50). Verwenden SiePutEncryptionConfig zur Angabe eines Kundenmasterschlüssels (Customer Master Key, CMK), derfür die Verschlüsselung verwendet werden soll.
$ aws xray put-encryption-config --type KMS --key-id alias/aws/xray{ "EncryptionConfig": { "KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5", "Status": "UPDATING", "Type": "KMS" }}
Für die Schlüssel-ID können Sie einen Alias verwenden (wie im Beispiel gezeigt), eine Schlüssel-ID odereinen ARN.
Verwenden Sie GetEncryptionConfig, um die aktuelle Konfiguration abzurufen. Wenn X-Ray dieAnwendung Ihrer Einstellungen abgeschlossen hat, ändert sich der Status von UPDATING in ACTIVE.
$ aws xray get-encryption-config{ "EncryptionConfig": { "KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5", "Status": "ACTIVE", "Type": "KMS" }
67
AWS X-Ray EntwicklerhandbuchCloudTrail
}
Um die Verwendung eines CMK zu beenden und die Standardverschlüsselung zu verwenden, setzen Sieden Verschlüsselungstyp auf NONE.
$ aws xray put-encryption-config --type NONE{ "EncryptionConfig": { "Status": "UPDATING", "Type": "NONE" }}
Protokollieren von X-Ray-API-Aufrufen mit AWSCloudTrail
AWS X-Ray ist in AWS CloudTrail integriert, um API-Aktionen eines Benutzers, einer Rolle oder einesAWS-Services in X-Ray aufzuzeichnen. Sie können CloudTrail zur Überwachung der X-Ray-API-Anfragen in Echtzeit verwenden und Protokolle in Amazon S3, Amazon CloudWatch Logs und AmazonCloudWatch Events speichern. X-Ray unterstützt die Protokollierung der folgenden Aktionen als Ereignissein CloudTrail-Protokolldateien:
Unterstützte API-Aktionen
• PutEncryptionConfig – Verwaltungsereignis (Schreiben)• GetEncryptionConfig – Verwaltungsereignis (Lesen)
Sie erstellen einen Trail wie folgt:
1. Öffnen Sie die Seite Trails der CloudTrail-Konsole.2. Wählen Sie Create Trail (Trail erstellen) aus.3. Geben Sie einen Trail-Namen ein und wählen Sie dann die aufzuzeichnenden Ereignistypen aus.
• Management events (Verwaltungsereignisse) – Aufzeichnung von API-Aktionen zum Erstellen,Lesen, Aktualisieren und Löschen von AWS-Ressourcen. Zeichnet Aufrufe aller unterstützten API-Aktionen für alle AWS-Services auf.
• Data events (Datenereignisse) – Zeichnet API-Aktionen auf, die für bestimmte Ressourcenvorgesehen sind, wie z. B. Amazon S3-Objektlesevorgänge oder AWS Lambda-Funktionsaufrufe.Sie können auswählen, welche Buckets und Funktionen überwacht werden sollen.
4. Wählen Sie einen Amazon S3-Bucket und Verschlüsselungseinstellungen aus.5. Wählen Sie Create aus.
CloudTrail zeichnet API-Aufrufe der Typen aus, für die Sie eine Aufzeichnung von Protokolldateien inAmazon S3 ausgewählt haben. Ein CloudTrail-Protokoll ist ein nicht sortiertes Array mit Ereignissen imJSON-Format. CloudTrail zeichnet für jeden Aufruf einer unterstützten API-Aktion Informationen über dieAnforderung und die Entity, die sie gemacht hat, auf. Protokollereignisse enthalten den Namen der Aktion,Parameter, die Antwort von X-Ray sowie Details über den Anforderer.
Example X-Ray GetEncryptionConfig-Protokolleintrag
{
68
AWS X-Ray EntwicklerhandbuchAWS Config
"eventVersion"=>"1.05", "userIdentity"=>{ "type"=>"AssumedRole", "principalId"=>"AROAJVHBZWD3DN6CI2MHM:MyName", "arn"=>"arn:aws:sts::123456789012:assumed-role/MyRole/MyName", "accountId"=>"123456789012", "accessKeyId"=>"AKIAIOSFODNN7EXAMPLE", "sessionContext"=>{ "attributes"=>{ "mfaAuthenticated"=>"false", "creationDate"=>"2018-6-01T00:24:36Z" }, "sessionIssuer"=>{ "type"=>"Role", "principalId"=>"AROAJVHBZWD3DN6CI2MHM", "arn"=>"arn:aws:iam::123456789012:role/MyRole", "accountId"=>"123456789012", "userName"=>"MyRole" } } }, "eventTime"=>"2018-6-01T00:24:36Z", "eventSource"=>"xray.amazonaws.com", "eventName"=>"GetEncryptionConfig", "awsRegion"=>"us-east-2", "sourceIPAddress"=>"33.255.33.255", "userAgent"=>"aws-sdk-ruby2/2.11.19 ruby/2.3.1 x86_64-linux", "requestParameters"=>nil, "responseElements"=>nil, "requestID"=>"3fda699a-32e7-4c20-37af-edc2be5acbdb", "eventID"=>"039c3d45-6baa-11e3-2f3e-e5a036343c9f", "eventType"=>"AwsApiCall", "recipientAccountId"=>"123456789012"}
Das userIdentity-Element enthält Informationen über den Ersteller der Anfrage. Anhand derIdentitätsinformationen zur Benutzeridentität können Sie Folgendes bestimmen:
• Ob die Anfrage mit Root- oder IAM-Benutzeranmeldeinformationen ausgeführt wurde.• Ob die Anfrage mit temporären Sicherheitsanmeldeinformationen für eine Rolle oder einen föderierten
Benutzer ausgeführt wurde.• Ob die Anforderung von einem anderen AWS-Service getätigt wurde.
Wenn Sie benachrichtigt werden möchten, wenn eine neue Protokolldateien zur Verfügung steht, könnenSie CloudTrail so konfigurieren, dass Amazon SNS-Benachrichtigungen veröffentlicht werden. WeitereInformationen finden Sie unter Konfigurieren von Amazon SNS-Benachrichtigungen für CloudTrail.
Sie können die X-Ray-Protokolldateien aus mehreren AWS-Regionen und -Konten auch in einem einzigenAmazon S3-Bucket zusammenfassen. Weitere Informationen finden Sie unter Empfangen von CloudTrail-Protokolldateien aus mehreren Regionen und Empfangen von CloudTrail-Protokolldateien aus mehrerenKonten.
Nachverfolgen von Änderungen an der X-Ray-Verschlüsselungskonfiguration mit AWS Config
AWS X-Ray wird zur Aufzeichnung von Konfigurationsänderungen an den X-Ray-Verschlüsselungsressourcen in AWS Config integriert. Sie können mit AWS Config eine
69
AWS X-Ray EntwicklerhandbuchErstellen eines Lambda-Funktionsauslösers
Bestandsaufnahme der X-Ray-Verschlüsselungsressourcen durchführen, den X-Ray-Konfigurationsverlaufüberprüfen und Benachrichtigungen basierend auf Ressourcenänderungen senden.
AWS Config unterstützt die Protokollierung der folgenden Änderungen der X-Ray-Verschlüsselungsressourcen als Ereignisse:
• Konfigurationsänderungen – Ändern oder Hinzufügen eines Verschlüsselungsschlüssels oderZurücksetzen auf die Standard-X-Ray-Verschlüsselungseinstellung.
Hier erhalten Sie Anweisungen zum Erstellen einer grundlegenden Verbindung zwischen X-Ray und AWSConfig.
Erstellen eines Lambda-FunktionsauslösersSie benötigen den ARN einer benutzerdefinierten AWS Lambda-Funktion, um eine benutzerdefinierteAWS Config-Regel generieren zu können. Befolgen Sie diese Anweisungen zum Erstellen einer einfachenFunktion mit Node.js, die basierend auf dem Zustand der XrayEncryptionConfig-Ressource als Wertan AWS Config zurückgibt, ob sie konform oder nicht konform ist.
So erstellen Sie eine Lambda-Funktion mit einem AWS::XrayEncryptionConfig-Änderungsauslöser
1. Öffnen Sie die Lambda-Konsole. Wählen Sie Create function.2. Wählen Sie Blueprints (Vorlagen) und filtern Sie die Vorlagenbibliothek dann nach der config-rule-
change-triggered-Vorlage. Klicken Sie auf den Link im Namen der Vorlage oder wählen Sie Configure(Konfigurieren), um fortzufahren.
3. Definieren Sie die folgenden Felder zum Konfigurieren der Vorlage:
• Geben Sie im Feld Name einen Namen ein.• Bei Role wählen Sie Create New Role from Template(s) aus.• Bei Role Name geben Sie einen Namen ein.• Wählen Sie für Policy Templates (Richtlinienvorlagen) die Option AWS Config Rules permissions
(AWS Config-Regelberechtigungen) aus.4. Klicken Sie auf Create function (Funktion erstellen) zum Erstellen und Anzeigen Ihrer Funktion in der
AWS Lambda-Konsole.5. Bearbeiten Sie Ihren Funktionscode, indem Sie AWS::EC2::Instance durch
AWS::XrayEncryptionConfig ersetzen. Sie können auch das Beschreibungsfeld aktualisieren,damit die Änderung wirksam wird.
Standardcode
if (configurationItem.resourceType !== 'AWS::EC2::Instance') { return 'NOT_APPLICABLE'; } else if (ruleParameters.desiredInstanceType === configurationItem.configuration.instanceType) { return 'COMPLIANT'; } return 'NON_COMPLIANT';
Aktualisierter Code
if (configurationItem.resourceType !== 'AWS::XRay::EncryptionConfig') { return 'NOT_APPLICABLE'; } else if (ruleParameters.desiredInstanceType === configurationItem.configuration.instanceType) { return 'COMPLIANT';
70
AWS X-Ray EntwicklerhandbuchErstellen einer benutzerdefinierten
AWS Config-Regel für X-Ray
} return 'NON_COMPLIANT';
6. Fügen Sie Folgendes zu Ihrer Ausführungsrolle in IAM hinzu, um Zugriff auf X-Ray zu erhalten.Diese Berechtigungen ermöglichen den schreibgeschützten Zugriff auf Ihre X-Ray-Ressourcen.Wenn Sie keinen Zugriff auf die entsprechenden Ressourcen ermöglichen, führt dies zu einerBereichsüberschreitungsmeldung von AWS Config, wenn es die der Regel zugeordnete Lambda-Funktion auswertet.
{ "Sid": "Stmt1529350291539", "Action": [ "xray:BatchGetTraces", "xray:GetServiceGraph", "xray:GetTraceGraph", "xray:GetTraceSummaries" ], "Effect": "Allow", "Resource": "*" }
Erstellen einer benutzerdefinierten AWS Config-Regelfür X-RayAchten Sie beim Erstellen der Lambda-Funktion auf den ARN der Funktion und rufen Sie die AWS Config-Konsole zum Erstellen Ihrer benutzerdefinierten Regel auf.
So erstellen Sie eine AWS Config-Regel für X-Ray
1. Öffnen Sie die Seite Rules (Regeln) der AWS Config-Konsole.2. Klicken Sie auf Add Rule (Regel hinzufügen) und danach auf Add custom rule (Benutzerdefinierte
Regel hinzufügen).3. Geben Sie unter AWS Lambda Function ARN (ARN der AWS Lambda-Funktion) den ARN ein, der der
Lambda-Funktion zugeordnet ist, die Sie verwenden möchten.4. Wählen Sie, welche Art von Auslöser festgelegt werden soll:
• Konfigurationsänderungen – AWS Config löst die Auswertung aus, wenn sich die Konfigurationeiner Ressource, die dem Umfang der Regel entspricht, ändert. Die Auswertung wird durchgeführt,nachdem AWS Config eine Änderungsbenachrichtigung wegen eines Konfigurationselementssendet.
• Regelmäßig – AWS Config führt Auswertungen für die Regel mit der gewünschten Häufigkeit (z. B.alle 24 Stunden) durch.
5. Wählen Sie für Resource type (Ressourcentyp) die Option EncryptionConfig im X-Ray-Bereich aus.6. Wählen Sie Save (Speichern) aus.
Die AWS Config-Konsole beginnt sofort mit der Auswertung der Compliance der Regel. Die Auswertungkann mehrere Minuten in Anspruch nehmen.
Wenn diese Regel konform ist, kann AWS Config mit dem Kompilieren eines Audit-Verlaufs beginnen.AWS Config erfasst Ressourcenänderungen in Form einer Timeline. Für jede Änderung in der Timeline derEreignisse erstellt AWS Config eine Tabelle im Format "Von/Zu", um aufzuzeigen, was sich in der JSON-Darstellung des Verschlüsselungsschlüssels geändert hat. Die beiden mit EncryptionConfig verbundenenFeldänderungen sind Configuration.type und Configuration.keyID.
71
AWS X-Ray EntwicklerhandbuchBeispielergebnisse
BeispielergebnisseIm Folgenden sehen Sie ein Beispiel einer AWS Config-Timeline mit Änderungen an bestimmten Tagenund Uhrzeiten.
Nachfolgend finden Sie ein Beispiel eines AWS Config-Änderungseintrags. Das Format "Von/Zu"veranschaulicht, was sich geändert hat. In diesem Beispiel wird aufgezeigt, dass die Standard-X-Ray-Verschlüsselungseinstellungen in einen definierten Verschlüsselungsschlüssel geändert wurden.
Amazon SNS-BenachrichtigungenWenn Sie benachrichtigt werden möchten, legen Sie für AWS Config die Veröffentlichung von AmazonSNS-Benachrichtigungen fest. Weitere Informationen finden Sie unter Überwachen von AWS Config-Ressourcenänderungen per E-Mail.
AWS X-Ray SegmentdokumenteEin Ablaufverfolgungssegment ist eine JSON-Darstellung einer Anfrage, die Ihrer Anwendung dient.Ein Ablaufverfolgungssegment zeichnet Informationen über die ursprüngliche Anforderung, die lokalenAufgaben Ihrer Anwendung sowie über Untersegmente mit Informationen über nachgelagerte Aufrufe auf,die von Ihrer Anwendung an AWS-Ressourcen, HTTP-APIs und SQL-Datenbanken gemacht werden.
Ein Segmentdokument übermittelt Informationen über ein Segment an X-Ray. Ein Segmentdokument kannbis zu 64 kB sein und ein ganzes Segment mit Untersegmenten, einem Segmentenfragment, das angibt,dass eine Anforderung in Bearbeitung ist, oder einem einzelnen Untersegment, das getrennt gesendet wird,enthalten. Sie können Dokumente mit der PutTraceSegments-API direkt an X-Ray senden.
X-Ray stellt Prozesssegmentdokumente zusammen, um abfragbareAblaufverfolgungszusammenfassungen und vollständige Ablaufverfolgungen zu generieren, auf die Siezugreifen können, indem Sie die GetTraceSummaries- und BatchGetTraces-APIs. nutzen. Zusätzlichzu den an X-Ray gesendeten Segmenten und Untersegmenten nutzt der Service die Informationen inSubsegmenten, um abgeleitete Segmente zu generieren und sie der vollständigen Ablaufverfolgunghinzuzufügen. Abgeleitete Segmente spiegeln nachgelagerte Services und Ressourcen in der Service-Übersicht wider.
72
AWS X-Ray EntwicklerhandbuchSegmentfelder
X-Ray bietet ein JSON-Schema für Segmentdokumente an. Sie können das Schema hier herunterladen:xray-segmentdocument-schema-v1.0.0. Die im Schema angegebenen Felder und Objekte werden in denfolgenden Abschnitten genauer beschrieben.
Eine Untergruppe der Segmentfelder ist zur Nutzung mit Filterausdrücken von X-Ray indiziert. Wenn Siezum Beispiel das user-Feld auf ein Segment mit einer eindeutigen Kennzeichnung einstellen, könnenSie durch Nutzung der GetTraceSummaries-API nach Segmenten suchen, die in Zusammenhang mitbestimmten Nutzern in der X-Ray-Konsole stehen. Weitere Informationen finden Sie unter Suchen nachAblaufverfolgungen in der AWS X-Ray-Konsole mit Filterausdrücken (p. 39).
Wenn Sie Ihre Anwendung mit dem X-Ray-SDK nutzen, generiert das SDK für Sie Segmentdokumente.Anstatt die Segmentdokumente direkt an X-Ray zu senden, übermittelt das SDK sie über einen lokalenUDP-Anschluss direkt an den X-Ray-Daemon (p. 112). Weitere Informationen finden Sie unter Sendenvon Segmentdokumenten an den X-Ray-Daemon (p. 58).
Abschnitte• Segmentfelder (p. 73)• Untersegmente (p. 75)• HTTP-Anfragedaten (p. 78)• Anmerkungen (p. 80)• Metadata (p. 80)• AWS-Ressourcendaten (p. 81)• Fehler und Ausnahmen (p. 83)• SQL-Abfragen (p. 84)
SegmentfelderEin Segment zeichnet Ablaufverfolgungsinformationen über eine Anforderung auf, die Ihrer Anwendungdient. Ein Segment zeichnet mindestens den Namen, die ID, die Anfangszeit, die Ablaufverfolgungs-ID unddie Endzeit der Anforderung auf.
Example Minimales vollständiges Segment
{ "name" : "example.com", "id" : "70de5b6f19ff9a0a", "start_time" : 1.478293361271E9, "trace_id" : "1-581cf771-a006649127e371903a2de979", "end_time" : 1.478293361449E9}
Die folgenden Felder sind für Segmente erforderlich oder in einigen Fällen notwendig.Note
Der Wert muss aus Zeichenfolgen (bis zu 250 Zeichen) bestehen, soweit nicht anders angegeben.
Erforderliche Segmentfelder
• name – Der logische Name des Services, der die Anforderungen verarbeitet, bis zu 200 Zeichen.Beispielsweise der Name der Anwendung oder Domäne. Namen dürfen Unicode-Buchstaben, -Ziffernund -Leerzeichen enthalten sowie die folgenden Symbole: _, ., :, /, %, &, #, =, +, \, -, @
• id – Eine 64-Bit-Kennung für das Segment, die sich von anderen Segmenten in derselbenAblaufverfolgung eindeutig unterscheidet, in 16 Hexadezimalziffern.
• trace_id – Eine eindeutige Kennung, die alle von einer einzigen Client-Anforderung stammendenSegmente und Untersegmente verbindet.
73
AWS X-Ray EntwicklerhandbuchSegmentfelder
Format der Ablaufverfolgungs-ID
Eine trace_id besteht aus drei durch Bindestriche getrennte Zahlen. Beispiel, 1-58406520-a006649127e371903a2de979. Dies umfasst:• Die Versionsnummer 1.• Die Zeit der ursprünglichen Anforderung als Zeit seit Unix-Epoche und in 8 Hexadezimalziffern
ausgedrückt.
Beispiel: 10:00 Uhr 1. Dezember 2016 PST entspricht einer Epoch-Zeit von 1480615200 Sekundenoder in hexadezimalen Ziffern ausgedrückt 58406520.
• Eine 96-Bit-Kennzeichnung für die Ablaufverfolgung, global eindeutig, in 24 Hexadezimalziffern.Sicherheit der Ablaufverfolgungs-ID
Ablaufverfolgungs-IDs sind in Antwortheadern (p. 26) sichtbar. Generieren SieAblaufverfolgungs-IDs mit einem sicheren Random-Algorithmus, um sicherzustellen, dassAngreifer zukünftige Ablaufverfolgungs-IDs nicht berechnen und keine Anforderungen mitdiesen IDs an Ihre Anwendung senden können.
• start_time – Zahl, die in Gleitkommasekunden seit Epoche angibt, wann das Segment erstellt wurde.Zum Beispiel 1480615200.010 oder 1.480615200010E9. Verwenden Sie so viele Dezimalstellen, wieSie benötigen. Mikrosekundenauflösung ist empfohlen, wenn verfügbar.
• end_time – Zahl, die angibt, wann das Segment geschlossen wurde. Zum Beispiel 1480615200.090oder 1.480615200090E9. Geben Sie entweder end_time oder in_progress an.
• in_progress – Boolescher Wert, der auf true festgelegt wurde, anstatt eine end_time anzugeben,um aufzuzeichnen, dass das Segment begonnen, aber nicht abgeschlossen wurde. Wenn IhreAnwendung eine Anforderung empfängt, die lange dauern wird, senden Sie ein in Bearbeitungbefindliches Segment, um den Empfang zu bestätigen. Wenn die Antwort gesendet wird, senden Sie dasvollständige Segment zum Überschreiben des in Bearbeitung befindlichen Segments. Senden Sie proAnforderung nur ein vollständiges Segment und ein oder kein angefangenes Segment.
Service-Namen
Der name eines Segments sollte mit dem Domänennamen oder logischen Namen des Servicesübereinstimmen, der das Segment generiert. Dies wird jedoch nicht erzwungen. Jede Anwendungmit Berechtigung für PutTraceSegments kann Segmente mit beliebigem Namen senden.
Die folgenden Felder sind für Segmente optional.
Optionale Segmentfelder
• service – Ein Objekt mit Informationen zu Ihrer Anwendung.• version – Eine Zeichenfolge, die die Version Ihrer Anwendung, welche die Anforderung unterstützt
hat, identifiziert.• user – Eine Zeichenfolge, die den Benutzer, der die Anforderung gesendet hat, identifiziert.• origin – Der AWS-Ressourcentyp, auf denen Ihre Anwendung ausgeführt wird.
Unterstützte Werte• AWS::EC2::Instance – Eine Amazon EC2-Instance.• AWS::ECS::Container – Ein Amazon ECS-Container.• AWS::ElasticBeanstalk::Environment – Eine Elastic Beanstalk-Umgebung.
Wenn mehrere Werte für Ihre Anwendung gelten, verwenden Sie den spezifischsten. In einerMulticontainer-Docker-Elastic Beanstalk-Umgebung wird Ihre Anwendung beispielsweise auf einemAmazon ECS-Container ausgeführt, der wiederum auf einer Amazon EC2-Instance ausgeführt wird. In
74
AWS X-Ray EntwicklerhandbuchUntersegmente
diesem Fall müssen Sie den Ursprung auf AWS::ElasticBeanstalk::Environment festlegen, dadie Umgebung das übergeordnete Element der beiden anderen Ressourcen ist.
• parent_id – Eine Untersegments-ID, die Sie festlegen, wenn die Anforderung von einerinstrumentierten Anwendung stammt. Das X-Ray-SDK fügt dem Ablaufverfolgungs-Header (p. 26) eineübergeordnete Untersegments-ID für nachgelagerte HTTP-Aufrufe hinzu.
• http – http (p. 78) Objekte mit Informationen über die ursprüngliche HTTP-Anforderung.• aws – aws (p. 81) Objekt mit Informationen über die AWS-Ressourcen, auf denen Ihre Anwendung
die Anforderung bereitstellt.• error, throttle, fault und cause – Fehler (p. 83)felder, die einen aufgetretenen Fehler angeben
und Informationen über die Ausnahme enthalten, die den Fehler verursacht hat.• annotations – annotations (p. 80) Objekt mit Schlüsselwertpaaren, die X-Ray zur Suche
indizieren soll.• metadata – metadata (p. 80) Objekt mit zusätzlichen Daten, die in einem Segment gespeichert
werden sollen.• subsegments – Array von subsegment (p. 75) Objekten.
UntersegmenteSie können Untersegmente erstellen, um Aufrufe von AWS-Services und -Ressourcen, die Sie mit demAWS-SDK machen, Aufrufe von internen oder externen HTTP-Web-APIs sowie SQL-Datenbankanfragenaufzuzeichnen. Sie können auch Untersegmente erstellen, um Code-Blöcke in Ihrer Anwendung zudebuggen oder zu kommentieren. Untersegmente können weitere Untersegmente enthalten, damit einindividuelles Untersegment, das Metadaten über einen internen Funktionsaufruf aufzeichnet, weitereindividuelle Untersegmente sowie Untersegmente nachgelagerter Aufrufe umfassen kann.
Ein Untersegment erfasst einen nachgelagerten Aufruf aus der Sicht des Service, der den Aufruf gestartethat. X-Ray nutzt Untersegmente, um nachgelagerte Services zu identifizieren, die keine Segmente sendenund Einträge für sie im Service-Diagramm erstellen.
Ein Untersegment kann in einem vollständigen Segmentdokument eingebettet oder separat gesendetwerden. Senden Sie Untersegmente separat, um nachgelagerte Aufrufe für lange andauerndeAnforderungen asynchron nachzuverfolgen oder um zu verhindern, dass die maximale Größe desSegmentdokuments überschritten wird.
Example Segment mit eingebettetem Untersegment
Ein unabhängiges Untersegment hat einen type vom subsegment und einen parent_id, der dasübergeordnete Segment identifiziert.
{ "trace_id" : "1-5759e988-bd862e3fe1be46a994272793", "id" : "defdfd9912dc5a56", "start_time" : 1461096053.37518, "end_time" : 1461096053.4042, "name" : "www.example.com", "http" : { "request" : { "url" : "https://www.example.com/health", "method" : "GET", "user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/601.7.7", "client_ip" : "11.0.3.111" }, "response" : { "status" : 200, "content_length" : 86 }
75
AWS X-Ray EntwicklerhandbuchUntersegmente
}, "subsegments" : [ { "id" : "53995c3f42cd8ad8", "name" : "api.example.com", "start_time" : 1461096053.37769, "end_time" : 1461096053.40379, "namespace" : "remote", "http" : { "request" : { "url" : "https://api.example.com/health", "method" : "POST", "traced" : true }, "response" : { "status" : 200, "content_length" : 861 } } } ]}
Für langwierige Anforderungen können Sie ein sich in Bearbeitung befindliches Segment senden, um X-Ray über den Erhalt der Anforderung zu informieren und Untersegmente anschließend zu senden, umdiese vor Abschluss der ursprünglichen Anforderung rückzuverfolgen.
Example In Bearbeitung befindliches Segment
{ "name" : "example.com", "id" : "70de5b6f19ff9a0b", "start_time" : 1.478293361271E9, "trace_id" : "1-581cf771-a006649127e371903a2de979", "in_progress": true}
Example Unabhängiges Untersegment
Ein unabhängiges Untersegment hat einen subsegment-type, eine trace_id und eine parent_id, diedas übergeordnete Segment identifiziert.
{ "name" : "api.example.com", "id" : "53995c3f42cd8ad8", "start_time" : 1.478293361271E9, "end_time" : 1.478293361449E9, "type" : "subsegment", "trace_id" : "1-581cf771-a006649127e371903a2de979" "parent_id" : "defdfd9912dc5a56", "namespace" : "remote", "http" : { "request" : { "url" : "https://api.example.com/health", "method" : "POST", "traced" : true }, "response" : { "status" : 200, "content_length" : 861 } }
76
AWS X-Ray EntwicklerhandbuchUntersegmente
}
Schließen Sie das Segment nach Abschluss der Anforderung mit einer end_time. Das vollständigeSegment überschreibt das sich in Bearbeitung befindliche Segment.
Sie können außerdem Untersegmente für abgeschlossene Anforderungen, die asynchrone Workflowsauslösen, getrennt senden. Beispielsweise kann eine Web-API eine OK 200-Antwort, unmittelbar bevordie vom Benutzer angeforderte Arbeit beginnt, zurücksenden. Sobald die Antwort gesendet ist, können Sieein vollständiges Segment an X-Ray, gefolgt von Untersegmenten für später abgeschlossene Arbeiten,senden. Wie bei Segmenten können Sie auch einen Untersegmentsfragment senden, um den Beginn desUntersegments aufzuzeichnen, und es anschließend mit einem vollständigen Segment überschreiben,sobald ein nachgelagerter Aufruf abgeschlossen ist.
Die folgenden Felder sind für Untersegmente erforderlich oder in einigen Fällen notwendig.
Note
Werte sind Zeichenfolgen, die aus bis zu 250 Zeichen bestehen, soweit nicht anders angegeben.
Erforderliche Untersegmentsfelder
• id – Eine 64-Bit-Kennung in 16 Hexadezimalziffern für das Untersegment, die sich eindeutig vonanderen Segmenten in derselben Ablaufverfolgung unterscheidet.
• name – Der logische Name des Untersegments. Benennen Sie bei nachgelagerten Aufrufen dasUntersegment, nachdem die Ressource oder der Service aufgerufen wurde. Benennen Sie beibenutzerdefinierten Untersegmenten das Untersegment nach dem genutzten Code (z. B. einemFunktionsnamen).
• start_time – Zahl, die den Erstellungszeitpunkt des Untersegments in Gleitkommasekundenseit Epoche, bis auf Millisekunden genau, angibt. Zum Beispiel 1480615200.010 oder1.480615200010E9.
• end_time – Zahl, die angibt, wann das Untersegment geschlossen wurde. Zum Beispiel1480615200.090 oder 1.480615200090E9. Geben Sie eine end_time oder in_progress ein.
• in_progress – Boolescher Wert, der auf true festgelegt wurde, anstatt eine end_time anzugeben,um aufzuzeichnen, dass das Untersegment begonnen, aber nicht abgeschlossen wurde. SendenSie pro nachgelagerter Anfrage nur ein vollständiges Untersegment und ein oder kein angefangenesUntersegment.
• trace_id – Ablaufverfolgungs-ID des übergeordneten Segments des Untersegments. Nur erforderlich,wenn ein Untersegment separat gesendet wird.
Format der Ablaufverfolgungs-ID
Eine trace_id besteht aus drei durch Bindestriche getrennte Zahlen. Beispiel, 1-58406520-a006649127e371903a2de979. Dies umfasst:• Die Versionsnummer 1.• Die Zeit der ursprünglichen Anforderung als Zeit seit Unix-Epoche und in 8 Hexadezimalziffern
ausgedrückt.
Beispiel: 10:00 Uhr 1. Dezember 2016 PST entspricht einer Epoch-Zeit von 1480615200 Sekundenoder in hexadezimalen Ziffern ausgedrückt 58406520.
• Eine 96-Bit-Kennzeichnung für die Ablaufverfolgung, global eindeutig, in 24 Hexadezimalziffern.• parent_id – Segments-ID des übergeordneten Segments des Untersegments. Nur erforderlich, wenn
ein Untersegment separat gesendet wird.• type – subsegment. Nur erforderlich, wenn ein Untersegment separat gesendet wird.
Die folgenden Felder sind für Untersegmente optional.
77
AWS X-Ray EntwicklerhandbuchHTTP-Anfragedaten
Optionale Untersegmentsfelder
• namespace – aws für AWS-SDK-Aufrufe remote für andere nachgelagerte Aufrufe.• http – http (p. 78) Objekt mit Informationen zu einem ausgehenden HTTP-Aufruf.• aws – aws (p. 81) Objekt mit Informationen über die nachgelagerte AWS-Ressource, die Ihre
Anwendung aufgerufen hat.• error, throttle, fault und cause – Fehler (p. 83)felder, die einen aufgetretenen Fehler angeben
und Informationen über die Ausnahme enthalten, die den Fehler verursacht hat.• annotations – annotations (p. 80) Objekt mit Schlüsselwertpaaren, die X-Ray zur Suche
indizieren soll.• metadata – metadata (p. 80) Objekt mit zusätzlichen Daten, die in einem Segment gespeichert
werden sollen.• subsegments – Array von subsegment (p. 75) Objekten.• precursor_ids – Array von Untersegments-IDs, das Untersegmente mit dem gleichen übergeordneten
Segment identifiziert, das vor diesem Untersegment vervollständigt wurde.
HTTP-AnfragedatenVerwenden Sie einen HTTP-Block, um Details zu einer HTTP-Anforderung aufzuzeichnen, die IhrerAnwendung (in einem Segment) dient oder die Ihre Anwendung (in einem Untersegment) an einenachgelagerte HTTP-API gestellt hat. Die meisten Felder in dieser Objektübersicht gehören zuInformationen von HTTP-Anforderungen und -Antworten.
http
Alle Felder sind optional.
• request – Informationen zu einer Anforderung.• method – Die Anforderungsmethode. Beispiel, GET.• url – Die vollständige URL der Anforderung, aus dem Protokoll, dem Hostname und dem
Anforderungspfad.• user_agent – Die Zeichenfolge des Benutzeragenten vom Client des Auftraggebers.• client_ip – Die IP-Adresse des Auftraggebers. Kann im IP-Paket Source Address oder, für
weitergeleitete Anforderungen, in einem X-Forwarded-For-Header eingesehen werden.• x_forwarded_for – (nur Segmente) Boolescher Wert, der angibt, dass die client_ip aus einemX-Forwarded-For-Header stammt und nicht verlässlich ist, weil sie gefälscht sein könnte.
• traced – (nur Subsegmente) Boolescher Wert, der angibt, dass der nachgelagerte Aufruf einweiterer rückverfolgter Dienst ist. Wenn dieses Feld auf true eingestellt ist, erachtet X-Ray dieAblaufverfolgung als beschädigt, bis der nachgelagerte Service ein Segment mit einer parent_idhochlädt, das der id des Untersegments mit dem Block entspricht.
• response – Informationen über eine Antwort.• status – Zahl, die den HTTP-Status der Antwort angibt.• content_length – Zahl, die die Länge des Antworttexts in Byte angibt.
Wenn Sie einen Aufruf einer nachgelagerten Web-API instrumentieren, erfassen Sie ein Untersegment mitInformationen über die HTTP-Anforderung und die Antwort. X-Ray verwendet das Untersegment, um einabgeleitetes Segment für die entfernte API zu generieren.
Example Segment für einen HTTP-Aufruf, der von einer Anwendung, die über Amazon EC2ausgeführt wird, bedient wird.
{
78
AWS X-Ray EntwicklerhandbuchHTTP-Anfragedaten
"id": "6b55dcc497934f1a", "start_time": 1484789387.126, "end_time": 1484789387.535, "trace_id": "1-5880168b-fd5158284b67678a3bb5a78c", "name": "www.example.com", "origin": "AWS::EC2::Instance", "aws": { "ec2": { "availability_zone": "us-west-2c", "instance_id": "i-0b5a4678fc325bg98" }, "xray": { "sdk_version": "1.3.1 for Java" }, }, "http": { "request": { "method": "POST", "client_ip": "78.255.233.48", "url": "http://www.example.com/api/user", "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0", "x_forwarded_for": true }, "response": { "status": 200 } }
Example Untersegment für einen nachgelagerten HTTP-Aufruf
{ "id": "004f72be19cddc2a", "start_time": 1484786387.131, "end_time": 1484786387.501, "name": "names.example.com", "namespace": "remote", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } }}
Example Abgeleitetes Segment für einen nachgelagerten HTTP-Anruf
{ "id": "168416dc2ea97781", "name": "names.example.com", "trace_id": "1-5880168b-fd5153bb58284b67678aa78c", "start_time": 1484786387.131, "end_time": 1484786387.501, "parent_id": "004f72be19cddc2a", "http": { "request": { "method": "GET", "url": "https://names.example.com/" },
79
AWS X-Ray EntwicklerhandbuchAnmerkungen
"response": { "content_length": -1, "status": 200 } }, "inferred": true}
AnmerkungenSegmente und Untersegmente können ein annotations-Objekt umfassen, das ein oder mehrere von X-Ray indizierte Felder zur Verwendung mit Filterausdrücken enthält. Felder können eine Zeichenfolge, Zahloder einen booleschen Werte (keine Objekte oder Arrays) umfassen.
Example Segment für HTTP-Aufrufe mit Anmerkungen
{ "id": "6b55dcc497932f1a", "start_time": 1484789187.126, "end_time": 1484789187.535, "trace_id": "1-5880168b-fd515828bs07678a3bb5a78c", "name": "www.example.com", "origin": "AWS::EC2::Instance", "aws": { "ec2": { "availability_zone": "us-west-2c", "instance_id": "i-0b5a4678fc325bg98" }, "xray": { "sdk_version": "1.3.1 for Java" }, }, "annotations": { "customer_category" : 124, "zip_code" : 98101, "country" : "United States", "internal" : false }, "http": { "request": { "method": "POST", "client_ip": "78.255.233.48", "url": "http://www.example.com/api/user", "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0", "x_forwarded_for": true }, "response": { "status": 200 } }
Die Schlüssel müssen alphanumerisch sein, um mit Filtern funktionieren zu können. Unterstriche sindzulässig. Andere Zeichen und Leerzeichen sind nicht zulässig.
MetadataSegmente und Untersegmente können ein metadata-Objekt umfassen, das ein oder mehrere Feldermit Werten jeglicher Art, einschließlich Objekten und Arrays, enthält. X-Ray indiziert keine Metadaten.Werte können jede Größe haben, so lange das Segmentdokument die Maximalgröße (64 kB) nicht
80
AWS X-Ray EntwicklerhandbuchAWS-Ressourcendaten
übersteigt. Sie können Metadaten im vollständigen Segmentdokument, das von der BatchGetTraces-API zurückgesendet wurde, einsehen. Feldschlüssel (debug im folgenden Beispiel) beginnen mit AWS. undsind für den Gebrauch durch von AWS bereitgestellten SDKs und Clients reserviert.
Example Individuelles Untersegment mit Metadaten
{ "id": "0e58d2918e9038e8", "start_time": 1484789387.502, "end_time": 1484789387.534, "name": "## UserModel.saveUser", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } }, "subsegments": [ { "id": "0f910026178b71eb", "start_time": 1484789387.502, "end_time": 1484789387.534, "name": "DynamoDB", "namespace": "aws", "http": { "response": { "content_length": 58, "status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "3AIENM5J4ELQ3SPODHKBIRVIC3VV4KQNSO5AEMVJF66Q9ASUAAJG", "resource_names": [ "scorekeep-user" ] } } ]}
AWS-RessourcendatenBei Segmenten enthält das aws-Objekt Informationen zu den Ressourcen, auf denen Ihre Anwendungausgeführt wird. Mehrere Felder können für eine einzelne Ressource zutreffen. Eine Anwendung in einerMulticontainer-Docker-Umgebung auf Elastic Beanstalk könnte beispielsweise Informationen über dieAmazon EC2-Instance, den Amazon ECS-Container in der Instance und die Elastic Beanstalk-Umgebungan sich haben.
aws (Segmente)
Alle Felder sind optional.
• account_id – Zeichnen Sie die ID des Kontos, auf dem Ihre Anwendung aufgeführt wird, auf, wenn IhreAnwendung Segmente an verschiedene AWS-Konten sendet.
• ecs – Informationen zu einem Amazon ECS-Container.• container – Die Container-ID des Containers, der Ihre Anwendung ausführt.
• ec2 – Informationen zu einer EC2-Instance.• instance_id – Die Instance-ID der EC2-Instance.
81
AWS X-Ray EntwicklerhandbuchAWS-Ressourcendaten
• availability_zone – Die Availability Zone an, in der die Instanz ausgeführt wird.
Example AWS-Block mit Plugins
"aws": { "elastic_beanstalk": { "version_label": "app-5a56-170119_190650-stage-170119_190650", "deployment_id": 32, "environment_name": "scorekeep" }, "ec2": { "availability_zone": "us-west-2c", "instance_id": "i-075ad396f12bc325a" }, "xray": { "sdk": "1.3.1 for Java" }}
• elastic_beanstalk – Informationen über eine Elastic Beanstalk-Umgebung. Sie findendiese Informationen in einer Datei mit der Bezeichnung /var/elasticbeanstalk/xray/environment.conf auf den neuesten Elastic Beanstalk-Plattformen.• environment_name – Der Name der Umgebung.• version_label – Der Name der Anwendungsversion, die aktuell für die Instance, die die
Anforderung bearbeitet, bereitgestellt wird.• deployment_id – Zahl, die die ID der letzten erfolgreichen Bereitstellung in der Instance angibt,
welche die Anforderung bearbeitet hat.
Bei Untersegmenten zeichnen Sie Informationen über den AWS-Service und Ressourcen auf, auf die IhreAnwendung zugreift. X-Ray erstellt anhand dieser Daten abgeleitete Segmente, die die nachgelagertenServices in Ihrer Service-Übersicht widerspiegeln.
aws (Untersegmente)
Alle Felder sind optional.
• operation – Der Name der API-Aktion, die bei jedem AWS-Service oder jeder Ressource aufgerufenwird.
• account_id – Wenn Ihre Anwendung auf die Ressourcen eines anderen Kontos zugreift oderSegmente an ein anderes Konto sendet, zeichnen Sie die Konto-ID des Kontos auf, zu dem die AWS-Ressource gehört und auf das Ihre Anwendung zugreift.
• region – Wenn sich die Ressource in einer anderen Region als Ihre Anwendung befindet, zeichnen Siediese Region auf. Beispiel, us-west-2.
• request_id – Eindeutige Bezeichnung für die Anforderung.• queue_url – Für Vorgänge in einer Amazon SQS-Warteschlange, die URL der Warteschlange.• table_name – Für Vorgänge in einer DynamoDB-Tabelle, den Namen der Tabelle.
Example Untersegment für einen Aufruf von DynamoDB zum Speichern eines Elements
{ "id": "24756640c0d0978a", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "DynamoDB", "namespace": "aws", "http": {
82
AWS X-Ray EntwicklerhandbuchFehler und Ausnahmen
"response": { "content_length": 60, "status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG", }}
Fehler und AusnahmenWenn ein Fehler auftritt, können Sie die Einzelheiten zum Fehler und den Ausnahmen, die er generiert,aufzeichnen. Zeichnen Sie Fehler in Segmenten auf, wenn Ihre Anwendung einen Fehler an den Benutzerzurückgibt, sowie in Untersegmenten, wenn ein nachgelagerter Aufruf einen Fehler ausgibt.
Fehlertypen
Stellen Sie ein oder mehrere der folgenden Felder auf true ein, um anzuzeigen, dass ein Fehleraufgetreten ist. Bei schwerwiegenden Fehlern können mehrere Typen ausgewählt werden. Ein 429 TooMany Requests-Fehler von einem nachgelagerten Aufruf kann beispielsweise dazu führen, dass IhreAnwendung zu einem 500 Internal Server Error zurückkehrt. In diesem Fall treffen alle drei Typenzu.
• error – Boolescher Wert, der angibt, ob ein Client-Fehler aufgetreten ist (Antwortstatuscode: 4XX-Client-Fehler).
• throttle – Boolescher Wert, der angibt, dass eine Anforderung gedrosselt wurde (Antwortstatuscode:429 Zu viele Anfragen).
• fault – Boolescher Wert, der angibt, ob ein Server-Fehler aufgetreten ist (Antwortstatuscode: 5XX-Server-Fehler).
Geben Sie die Fehlerursache an, indem Sie im Segment oder Untersegment ein Ursachenobjekteinschließen.
cause
Eine Ursache kann entweder eine 16-stellige Ausnahmen-ID oder ein Objekt mit den folgenden Feldernsein:
• working_directory – Die vollständigen Pfad des Arbeitsverzeichnisses bei Auftreten der Aufnahme.• paths – Das Array von Bibliothekspfaden oder -modulen, die verwendet wurden, als der Fehler auftrat.• exceptions – Das Array von Ausnahmenobjekten.
Geben Sie detaillierte Informationen über die Fehler in einem oder mehreren Ausnahmenobjekten an.
exception
Alle Felder sind optional außer id.
• id – Eine 64-Bit-Kennung mit 16 Hexadezimalziffern für die Ausnahme, die sich eindeutig von denSegmenten in derselben Ablaufverfolgung unterscheidet.
• message – Die Ausnahmenachricht.• type – Die Ausnahmeart.
83
AWS X-Ray EntwicklerhandbuchSQL-Abfragen
• remote – Boolescher Wert, der angibt, dass die Ausnahme durch einen Fehler, der von einemnachgelagerten Dienst zurückgegeben wurde, verursacht wurde.
• truncated – Ganzzahl, welche die Anzahl der Stack-Rahmen, die vom stack unterdrückt werden,angibt.
• skipped – Ganzzahl, für die Anzahl der Ausnahmen, die zwischen dieser Ausnahme und deruntergeordneten Ausnahme, welche die Ausnahme verursacht hat, übersprungen wurden.
• cause – Ausnahmen-ID der übergeordneten Ausnahme, d. h. die Ausnahme, welche die Ausnahmeverursacht hat.
• stack – Array von stackFrame-Objekten.
Falls verfügbar, zeichnen Sie Informationen zu dem Aufruf-Stack in stackFrame-Objekten auf.
stackFrame
Alle Felder sind optional.
• path – Der relative Pfad der Datei.• line – Die Zeile in der Datei.• label – Der Funktions- oder Methodenname.
SQL-AbfragenFür Anfragen, die Ihre Anwendung in eine SQL-Datenbank umwandeln, können Sie Untersegmenteerstellen.
sql
Alle Felder sind optional.
• connection_string – Zeichnen Sie für SQL-Server oder andere Datenbankverbindungen, die keineURL-Verbindungszeichenfolgen nutzen, die Verbindungszeichenfolge ohne Passwörter auf.
• url – Zeichnen Sie für eine Datenbankverbindung, die eine URL-Verbindungszeichenfolge nutzt, dieURL ohne Passwörter auf.
• sanitized_query – Die Datenbankanfrage mit von Benutzern eingegeben Werten werden durch einenPlatzhalter ersetzt.
• database_type – Der Name des Datenbank-Engine.• database_version – Die Versionsnummer des Datenbank-Engines.• driver_version – Der Namen und die Versionsnummer des Datenbank-Engine-Treibers, die Ihre
Anwendung nutzt.• user – Der Datenbankbenutzername.• preparation – call, wenn die Abfrage eine PreparedCall nutzt; statement, wenn die Abfrage
eine PreparedStatement nutzt.
Example Untersegment mit einer SQL-Abfrage
{ "id": "3fd8634e78ca9560", "start_time": 1484872218.696, "end_time": 1484872218.697, "name": "[email protected]", "namespace": "remote", "sql" : {
84
AWS X-Ray EntwicklerhandbuchSQL-Abfragen
"url": "jdbc:postgresql://aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com:5432/ebdb", "preparation": "statement", "database_type": "PostgreSQL", "database_version": "9.5.4", "driver_version": "PostgreSQL 9.4.1211.jre7", "user" : "dbuser", "sanitized_query" : "SELECT * FROM customers WHERE customer_id=?;" }}
85
AWS X-Ray EntwicklerhandbuchVerwaltete IAM-Richtlinien für X-Ray
AWS X-Ray-BerechtigungenSie können mit AWS Identity and Access Management (IAM) Benutzern undDatenverarbeitungsressourcen in Ihrem Konto X-Ray-Berechtigungen gewähren. IAM steuert den Zugriffauf den X-Ray-Service auf API-Ebene zur einheitlichen Durchsetzung von Berechtigungen, unabhängigdavon, welchen Client (Konsole, AWS-SDK, AWS CLI) Ihre Benutzer verwenden.
Um die X-Ray-Konsole (p. 29) zur Anzeige von Service-Übersichten und Segmenten zu verwenden,benötigen Sie lediglich Leseberechtigungen. Um den Zugriff auf die Konsole zu ermöglichen, fügen SieIhrem IAM-Benutzer die AWSXrayReadOnlyAccess verwaltete Richtlinie (p. 86) hinzu.
Für lokale Entwicklung und Tests (p. 87) erstellen Sie einen IAM-Benutzer mit Lese- undSchreibberechtigungen. Generieren Sie Zugriffsschlüssel für den Benutzer und speichern Sie sie amStandard-AWS-SDK-Speicherort. Sie können diese Anmeldeinformationen mit dem X-Ray-Daemon, derAWS CLI und dem AWS SDK verwenden.
Zur Bereitstellung Ihrer instrumentierten App für AWS (p. 88) erstellen Sie eine IAM-Rolle mitSchreibberechtigungen und weisen Sie sie den Ressourcen zu, die Ihre Anwendung ausführen.
Abschnitte• Verwaltete IAM-Richtlinien für X-Ray (p. 86)• Lokale Ausführung Ihrer Anwendung (p. 87)• Ausführung Ihrer Anwendung in AWS (p. 88)
Verwaltete IAM-Richtlinien für X-RayUm die Gewährung von Berechtigungen zu vereinfachen, unterstützt IAM verwaltete Richtlinien für jedenService. Ein Service kann diese verwalteten Richtlinien mit neuen Berechtigungen aktualisieren, wenn neueAPIs freigegeben werden. AWS X-Ray bietet verwaltete Richtlinien (p. 86) für Nur-Lese-, Nur-Schreib-und Lese-/Schreib-Anwendungsfälle.
• AWSXrayReadOnlyAccess – Leseberechtigungen für die Verwendung der X-Ray-Konsole, der AWSCLI oder des AWS SDK zum Abruf von Ablaufverfolgungsdaten und Service-Übersichten von der X-Ray-API.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "xray:BatchGetTraces", "xray:GetServiceGraph", "xray:GetTraceGraph", "xray:GetTraceSummaries" ], "Resource": [ "*" ] } ]
86
AWS X-Ray EntwicklerhandbuchLokale Ausführung Ihrer Anwendung
}
• AWSXrayWriteOnlyAccess – Schreibberechtigungen für die Verwendung des X-Ray-Daemon, derAWS CLI oder des AWS SDK zum Hochladen von Segmentdokumenten und von Telemetriedaten zur X-Ray-API.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "xray:PutTraceSegments", "xray:PutTelemetryRecords" ], "Resource": [ "*" ] } ]}
• AWSXrayFullAccess –-Lese-/Schreibberechtigungen.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "xray:*" ], "Resource": [ "*" ] } ]}
• AmazonS3ReadOnlyAccess – Berechtigung für den Benutzer oder die Ressource zum Herunterladendes X-Ray-Daemons von Amazon S3.
So fügen Sie einem IAM-Benutzer, einer Gruppe oder einer Rolle eine veraltete Richtlinie hinzu:
1. Öffnen Sie die IAM-Konsole.2. Öffnen Sie die Rolle, die Ihrem Instance-Profil, einem IAM-Benutzer oder einer IAM-Gruppe
zugewiesen ist.3. Fügen Sie unter Berechtigungen die verwaltete Richtlinie an.
Lokale Ausführung Ihrer AnwendungIhre instrumentierte Anwendung sendet Ablaufverfolgungsdaten an den X-Ray-Daemon. Der Daemonpuffert Segmentdokumente und lädt sie in Stapeln in den X-Ray-Service hoch. Der Daemon benötigtSchreibberechtigungen zum Hochladen von Ablaufverfolgungsdaten und Telemetrie zum X-Ray-Service.
Wenn Sie den Daemon lokal ausführen (p. 117), speichern Sie den Zugriffsschlüssel und denGeheimschlüssel Ihres IAM-Benutzers in einer Datei mit der Bezeichnung credentials in einem Ordnermit der Bezeichnung .aws in Ihrem Benutzerordner.
87
AWS X-Ray EntwicklerhandbuchAusführung Ihrer Anwendung in AWS
Example ~/.aws/credentials
[default]aws_access_key_id=AKIAIOSFODNN7EXAMPLEaws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Wenn Sie bereits Anmeldeinformationen zur Verwendung mit dem AWS SDK oder der AWS CLIkonfiguriert haben, kann der Daemon diese verwenden. Wenn mehrere Profile verfügbar sind, verwendetder Daemon das Standard-Profil.
Ausführung Ihrer Anwendung in AWSWenn Sie Ihre Anwendung in AWS ausführen, verwenden Sie eine Rolle zum gewähren der Berechtigungzur Amazon EC2-Instance oder zur Lambda-Funktion, die den Daemon ausführt.
• Amazon Elastic Compute Cloud – Erstellen Sie eine IAM-Rolle und fügen Sie sie an die EC2 Instance alsInstance-Profil an.
• Amazon Elastic Container Service – Erstellen Sie eine IAM-Rolle und fügen Sie sie an Container-Instances als Container-Instance-IAM-Rolle an.
• AWS Elastic Beanstalk – Elastic Beanstalk enthält X-Ray-Berechtigungen in seinen Standard-Instance-Profilen. Sie können das Standard-Instance-Profil verwenden oder einem benutzerdefinierten Instance-Profil Schreibberechtigungen hinzufügen.
• AWS Lambda – fügen Sie der Ausführungsrolle Ihrer Funktion Schreibberechtigungen hinzu.
So erstellen Sie eine Rolle für die Verwendung mit X-Ray:
1. Öffnen Sie die IAM-Konsole.2. Wählen Sie Roles.3. Klicken Sie auf Create New Role.4. Geben Sie für Rollenname xray-application ein. Klicken Sie auf Next Step.5. Wählen Sie für Rollentyp Amazon EC2.6. Fügen Sie verwaltete Richtlinien an, um Ihrer Anwendung den Zugriff auf AWS-Services zu
ermöglichen.
• AWSXrayWriteOnlyAccess – gibt dem X-Ray-Daemon die Berechtigung zum Hochladen vonAblaufverlaufsdaten.
• AmazonS3ReadOnlyAccess (nur Amazon EC2) – gibt der Instance die Berechtigung zum Downloaddes X-Ray-Daemons von Amazon S3.
Wenn Ihre Anwendung das AWS-SDK für den Zugriff auf andere Services verwendet, fügen SieRichtlinien hinzu, die diesen Services den Zugriff ermöglichen.
7. Klicken Sie auf Next Step.8. Wählen Sie Create Role aus.
88
AWS X-Ray Entwicklerhandbuch
AWS X-Ray-BeispielanwendungDie AWS X-Ray-Beispielanwendung eb-java-scorekeep auf GitHub zeigt die Verwendung des AWS-X-Ray-SDK für die Instrumentierung eingehender HTTP-Aufrufes, von DynamoDB-SDK-Clients undHTTP-Clients. Die Beispielanwendung verwendet AWS Elastic Beanstalk-Funktionen, um DynamoDB-Tabellen zu erstellen, Java-Code auf der Instance zu kompilieren und den X-Ray-Daemon ohne zusätzlicheKonfiguration auszuführen.
Das Beispiel ist eine instrumentierte Version des Scorekeep-Projekts in AWSLabs. Es enthält eine Front-End-Web-App, die aufgerufene API und die DynamoDB-Tabellen, die zum Speichern von Daten verwendetwerden. Alle Komponenten werden in einer Elastic Beanstalk-Umgebung gehostet, um Portabilität und eineeinfache Bereitstellung zu ermöglichen.
Die grundlegende Instrumentierung mit Filtern (p. 135), Plugins (p. 130) und instrumentierten AWSSDK-Clients (p. 138) wird in der Projektverzweigung xray-gettingstarted dargestellt. Dies istdie Verzweigung, die Sie im Tutorial "Erste Schritte" (p. 8) bereitstellen. Da diese Verzweigung nur dieGrundlagen beinhaltet, können Sie einen diff-Vorgang mit der master-Verzweigung durchführen, umschnell die Grundlagen zu erfassen.
89
AWS X-Ray Entwicklerhandbuch
Die Beispielanwendung veranschaulicht die grundlegende Instrumentierung in folgenden Dateien:
• HTTP-Anforderungsfilter – WebConfig.java• AWS SDK Client-Instrumentierung – build.gradle
Die xray-Verzweigung der Anwendung fügt die Verwendung von HTTP-Client (p. 139),Anmerkungen (p. 144), SQL-Abfragen (p. 141), benutzerdefinierten Untersegmenten (p. 142),einer instrumentierten AWS Lambda (p. 229)-Funktion und instrumentierten Initialisierungscodes undSkripten (p. 103) hinzu. Diese Service-Übersicht zeigt die xray-Verzweigung, die ohne verbundene SQL-Datenbank ausgeführt wird:
90
AWS X-Ray Entwicklerhandbuch
Zur Unterstützung der Benutzeranmeldung und der Verwendung von AWS SDK for JavaScript im Browserfügt die xray-cognito-Verzweigung Amazon Cognito hinzu, um eine Benutzer-Authentifizierung und-Autorisierung zu unterstützen. Mit Anmeldeinformationen aus Amazon Cognito sendet die Web-Appaußerdem Ablaufverfolgungsdaten an X-Ray, um Anfrageinformationen aus Sicht des Clients zu erfassen.Der Browser-Client wird als separater Knoten in der Service-Übersicht angezeigt und zeichnet weitereInformationen auf, einschließlich der URL der Seite, die der Benutzer sich ansieht, und der Benutzer-ID.
Die xray-worker-Verzweigung fügt eine instrumentierte Python Lambda-Funktion hinzu, die unabhängigausgeführt wird und Elemente aus einer Amazon SQS-Warteschlange verarbeitet. Scorekeep fügtein Element zur Warteschlange hinzu, wenn ein Spiel endet. Der von CloudWatch Events ausgelöste
91
AWS X-Ray Entwicklerhandbuch
Lambda Worker, ruft alle paar Minuten Elemente aus der Warteschlange ab und verarbeitet diese, umSpieledatensätze in Amazon S3 für die Analyse zu speichern.
Wenn alle Funktionen aktiviert sind, sieht die Service-Übersicht von Scorekeep wie folgt aus:
92
AWS X-Ray EntwicklerhandbuchAWS SDK-Clients
Anweisungen dazu, wie Sie die Beispielanwendung mit X-Ray verwenden, finden Sie im Tutorial ErsteSchritte (p. 8). Zusätzlich zu der in diesem Tutorial erörterten grundlegenden Nutzung des X-Ray SDK forJava zeigt das Beispiel außerdem, wie die folgenden Funktionen verwendet werden.
Erweiterte Funktionen• Manuelles Instrumentieren von AWS SDK-Clients (p. 93)• Erstellen zusätzlicher Untersegmente (p. 93)• Aufzeichnung von Anmerkungen, Metadaten und Benutzer-IDs (p. 94)• Instrumentieren von ausgehenden HTTP-Aufrufen (p. 95)• Instrumentieren von Aufrufen einer PostgreSQL-Datenbank (p. 95)• Instrumentieren von AWS Lambda-Funktionen (p. 98)• Instrumentierung von Amazon ECS Anwendungen (p. 102)• Instrumentieren von Startup-Code (p. 103)• Instrumentieren von Skripten (p. 104)• Instrumentieren eines Web-App-Clients (p. 106)• Verwenden instrumentierter Clients in Auftragnehmer-Threads (p. 109)• Deep Linking mit der X-Ray-Konsole (p. 111)
Manuelles Instrumentieren von AWS SDK-ClientsDas X-Ray SDK for Java instrumentiert automatisch alle AWS SDK-Clients, wenn Sie das UntermodulAWS SDK Instrumentor in Ihre Build-Abhängigkeiten aufnehmen (p. 129).
Sie können die automatische Client-Instrumentierung durch Löschen des Instrumentor-Untermodulsdeaktivieren. Auf diese Weise können Sie einige Clients manuell instrumentieren und andere ignorierenoder verschiedene Tracing-Handler auf unterschiedlichen Clients anwenden.
Zur Veranschaulichung der Unterstützung für die Instrumentierung bestimmter AWS SDK-Clientsübergibt die Anwendung einen Ablaufverfolgungshandler an AmazonDynamoDBClientBuilder alsAnforderungshandler im Benutzer-, Spiel- und Sitzungsmodell. Diese Codeänderung teilt dem SDK mit, alleAufrufe an DynamoDB mithilfe dieser Clients zu instrumentieren.
Example src/main/java/scorekeep/SessionModel.java – Manuelle AWS-SDK-Client-Instrumentierung
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.handlers.TracingHandler;
public class SessionModel { private AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard() .withRegion(Constants.REGION) .withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder())) .build(); private DynamoDBMapper mapper = new DynamoDBMapper(client);
Wenn Sie das Untermodul AWS SDK Instrumentor aus Projektabhängigkeiten entfernen, werden nur diemanuell instrumentierten AWS SDK-Clients in der Service-Übersicht angezeigt.
Erstellen zusätzlicher UntersegmenteIn der Benutzermodellklasse erstellt die Anwendung manuell Untersegmente, um alle nachgelagertenAufrufe, die innerhalb der saveUser-Funktion vorgenommen wurden, zu gruppieren, und fügt Metadatenhinzu.
93
AWS X-Ray EntwicklerhandbuchAnmerkungen und Metadaten
Example src/main/java/scorekeep/UserModel.java - Benutzerdefinierte Untersegmente
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.entities.Subsegment;... public void saveUser(User user) { // Wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## UserModel.saveUser"); try { mapper.save(user); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } }
Aufzeichnung von Anmerkungen, Metadaten undBenutzer-IDs
In der Spielmodellklasse erfasst die Anwendung jedes Mal Game-Objekte in einem Metadaten (p. 146)-Block, wenn ein Spiel in DynamoDB gespeichert wird. Unabhängig davon erfasst die Anwendung Spiel-IDsin Anmerkungen (p. 144) zur Verwendung mit Filterausdrücken (p. 39).
Example src/main/java/scorekeep/GameModel.java – Anmerkungen und Metadaten
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.entities.Segment;import com.amazonaws.xray.entities.Subsegment;... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } Segment segment = AWSXRay.getCurrentSegment(); subsegment.putMetadata("resources", "game", game); segment.putAnnotation("gameid", game.getId()); mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } }
Im Bewegungs-Controller erfasst die Anwendung Benutzer-IDs (p. 147) mit setUser. Benutzer-IDswerden in einem eigenen Feld aufgezeichnet und zur Suche indiziert.
Example src/main/java/scorekeep/MoveController.java – Benutzer-ID
import com.amazonaws.xray.AWSXRay;
94
AWS X-Ray EntwicklerhandbuchHTTP-Clients
... @RequestMapping(value="/{userId}", method=RequestMethod.POST) public Move newMove(@PathVariable String sessionId, @PathVariable String gameId, @PathVariable String userId, @RequestBody String move) throws SessionNotFoundException, GameNotFoundException, StateNotFoundException, RulesException { AWSXRay.getCurrentSegment().setUser(userId); return moveFactory.newMove(sessionId, gameId, userId, move); }
Instrumentieren von ausgehenden HTTP-AufrufenDie "User Factory"-Klasse zeigt, wie die Anwendung die Version HTTPClientBuilder des X-Ray SDK forJava zum Instrumentieren ausgehender HTTP-Aufrufe verwendet.
Example src/main/java/scorekeep/UserFactory.java – HTTPClient-Instrumentierung
import com.amazonaws.xray.proxies.apache.http.HttpClientBuilder;
public String randomName() throws IOException { CloseableHttpClient httpclient = HttpClientBuilder.create().build(); HttpGet httpGet = new HttpGet("http://uinames.com/api/"); CloseableHttpResponse response = httpclient.execute(httpGet); try { HttpEntity entity = response.getEntity(); InputStream inputStream = entity.getContent(); ObjectMapper mapper = new ObjectMapper(); Map<String, String> jsonMap = mapper.readValue(inputStream, Map.class); String name = jsonMap.get("name"); EntityUtils.consume(entity); return name; } finally { response.close(); } }
Wenn Sie derzeit org.apache.http.impl.client.HttpClientBuilder verwenden,können Sie einfach die Import-Anweisung für die Klasse mit einer Anweisung fürcom.amazonaws.xray.proxies.apache.http.HttpClientBuilder austauschen.
Instrumentieren von Aufrufen einer PostgreSQL-Datenbank
Die Datei application-pgsql.properties fügt der in RdsWebConfig.java erstellen Datenquelleeinen X-Ray PostgreSQL-Ablaufverfolgungs-Interceptor hinzu.
Example application-pgsql.properties – PostgreSQL-Datenbank-Instrumentierung
spring.datasource.continue-on-error=truespring.jpa.show-sql=falsespring.jpa.hibernate.ddl-auto=create-dropspring.datasource.jdbc-interceptors=com.amazonaws.xray.sql.postgres.TracingInterceptorspring.jpa.database-platform=org.hibernate.dialect.PostgreSQL94Dialect
95
AWS X-Ray EntwicklerhandbuchSQL-Clients
Note
Weitere Informationen zum Hinzufügen einer PostgreSQL-Datenbank zum Anwendungsumfeldfinden Sie unter Konfiguration von Datenbanken mit Elastic Beanstalk im AWS Elastic Beanstalk-Entwicklerhandbuch.
Die X-Ray-Demo-Seite im xray-Bereich umfasst eine Demonstration, die instrumentierte Datenquellennutzt, um Ablaufverfolgungen zu generieren, die Informationen zu den erzeugten SQL-Abfragenanzeigt. Navigieren Sie zu dem /#/xray-Pfad in der laufenden Anwendung oder wählen Sie in derNavigationsleiste Powered by AWS X-Ray aus, um die Demo-Seite anzusehen.
96
AWS X-Ray EntwicklerhandbuchSQL-Clients
97
AWS X-Ray EntwicklerhandbuchAWS Lambda-Funktionen
Wählen Sie SQL-Abfragen nachverfolgen aus, um Spielsitzungen zu simulieren und die Ergebnisse inder zugehörigen Datenbank zu speichern. Wählen Sie dann Ablaufverfolgungen in AWS X-Ray anzeigen,um eine gefilterte Liste der Ablaufverfolgungen anzuzeigen, die auf die /api/history-Route der APIgetroffen sind.
Wählen Sie eine der Ablaufverfolgungen aus der Liste aus, um die Zeitleiste, einschließlich der SQL-Abfrage, ansehen zu können.
Instrumentieren von AWS Lambda-FunktionenScorekeep unterstützt zwei AWS Lambda-Funktionen. Bei der ersten handelt es sich um eine Node.js-Funktion der lambda-Verzweigung, die zufällige Namen für neue Benutzer generiert. Wenn ein Benutzereine Sitzung erstellt, ohne einen Namen einzugeben, ruft die Anwendung eine Funktion namens random-name mit dem AWS SDK for Java auf. Das X-Ray SDK for Java zeichnet Informationen zu dem Aufruf anLambda in einem Untersegment auf, genau, wie bei jedem anderen Aufruf mit einem instrumentierten AWSSDK-Client.
Note
Das Ausführen der Lambda-Funktion random-name erfordert die Erstellung weiterer Ressourcenaußerhalb der Elastic Beanstalk-Umgebung. Weitere Informationen und Anleitungen finden Sie imReadme-Text: AWS Lambda-Integration.
Die zweite Funktion, scorekeep-worker, ist eine Python-Funktion, die unabhängig von der Scorekeep-API ausgeführt wird. Wenn ein Spiel endet, schreibt die API die Sitzungs- und Spiele-ID in eine SQS-Warteschlange. Die Worker-Funktion liest Elemente aus der Warteschlange und ruft die Scorekeep-APIauf, um für die Speicherung in Amazon S3 vollständige Datensätze für jede Spielesitzung zu erstellen.
Scorekeep enthält AWS CloudFormation-Vorlagen und -Skripte zum Erstellen beider Funktionen. Da Siedas X-Ray-SDK mit dem Funktionscode bündeln müssen, werden die Funktionen über die Vorlagen ohneCode erstellt. Wenn Sie Scorekeep bereitstellen, erstellt eine im Ordner .ebextensions enthalteneKonfigurationsdatei ein Quell-Bundle, in dem das SDK enthalten ist, und aktualisiert den Funktionscode unddie Konfiguration mit der AWS Command Line Interface.
Funktionen• Zufälliger Name (p. 99)• Worker (p. 100)
98
AWS X-Ray EntwicklerhandbuchZufälliger Name
Zufälliger NameScorekeep ruft die Funktion für zufällige Namen auf, wenn ein Benutzer eine Spielesitzung beginnt,ohne dass er sich anmeldet oder einen Benutzernamen angibt. Wenn Lambda den Aufruf an random-name verarbeitet, liest es den Ablaufverfolgungskopf (p. 26), der die Ablaufverfolgungs-ID und dieSamplingentscheidung enthält, die vom X-Ray SDK for Java geschrieben wurden.
Für jede gesampelte Anforderung führt Lambda den X-Ray-Daemon aus und schreibt zwei Segmente. Dieerste Segment zeichnet Informationen über den Aufruf an Lambda auf, das die Funktion aufruft. DiesesSegment enthält die gleichen Informationen wie das von Scorekeep aufgezeichnete Untersegment, jedochaus Sicht von Lambda. Das zweite Segment repräsentiert die von der Funktion durchgeführte Arbeit.
Lambda übergibt das Funktionssegment über den Funktionskontext an das X-Ray-SDK. Wenn Sie eineLambda-Funktion instrumentieren, verwenden Sie das SDK nicht, um ein Segment für eingehendeAnforderungen zu erstellen (p. 168). Lambda stellt das Segment bereit und Sie nutzen das SDK zumInstrumentieren von Clients und Schreiben von Untersegmenten.
Die random-name-Funktion wird in Node.js implementiert. Sie verwendet den SDK for JavaScript inNode.js zum Senden von Benachrichtigungen mit Amazon SNS und das X-Ray SDK for Node.js zurInstrumentierung des AWS SDK-Clients. Zum Schreiben von Anmerkungen erstellt die Funktion einbenutzerdefiniertes Untersegment mit AWSXRay.captureFunc und schreibt die Anmerkungen in dieinstrumentierte Funktion. In Lambda können Sie Anmerkungen nicht direkt in das Funktionssegmentschreiben, sondern nur in das von Ihnen erstellte Untersegment.
Example _lambda/random-name/index.js -- Zufallsname-Lambda-Funktion
var AWSXRay = require('aws-xray-sdk-core');var AWS = AWSXRay.captureAWS(require('aws-sdk'));
99
AWS X-Ray EntwicklerhandbuchWorker
AWS.config.update({region: process.env.AWS_REGION});var Chance = require('chance');
var myFunction = function(event, context, callback) { var sns = new AWS.SNS(); var chance = new Chance(); var userid = event.userid; var name = chance.first();
AWSXRay.captureFunc('annotations', function(subsegment){ subsegment.addAnnotation('Name', name); subsegment.addAnnotation('UserID', event.userid); });
// Notify var params = { Message: 'Created randon name "' + name + '"" for user "' + userid + '".', Subject: 'New user: ' + name, TopicArn: process.env.TOPIC_ARN }; sns.publish(params, function(err, data) { if (err) { console.log(err, err.stack); callback(err); } else { console.log(data); callback(null, {"name": name}); } });};
exports.handler = myFunction;
Diese Funktion wird automatisch erstellt, wenn Sie die Beispielanwendung für Elastic Beanstalkbereitstellen. Der xray-Bereich enthält ein Skript für die Erstellung einer leeren Lambda-Funktion.Konfigurationsdateien im Ordner .ebextensions erstellen bei der Bereitstellung das Funktionspaket mitnpm install und aktualisieren dann die Lambda-Funktion mit der AWS-CLI.
WorkerDie instrumentierten Worker-Funktion wird in einer eigenen Verzweigung, xray-worker, bereitgestellt,da sie nur ausgeführt werden kann, wenn Sie die Worker-Funktion und verwandte Ressourcen zuersterstellen. Detaillierte Anweisungen finden Sie in der Readme-Datei zur Verzweigung.
Die Funktion wird alle 5 Minutendurch ein gebündeltes Amazon CloudWatch Events-Ereignis aufgerufen.Während der Ausführung ruft die Funktion ein Element aus einer von Scorekeep verwalteten Amazon SQS-Warteschlange ab. Jede Nachricht enthält Informationen zu einem abgeschlossenen Spiel.
Der Worker ruft den Spieledatensatz und die Spieledokumente von anderen Tabellen ab, auf die derSpieledatensatz verweist. So enthält der Spieledatensatz in DynamoDB beispielsweise eine Liste vonZügen, die während des Spiels durchgeführt wurden. Die Liste enthält nicht die Züge selbst, sondern dieIDs der Züge, die in einer separaten Tabelle gespeichert werden.
Sitzungen und Status werden ebenfalls als Referenzen gespeichert. Auf diese Weise wird verhindert,dass die Einträge in der Spieletabelle zu groß werden. Allerdings sind zusätzliche Aufrufe notwendig,um alle Informationen zum Spiel zu erhalten. Der Worker dereferenziert all diese Einträge und erstellteinen vollständigen Datensatz des Spiels in Form eines einzelnen Dokuments in Amazon S3. WennSie die Daten analysieren möchten, können Sie in Amazon S3 mit Amazon Athena direkte Abfragen fürdiese Daten durchführen, ohne dass leseintensive Datenmigrationen erforderlich sind, um Ihre Daten ausDynamoDB zu bekommen.
100
AWS X-Ray EntwicklerhandbuchWorker
Für die Worker-Funktion ist die aktive Nachverfolgung in der Konfiguration in AWS Lambda aktiviert. ImGegensatz zur Funktion für zufällige Namen erhält der Worker keine Anforderungen von instrumentiertenAnwendungen, somit empfängt AWS Lambda keinen Ablaufverfolgungs-Header. Bei aktiverNachverfolgung erstellt Lambda die Ablaufverfolgungs-ID und trifft Samplingentscheidungen.
Das X-Ray SDK für Python besteht lediglich aus ein paar Zeilen über der Funktion, die das SDK importiertund die Funktion patch_all ausführt, um die AWS SDK for Python (Boto) und HTTclients zu patchen,mit der Amazon SQS und Amazon S3 aufgerufen werden. Wenn der Worker die Scorekeep-API aufruft,fügt das SDK den Ablaufverfolgungs-Header (p. 26) zur Anforderung hinzu, um Aufrufe über die APInachzuverfolgen.
Example _lambda/scorekeep-worker/scorekeep-worker.py -- Worker Lambda-Funktion
import osimport boto3import jsonimport requestsimport timefrom aws_xray_sdk.core import xray_recorderfrom aws_xray_sdk.core import patch_all
patch_all()queue_url = os.environ['WORKER_QUEUE']
101
AWS X-Ray EntwicklerhandbuchAmazon ECS
def lambda_handler(event, context): # Create SQS client sqs = boto3.client('sqs') s3client = boto3.client('s3')
# Receive message from SQS queue response = sqs.receive_message( QueueUrl=queue_url, AttributeNames=[ 'SentTimestamp' ], MaxNumberOfMessages=1, MessageAttributeNames=[ 'All' ], VisibilityTimeout=0, WaitTimeSeconds=0 ) ...
Instrumentierung von Amazon ECS AnwendungenIn der Verzweigung xray-ecs veranschaulicht die Scorekeep-Beispielanwendung, wie eine in AmazonElastic Container Service (Amazon ECS) ausgeführte Anwendung instrumentiert wird. Die Verzweigungstellt Skripts und Konfigurationsdateien zum Erstellen, Hochladen und Ausführen von Docker-Images ineiner Multicontainer-Docker-Umgebung in AWS Elastic Beanstalk zur Verfügung.
Das Projekt enthält drei Dockerfiles, die Container-Abbilder für die API, das Frontend und X-Ray-DaemonKomponenten definieren.
• /Dockerfile – Die Scorekeep-API.• /scorekeep-frontend/Dockerfile – Der Client der Angular-Webanwendung und der nginx-Proxy,
der eingehenden Datenverkehr weiterleitet.• /xray-daemon/Dockerfile – Der X-Ray-Daemon.
Die X-Ray-Daemon-Dockerfile erstellt ein auf Amazon Linux basierendes Abbild zur Ausführung des X-Ray-Daemons.
Example Dockerfile – Amazon Linux
FROM amazonlinuxRUN yum install -y unzipRUN curl -o daemon.zip https://s3.dualstack.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-linux-2.x.zipRUN unzip daemon.zip && cp xray /usr/bin/xrayENTRYPOINT ["/usr/bin/xray", "-b", "0.0.0.0:2000"]EXPOSE 2000/udp
Die makefile-Datei in demselben Verzeichnis definiert Befehle, mit denen das Abbild erstellt, zu AmazonECR hochgeladen und lokal ausgeführt wird (p. 118).
Für die Ausführung von Containern auf Amazon ECS enthält die Verzweigung ein Skript zum Generiereneiner Dockerrun.aws.json-Datei. Sie können diese Datei in einer Multicontainer-Docker-Umgebungin Elastic Beanstalk bereitstellen. Die vom Skript verwendete Vorlage zeigt, wie eine Aufgabendefinitiongeschrieben wird, mit der Netzwerke zwischen den Containern in Amazon ECS (p. 124) konfiguriertwerden.
102
AWS X-Ray EntwicklerhandbuchStartup-Code
Note
Dockerrun.aws.json ist die Elastic Beanstalk-Version einer Amazon ECS-Aufgabendefinitionsdatei. Wenn Sie Ihren Amazon ECS-Cluster nicht mit Elastic Beanstalkerstellen möchten, können Sie die Datei Dockerrun.aws.json so abändern, dass sie direkt aufAmazon ECS ausgeführt wird. Dazu entfernen Sie den Schlüssel AWSEBDockerrunVersion ausder Datei.
Weitere Informationen zum Bereitstellen von Scorekeep für Amazon ECS finden Sie in der Readme-Dateizur Verzweigung.
Instrumentieren von Startup-CodeDas X-Ray SDK for Java erstellt automatisch Segmente für eingehende Anfragen. Wenn eine Anfrage imLeistungsumfang enthalten ist, können Sie instrumentierte Clients verwenden und Untersegmente ohneProbleme aufzeichnen. Wenn Sie jedoch versuchen, einen instrumentierten Client im Startup-Code zuverwenden, erhalten Sie eine SegmentNotFoundException.
Startup-Code wird außerhalb des standardmäßigen Anfrage-/Antwort-Ablaufs einer Webanwendungausgeführt, sodass Sie für eine Instrumentierung Segmente manuell erstellen müssen. Scorekeep stellt dieInstrumentierung von Startup-Code in den WebConfig-Dateien dar. Scorekeep ruft während des Startseine SQL-Datenbank und Amazon SNS auf.
103
AWS X-Ray EntwicklerhandbuchSkripte
Die standardmäßige WebConfig-Klasse erstellt ein Amazon SNS-Abonnement für Benachrichtigungen.Um ein Segment bereitzustellen, auf das das X-Ray-SDK schreiben kann, wenn der Amazon SNS-Clientverwendet wird, ruft Scorekeep beginSegment und endSegment in der globalen Aufzeichnung auf.
Example src/main/java/scorekeep/WebConfig.java – Instrumentierter AWS SDK-Clientim Startup-Code
AWSXRay.beginSegment("Scorekeep-init");if ( System.getenv("NOTIFICATION_EMAIL") != null ){ try { Sns.createSubscription(); } catch (Exception e ) { logger.warn("Failed to create subscription for email "+ System.getenv("NOTIFICATION_EMAIL")); }}AWSXRay.endSegment();
In RdsWebConfig, das Scorekeep verwendet, wenn eine Amazon RDS-Datenbank verbunden ist, erstelltdie Konfiguration außerdem ein Segment für den SQL-Client, das Hibernate verwendet, wenn es dasDatenbankschema während des Starts anwendet.
Example src/main/java/scorekeep/RdsWebConfig.java – Instrumentierter SQL-Datenbank-Client im Startup-Code
@PostConstructpublic void schemaExport() { EntityManagerFactoryImpl entityManagerFactoryImpl = (EntityManagerFactoryImpl) localContainerEntityManagerFactoryBean.getNativeEntityManagerFactory(); SessionFactoryImplementor sessionFactoryImplementor = entityManagerFactoryImpl.getSessionFactory(); StandardServiceRegistry standardServiceRegistry = sessionFactoryImplementor.getSessionFactoryOptions().getServiceRegistry(); MetadataSources metadataSources = new MetadataSources(new BootstrapServiceRegistryBuilder().build()); metadataSources.addAnnotatedClass(GameHistory.class); MetadataImplementor metadataImplementor = (MetadataImplementor) metadataSources.buildMetadata(standardServiceRegistry); SchemaExport schemaExport = new SchemaExport(standardServiceRegistry, metadataImplementor);
AWSXRay.beginSegment("Scorekeep-init"); schemaExport.create(true, true); AWSXRay.endSegment();}
SchemaExport wird automatisch ausgeführt und verwendet einen SQL-Client. Da der Client instrumentiertist, muss Scorekeep die Standardimplementierung überschreiben und ein Segment bereitstellen, das dasSDK verwenden kann, wenn der Client aufgerufen wird.
Instrumentieren von SkriptenSie können auch Code instrumentieren, der nicht Teil Ihrer Anwendung ist. Wenn der X-Ray-Daemonausgeführt wird, gibt er alle empfangenen Segmente an X-Ray weiter, auch wenn diese nicht vom X-Ray-SDK erzeugt wurden. Scorekeep nutzt seine eigenen Skripte zur Instrumentierung des Builds, der dieAnwendung während der Bereitstellung kompiliert.
Example bin/build.sh – Instrumentiertes Build-Skript
SEGMENT=$(python bin/xray_start.py)
104
AWS X-Ray EntwicklerhandbuchSkripte
gradle build --quiet --stacktrace &> /var/log/gradle.log; GRADLE_RETURN=$?if (( GRADLE_RETURN != 0 )); then echo "Gradle failed with exit status $GRADLE_RETURN" >&2 python bin/xray_error.py "$SEGMENT" "$(cat /var/log/gradle.log)" exit 1fipython bin/xray_success.py "$SEGMENT"
xray_start.py, xray_error.py und xray_success.py sind einfache Python-Skripte, dieSegmentobjekte erstellen, diese in JSON-Dokumente konvertieren und über UDP an den Daemon senden.Wenn der Gradle-Build fehlschlägt, können Sie die Fehlermeldung einsehen, indem Sie auf den Knotenscorekeep-build in der Service-Übersicht der X-Ray-Konsole klicken.
105
AWS X-Ray EntwicklerhandbuchClient
Instrumentieren eines Web-App-ClientsIn der xray-cognito- Verzweigung nutzt Scorekeep Amazon Cognito, um Benutzern die Kontoerstellungund Anmeldung zum Abrufen ihrer Benutzerinformationen aus einem Amazon Cognito-Benutzerpoolzu ermöglichen. Wenn ein Benutzer sich anmeldet, verwendet Scorekeep einen Amazon Cognito-Identitätenpool, um temporäre AWS-Anmeldeinformationen für die Verwendung mit AWS SDK forJavaScript zu erhalten.
Der Identitätenpool ist so konfiguriert, dass angemeldete Benutzer Ablaufverfolgungsdaten in AWS X-Rayschreiben können. Die Web-App nutzt diese Anmeldeinformationen, um die Benutzer-ID des angemeldetenBenutzers, den Browserpfad und die Client-Ansicht von Aufrufen der Scorekeep-API aufzuzeichnen.
Der Großteil der Vorgänge wird in einer Service-Klasse mit dem Namen xray ausgeführt. Diese Service-Klasse bietet Methoden zum Generieren der erforderlichen IDs, Erstellen von in Bearbeitung befindlichenSegmenten, Abschließen von Segmenten und Senden von Segmentdokumenten an die X-Ray-API.
106
AWS X-Ray EntwicklerhandbuchClient
Example public/xray.js – Aufzeichnen und Hochladen von Segmenten
... service.beginSegment = function() { var segment = {}; var traceId = '1-' + service.getHexTime() + '-' + service.getHexId(24);
var id = service.getHexId(16); var startTime = service.getEpochTime();
segment.trace_id = traceId; segment.id = id; segment.start_time = startTime; segment.name = 'Scorekeep-client'; segment.in_progress = true; segment.user = sessionStorage['userid']; segment.http = { request: { url: window.location.href } };
var documents = []; documents[0] = JSON.stringify(segment); service.putDocuments(documents); return segment; }
service.endSegment = function(segment) { var endTime = service.getEpochTime(); segment.end_time = endTime; segment.in_progress = false; var documents = []; documents[0] = JSON.stringify(segment); service.putDocuments(documents); }
service.putDocuments = function(documents) { var xray = new AWS.XRay(); var params = { TraceSegmentDocuments: documents }; xray.putTraceSegments(params, function(err, data) { if (err) { console.log(err, err.stack); } else { console.log(data); } }) }
Diese Methoden werden im Header und in transformResponse-Funktionen in den Ressourcen-Servicesaufgerufen, die die Web-App zum Aufrufen der Scorekeep-API verwendet. Um das Client-Segment indieselbe Ablaufverfolgung einzubeziehen wie das Segment, das die API generiert, muss die Web-App dieAblaufverfolgungs-ID und Segment-ID in einen Ablaufverfolgungs-Header (p. 26) (X-Amzn-Trace-Id)einbeziehen, den das X-Ray-SDK lesen kann. Wenn die instrumentierte Java-Anwendung eine Anfrage mitdiesem Header empfängt, verwendet das X-Ray SDK for Java dieselbe Ablaufverfolgungs-ID und machtdas Segment aus dem Web-App-Client zum übergeordneten Element seines Segments.
Example public/app/services.js – Aufzeichnung von Segmente für Angular-Ressourcenaufrufe und Schreiben von Ablaufverfolgungs-Headern
var module = angular.module('scorekeep');
107
AWS X-Ray EntwicklerhandbuchClient
module.factory('SessionService', function($resource, api, XRay) { return $resource(api + 'session/:id', { id: '@_id' }, { segment: {}, get: { method: 'GET', headers: { 'X-Amzn-Trace-Id': function(config) { segment = XRay.beginSegment(); return XRay.getTraceHeader(segment); } }, transformResponse: function(data) { XRay.endSegment(segment); return angular.fromJson(data); }, },...
Die daraus resultierende Service-Übersicht beinhaltet einen Knoten für den Web-App-Client.
108
AWS X-Ray EntwicklerhandbuchAuftragnehmer-Threads
Ablaufverfolgungen, die Segmente aus der Web-App einschließen, zeigen die URL an, die der Benutzer imBrowser sieht (Pfad beginnend mit /#/). Ohne Client-Instrumentierung erhalten Sie nur die URL der API-Ressource, die die Web-App aufruft (Pfade beginnend mit /api/).
Verwenden instrumentierter Clients inAuftragnehmer-Threads
Scorekeep verwendet einen Auftragnehmer-Thread, um eine Benachrichtigung in Amazon SNS zuveröffentlichen, wenn ein Benutzer ein Spiel gewinnt. Die Veröffentlichung der Benachrichtigung dauertlänger als alle übrigen Anfragevorgänge zusammen und wirkt sich nicht auf den Client oder Benutzer aus.Die Aufgabe asynchron auszuführen ist daher eine gute Möglichkeit, die Reaktionszeit zu verbessern.
Das X-Ray SDK for Java erkennt jedoch nicht, welches Segment aktiv war, wenn der Thread erstelltwird. Wenn Sie also versuchen, den instrumentierten AWS SDK for Java-Client innerhalb des Threads zuverwenden, wird eine SegmentNotFoundException ausgegeben und der Thread stürzt ab.
Example web-1.error.log
Exception in thread "Thread-2" com.amazonaws.xray.exceptions.SegmentNotFoundException: Failed to begin subsegment named 'AmazonSNS': segment cannot be found. at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method) at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:62) at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)...
Um dieses Problem zu beheben, verwendet die Anwendung GetTraceEntity, um eine Referenz zumSegment im Haupt-Thread zu erhalten, und SetTraceEntity, um das Segment wieder an den Recorderim Auftragnehmer-Thread zu übergeben.
Example src/main/java/scorekeep/MoveFactory.java – Übergeben vonAblaufverfolgungskontext an einen Auftragnehmer-Thread
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.AWSXRayRecorder;import com.amazonaws.xray.entities.Entity;
109
AWS X-Ray EntwicklerhandbuchAuftragnehmer-Threads
import com.amazonaws.xray.entities.Segment;import com.amazonaws.xray.entities.Subsegment;... Entity segment = recorder.getTraceEntity(); Thread comm = new Thread() { public void run() { recorder.setTraceEntity(segment); Subsegment subsegment = AWSXRay.beginSubsegment("## Send notification"); Sns.sendNotification("Scorekeep game completed", "Winner: " + userId); AWSXRay.endSubsegment(); }
Da die Anfrage jetzt vor dem Aufruf von Amazon SNS behoben wird, erstellt die Anwendung ein separatesUntersegment für den Thread. Dadurch wird verhindert, dass das X-Ray-SDK das Segment schließt,bevor es die Antwort von Amazon SNS aufzeichnet. Wenn Scorekeep die Anfrage gelöst hat und keinUntersegment offen war, kann die Antwort von Amazon SNS verloren gehen.
110
AWS X-Ray EntwicklerhandbuchErstellen von Deep-Links
Weitere Informationen zu Multithreading finden Sie unter Übermitteln von Segmentkontext zwischenThreads in einer Multithread-Anwendung (p. 147).
Deep Linking mit der X-Ray-KonsoleDie Sitzungs- und Spieleseiten der Scorekeep-Web-App verwenden Deep Linking, um gefilterteAblaufverfolgungslisten und Service-Übersichten zu verknüpfen.
Example public/game.html – Deep-Links
<div id="xray-link"> <p><a href="https://console.aws.amazon.com/xray/home#/traces?filter=http.url%20CONTAINS%20%22{{ gameid }}%22&timeRange=PT1H" target="blank">View traces for this game</a></p> <p><a href="https://console.aws.amazon.com/xray/home#/service-map&timeRange=PT1H" target="blank">View service map</a></p></div>
Detaillierte Informationen zum Erstellen von Deep-Links finden Sie unter Erstellen von Deep-Links (p. 47).
111
AWS X-Ray EntwicklerhandbuchHerunterladen des Daemons
AWS X-Ray-DaemonDer AWS X-Ray-Daemon ist eine Softwareanwendung, die auf UDP-Port 2000 auf Datenverkehr wartet,unformatierte Segmentdaten sammelt und an die AWS X-Ray-API weiterleitet. Der Daemon funktioniert inVerbindung mit den AWS X-Ray SDKs und muss ausgeführt werden, damit die von den SDKs gesendetenDaten den X-Ray-Service erreichen.
Note
Der X-Ray-Daemon ist ein Open-Source-Projekt. Sie können das Projekt auf GitHub verfolgen undProbleme und Pull-Anforderungen übermitteln: github.com/aws/aws-xray-daemon
Verwenden Sie auf AWS Lambda und AWS Elastic Beanstalk, die Integration dieser Services mit X-Ray,um den Daemon auszuführen. Lambda führt den Daemon automatisch jedes Mal aus, wenn eine Funktionfür eine gesampelte Anforderung aufgerufen wird. Verwenden Sie auf Elastic Beanstalk, die XRayEnabledKonfigurationsoption (p. 120), um den Daemon auf der Instance in Ihrer Umgebung auszuführen.
Um den X-Ray-Daemon lokal, vor Ort oder auf anderen AWS-Services auszuführen, laden Sie ihnvon Amazon S3 herunter (p. 112), führen Sie ihn aus (p. 113), und geben Sie ihm dann dieBerechtigung (p. 114) zum Hochladen von Segmentdokumenten zu X-Ray.
Herunterladen des DaemonsSie können den Daemon von Amazon S3 herunterladen, um ihn lokal auszuführen, oder ihn beim Start aufeiner Amazon EC2-Instance installieren.
X-Ray-Daemon-Installationsprogramme und -Executables
• Linux (Executable) – aws-xray-daemon-linux-2.x.zip (sig)• Linux (RPM-Installationsprogramm) – aws-xray-daemon-2.x.rpm• Linux (DEB-Installationsprogramm) – aws-xray-daemon-2.x.deb• OS X (Executable) – aws-xray-daemon-macos-2.x.zip (sig)• Windows (Executable) – aws-xray-daemon-windows-process-2.x.zip (sig)• Windows (Service) – aws-xray-daemon-windows-service-2.x.zip (sig)
Diese Links verweisen immer auf die neueste V2-Version des Daemons. Um eine bestimmte Versionherunterzuladen, ersetzen Sie 2.x durch die Versionsnummer. Beispiel, 2.1.0.
X-Ray-Komponenten werden in Buckets in jeder unterstützten Region repliziert. Um den Bucket zuverwenden, der Ihren AWS-Ressourcen am nächsten liegt, ersetzen Sie die Region in obigem Link durchIhre Region.
https://s3.dualstack.us-west-2.amazonaws.com/aws-xray-assets.us-west-2/xray-daemon/aws-xray-daemon-2.x.rpm
Überprüfen der Signatur des Daemon-ArchivsGPG-Signatur-Dateien sind für Daemon-Komponenten in komprimierten ZIP-Archiven eingeschlossen. Deröffentliche Schlüssel ist hier: aws-xray.gpg.
112
AWS X-Ray EntwicklerhandbuchAusführen des Daemons
Sie können den öffentlichen Schlüssel verwenden, um zu überprüfen, ob das Daemon-ZIP-Archiv einOriginal und unverändert ist. Importieren Sie zunächst den öffentlichen Schlüssel mit GnuPG.
So importieren Sie den öffentlichen Schlüssel
1. Laden Sie den öffentlichen Schlüssel herunter.
$ BUCKETURL=https://s3.dualstack.us-east-2.amazonaws.com/aws-xray-assets.us-east-2$ wget $BUCKETURL/xray-daemon/aws-xray.gpg
2. Importieren Sie den öffentlichen Schlüssel in Ihren Schlüsselbund.
$ gpg --import aws-xray.gpggpg: /Users/me/.gnupg/trustdb.gpg: trustdb createdgpg: key 7BFE036BFE6157D3: public key "AWS X-Ray <[email protected]>" importedgpg: Total number processed: 1gpg: imported: 1
Verwenden Sie den importierten Schlüssel, um die Signatur des Daemon-ZIP-Archivs zu überprüfen.
So überprüfen Sie die Signatur eines Archivs
1. Laden Sie das Archiv und die Signaturdatei herunter.
$ BUCKETURL=https://s3.dualstack.us-east-2.amazonaws.com/aws-xray-assets.us-east-2$ wget $BUCKETURL/xray-daemon/aws-xray-daemon-linux-2.0.0.zip$ wget $BUCKETURL/xray-daemon/aws-xray-daemon-linux-2.0.0.zip.sig
2. Führen Sie gpg --verify aus, um die Signatur zu überprüfen.
$ gpg --verify aws-xray-daemon-linux-2.0.0.zip.sig aws-xray-daemon-linux-2.0.0.zipgpg: Signature made Wed 19 Apr 2017 05:06:31 AM UTC using RSA key ID FE6157D3gpg: Good signature from "AWS X-Ray <[email protected]>"gpg: WARNING: This key is not certified with a trusted signature!gpg: There is no indication that the signature belongs to the owner.Primary key fingerprint: EA6D 9271 FBF3 6990 277F 4B87 7BFE 036B FE61 57D3
Beachten Sie die Warnung zu vertrauenswürdigen Inhalten. Ein Schlüssel ist nur vertrauenswürdig, wennSie oder eine Person Ihres Vertrauens ihn signiert hat. Das bedeutet nicht, dass die Signatur ungültig ist,sondern nur, dass Sie den öffentlichen Schlüssel nicht überprüft haben.
Ausführen des DaemonsFühren Sie den Daemon lokal über eine Befehlszeile aus. Verwenden Sie die Option -o zur Ausführung imlokalen Modus und -n zum Festlegen der Region.
~/Downloads$ ./xray -o -n us-east-2
Detaillierte plattformspezifische Anweisungen finden Sie in den folgenden Themen:
• Linux (lokal) – Ausführen des X-Ray-Daemons unter Linux (p. 117)• Windows (lokal) – Ausführen des X-Ray-Daemons unter Windows (p. 119)• Elastic Beanstalk – Ausführen des X-Ray-Daemons in AWS Elastic Beanstalk (p. 120)
113
AWS X-Ray EntwicklerhandbuchErteilen der Berechtigung zum Sendenvon Daten an X-Ray für den Daemon
• Amazon EC2 – Ausführen des X-Ray-Daemons in Amazon EC2 (p. 123)• Amazon ECS – Ausführen des X-Ray-Daemons in Amazon ECS (p. 124)
Sie können mithilfe von Befehlszeilenoptionen oder einer Konfigurationsdatei das Verhalten des Daemonsanpassen. Details dazu finden Sie unter Konfigurieren des AWS X-Ray-Daemons (p. 115).
Erteilen der Berechtigung zum Senden von Datenan X-Ray für den Daemon
Der X-Ray.Daemon verwendet das AWS SDK, um Ablaufverfolgungsdaten auf X-Ray hochzuladen, undbenötigt AWS-Anmeldeinformationen mit der entsprechenden Berechtigung.
In Amazon EC2 verwendet der Daemon automatisch die Instance-Profilrolle der Instance. SpeichernSie Ihre Zugriffsschlüssel lokal in einer Datei mit dem Namen credentials im Ordner .aws IhresBenutzerverzeichnisses.
Example ~/.aws/credentials
[default]aws_access_key_id = AKIAIOSFODNN7EXAMPLEaws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Wenn Sie an mehreren Orten (Anmeldeinformationsdatei, Instance-Profil oder Umgebungsvariablen)Anmeldeinformationen angeben, bestimmt die SDK-Anbieterkette, welche Anmeldeinformationenverwendet werden. Weitere Informationen zur Bereitstellung von Anmeldeinformationen für das SDK findenSie unter Festlegen von Anmeldeinformationen im Entwicklerhandbuch für AWS SDK for Go.
Die IAM-Rolle oder der Benutzer, zu der bzw. dem die Anmeldeinformationen des Daemons gehören,benötigt die Berechtigung zum Schreiben von Daten in den Service in Ihrem Namen.
• Zum Verwenden des Daemons in Amazon EC2 erstellen Sie eine neue Instance-Profilrolle oder fügenSie die verwaltete Richtlinie einer vorhandenen Richtlinie hinzu.
• Um den Daemon in Elastic Beanstalk zu verwenden, fügen Sie die verwaltete Richtlinie der ElasticBeanstalk Standard-Instance-Profilrolle hinzu.
• Um den Daemon lokal auszuführen, erstellen Sie einen IAM-Benutzer und speichern Sie dessenZugriffsschlüssel auf Ihrem Computer.
Weitere Informationen finden Sie unter AWS X-Ray-Berechtigungen (p. 86).
Protokolle des X-Ray-DaemonsDer Daemon gibt Informationen über seine aktuelle Konfiguration und Segmente aus, die er an AWS X-Raysendet.
2016-11-24T06:07:06Z [Info] Initializing AWS X-Ray daemon 2.1.02016-11-24T06:07:06Z [Info] Using memory limit of 49 MB2016-11-24T06:07:06Z [Info] 313 segment buffers allocated2016-11-24T06:07:08Z [Info] Successfully sent batch of 1 segments (0.123 seconds)2016-11-24T06:07:09Z [Info] Successfully sent batch of 1 segments (0.006 seconds)
114
AWS X-Ray EntwicklerhandbuchKonfiguration
Der Daemon gibt Protokolle standardmäßig an STDOUT aus. Wenn Sie den Daemon im Hintergrundausführen, verwenden Sie zum Festlegen des Protokolldateipfades die Befehlszeilenoption --log-file oder eine Konfigurationsdatei. Sie können auch die Protokollierungsebene festlegen und dieProtokoll-Rotation deaktivieren. Detaillierte Anweisungen finden Sie unter Konfigurieren des AWS X-Ray-Daemons (p. 115).
In Elastic Beanstalk legt die Plattform den Speicherort der Daemon-Protokolle fest. Details dazu finden Sieunter Ausführen des X-Ray-Daemons in AWS Elastic Beanstalk (p. 120).
Konfigurieren des AWS X-Ray-DaemonsSie können mithilfe von Befehlszeilenoptionen oder einer Konfigurationsdatei das Verhalten des X-Ray-Daemons anpassen. Die meisten Optionen sind bei beiden Methoden verfügbar. Manche sind jedoch nur inForm von Konfigurationsdateien oder nur in der Befehlszeile verfügbar.
Zum Einstieg müssen Sie nur mit der Option -n oder --region vertraut sein. Sie legen damit die Regionfest, die der Daemon zum Senden von Ablaufverfolgungsdaten an X-Ray verwendet.
~/xray-daemon$ ./xray -n us-east-2
Wenn Sie den Daemon lokal ausführen, d. h. nicht in Amazon EC2, können Sie die Option -o hinzufügen.Mit ihr wird die Überprüfung auf Anmeldeinformationen des Instance-Profils übersprungen. Der Daemon istsomit schneller bereit.
~/xray-daemon$ ./xray -o -n us-east-2
Mithilfe der restlichen Befehlszeilenoptionen können Sie die Protokollierung konfigurieren, einen anderenPort abhören, die vom Daemon nutzbare Speichermenge begrenzen oder eine Rolle annehmen, umAblaufverfolgungsdaten an ein anderes Konto zu senden.
Sie können eine Konfigurationsdatei an den Daemon weiterleiten, um auf erweiterte Konfigurationsoptionenzuzugreifen und bestimmte Aktivitäten, wie Begrenzen der Anzahl gleichzeitiger Aufrufe von X-Ray,Deaktivieren der Protokoll-Rotation und Senden von Datenverkehr an einen Proxy auszuführen.
Abschnitte• Verwendung von Befehlszeilenoptionen (p. 115)• Verwendung einer Konfigurationsdatei (p. 116)
Verwendung von BefehlszeilenoptionenÜbergeben Sie diese Optionen an den Daemon, wenn Sie ihn lokal oder mit einem Benutzerdatenskriptausführen.
Befehlszeilenoptionen
• -b, --bind – Binden Sie den Daemon an einen anderen Port.
--bind "127.0.0.1:3000"
Standard – 2000.• -c, --config – Laden Sie eine Konfigurationsdatei aus dem angegebenen Pfad.
115
AWS X-Ray EntwicklerhandbuchVerwendung einer Konfigurationsdatei
--config "/home/ec2-user/xray-daemon.yaml"
• -f, --log-file – Geben Sie Protokolle in den angegebenen Dateipfad aus.
--log-file "/var/log/xray-daemon.log"
• -l, --log-level – Protokollierungsebene, von der höchsten bis zur niedrigsten: dev, debug, info,warn, error, prod.
--log-level warn
Standard – prod• -m, --buffer-memory – Ändern Sie die Größe des Speichers in MB, den die Puffer verwenden können
(Minimum 3).
--buffer-memory 50
Standard – 1 % des verfügbaren Arbeitsspeichers.• -o, --local-mode – Es wird nicht auf EC2 Instance-Metadaten geprüft.• -r, --role-arn – Nehmen Sie die angegebene IAM-Rolle zum Hochladen von Segmenten auf ein
anderes Konto an.
--role-arn "arn:aws:iam::123456789012:role/xray-cross-account"
• -a, --resource-arn – Amazon-Ressourcenname (ARN) der AWS-Ressource, die den Daemonausführt.
• -n, --region – Senden von Segmenten an den X-Ray-Service in einer bestimmten Region.• -v, --version – Zeigt die AWS X-Ray-Daemon-Version an.• -h, --help – Zeigt den Hilfebildschirm an.
Verwendung einer KonfigurationsdateiSie können auch eine Datei im YAML-Format zur Konfiguration des Daemons verwenden. Übergeben Siedie Konfigurationsdatei mit der -c-Option an den Daemon.
~$ ./xray -c ~/xray-daemon.yaml
Konfigurationsdateioptionen
• TotalBufferSizeMB – Maximale Puffergröße in MB (Minimum 3). Wählen Sie 0, um 1 % des Host-Speichers zu verwenden.
• Concurrency – Maximale Anzahl gleichzeitiger Aufrufe an AWS X-Ray zum Upload vonSegmentdokumenten.
• Region – Senden von Segmenten an den AWS X-Ray-Service in einer bestimmten Region.• Socket – Konfigurieren Sie die Bindung des Daemons.
• UDPAddress – Ändern Sie den Port, an dem der Daemon lauscht.• Logging – Konfigurieren Sie das Protokollierungsverhalten.
• LogRotation – Auf false einstellen, um die Protokollrotation zu deaktivieren.• LogLevel – Ändern Sie die Protokollierungsebene, von der höchsten bis zur niedrigsten: dev, debug,info, warn, error, prod (Standard).
116
AWS X-Ray EntwicklerhandbuchLokales Ausführen des Daemons
• LogPath – Geben Sie Protokolle in den angegebenen Dateipfad aus.• LocalMode – Legen Sie den Wert auf true fest, um das Überprüfen auf EC2 Instance-Metadaten zu
überspringen.• ResourceARN – Amazon-Ressourcenname (ARN) der AWS-Ressource, die den Daemon ausführt.• RoleARN – Nehmen Sie die angegebene IAM-Rolle zum Hochladen von Segmenten auf ein anderes
Konto an.• ProxyAddress – Upload von Segmenten zu AWS X-Ray über einen Proxy.• Endpoint – Ändern des X-Ray-Service-Endpunkts, an den der Daemon Segmentdokumente sendet.• NoVerifySSL – Deaktivieren der Verifizierung des TLS-Zertifikats.• Version – Dateiformatversion der Daemon-Konfiguration
Example xray-daemon.yaml
In dieser Konfigurationsdatei wird der Listening-Port des Daemons in 3000 geändert. Dazu werden diePrüfungen auf Instance-Metadaten deaktiviert, eine Rolle für den Upload von Segmenten eingerichtet unddie Optionen für Region und Protokollierung geändert.
Socket: UDPAddress: "127.0.0.1:3000"Region: "us-west-2"Logging: LogLevel: "warn" LogPath: "/var/log/xray-daemon.log"LocalMode: trueRoleARN: "arn:aws:iam::123456789012:role/xray-cross-account"Version: 1
Lokales Ausführen des X-Ray-DaemonsSie können den AWS X-Ray-Daemon lokal auf Linux, Mac OS, Windows oder in einem Docker-Containerausführen. Führen Sie den Daemon aus, um Ablaufverfolgungsdaten an X-Ray weiterzuleiten, wenn SieIhre instrumentierte Anwendung entwickeln und testen. Laden Sie den Daemon herunter und extrahierenSie ihn. Diesbezügliche Anweisungen finden Sie hier (p. 112).
Wenn der Daemon lokal ausgeführt wird, kann er Anmeldeinformationen aus einer AWS SDK-Anmeldeinformationsdatei (.aws/credentials in Ihrem Benutzerverzeichnis) oder vonUmgebungsvariablen lesen. Weitere Informationen finden Sie unter Erteilen der Berechtigung zum Sendenvon Daten an X-Ray für den Daemon (p. 114).
Der Daemon lauscht an Port 2000 auf Daten. Sie können den Port und andere Optionen mithilfe einerKonfigurationsdatei und von Befehlszeilenoptionen ändern. Weitere Informationen finden Sie unterKonfigurieren des AWS X-Ray-Daemons (p. 115).
Ausführen des X-Ray-Daemons unter LinuxSie können die ausführbare Datei des Daemons an der Befehlszeile ausführen. Verwenden Sie die Option-o zur Ausführung im lokalen Modus und -n zum Festlegen der Region.
~/xray-daemon$ ./xray -o -n us-east-2
Zum Ausführen des Daemons im Hintergrund verwenden Sie &.
117
AWS X-Ray EntwicklerhandbuchAusführen des X-Ray-Daemons in einem Docker-Container
~/xray-daemon$ ./xray -o -n us-east-2 &
Beenden Sie einen Daemonprozess, der im Hintergrund ausgeführt wird, mit pkill.
~$ pkill xray
Ausführen des X-Ray-Daemons in einem Docker-ContainerUm den Daemon lokal in einem Docker-Container auszuführen, speichern Sie den folgenden Text in einerDatei mit dem Namen Dockerfile.
Example Dockerfile – Amazon Linux
FROM amazonlinuxRUN yum install -y unzipRUN curl -o daemon.zip https://s3.dualstack.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-linux-2.x.zipRUN unzip daemon.zip && cp xray /usr/bin/xrayENTRYPOINT ["/usr/bin/xray", "-b", "0.0.0.0:2000"]EXPOSE 2000/udp
Entwickeln Sie das Container-Image mit docker build.
~/xray-daemon$ docker build -t xray-daemon .
Führen Sie das Abbild in einem Container mit docker run aus.
~/xray-daemon$ docker run \ --attach STDOUT \ -v ~/.aws/:/root/.aws/:ro \ --net=host \ -e AWS_REGION=us-east-2 \ --name xray-daemon \ -p 2000:2000/udp \ xray-daemon -o
Dieser Befehl verwendet die folgenden Optionen:
• --attach STDOUT – Zeigt Ausgabe von dem Daemon im Terminal an.• -v ~/.aws/:/root/.aws/:ro – Erteilt dem Container schreibgeschützten Zugriff auf das Verzeichnis.aws, sodass er Ihre AWS-SDK-Anmeldeinformationen lesen kann.
• AWS_REGION=us-east-2 – Legt die Umgebungsvariable AWS_REGION fest, um dem Daemonmitzuteilen, welche Region verwendet werden soll.
• --net=host – Fügt den Container an das Netzwerk host an. Container im Hostnetzwerk könnenmiteinander kommunizieren, ohne Ports zu veröffentlichen.
• -p 2000:2000/udp – Ordnet UDP-Port 2000 auf Ihrem Computer demselben Port im Container zu.Dies ist für die Kommunikation von Containern in demselben Netzwerk nicht erforderlich. Sie können mitihr aber Segmente über die Befehlszeile (p. 58) oder Anwendung, die nicht in Docker ausgeführt wird,zum Daemon senden.
• --name xray-daemon – Gibt dem Container den Namen xray-daemon, anstatt einen Zufallsnamenzu generieren.
118
AWS X-Ray EntwicklerhandbuchAusführen des X-Ray-Daemons unter Windows
• -o (nach dem Abbildnamen) – Hängt die Option -o an den Einstiegspunkt an, an dem der Daemon imContainer ausgeführt wird. Mit dieser Option wird der Daemon im lokalen Modus ausgeführt, um ihn amLesen von Amazon EC2-Instance-Metadaten zu hindern.
Um den Daemon zu beenden, verwenden Sie docker stop. Wenn Sie nach der Vornahme vonÄnderungen am Dockerfile ein neues Abbild erstellen, müssen Sie den vorhandenen Container löschen,damit Sie einen anderen mit demselben Namen erstellen können. Verwenden Sie docker rm zumLöschen des Containers.
$ docker stop xray-daemon$ docker rm xray-daemon
Die Scorekeep-Beispielanwendung zeigt, wie der X-Ray-Daemon in einem lokalen Docker-Containerverwendet wird. Details dazu finden Sie unter Instrumentierung von Amazon ECS Anwendungen (p. 102).
Ausführen des X-Ray-Daemons unter WindowsSie können die ausführbare Datei des Daemons an der Befehlszeile ausführen. Verwenden Sie die Option-o zur Ausführung im lokalen Modus und -n zum Festlegen der Region.
> .\xray_windows.exe -o -n us-east-2
Verwenden Sie ein PowerShell-Skript zum Erstellen und Ausführen eines Service für den Daemon.
Example PowerShell-Skript – Windows
if ( Get-Service "AWSXRayDaemon" -ErrorAction SilentlyContinue ){ sc.exe stop AWSXRayDaemon sc.exe delete AWSXRayDaemon}if ( Get-Item -path aws-xray-daemon -ErrorAction SilentlyContinue ) { Remove-Item -Recurse -Force aws-xray-daemon}
$currentLocation = Get-Location$zipFileName = "aws-xray-daemon-windows-service-2.x.zip"$zipPath = "$currentLocation\$zipFileName"$destPath = "$currentLocation\aws-xray-daemon"$daemonPath = "$destPath\xray.exe"$daemonLogPath = "C:\inetpub\wwwroot\xray-daemon.log"$url = "https://s3.dualstack.us-west-2.amazonaws.com/aws-xray-assets.us-west-2/xray-daemon/aws-xray-daemon-windows-service-2.x.zip"
Invoke-WebRequest -Uri $url -OutFile $zipPathAdd-Type -Assembly "System.IO.Compression.Filesystem"[io.compression.zipfile]::ExtractToDirectory($zipPath, $destPath)
sc.exe create AWSXRayDaemon binPath= "$daemonPath -f $daemonLogPath"sc.exe start AWSXRayDaemon
Ausführen des X-Ray-Daemons unter OS XSie können die ausführbare Datei des Daemons an der Befehlszeile ausführen. Verwenden Sie die Option-o zur Ausführung im lokalen Modus und -n zum Festlegen der Region.
~/xray-daemon$ ./xray_mac -o -n us-east-2
119
AWS X-Ray EntwicklerhandbuchIn Elastic Beanstalk
Zum Ausführen des Daemons im Hintergrund verwenden Sie &.
~/xray-daemon$ ./xray_mac -o -n us-east-2 &
Verwenden Sie nohup, um zu verhindern, dass der Daemon vorzeitig beendet wird, wenn das Terminalgeschlossen wird.
~/xray-daemon$ nohup ./xray_mac &
Ausführen des X-Ray-Daemons in AWS ElasticBeanstalk
Um Ablaufverfolgungsdaten aus Ihrer Anwendung an AWS X-Ray weiterzuleiten, können Sie den X-Ray-Daemon in den Amazon EC2-Instances Ihrer Elastic Beanstalk-Umgebung ausführen. Eine Liste derunterstützten Plattformen finden Sie unter Configuring AWS X-Ray Debugging (Konfigurieren von AWS X-Ray-Debugging) im Entwicklerhandbuch für AWS Elastic Beanstalk.
Note
Der Daemon verwendet das Instance-Profil Ihrer Umgebung für Berechtigungen. Anweisungenzum Hinzufügen von Berechtigungen zum Elastic Beanstalk-Instance-Profil finden Sie unterErteilen der Berechtigung zum Senden von Daten an X-Ray für den Daemon (p. 114).
Elastic Beanstalk-Plattformen bieten eine Konfigurationsoption, die Sie festlegen können, um den Daemonautomatisch auszuführen. Sie können den Daemon in einer Konfigurationsdatei in Ihrem Quellcode oderdurch Wahl einer Option in der Elastic Beanstalk-Konsole aktivieren. Wenn Sie die Konfigurationsoptionaktivieren, wird der Daemon in der Instance installiert und als Service ausgeführt.
Die auf den Elastic Beanstalk-Plattformen enthaltene Version ist möglicherweise nicht die neueste Version.Dem Thema "Unterstützte Plattformen" können Sie entnehmen, welche Version des Daemons für IhrePlattformkonfiguration verfügbar ist.
Elastic Beanstalk stellt den X-Ray-Daemon nicht auf der Multicontainer Docker (Amazon ECS)-Plattformzur Verfügung. Die Beispielanwendung Scorekeep zeigt, wie der X-Ray-Daemon auf Amazon ECS mitElastic Beanstalk verwendet wird. Details dazu finden Sie unter Instrumentierung von Amazon ECSAnwendungen (p. 102).
Verwenden der Elastic Beanstalk X-Ray-Integrationzum Ausführen des X-Ray-DaemonsVerwenden Sie die Konsole, um die X-Ray-Integration zu aktivieren, oder konfigurieren Sie sie in IhremAnwendungsquellcode mit einer Konfigurationsdatei.
Aktivieren Sie den X-Ray-Daemon in der Elastic Beanstalk-Konsole wie folgt:
1. Open the Elastic Beanstalk console.2. Navigate to the management console for your environment.3. Choose Configuration.4. Wählen Sie Software Settings.5. Wählen Sie für X-Ray daemon Enabled.6. Wählen Sie Apply aus.
120
AWS X-Ray EntwicklerhandbuchManuelles Herunterladen und Ausführen
des X-Ray-Daemons (Erweitert)
Sie können eine Konfigurationsdatei in Ihren Quellcode aufnehmen, um die Konfiguration zwischenverschiedenen Umgebungen übertragbar zu gestalten.
Example .ebextensions/xray-daemon.config
option_settings: aws:elasticbeanstalk:xray: XRayEnabled: true
Elastic Beanstalk übergibt eine Konfigurationsdatei an den Daemon und gibt Protokolle an einemStandardstandort aus.
Auf Windows Server-Plattformen
• Konfigurationsdatei – C:\Progam Files\Amazon\XRay\cfg.yaml• Protokolle – c:\Program Files\Amazon\XRay\logs\xray-service.log
Auf Linux-Plattformen
• Konfigurationsdatei – /etc/amazon/xray/cfg.yaml• Protokolle – /var/log/xray/xray.log
Elastic Beanstalk stellt Tools für das Extrahieren von Instance-Protokollen aus der AWS ManagementConsole oder der Befehlszeile bereit. Sie können Elastic Beanstalk anweisen, die X-Ray-Daemon-Protokolle einzuschließen, indem Sie eine Aufgabe mit einer Konfigurationsdatei hinzufügen.
Example .ebextensions/xray-logs.config – Linux
files: "/opt/elasticbeanstalk/tasks/taillogs.d/xray-daemon.conf" : mode: "000644" owner: root group: root content: | /var/log/xray/xray.log
Example .ebextensions/xray-logs.config – Windows Server
files: "c:/Program Files/Amazon/ElasticBeanstalk/config/taillogs.d/xray-daemon.conf" : mode: "000644" owner: root group: root content: | c:\Progam Files\Amazon\XRay\logs\xray-service.log
Weitere Informationen finden Sie unter Viewing Logs from Your Elastic Beanstalk Environment's AmazonEC2 Instances im Entwicklerhandbuch für AWS Elastic Beanstalk.
Manuelles Herunterladen und Ausführen des X-Ray-Daemons (Erweitert)Wenn der X-Ray-Daemon für Ihre Plattformkonfiguration nicht verfügbar ist, können Sie sie von Amazon S3herunterladen und mit einer Konfigurationsdatei ausführen.
121
AWS X-Ray EntwicklerhandbuchManuelles Herunterladen und Ausführen
des X-Ray-Daemons (Erweitert)
Verwenden Sie eine Elastic Beanstalk-Konfigurationsdatei, um den Daemon herunterzuladen undauszuführen.
Example .ebextensions/xray.config – Linux
commands: 01-stop-tracing: command: yum remove -y xray ignoreErrors: true 02-copy-tracing: command: curl https://s3.dualstack.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-2.x.rpm -o /home/ec2-user/xray.rpm 03-start-tracing: command: yum install -y /home/ec2-user/xray.rpm
files: "/opt/elasticbeanstalk/tasks/taillogs.d/xray-daemon.conf" : mode: "000644" owner: root group: root content: | /var/log/xray/xray.log "/etc/amazon/xray/cfg.yaml" : mode: "000644" owner: root group: root content: | Logging: LogLevel: "debug"
Example .ebextensions/xray.config – Windows Server
container_commands: 01-execute-config-script: command: Powershell.exe -ExecutionPolicy Bypass -File c:\\temp\\installDaemon.ps1 waitAfterCompletion: 0 files: "c:/temp/installDaemon.ps1": content: | if ( Get-Service "AWSXRayDaemon" -ErrorAction SilentlyContinue ) { sc.exe stop AWSXRayDaemon sc.exe delete AWSXRayDaemon }
$targetLocation = "C:\Program Files\Amazon\XRay" if ((Test-Path $targetLocation) -eq 0) { mkdir $targetLocation }
$zipFileName = "aws-xray-daemon-windows-service-2.x.zip" $zipPath = "$targetLocation\$zipFileName" $destPath = "$targetLocation\aws-xray-daemon" if ((Test-Path $destPath) -eq 1) { Remove-Item -Recurse -Force $destPath }
$daemonPath = "$destPath\xray.exe" $daemonLogPath = "$targetLocation\xray-daemon.log" $url = "https://s3.dualstack.us-west-2.amazonaws.com/aws-xray-assets.us-west-2/xray-daemon/aws-xray-daemon-windows-service-2.x.zip"
Invoke-WebRequest -Uri $url -OutFile $zipPath
122
AWS X-Ray EntwicklerhandbuchIn Amazon EC2
Add-Type -Assembly "System.IO.Compression.Filesystem" [io.compression.zipfile]::ExtractToDirectory($zipPath, $destPath)
New-Service -Name "AWSXRayDaemon" -StartupType Automatic -BinaryPathName "`"$daemonPath`" -f `"$daemonLogPath`"" sc.exe start AWSXRayDaemon encoding: plain "c:/Program Files/Amazon/ElasticBeanstalk/config/taillogs.d/xray-daemon.conf" : mode: "000644" owner: root group: root content: | C:\Program Files\Amazon\XRay\xray-daemon.log
In diesen Beispielen wird die Protokolldatei des Daemons außerdem der Elastic Beanstalk-Protokollfragmentaufgabe hinzugefügt, um sie einzubeziehen, wenn Sie Protokolle mit der Konsole oderElastic Beanstalk-Befehlszeilenschnittstelle (EB CLI) anfordern.
Ausführen des X-Ray-Daemons in Amazon EC2Sie können den X-Ray-Daemon unter folgenden Betriebssystemen in Amazon EC2 ausführen:
• Amazon Linux• Ubuntu • Windows Server (2012 R2 und neuer)
Verwenden Sie ein Instance-Profil, um dem Daemon die Berechtigung zum Hochladen vonAblaufverfolgungsdaten auf X-Ray zu erteilen. Weitere Informationen finden Sie unter Erteilen derBerechtigung zum Senden von Daten an X-Ray für den Daemon (p. 114).
Verwenden Sie ein Benutzerdatenskript, um den Daemon automatisch auszuführen, wenn Sie die Instancestarten.
Example Benutzerdatenskript – Linux
#!/bin/bashcurl https://s3.dualstack.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-2.x.rpm -o /home/ec2-user/xray.rpmyum install -y /home/ec2-user/xray.rpm
Example Benutzerdatenskript – Windows Server
<powershell>if ( Get-Service "AWSXRayDaemon" -ErrorAction SilentlyContinue ) { sc.exe stop AWSXRayDaemon sc.exe delete AWSXRayDaemon}
$targetLocation = "C:\Program Files\Amazon\XRay"if ((Test-Path $targetLocation) -eq 0) { mkdir $targetLocation}
$zipFileName = "aws-xray-daemon-windows-service-2.x.zip"$zipPath = "$targetLocation\$zipFileName"$destPath = "$targetLocation\aws-xray-daemon"if ((Test-Path $destPath) -eq 1) {
123
AWS X-Ray EntwicklerhandbuchIn Amazon ECS
Remove-Item -Recurse -Force $destPath}
$daemonPath = "$destPath\xray.exe"$daemonLogPath = "$targetLocation\xray-daemon.log"$url = "https://s3.dualstack.us-west-2.amazonaws.com/aws-xray-assets.us-west-2/xray-daemon/aws-xray-daemon-windows-service-2.x.zip"
Invoke-WebRequest -Uri $url -OutFile $zipPathAdd-Type -Assembly "System.IO.Compression.Filesystem"[io.compression.zipfile]::ExtractToDirectory($zipPath, $destPath)
New-Service -Name "AWSXRayDaemon" -StartupType Automatic -BinaryPathName "`"$daemonPath`" -f `"$daemonLogPath`""sc.exe start AWSXRayDaemon</powershell>
Ausführen des X-Ray-Daemons in Amazon ECSErstellen Sie in Amazon ECS ein Docker-Image, das den X-Ray-Daemon ausführt. Laden Sie es inein Docker-Image-Repository hoch und stellen Sie es dann für Ihren Amazon ECS-Cluster bereit.Sie können Ihrer Anwendung über Port-Zuordnungen und Netzwerkmodus-Einstellungen in IhrerAufgabendefinitionsdatei die Kommunikation mit dem Daemon-Container ermöglichen.
Note
Die Scorekeep-Beispielanwendung zeigt, wie der X-Ray-Daemon auf Amazon ECS verwendetwird. Details dazu finden Sie unter Instrumentierung von Amazon ECS Anwendungen (p. 102).
Fügen Sie verwaltete Richtlinien zu Ihrer Aufgabenrolle hinzu, um dem Daemon Berechtigung zumHochladen von Ablaufverfolgungsdaten in X-Ray zu gewähren. Weitere Informationen finden Sie unterErteilen der Berechtigung zum Senden von Daten an X-Ray für den Daemon (p. 114).
Erstellen Sie mit einer der folgenden Dockerfiles ein Abbild, mit dem der Daemon ausführt wird.
Example Dockerfile – Amazon Linux
FROM amazonlinuxRUN yum install -y unzipRUN curl -o daemon.zip https://s3.dualstack.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-linux-2.x.zipRUN unzip daemon.zip && cp xray /usr/bin/xrayENTRYPOINT ["/usr/bin/xray", "-b", "0.0.0.0:2000"]EXPOSE 2000/udp
Example Dockerfile – Ubuntu
Für Debian-Derivate müssen Sie auch Zertifikate installieren, die von einer Zertifizierungsstelle (CertificateAuthority, CA) ausgegeben wurden, um Probleme beim Herunterladen des Installationsprogramms zuvermeiden.
FROM ubuntu:16.04RUN apt-get update && apt-get install -y --force-yes --no-install-recommends apt-transport-https curl ca-certificates wget && apt-get clean && apt-get autoremove && rm -rf /var/lib/apt/lists/*RUN wget https://s3.dualstack.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-2.x.debRUN dpkg -i aws-xray-daemon-2.x.debCMD ["/usr/bin/xray", "--bind=0.0.0.0:2000"]
124
AWS X-Ray EntwicklerhandbuchIn Amazon ECS
EXPOSE 2000/udp
In Ihrer Aufgabendefinition hängt die Konfiguration von dem Netzwerkmodus ab, den Sie tatsächlichnutzen. Brückennetzwerke sind die Standardeinstellung und können in Ihrer Standard-VPCverwendet werden. Veröffentlichen Sie in einem Brückennetzwerk UDP-Port 2000 und erstellenSie einen Link von Ihrem Anwendungs-Container zum Daemon-Container. Geben Sie mithilfe derAWS_XRAY_DAEMON_ADDRESS-Umgebungsvariable das X-Ray-SDK an, an das Ablaufverfolgungengesendet werden sollen.
Example Aufgabendefinition
{ "name": "xray-daemon", "image": "123456789012.dkr.ecr.us-east-2.amazonaws.com/xray-daemon", "cpu": 32, "memoryReservation": 256, "portMappings" : [ { "hostPort": 2000, "containerPort": 2000, "protocol": "udp" } ], }, { "name": "scorekeep-api", "image": "123456789012.dkr.ecr.us-east-2.amazonaws.com/scorekeep-api", "cpu": 192, "memoryReservation": 512, "environment": [ { "name" : "AWS_REGION", "value" : "us-east-2" }, { "name" : "NOTIFICATION_TOPIC", "value" : "arn:aws:sns:us-east-2:123456789012:scorekeep-notifications" }, { "name" : "AWS_XRAY_DAEMON_ADDRESS", "value" : "xray-daemon:2000" } ], "portMappings" : [ { "hostPort": 5000, "containerPort": 5000 } ], "links": [ "xray-daemon" ] }
Wenn Sie Ihren Cluster im privaten Subnetz einer VPC ausführen, können Sie Ihren Containern mit demawsvpc-Netzwerkmodus einer Elastic Network-Schnittstelle (ENI) zuweisen. Auf diese Weise können Siedie Nutzung von Links vermeiden. Lassen Sie den Host-Port in den Port-Zuordnungen, dem Link und derUmgebungsvariable AWS_XRAY_DAEMON_ADDRESS weg.
Example VPC-Aufgabendefinition
{ "family": "scorekeep", "networkMode":"awsvpc", "containerDefinitions": [ { "name": "xray-daemon", "image": "123456789012.dkr.ecr.us-east-2.amazonaws.com/xray-daemon", "cpu": 32,
125
AWS X-Ray EntwicklerhandbuchIn Amazon ECS
"memoryReservation": 256, "portMappings" : [ { "containerPort": 2000, "protocol": "udp" } ] } { "name": "scorekeep-api", "image": "123456789012.dkr.ecr.us-east-2.amazonaws.com/scorekeep-api", "cpu": 192, "memoryReservation": 512, "environment": [ { "name" : "AWS_REGION", "value" : "us-east-2" }, { "name" : "NOTIFICATION_TOPIC", "value" : "arn:aws:sns:us-east-2:123456789012:scorekeep-notifications" } ], "portMappings" : [ { "containerPort": 5000 } ] } ]
126
AWS X-Ray Entwicklerhandbuch
AWS X-Ray SDK für JavaDas X-Ray SDK for Java besteht aus einer Reihe von Bibliotheken für Java-Webanwendungen, dieKlassen und Methoden zum Generieren und Senden von Ablaufverfolgungsdaten zum X-Ray-Daemonbereitstellen. Ablaufverfolgungsdaten enthalten Informationen zu eingehenden HTTP-Anforderungen, dievon der Anwendung verarbeitet werden, sowie Aufrufen, die Anwendung an nachgelagerten Servicesmithilfe des AWS SDK, von HTTP-Clients oder einer SQL-Datenbankanbindung vornimmt. Sie könnenSegmente auch manuell erstellen und Debug-Informationen Anmerkungen und Metadaten hinzufügen.
Note
Das X-Ray SDK for Java ist ein Open-Source-Projekt. Sie können das Projekt auf GitHubverfolgen und Probleme und Pull-Anforderungen übermitteln: github.com/aws/aws-xray-sdk-java
Fügen Sie zunächst AWSXRayServletFilter als Servlet-Filter (p. 135) hinzu, um eingehendeAnforderungen zu verfolgen. Ein servlet-Filter erstellt ein Segment (p. 20) Während das Segment geöffnetist, können Sie mithilfe der SDK-Client-Methoden dem Segment Informationen hinzufügen, Untersegmenteerstellen und nachgelagerte Aufrufe zurückverfolgen. Das SDK erfasst auch automatisch Ausnahmen, dieIhre Anwendung ausgibt, während das Segment geöffnet ist.
Ab Version 1.3 können Sie jetzt Ihre Anwendung mit aspekt-orientierter Programmierung (AOP) inSpring (p. 148) instrumentieren. Das heißt, Sie können Ihre Anwendung instrumentieren, während sie aufAWS ausgeführt wird, ohne der Laufzeitumgebung Ihrer Anwendung Code hinzufügen zu müssen.
Verwenden Sie dann X-Ray SDK for Java, um Ihre AWS SDK for Java-Clients durch zu instrumentieren,einschließlich des Untermoduls SDK-Instrumentor (p. 129) in Ihrer Build-Konfiguration. Sobald Sieeine Anfrage stellen, um einen AWS-Service oder eine Ressource mit einem instrumentierten Clientrückzuverfolgen, zeichnet SDK in einem Untersegment Informationen zu dieser Anfrage auf. AWS-Servicesund die Ressourcen, auf die Sie innerhalb der Services zugreifen, erscheinen in der Service-Übersicht alsnachgelagerte Knoten, um Ihnen bei der Identifikation von Fehlern und der Ablehnung von Problemen mitindividuellen Verbindungen zu helfen.
Wenn Sie nicht alle nachgelagerten Aufrufe der AWS-Services instrumentieren möchten, können Siedas Instrumentor-Untermodul weglassen und auswählen, welche Clients instrumentiert werden sollen.Instrumentieren Sie einzelne Clients, indem Sie einen TracingHandler (p. 138) für einen AWS SDK-Service-Client hinzufügen.
Andere X-Ray SDK for Java-Untermodule bieten Instrumentierung für nachgelagerte Aufrufe von HTTP-Web-APIs und SQL-Datenbanken. Sie können die HTTPClient- und HTTPClientBuilder (p. 139)-Versionen von X-Ray SDK for Java im Apache HTTP-Untermodul verwenden, um Apache HTTP-Clientszu instrumentieren. Um SQL-Anfragen zu instrumentieren, fügen Sie der Datenquelle den SDK-Interceptorhinzu (p. 141).
Sobald Sie die ersten Schritte mit dem SDK gemacht haben, können Sie das Verhalten durch dieKonfiguration des Aufzeichnungs- und Servlet-Filters (p. 130) individualisieren. Sie können Plugins zumFesthalten von Daten über die Datenverarbeitungsressourcen, auf denen Ihre Anwendung ausgeführt wird,hinzufügen, das Samplingverhalten durch Samplingregeln anpassen und Protokollebenen einrichten, ummehr oder weniger Informationen von dem SDK in Ihren Anwendungsprotokollen zu sehen.
Zeichnen Sie zusätzliche Informationen zu Anforderungen und den Aufgaben, die Ihre Anwendungausführt, in Anmerkungen und Metadaten (p. 144) auf. Anmerkungen sind einfache Schlüsselwertpaare,die für die Verwendung mit Filterausdrücken (p. 39) indiziert werden, damit Sie nach Ablaufverfolgen mit
127
AWS X-Ray EntwicklerhandbuchVoraussetzungen
bestimmten Daten suchen können. Metadateneinträge sind weniger einschränkend und können ganzeObjekte und Arrays aufzeichnen – alle Daten, die in eine JSON zusammengefasst werden können.
Anmerkungen und Metadaten
Anmerkungen und Metadaten sind beliebiger Text, den Sie mit dem X-Ray-SDK zu Segmentenhinzufügen. Anmerkung werden für die Verwendung mit Filterausdrücken indiziert. Metadatawerden nicht indiziert, können aber im unformatierten Segment mit der X-Ray-Konsole oder -API angezeigt werden. Alle Personen, denen Sie Lesezugriff auf X-Ray gewähren, können dieseDaten anzeigen.
Wenn Sie viele instrumentierten Clients in Ihrem Code haben, kann ein einzelnes Anforderungssegmenteviele Untersegmente enthalten, eines für jeden Aufruf mit einem instrumentierten Client. Sie könnenUntersegmente organisieren und gruppieren, indem Sie Client-Aufrufe in benutzerdefiniertenUntersegmenten (p. 142) zusammenfassen. Sie können ein benutzerdefiniertes Untersegment für eineganze Funktion oder eine Code-Abschnitt erstellen und Metadaten und Anmerkungen im Untersegmentfesthalten, anstatt alles im übergeordneten Segment aufzuzeichnen.
Sie können das X-Ray SDK for Java von Maven herunterladen. Das X-Ray SDK for Java ist in Untermodulenach Anwendungsfall aufgeteilt, mit einer Stückliste für die Versionsverwaltung:
• aws-xray-recorder-sdk-core (erforderlich) – Grundlegende Funktionen zur Erstellung undÜbermittlung von Segmenten. Umfasst AWSXRayServletFilter für die Instrumentierung eingehenderAnforderungen.
• aws-xray-recorder-sdk-aws-sdk – Instrumentiert Aufrufe der AWS-Services, die mit AWS SDKfor Java-Clients vorgenommen werden, indem einen Ablaufverfolgungs-Client als Anforderungshandlerhinzugefügt wird.
• aws-xray-recorder-sdk-aws-sdk-instrumentor – Mit aws-xray-recorder-sdk-aws-sdkwerden alle AWS SDK for Java-Clients automatisch instrumentiert.
• aws-xray-recorder-sdk-apache-http – Instrumentiert ausgehende HTTP-Aufrufe, die mit ApacheHTTP-Clients erfolgen.
• aws-xray-recorder-sdk-spring – Stellt Interceptors for Spring AOP Framework-Anwendungenbereit.
• aws-xray-recorder-sdk-sql-postgres – Instrumentiert ausgehende Aufrufe der PostgreSQL-Datenbank, die mit JDBC erfolgen.
• aws-xray-recorder-sdk-sql-mysql – Instrumentiert ausgehende Aufrufe der MySQL-Datenbank,die mit JDBC erfolgen.
• aws-xray-recorder-sdk-bom – Bietet eine Stückliste, die Sie verwenden können, um die für alleUntermodule zu verwendende Version anzugeben.
Wenn Sie Maven oder Gradle verwenden, um Ihre Anwendung zu erstellen, fügen Sie das X-Ray SDK forJava Ihrer Build-Konfiguration hinzu (p. 129).
Referenzdokumentation zu den SDK-Klassen und -Methoden finden Sie unter Referenz zur AWS X-RaySDK für Java API.
VoraussetzungenDas X-Ray SDK for Java erfordert Java 8 oder höher, Servlet API 3, das AWS SDK und Jackson.
Das SDK hängt von den folgenden Bibliotheken zur Kompilierungs- und Laufzeit ab:
• AWS SDK for Java Version 1.11.106 oder höher
128
AWS X-Ray EntwicklerhandbuchAbhängigkeitsmanagement
• Servlet API 3.1.0
Diese Abhängigkeiten werden in der pom.xml-Datei des SDK deklariert und automatisch eingefügt, wennSie Maven oder Gradle für die Build-Erstellung verwenden.
Wenn Sie eine Bibliothek verwenden, die im X-Ray SDK for Java enthalten ist, müssen Sie die mitgelieferteVersion nutzen. Wenn Sie beispielsweise bereits von Jackson zur Laufzeit abhängen und für dieseAbhängigkeit JARs in Ihre Bereitstellung aufnehmen, müssen Sie diese JARs entfernen, da das SDK JAReigene Versionen von Jackson-Bibliotheken umfasst.
AbhängigkeitsmanagementDas X-Ray SDK for Java ist über Maven verfügbar:
• Gruppe – com.amazonaws• Stückliste – aws-xray-recorder-sdk-bom• Version – 1.3.1
Wenn Sie Ihre Anwendung mit Maven erstellen, fügen Sie das SDK als Abhängigkeit in Ihrer pom.xml-Datei hinzu.
Example pom.xml - Abhängigkeiten
<dependencyManagement> <dependencies> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-bom</artifactId> <version>1.3.1</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies></dependencyManagement><dependencies> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-core</artifactId> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-apache-http</artifactId> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-aws-sdk</artifactId> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-aws-sdk-instrumentor</artifactId> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-sql-postgres</artifactId> </dependency> <dependency> <groupId>com.amazonaws</groupId>
129
AWS X-Ray EntwicklerhandbuchKonfiguration
<artifactId>aws-xray-recorder-sdk-sql-mysql</artifactId> </dependency></dependencies>
Für Gradle fügen Sie das SDK als Kompilierungszeitabhängigkeit in Ihrer build.gradle-Datei hinzu.
Example build.gradle – Abhängigkeiten
dependencies { compile("org.springframework.boot:spring-boot-starter-web") testCompile("org.springframework.boot:spring-boot-starter-test") compile("com.amazonaws:aws-java-sdk-dynamodb") compile("com.amazonaws:aws-xray-recorder-sdk-core") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk-instrumentor") compile("com.amazonaws:aws-xray-recorder-sdk-apache-http") compile("com.amazonaws:aws-xray-recorder-sdk-sql-postgres") compile("com.amazonaws:aws-xray-recorder-sdk-sql-mysql") testCompile("junit:junit:4.11")}dependencyManagement { imports { mavenBom('com.amazonaws:aws-java-sdk-bom:1.11.39') mavenBom('com.amazonaws:aws-xray-recorder-sdk-bom:1.3.1') }}
Wenn Sie Ihre Anwendung mit Elastic Beanstalk bereitstellen, können Sie Maven oder Gradle verwenden,um die Build-Erstellung bei jeder Bereitstellung für die einzelne Instance vorzunehmen, statt ein großesArchiv zu erstellen und hochzuladen, das alle Abhängigkeiten enthält. Für ein Beispiel, bei dem Gradleverwendet wird, sehen Sie sich die Beispielanwendung (p. 89) an.
Konfigurieren des X-Ray SDK for JavaDas X-Ray SDK for Java bietet eine Klasse namens AWSXRay, die die globale Aufzeichnung bereitstellt,einen TracingHandler, mit dem Sie Ihren Code instrumentieren können. Sie können die globaleAufzeichnung so konfigurieren, dass der AWSXRayServletFilter, der Segmente für eingehende HTTP-Aufrufe erstellt, angepasst wird.
Abschnitte• Service-Plugins (p. 130)• Samplingregeln (p. 132)• Protokollierung (p. 134)• Umgebungsvariablen (p. 134)• Systemeigenschaften (p. 135)
Service-PluginsUse plugins to record information about the service hosting your application.
Plugins
• Amazon EC2 – EC2Plugin fügt die Instance-ID und Availability Zone hinzu.
130
AWS X-Ray EntwicklerhandbuchService-Plugins
• Elastic Beanstalk – ElasticBeanstalkPlugin fügt den Umgebungsnamen, die Versionsbezeichnungund die Bereitstellungs-ID hinzu.
• Amazon ECS – ECSPlugin fügt die Container-ID hinzu.
Um ein Plugin zu verwenden, rufen Sie withPlugin im AWSXRayRecorderBuilder auf.
Example src/main/java/scorekeep/WebConfig.java – Aufzeichnung
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.AWSXRayRecorderBuilder;import com.amazonaws.xray.plugins.EC2Plugin;import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin;import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
@Configuration
131
AWS X-Ray EntwicklerhandbuchSamplingregeln
public class WebConfig {... static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build()); }}
Das SDK verwendet auch Plug-in-Einstellungen, um das origin-Feld im Segment auszufüllen.Dies gibt den Typ der AWS-Ressource an, die Ihre Anwendung ausführt. Der Ressourcentypwird unter dem Namen der Anwendung in der Service-Übersicht angezeigt. Beispiel,AWS::ElasticBeanstalk::Environment.
Wenn Sie mehrere Plug-ins verwenden, benutzt das SDK das zuletzt geladene Plug-in.
SamplingregelnDas SDK hat eine Sampling-Strategie, durch die bestimmt wird, welche Anfragen verfolgt werden.Standardmäßig zeichnet das SDK die erste Anfragen pro Sekunde und fünf Prozent aller weiterenAnfragen. auf. Sie können das Sampling-Verhalten des SDK durch die Anwendung von Regeln anpassen,die in einer lokalen Datei definiert sind.
Example sampling-rules.json
{ "version": 1, "rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1,
132
AWS X-Ray EntwicklerhandbuchSamplingregeln
"rate": 0.1 }}
In diesem Beispiel sind eine benutzerdefinierte Regel und eine Standardregel definiert. Diebenutzerdefinierte Regel wendet eine Abtastrate von fünf Prozent ohne minimale Anforderungsanzahlauf die Verfolgung von Pfaden unter /api/move/ an. Die Standardregel verfolgt die erste Anfragen proSekunde und 10 % aller weiteren Anfragen.
Das SDK wendet benutzerdefinierte Regeln in der Reihenfolge an, in der sie definiert sind. Wenn eineAnfrage mehreren benutzerdefinierten Regeln entspricht, wendet das SDK nur die erste Regel an.
In Lambda können Sie die Samplingrate nicht ändern. Wenn Ihre Funktion von einem instrumentiertenService aufgerufen wird, werden von Aufrufen erzeugte Anforderungen, für die von diesem Service einSampling durchgeführt wird, von Lambda aufgezeichnet. Bei aktiver Nachverfolgung ohne vorhandenenNachverfolgungs-Header trifft Lambda die Sampling-Entscheidung.
Für Spring konfigurieren Sie die globale Aufzeichnung in einer Konfigurationsklasse.
Example src/main/java/myapp/WebConfig.java – Aufzeichnungskonfiguration
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.AWSXRayRecorderBuilder;import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;import com.amazonaws.xray.plugins.EC2Plugin;import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
@Configurationpublic class WebConfig {
static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());
URL ruleFile = WebConfig.class.getResource("file://sampling-rules.json"); builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());}
Für Tomcat fügen Sie einen Listener hinzu, der ServletContextListener erweitert.
Example src/com/myapp/web/Startup.java
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.AWSXRayRecorderBuilder;import com.amazonaws.xray.plugins.EC2Plugin;import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
import java.net.URL;import javax.servlet.ServletContextEvent;import javax.servlet.ServletContextListener;
public class Startup implements ServletContextListener {
@Override public void contextInitialized(ServletContextEvent event) { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());
URL ruleFile = Startup.class.getResource("/sampling-rules.json");
133
AWS X-Ray EntwicklerhandbuchProtokollierung
builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build()); }
@Override public void contextDestroyed(ServletContextEvent event) { }}
Registrieren Sie den Listener in der Bereitstellungsbeschreibung.
Example WEB-INF/web.xml
... <listener> <listener-class>com.myapp.web.Startup</listener-class> </listener>
ProtokollierungDas SDK gibt standardmäßig Meldungen auf SEVERE- und ERROR-Ebene an Ihre Anwendungsprotokolleaus. Sie können eine Protokollierung auf Debug-Ebene aktivieren, so dass das SDK detailliertere Protokollean Ihre Anwendungsprotokolldatei ausgibt.
Example application.properties
Legen Sie die Protokollierungsebene mit der logging.level.com.amazonaws.xray-Eigenschaft fest.
logging.level.com.amazonaws.xray = DEBUG
Verwenden Sie Debug-Protokolle, um Probleme wie nicht geschlossene Untersegmente zu identifizieren,wenn Sie Untersegmente manuell generieren (p. 142).
UmgebungsvariablenSie können Umgebungsvariablen zum Konfigurieren von X-Ray SDK for Java verwenden. Das SDKunterstützt die folgenden Variablen.
• AWS_XRAY_TRACING_NAME – Legen Sie einen Dienstnamen fest, der vom SDK für Segmente verwendetwird. Überschreibt den für die Segmentbenennungsstrategie (p. 137) des Servlet-Filters festgelegtenDienstnamen.
• AWS_XRAY_DAEMON_ADDRESS – Legen Sie den Host und den Port des X-Ray-Daemon-Listeners fest.Standardmäßig sendet das SDK Ablaufverfolgungsdaten an 127.0.0.1:2000. Verwenden Sie dieseVariable, wenn Sie den Daemon so konfiguriert haben, dass er einen anderen Port überwacht (p. 115),oder wenn er auf einem anderen Host ausgeführt wird.
• AWS_XRAY_CONTEXT_MISSING – Set to LOG_ERROR to avoid throwing exceptions when yourinstrumented code attempts to record data when no segment is open.
Valid Values
• RUNTIME_ERROR – Throw a runtime exception (default).• LOG_ERROR – Log an error and continue.
Errors related to missing segments or subsegments can occur when you attempt to use an instrumentedclient in startup code that runs when no request is open, or in code that spawns a new thread.
134
AWS X-Ray EntwicklerhandbuchSystemeigenschaften
Umgebungsvariablen überschreiben äquivalente Systemeigenschaften (p. 135) und Werte in Code.
SystemeigenschaftenSie können Systemeigenschaften als JVM-spezifische Alternative zu Umgebungsvariablen (p. 134)verwenden. Das SDK unterstützt die folgenden Eigenschaften.
• com.amazonaws.xray.strategy.tracingName – Äquivalent zu AWS_XRAY_TRACING_NAME.• com.amazonaws.xray.emitters.daemonAddress – Äquivalent zu AWS_XRAY_DAEMON_ADDRESS.• com.amazonaws.xray.strategy.contextMissingStrategy – Äquivalent zuAWS_XRAY_CONTEXT_MISSING.
Wenn eine Systemeigenschaft und die entsprechende Umgebungsvariable eingerichtet sind, werden dieWerte der Umgebungsvariablen verwendet. Bei beiden Methoden werden Werte in Code überschrieben.
Ablaufverfolgung eingehender Anforderungen mitdem X-Ray SDK for Java
Sie können mit dem X-Ray SDK eingehende HTTP-Anforderungen verfolgen, die Ihre Anwendung auf einerEC2 Instance in Amazon EC2, AWS Elastic Beanstalk oder Amazon ECS verarbeitet.
Verwenden Sie einen Filter, um eingehende HTTP-Anforderungen zu instrumentieren. Wenn Sie den X-Ray-Servlet-Filter zu Ihrer Anwendung hinzufügen, erstellt das X-Ray SDK for Java ein Segment für jedestichprobenartig geprüfte Anforderung. Dieses Segment umfasst Dauer, Methode und Status der HTTP-Anforderung. Die zusätzliche Instrumentierung schafft Untersegmente zu diesem Segment.
Note
Lambda erstellt für AWS Lambda-Funktionen ein Segment für jede Anforderung, die per Samplingerfasst wurde. Weitere Informationen finden Sie unter AWS Lambda und AWS X-Ray (p. 229).
Each segment has a name that identifies your application in the service map. The segment can be namedstatically, or you can configure the SDK to name it dynamically based on the host header in the incomingrequest. Dynamic naming lets you group traces based on the domain name in the request, and apply adefault name if the name doesn't match an expected pattern (for example, if the host header is forged).
Weitergeleitete Anfragen
Wenn ein Load Balancer oder ein anderer Mittler eine Anforderung an Ihre Anwendungweiterleitet, übernimmt X-Ray die Client-IP aus der X-Forwarded-For-Kopfzeile der Anforderungund nicht aus der Quell-IP im IP-Paket. Die für eine weitergeleitete Anforderung aufgezeichneteClient-IP kann gefälscht sein und ist daher nicht vertrauenswürdig.
When a request is forwarded, the SDK sets an additional field in the segment to indicate this. If the segmentcontains the field x_forwarded_for set to true, the client IP was taken from the X-Forwarded-Forheader in the HTTP request.
Der Meldungshandler erzeugt für jede eingehende Anforderung ein Segment mit einem http-Block, derdie folgenden Informationen enthält:
• HTTP-Methode – GET, POST, PUT, DELETE usw.• Client-Adresse – Die IP-Adresse des Clients, der die Anforderung gesendet hat.
135
AWS X-Ray EntwicklerhandbuchHinzufügen eines Ablaufverfolgungsfilters
zu Ihrer Anwendung (Tomcat)
• Antwortcode – Der HTTP-Antwortcode für die abgeschlossene Anforderung.• Dauer – Die Startzeit (zu der die Anforderung empfangen wurde) und die Endzeit (zu der die Antwort
gesendet wurde).• Nutzer-Agent — Der user-agent aus der Anfrage.• Inhaltslänge — Die content-length aus der Antwort.
Abschnitte• Hinzufügen eines Ablaufverfolgungsfilters zu Ihrer Anwendung (Tomcat) (p. 136)• Hinzufügen eines Ablaufverfolgungsfilters zu Ihrer Anwendung (Spring) (p. 136)• Konfiguration einer Segmentbenennungsstrategie (p. 137)
Hinzufügen eines Ablaufverfolgungsfilters zu IhrerAnwendung (Tomcat)Im Fall von Tomcat fügen Sie einen <filter> zur web.xml-Datei Ihres Projekts hinzu. Legen Sie mit demfixedName Parameter einen Servicenamen (p. 137) fest, damit die erstellten Segmente auf eingehendeAnforderungen angewendet werden.
Example WEB-INF/web.xml – Tomcat
<filter> <filter-name>AWSXRayServletFilter</filter-name> <filter-class>com.amazonaws.xray.javax.servlet.AWSXRayServletFilter</filter-class> <init-param> <param-name>fixedName</param-name> <param-value>MyApp</param-value> </init-param></filter><filter-mapping> <filter-name>AWSXRayServletFilter</filter-name> <url-pattern>*</url-pattern></filter-mapping>
Hinzufügen eines Ablaufverfolgungsfilters zu IhrerAnwendung (Spring)Für Spring fügen Sie einen Filter zu Ihrer WebConfig-Klasse hinzu. Übermitteln Sie denSegmentnamen als Zeichenfolge an den AWSXRayServletFilter-Konstruktor.
Example src/main/java/myapp/WebConfig.java – Spring
package myapp;import org.springframework.context.annotation.Configuration;import org.springframework.context.annotation.Bean;import javax.servlet.Filter;import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;
@Configurationpublic class WebConfig {
@Bean public Filter TracingFilter() {
136
AWS X-Ray EntwicklerhandbuchKonfiguration einer Segmentbenennungsstrategie
return new AWSXRayServletFilter("Scorekeep"); }}
Konfiguration einer SegmentbenennungsstrategieAWS X-Ray verwendet einen Servicenamen, um Ihre Anwendung zu identifizieren und sie von anderenAnwendungen, Datenbanken, externen APIs und AWS-Ressourcen zu unterscheiden, die Ihre Anwendungnutzt. Wenn das X-Ray SDK Segmente für eingehende Anfragen generiert, zeichnet es den ServicenamenIhrer Anwendung im Feld name field (p. 73) auf.
Das X-Ray SDK kann Segmente nachdem Hostnamen im HTTP-Anfrageheader benennen. Dieser Headerkann jedoch gefälscht sein, was zu unerwarteten Knoten in Ihrer Service-Übersicht führen könnte. Und zuverhindern, dass das SDK Segmente aufgrund von Anforderungen mit gefälschten Host-Headern falschbenennt, müssen Sie einen standardmäßigen Namen für eingehende Anfragen angeben.
Wenn Ihre Anwendung Anfragen für mehrere Domänen bedient, können Sie das SDK so konfigurieren,dass es eine dynamische Benennungsstrategie verwendet, um dies in den Segmentnamen zuberücksichtigen. Eine dynamische Benennungsstrategie erlaubt es dem SDK, den Host-Namen beiAnfragen zu verwenden, die einem erwarteten Muster entsprechen, und den standardmäßigen Namen fürsolche zu vergeben, die es nicht tun.
Beispielsweise haben Sie vielleicht eine einzelne Anwendung, die Anfragen für drei Subdomänen bedient,– www.example.com, api.example.com und static.example.com. Sie können eine dynamischeBenennungsstrategie mit dem Muster *.example.com verwenden, um Segmente für die einzelnenSubdomänen unterschiedlich zu benennen. Auf der Service-Übersicht werden dann drei Service-Knotenangezeigt. Wenn Ihre Anwendung Anfragen mit einem Hostnamen erhält, der diesem Muster nichtentspricht, sehen Sie auf der Service-Übersicht einen vierten Knoten mit einem von Ihnen festgelegtenAusweichnamen.
Wenn Sie denselben Namen für alle Segmente verwenden möchten, geben Sie bei der Initialisierung desServlet-Filters den Namen Ihrer Anwendung, wie im vorherigen Abschnitt (p. 136) gezeigt, ein. Dies hatden gleichen Effekt wie die Erstellung einer FixedSegmentNamingStrategy und die Übergabe an einenAWSXRayServletFilter-Konstruktor.
Note
Sie können den mit der AWS_XRAY_TRACING_NAME-Umgebungsvariablen (p. 134) in Codedefinierten standardmäßigen Dienstnamen überschreiben.
Eine dynamische Benennungsstrategie definiert ein Muster, dem Hostnamen entsprechen sollten,sowie einen Standardnamen, der verwendet wird, wenn der Hostname in der HTTP-Anforderung nichtmit diesem Muster übereinstimmt. Alternativ können Sie dynamicNamingRecognizedHosts unddynamicNamingFallbackName nutzen, um das Muster und den Standardnamen zu bestimmen undSegmente in Tomcat dynamisch zu benennen.
Example WEB-INF/web.xml – Servlet-Filter mit dynamischer Benennung
<filter> <filter-name>AWSXRayServletFilter</filter-name> <filter-class>com.amazonaws.xray.javax.servlet.AWSXRayServletFilter</filter-class> <init-param> <param-name>dynamicNamingRecognizedHosts</param-name> <param-value>*.example.com</param-value> </init-param> <init-param> <param-name>dynamicNamingFallbackName</param-name> <param-value>MyApp</param-value>
137
AWS X-Ray EntwicklerhandbuchAWS SDK-Clients
</init-param></filter><filter-mapping> <filter-name>AWSXRayServletFilter</filter-name> <url-pattern>*</url-pattern></filter-mapping>
Erstellen Sie für Spring eine DynamicSegmentNamingStrategy und übertragen Sie sie an denAWSXRayServletFilter-Konstruktor.
Example src/main/java/myapp/WebConfig.java – Servlet-Filter mit dynamischer Benennung
package myapp;import org.springframework.context.annotation.Configuration;import org.springframework.context.annotation.Bean;import javax.servlet.Filter;import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;import com.amazonaws.xray.strategy.DynamicSegmentNamingStrategy;
@Configurationpublic class WebConfig {
@Bean public Filter TracingFilter() { return new AWSXRayServletFilter(new DynamicSegmentNamingStrategy("MyApp", "*.example.com")); }}
Verfolgen von AWS SDK-Aufrufen mit dem X-RaySDK for Java
Wenn Ihre Anwendung die AWS-Services aufruft, um Daten zu speichern, Daten in eine Warteschlangezu schreiben oder Benachrichtigungen zu senden, verfolgt das X-Ray SDK for Java die Aufrufe innachgelagerten Untersegmenten (p. 142). Verfolgte AWS-Services und -Ressourcen, auf die Sieinnerhalb dieser Services zugreifen (z. B. ein Amazon S3-Bucket oder eine Amazon SQS-Warteschlange)erscheinen als nachgelagerte Knoten in der Service-Übersicht der X-Ray-Konsole.
Das X-Ray SDK for Java instrumentiert alle AWS SDK-Clients automatisch, wenn Sie das aws-sdk sowiedie aws-sdk-instrumentor- und -Untermodule (p. 129) in Ihren Build aufnehmen. Wenn Sie dasInstrumentor-Untermodul nicht einbeziehen, können Sie auswählen, welche Clients Sie instrumentierenmöchten, und andere ausschließen.
Um einzelne Clients zu instrumentieren, entfernen Sie das aws-sdk-instrumentor-Untermodul ausIhrem Build und fügen Sie einen XRayClient als TracingHandler auf dem AWS SDK-Client mit demClient Builder des Service hinzu.
Wenn Sie beispielsweise einen AmazonDynamoDB-Client instrumentieren möchten, übergeben Sie einenAblaufverfolgungshandler an AmazonDynamoDBClientBuilder.
Example MyModel.java - DynamoDB-Client
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.handlers.TracingHandler;
...
138
AWS X-Ray EntwicklerhandbuchAusgehende HTTP-Aufrufe
public class MyModel { private AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard() .withRegion(Regions.fromName(System.getenv("AWS_REGION"))) .withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder())) .build();...
Bei allen Services wird der Name der aufgerufenen API in der X-Ray-Konsole angezeigt. Bei einerUntergruppe von Services fügt das X-Ray SDK Informationen zum Segment hinzu, um mehr Granularität inder Service-Übersicht zu erreichen.
Wenn Sie beispielsweise einen Aufruf mit einem instrumentierten DynamoDB-Client erstellen, fügt dasSDK für Aufrufe, die auf eine Tabelle abzielen, den Tabellennamen zu dem Segment hinzu. In der Konsolewerden die Tabellen als einzelne Knoten in der Service-Übersicht angezeigt, zusammen mit einemgenerischen DynamoDB-Knoten für Aufrufe, die nicht auf eine Tabelle abzielen.
Example Untersegment für einen Aufruf von DynamoDB zum Speichern eines Elements
{ "id": "24756640c0d0978a", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "DynamoDB", "namespace": "aws", "http": { "response": { "content_length": 60, "status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG", }}
Wenn Sie auf benannte Ressourcen zugreifen, werden durch Aufrufe der folgenden Services weitereKnoten in der Service-Übersicht erstellt. Durch Aufrufe, die keinen bestimmten Ressourcen gelten, wird eingenerischer Knoten für den Service erstellt.
• Amazon DynamoDB – Tabellenname• Amazon Simple Storage Service – Bucket und Schlüsselname• Amazon Simple Queue Service – Warteschlangenname
Nachverfolgen von Aufrufen nachgelagerter HTTP-Web-Services mit dem X-Ray SDK for Java
Wenn Ihre Anwendung Microservices oder öffentliche HTTP-APIs aufruft, können Sie diese Aufrufe mitder X-Ray SDK for Java-Version von HttpClient instrumentieren und die API der Service-Grafik alsnachgelagerten Service hinzufügen.
Das X-Ray SDK for Java enthält die Klassen DefaultHttpClient und HttpClientBuilder, dieanstelle der Apache HttpComponents-Entsprechungen verwendet werden können, um ausgehende HTTP-Aufrufe zu instrumentieren.
139
AWS X-Ray EntwicklerhandbuchAusgehende HTTP-Aufrufe
• com.amazonaws.xray.proxies.apache.http.DefaultHttpClient –org.apache.http.impl.client.DefaultHttpClient
• com.amazonaws.xray.proxies.apache.http.HttpClientBuilder –org.apache.http.impl.client.HttpClientBuilder
Diese Bibliotheken befinden sich im aws-xray-recorder-sdk-apache-http (p. 127)-Untermodul.
Sie können Ihre vorhandenen Importanweisungen mit der X-Ray-Entsprechung ersetzen, um alle Clients zuinstrumentieren, oder Sie können beim Initialisieren eines Clients den vollständigen Namen verwenden, umspezifische Clients zu instrumentieren.
Example HttpClientBuilder
import com.fasterxml.jackson.databind.ObjectMapper;import org.apache.http.HttpEntity;import org.apache.http.client.methods.CloseableHttpResponse;import org.apache.http.client.methods.HttpGet;import org.apache.http.impl.client.CloseableHttpClient;import org.apache.http.util.EntityUtils;import com.amazonaws.xray.proxies.apache.http.HttpClientBuilder;... public String randomName() throws IOException { CloseableHttpClient httpclient = HttpClientBuilder.create().build(); HttpGet httpGet = new HttpGet("http://names.example.com/api/"); CloseableHttpResponse response = httpclient.execute(httpGet); try { HttpEntity entity = response.getEntity(); InputStream inputStream = entity.getContent(); ObjectMapper mapper = new ObjectMapper(); Map<String, String> jsonMap = mapper.readValue(inputStream, Map.class); String name = jsonMap.get("name"); EntityUtils.consume(entity); return name; } finally { response.close(); } }
Wenn Sie einen Aufruf einer nachgelagerten Web-API instrumentieren, erfasst das X-Ray SDK for Javaein Untersegment mit Informationen über die HTTP-Anforderung und Antwort. X-Ray verwendet dasUntersegment, um ein abgeleitetes Segment für die entfernte API zu generieren.
Example Untersegment für einen nachgelagerten HTTP-Aufruf
{ "id": "004f72be19cddc2a", "start_time": 1484786387.131, "end_time": 1484786387.501, "name": "names.example.com", "namespace": "remote", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } }}
140
AWS X-Ray EntwicklerhandbuchSQL-Abfragen
Example Abgeleitetes Segment für einen nachgelagerten HTTP-Anruf
{ "id": "168416dc2ea97781", "name": "names.example.com", "trace_id": "1-5880168b-fd5153bb58284b67678aa78c", "start_time": 1484786387.131, "end_time": 1484786387.501, "parent_id": "004f72be19cddc2a", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } }, "inferred": true}
Rückverfolgung von SQL-Abfragen mit X-Ray SDKfor Java
Instrumentieren Sie SQL-Datenbankabfragen, indem Sie Ihrer Datenquellenkonfiguration den X-Ray SDKfor Java JDBC-Interceptor hinzufügen.
• PostgreSQL – com.amazonaws.xray.sql.postgres.TracingInterceptor• MySQL – com.amazonaws.xray.sql.mysql.TracingInterceptor
Diese Interceptors befinden sich im aws-xray-recorder-sql-postgres- bzw.aws-xray-recorder-sql-mysql-Untermodul (p. 127). Sie implementierenorg.apache.tomcat.jdbc.pool.JdbcInterceptor und sind mit Tomcat-Verbindungspoolskompatibel.
Für Spring fügen Sie der Eigenschaftendatei einen Interceptor hinzu und erstellen Sie die Datenquelle mitdem DataSourceBuilder von Spring Boot.
Example src/main/java/resources/application.properties – PostgreSQL-JDBC-Interceptor
spring.datasource.continue-on-error=truespring.jpa.show-sql=falsespring.jpa.hibernate.ddl-auto=create-dropspring.datasource.jdbc-interceptors=com.amazonaws.xray.sql.postgres.TracingInterceptorspring.jpa.database-platform=org.hibernate.dialect.PostgreSQL94Dialect
Example src/main/java/myapp/WebConfig.java – Datenquelle
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;import org.springframework.boot.autoconfigure.jdbc.DataSourceBuilder;import org.springframework.boot.context.properties.ConfigurationProperties;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;
141
AWS X-Ray EntwicklerhandbuchBenutzerdefinierte Untersegmente
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
import javax.servlet.Filter;import javax.sql.DataSource;import java.net.URL;
@Configuration@EnableAutoConfiguration@EnableJpaRepositories("myapp")public class RdsWebConfig {
@Bean @ConfigurationProperties(prefix = "spring.datasource") public DataSource dataSource() { logger.info("Initializing PostgreSQL datasource"); return DataSourceBuilder.create() .driverClassName("org.postgresql.Driver") .url("jdbc:postgresql://" + System.getenv("RDS_HOSTNAME") + ":" + System.getenv("RDS_PORT") + "/ebdb") .username(System.getenv("RDS_USERNAME")) .password(System.getenv("RDS_PASSWORD")) .build(); }...}
Für Tomcat rufen Sie in der JDBC-Datenquelle setJdbcInterceptors mit einer Referenz zur X-RaySDK for Java-Klasse auf.
Example src/main/myapp/model.java – Datenquelle
import org.apache.tomcat.jdbc.pool.DataSource;...DataSource source = new DataSource();source.setUrl(url);source.setUsername(user);source.setPassword(password);source.setDriverClassName("com.mysql.jdbc.Driver");source.setJdbcInterceptors("com.amazonaws.xray.sql.mysql.TracingInterceptor;");
Die Tomcat JDBC-Datenquellenbibliothek ist im X-Ray SDK for Java enthalten, Sie können sie jedoch alsbereitgestellte Abhängigkeit deklarieren, um zu dokumentieren, dass Sie sie verwenden.
Example pom.xml – JDBC-Datenquelle
<dependency> <groupId>org.apache.tomcat</groupId> <artifactId>tomcat-jdbc</artifactId> <version>8.0.36</version> <scope>provided</scope></dependency>
Erstellen von benutzerdefinierten Untersegmentenmit dem X-Ray SDK for Java
Untersegmente erweitern das Segment (p. 20) eines Traces um Details zu erledigten Aufgaben, umAnforderungen zu senden. Jedesmal, wenn Sie einen Aufruf mit einem instrumentierten Client erstellen,
142
AWS X-Ray EntwicklerhandbuchBenutzerdefinierte Untersegmente
erfasst das X-Ray SDK die in einem Untersegment erzeugten Informationen. Sie können zusätzlicheUntersegmente erstellten, um andere Untersegmente zu gruppieren, die Leistung eines Codeabschnitts zumessen oder Anmerkungen und Metadaten aufzuzeichnen.
Um Untersegmente zu verwalten, verwenden Sie die Methoden beginSubsegment und endSubsegment.
Example GameModel.java, - Benutzerdefinierte Untersegmente
import com.amazonaws.xray.AWSXRay;... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("Save Game"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } }
In diesem Beispiel lädt der Code innerhalb des Untersegments die Sitzung des Spiels von DynamoDBmit einer Methode für das Sitzungsmodell und speichert das Spiel mit dem DynamoDB-Mapper von AWSSDK for Java. Durch Verpacken dieses Codes in ein Untersegment werden die Aufrufe zu untergeordnetenDynamoDB-Elementen des Save Game-Untersegments in der Ablaufverfolgungsansicht der Konsole.
Wenn der Code in Ihrem Untersegment geprüfte Ausnahmen auslöst, verpacken Sie ihn in einen try-Block und rufen Sie AWSXRay.endSubsegment() in einem finally-Block auf, um sicherzustellen,dass das Untersegment immer geschlossen ist. Wenn ein Untersegment nicht geschlossen ist, kann dasübergeordnete Segment nicht abgeschlossen werden und wird nicht an X-Ray gesendet.
Code, der keine geprüften Ausnahmen auslöst, können Sie AWSXRay.CreateSubsegment als Lambda-Funktion übergeben.
Example Untersegment-Lambda-Funktion
import com.amazonaws.xray.AWSXRay;
143
AWS X-Ray EntwicklerhandbuchAnmerkungen und Metadaten
AWSXRay.createSubsegment("getMovies", (subsegment) -> { // function code});
Beim Erstellen eines Untersegments innerhalb eines Segments oder eines anderen Untersegmentsgeneriert das X-Ray SDK for Java eine ID dafür und erfasst die Start- und Endzeit.
Example Untersegment mit Metadaten
"subsegments": [{ "id": "6f1605cd8a07cb70", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "Custom subsegment for UserModel.saveUser function", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } },
Hinzufügen von Anmerkungen und Metadaten zuSegmenten mit X-Ray SDK for Java
Mithilfe von Anmerkungen und Metadaten können Sie zusätzliche Informationen zu Anforderungen, derUmgebung oder Ihrer Anwendung aufzeichnen. Sie können den vom X-Ray SDK erstellten Segmentenoder den von Ihnen erstellten benutzerdefinierten Untersegmenten Anmerkungen und Metadatenhinzufügen.
Annotations are key-value pairs with string, number, or Boolean values. Annotations are indexed for usewith filter expressions (p. 39). Use annotations to record data that you want to use to group traces in theconsole, or when calling the GetTraceSummaries API.
Metadata are key-value pairs that can have values of any type, including objects and lists, but are notindexed for use with filter expressions. Use metadata to record additional data that you want stored in thetrace but don't need to use with search.
Zusätzlich zu Anmerkungen und Metadaten können Sie auch Benutzer-ID-Zeichenfolgen (p. 147) inSegmenten aufzeichnen. Benutzer-IDs werden in einem eigenen Feld aufgezeichnet und zur Sucheindiziert.
Abschnitte• Aufzeichnung von Anmerkungen mit X-Ray SDK for Java (p. 144)• Aufzeichnung von Metadaten mit X-Ray SDK for Java (p. 146)• Aufzeichnung von Benutzer-IDs mit X-Ray SDK for Java (p. 147)
Aufzeichnung von Anmerkungen mit X-Ray SDK forJavaVerwenden Sie Anmerkungen, um Informationen zu Segmenten oder Untersegmenten, die zur Sucheindiziert werden sollten, aufzuzeichnen.
144
AWS X-Ray EntwicklerhandbuchAufzeichnung von Anmerkungen mit X-Ray SDK for Java
Anmerkung zu Anforderungen
• Schlüssel – Bis zu 500 alphanumerische Zeichen. Keine Leerzeichen oder Symbole außer Unterstrichen.• Werte – bis zu 1,000 Unicode-Zeichen.• Einträge – Bis zu 50 Anmerkungen pro Ablaufverfolgung.
So zeichnen Sie Anmerkungen auf
1. Eine Referenz des aktuellen Segments oder Untersegments finden Sie unter AWSXRay.
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.entities.Segment;...Segment document = AWSXRay.getCurrentSegment();
oder
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.entities.Subsegment;...Subsegment document = AWSXRay.getCurrentSubsegment();
2. Rufen Sie putAnnotation mit einem Aktivierungsschlüssel und einem booleschen Wert oder einemZeichenfolgenwert auf.
document.putAnnotation("mykey", "my value");
Das SDK zeichnet Anmerkungen als Schlüssel-Wert-Paare in einem annotations-Objekt imSegmentdokument auf. Wenn putAnnotation zweimal mit demselben Schlüssel aufgerufen wird, werdenzuvor aufgezeichnete Werte im gleichen Segment oder Untersegment überschrieben.
Nutzen Sie das annotations.key-Schlüsselwort in einem Filterausdruck (p. 39), um Ablaufverfolgungendurch Anmerkungen mit bestimmten Werten zu finden.
Example src/main/java/scorekeep/GameModel.java – Anmerkungen und Metadaten
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.entities.Segment;import com.amazonaws.xray.entities.Subsegment;... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } Segment segment = AWSXRay.getCurrentSegment(); subsegment.putMetadata("resources", "game", game); segment.putAnnotation("gameid", game.getId()); mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment();
145
AWS X-Ray EntwicklerhandbuchAufzeichnung von Metadaten mit X-Ray SDK for Java
} }
Aufzeichnung von Metadaten mit X-Ray SDK for JavaVerwenden Sie Metadaten, um Segment- oder Untersegmentinformationen aufzuzeichnen, die nicht zurSuche indiziert werden müssen. Metadatenwerte sind Zeichenfolgen, Zahlen, boolesche Werte oder andereObjekte, die in Form eines JSON-Objekts oder eines Arrays angeordnet sein können.
So zeichnen Sie Metadaten auf
1. Eine Referenz des aktuellen Segments oder Untersegments finden Sie unter AWSXRay.
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.entities.Segment;...Segment document = AWSXRay.getCurrentSegment();
oder
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.entities.Subsegment;...Subsegment document = AWSXRay.getCurrentSubsegment();
2. Rufen Sie putMetadata mit einem String-Namespace, einem Aktivierungsschlüssel sowie einembooleschen Wert, einer Zahl, einer Zeichenfolge oder einem Objektwert auf.
document.putMetadata("my namespace", "my key", "my value");
oder
Rufen Sie putMetadata nur mit einem Aktivierungsschlüssel und einem Wert auf.
document.putMetadata("my key", "my value");
Wenn Sie keinen Namespace angeben, verwendet SDK default. Wenn putMetadata zweimal mitdemselben Schlüssel aufgerufen wird, werden zuvor aufgezeichnete Werte im gleichen Segment oderUntersegment überschrieben.
Example src/main/java/scorekeep/GameModel.java – Anmerkungen und Metadaten
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.entities.Segment;import com.amazonaws.xray.entities.Subsegment;... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } Segment segment = AWSXRay.getCurrentSegment(); subsegment.putMetadata("resources", "game", game);
146
AWS X-Ray EntwicklerhandbuchAufzeichnung von Benutzer-IDs mit X-Ray SDK for Java
segment.putAnnotation("gameid", game.getId()); mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } }
Aufzeichnung von Benutzer-IDs mit X-Ray SDK forJavaZeichnen Sie Benutzer-IDs in Anforderungssegmenten auf, um den Benutzer zu identifizieren, der dieAnforderung gesendet hat.
So zeichnen Sie Benutzer-IDs auf
1. Eine Referenz des aktuellen Segments finden Sie unter AWSXRay.
import com.amazonaws.xray.AWSXRay;import com.amazonaws.xray.entities.Segment;...Segment document = AWSXRay.getCurrentSegment();
2. Rufen Sie setUser mit einer Zeichenfolgen-ID des Benutzers auf, der die Anforderung gesendet hat.
document.setUser("U12345");
Sie können setUser in Ihrem Controller aufrufen, um die Benutzer-ID aufzuzeichnen, sobald dieAnwendung mit der Bearbeitung einer Anfrage beginnt. Wenn Sie das Segment nur zur Einrichtung derBenutzer-ID verwenden, können Sie die Aufrufe in einer einzelnen Zeile anordnen.
Example src/main/java/scorekeep/MoveController.java – Benutzer-ID
import com.amazonaws.xray.AWSXRay;... @RequestMapping(value="/{userId}", method=RequestMethod.POST) public Move newMove(@PathVariable String sessionId, @PathVariable String gameId, @PathVariable String userId, @RequestBody String move) throws SessionNotFoundException, GameNotFoundException, StateNotFoundException, RulesException { AWSXRay.getCurrentSegment().setUser(userId); return moveFactory.newMove(sessionId, gameId, userId, move); }
Nutzen Sie das user-Schlüsselwort in einem Filterausdruck (p. 39), um Ablaufverfolgungen einerBenutzer-ID zu finden.
Übermitteln von Segmentkontext zwischen Threadsin einer Multithread-Anwendung
Beim Erstellen eines neuen Threads in Ihrer Anwendung behält AWSXRayRecorder eine Referenz zuraktuellen Segment- oder Untersegment-Entity nicht bei. Wenn Sie einen instrumentierten Client im neuen
147
AWS X-Ray EntwicklerhandbuchAOP mit Spring
Thread verwenden, versucht das SDK, auf ein Segment zu schreiben, das nicht existiert. Dies führt zu einerSegmentNotFoundException.
Um das Auslösen von Ausnahmen während der Entwicklung zu vermeiden, können Sie den Recorder miteiner ContextMissingStrategy konfigurieren, die festlegt, dass stattdessen ein Fehler protokolliert werdensoll. Sie können die Strategie im Code mit SetContextMissingStrategy konfigurieren oder ähnliche Optionenmit einer Umgebungsvariablen (p. 134) oder Systemeigenschaft (p. 135) konfigurieren.
Eine Möglichkeit zur Behebung des Fehlers ist die Verwendung eines neuen Segments, indem SiebeginSegment aufrufen, wenn Sie den Thread starten, und endSegment, wenn Sie ihn schließen. Diesfunktioniert, wenn Sie Code instrumentieren, der nicht als Reaktion auf eine HTTP-Anforderung ausgeführtwird, z. B. Code, der beim Starten Ihrer Anwendung ausgeführt wird.
Wenn Sie mehrere Threads zur Verarbeitung eingehender Anfragen verwenden, können Sie dasaktuelle Segment oder Untersegment an den neuen Thread übergeben und für die globale Aufzeichnungbereitstellen. Auf diese Weise wird sichergestellt, dass die im neuen Thread aufgezeichneten Informationenmit demselben Segment verknüpft werden wie die übrigen zu dieser Anfrage aufgezeichnetenInformationen.
Um Ablaufverfolgungskontext zwischen Threads zu übermitteln, rufen Sie GetTraceEntity in derglobalen Aufzeichnung auf, um eine Referenz zur aktuellen Entity (Segment oder Untersegment) zuerhalten. Übergeben Sie die Entity an den neuen Thread und rufen Sie dann SetTraceEntity auf, um zukonfigurieren, dass die globale Aufzeichnung dies zur Aufzeichnung von Ablaufverfolgungsdaten innerhalbdes Threads verwenden soll.
Ein Beispiel finden Sie unter Verwenden instrumentierter Clients in Auftragnehmer-Threads (p. 109).
AOP mit Spring und dem X-Ray SDK for JavaIn diesem Thema wird beschrieben, wie Sie das X-Ray SDK und das Spring Framework nutzen, um IhreAnwendung zu instrumentieren, ohne ihre Kern-Logik zu ändern. Das bedeutet, dass es jetzt eine nichtinvasive Methode gibt, um Ihre Anwendungen zu instrumentieren, die remote in AWS ausgeführt werden.
Um diese Funktion zu aktivieren, müssen Sie drei Aufgaben erledigen.
So aktivieren Sie AOP in Spring
1. Konfigurieren von Spring (p. 148)2. Kommentieren Ihres Codes oder implementieren einer Schnittstelle (p. 149)3. Aktivieren von X-Ray in Ihrer Anwendung (p. 149)
Konfigurieren von SpringSie können Maven oder Gradle verwenden, um Spring zu konfigurieren, um AOP für die InstrumentierungIhrer Anwendung verwenden zu können.
Wenn Sie Ihre Anwendung mit Maven erstellen, fügen Sie die folgende Abhängigkeit in Ihrer pom.xml-Datei hinzu.
<dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-xray-recorder-sdk-spring</artifactId> <version>1.3.1</version> </dependency>
148
AWS X-Ray EntwicklerhandbuchKommentieren Ihres Codes oderimplementieren einer Schnittstelle
Für Gradle fügen Sie die folgende Abhängigkeit in Ihre build.gradle-Datei ein.
compile 'com.amazonaws:aws-xray-recorder-sdk-spring:1.3.1'
Kommentieren Ihres Codes oder implementieren einerSchnittstelleIhre Klassen müssen entweder mit der @XRayEnabled-Kommentaren kommentiert werden oder dieXRayTraced-Schnittstelle implementieren. Damit wird das AOP-System angewiesen, die Funktionen derbetroffenen Klasse für die X-Ray-Instrumentierung zu kapseln.
Aktivieren von X-Ray in Ihrer AnwendungUm das X-Ray-Tracing in Ihrer Anwendung zu aktivieren, muss Ihr Code die abstrakte KlasseAbstractXRayInterceptor erweitern, indem er die folgenden Methoden überschreibt.
• generateMetadata – Diese Funktion ermöglicht die Anpassung der Metadaten, die dem Trace deraktuellen Funktion zugeordnet sind. Standardmäßig wird der Klassenname der ausgeführten Funktion inden Metadaten aufgezeichnet. Sie können weitere Daten hinzufügen, wenn Sie zusätzliche Informationenbenötigen.
• xrayEnabledClasses – Diese Funktion ist leer und sollte dies auch bleiben. Sie dient als Host fürein Pointcut, das den Interceptor anweist, welche Methoden gekapselt werden sollen. Definieren Siedas Pointcut, indem Sie angeben, welche der Klassen mit @XRayEnabled kommentiert sind, um einTracing durchzuführen. Die folgende pointcut-Anweisung weist den Interceptor an, alle Controller-Beanseinzukapseln, die mit dem Kommentar @XRayEnabled gekennzeichnet sind.
@Pointcut(“@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)”)
BeispielDer folgende Code erweitert die abstrakte Klasse AbstractXRayInterceptor.
@Aspect@Componentpublic class XRayInspector extends AbstractXRayInterceptor { @Override protected Map<String, Map<String, Object>> generateMetadata(ProceedingJoinPoint proceedingJoinPoint, Subsegment subsegment) throws Exception { return super.generateMetadata(proceedingJoinPoint, subsegment); } @Override @Pointcut("@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)") public void xrayEnabledClasses() {} }
Der folgenden Code ist eine Klasse, die von X-Ray instrumentiert wird.
@Service@XRayEnabledpublic class MyServiceImpl implements MyService { private final MyEntityRepository myEntityRepository;
149
AWS X-Ray EntwicklerhandbuchBeispiel
@Autowired public MyServiceImpl(MyEntityRepository myEntityRepository) { this.myEntityRepository = myEntityRepository; } @Transactional(readOnly = true) public List<MyEntity> getMyEntities(){ try(Stream<MyEntity> entityStream = this.myEntityRepository.streamAll()){ return entityStream.sorted().collect(Collectors.toList()); } }}
Wenn Sie Ihre Anwendung ordnungsgemäß konfiguriert haben, sollten Sie den vollständigen Aufruf-Stack der Anwendung sehen, vom Controller bis zu den Service-Aufrufe, wie im folgenden Screenshot derKonsole gezeigt.
150
AWS X-Ray Entwicklerhandbuch
AWS X-Ray-SDK für GoDas X-Ray SDK für Go besteht aus einer Reihe von Bibliotheken für Go-Anwendungen, die Klassen undMethoden zum Generieren und Senden von Ablaufverfolgungsdaten an den X-Ray-Daemon bereitstellen.Ablaufverfolgungsdaten enthalten Informationen zu eingehenden HTTP-Anforderungen, die von derAnwendung verarbeitet werden, sowie Aufrufen, die Anwendung an nachgelagerten Services mithilfe desAWS SDK, von HTTP-Clients oder einer SQL-Datenbankanbindung vornimmt. Sie können Segmente auchmanuell erstellen und Debug-Informationen Anmerkungen und Metadaten hinzufügen.
Laden Sie das SDK aus seinem GitHub-Repository mit go get herunter:
$ go get -u github.com/aws/aws-xray-sdk-go/...
Für Webanwendungen beginnen Sie damit, die Funktion xray.Handler zu verwenden (p. 156),um eingehende Anforderungen nachzuverfolgen. Der Message Handler erstellt für jede rückverfolgteAnforderung ein Segment (p. 20) und vervollständigt das Segment, nachdem die Antwort gesendet wurde.Während das Segment geöffnet ist, können Sie die SDK-Client-Methoden nutzen, um dem SegmentInformationen hinzuzufügen, Untersegmente zu erstellen und nachgelagerte Aufrufe rückzuverfolgen. DasSDK erfasst auch automatisch Ausnahmen, die Ihre Anwendung ausgibt, während das Segment geöffnetist.
Lambda liest für Lambda-Funktionen, die von instrumentalisierten Anwendungen oder Services aufgerufenwerden, den Nachverfolgungs-Header (p. 26) und verfolgt per Sampling erfasste Anforderungenautomatisch. Für andere Funktionen können Sie Lambda so konfigurieren (p. 229), dass für eingehendeAnforderungen Sampling und Nachverfolgung durchgeführt werden. In jedem Fall erstellt Lambda dasSegment und stellt es dem X-Ray SDK zur Verfügung.
Note
In Lambda ist das X-Ray SDK optional. Auch wenn Sie es nicht in Ihrer Funktion verwenden,enthält die Service-Map einen Knoten für den Lambda-Service sowie einen Knoten für jedeLambda-Funktion. Durch Hinzufügen des SDK können Sie Ihren Funktionscode instrumentieren,um dem von Lambda aufgezeichneten Funktionssegment Untersegmente hinzuzufügen. WeitereInformationen finden Sie unter AWS Lambda und AWS X-Ray (p. 229).
Als Nächstes umschließen Sie den Client mit einem Aufruf der AWS-Funktion (p. 158). Dieser Schrittstellt sicher, dass X-Ray Aufrufe jeder Client-Methode instrumentiert. Sie können auch Aufrufe von SQL-Datenbanken instrumentieren (p. 160).
Sobald Sie die ersten Schritte mit dem SDK gemacht haben, können Sie das Verhalten durch dieKonfiguration von Recorder und Middleware (p. 152) individualisieren. Sie können Plugins zumFesthalten von Daten über die Datenverarbeitungsressourcen, auf denen Ihre Anwendung ausgeführt wird,hinzufügen, das Samplingverhalten durch Samplingregeln anpassen und Protokollebenen einrichten, ummehr oder weniger Informationen von dem SDK in Ihren Anwendungsprotokollen zu sehen.
Zeichnen Sie zusätzliche Informationen zu Anforderungen und den Aufgaben, die Ihre Anwendungausführt, in Anmerkungen und Metadaten (p. 161) auf. Anmerkungen sind einfache Schlüsselwertpaare,die für die Verwendung mit Filterausdrücken (p. 39) indiziert werden, damit Sie nach Ablaufverfolgen mitbestimmten Daten suchen können. Metadateneinträge sind weniger einschränkend und können ganzeObjekte und Arrays aufzeichnen – alle Daten, die in eine JSON zusammengefasst werden können.
Anmerkungen und Metadaten
Anmerkungen und Metadaten sind beliebiger Text, den Sie mit dem X-Ray-SDK zu Segmentenhinzufügen. Anmerkung werden für die Verwendung mit Filterausdrücken indiziert. Metadata
151
AWS X-Ray EntwicklerhandbuchVoraussetzungen
werden nicht indiziert, können aber im unformatierten Segment mit der X-Ray-Konsole oder -API angezeigt werden. Alle Personen, denen Sie Lesezugriff auf X-Ray gewähren, können dieseDaten anzeigen.
Wenn Sie viele instrumentierten Clients in Ihrem Code haben, kann ein einzelnes Anforderungssegmenteviele Untersegmente enthalten, eines für jeden Aufruf mit einem instrumentierten Client. Sie könnenUntersegmente organisieren und gruppieren, indem Sie Client-Aufrufe in benutzerdefiniertenUntersegmenten (p. 160) zusammenfassen. Sie können ein benutzerdefiniertes Untersegment für eineganze Funktion oder eine Code-Abschnitt erstellen und Metadaten und Anmerkungen im Untersegmentfesthalten, anstatt alles im übergeordneten Segment aufzuzeichnen.
VoraussetzungenDas X-Ray SDK für Go erfordert Go 1.7 oder höher.
Das SDK hängt von den folgenden Bibliotheken zur Kompilierungs- und Laufzeit ab:
• AWS SDK für Go Version 1.10.0 oder höher
Diese Abhängigkeiten werden in der README.md-Datei des SDK angegeben.
ReferenzdokumentationNachdem Sie das SDK heruntergeladen haben, erstellen und hosten Sie die Dokumentation lokal, um sie ineinem Webbrowser anzuzeigen.
So zeigen Sie die Referenzdokumentation an
1. Navigieren Sie zum (Linux- oder Mac-)Verzeichnis $GOPATH/src/github.com/aws/aws-xray-sdk-go oder zum (Windows-)Ordner %GOPATH%\src\github.com\aws\aws-xray-sdk-go
2. Führen Sie den Befehl godoc aus.
$ godoc -http=:6060
3. Öffnen Sie einen Browser unter http://localhost:6060/pkg/github.com/aws/aws-xray-sdk-go/.
Konfigurieren des X-Ray SDK für GoSie können angeben, dass die Konfiguration für das X-Ray SDK für Go über Umgebungsvariablen, durchden Aufruf von Configure mit einem Config-Objekt oder durch die Verwendung von Standardwertenerfolgen soll. Umgebungsvariablen haben Vorrang vor Config-Werten, die wiederum Vorrang vorStandardwerten haben.
Abschnitte• Service-Plugins (p. 153)• Samplingregeln (p. 154)• Protokollierung (p. 155)• Umgebungsvariablen (p. 155)
152
AWS X-Ray EntwicklerhandbuchService-Plugins
• Verwenden von "Configure" (p. 156)
Service-PluginsUse plugins to record information about the service hosting your application.
Plugins
• Amazon EC2 – EC2Plugin fügt die Instance-ID und Availability Zone hinzu.• Elastic Beanstalk – ElasticBeanstalkPlugin fügt den Umgebungsnamen, die Versionsbezeichnung
und die Bereitstellungs-ID hinzu.• Amazon ECS – ECSPlugin fügt die Container-ID hinzu.
Um ein Plugin zu verwenden, importieren Sie eines der folgenden Pakete.
_ "github.com/aws/aws-xray-sdk-go/plugins/ec2"_ "github.com/aws/aws-xray-sdk-go/plugins/ecs"_ "github.com/aws/aws-xray-sdk-go/plugins/beanstalk"
Das SDK verwendet auch Plug-in-Einstellungen, um das origin-Feld im Segment auszufüllen.Dies gibt den Typ der AWS-Ressource an, die Ihre Anwendung ausführt. Der Ressourcentyp
153
AWS X-Ray EntwicklerhandbuchSamplingregeln
wird unter dem Namen der Anwendung in der Service-Übersicht angezeigt. Beispiel,AWS::ElasticBeanstalk::Environment.
Wenn Sie mehrere Plug-ins verwenden, benutzt das SDK das zuletzt geladene Plug-in.
SamplingregelnDas SDK hat eine Sampling-Strategie, durch die bestimmt wird, welche Anfragen verfolgt werden.Standardmäßig zeichnet das SDK die erste Anfragen pro Sekunde und fünf Prozent aller weiterenAnfragen. auf. Sie können das Sampling-Verhalten des SDK durch die Anwendung von Regeln anpassen,die in einer lokalen Datei definiert sind.
Example sampling-rules.json
{ "version": 1, "rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 }}
In diesem Beispiel sind eine benutzerdefinierte Regel und eine Standardregel definiert. Diebenutzerdefinierte Regel wendet eine Abtastrate von fünf Prozent ohne minimale Anforderungsanzahlauf die Verfolgung von Pfaden unter /api/move/ an. Die Standardregel verfolgt die erste Anfragen proSekunde und 10 % aller weiteren Anfragen.
Das SDK wendet benutzerdefinierte Regeln in der Reihenfolge an, in der sie definiert sind. Wenn eineAnfrage mehreren benutzerdefinierten Regeln entspricht, wendet das SDK nur die erste Regel an.
In Lambda können Sie die Samplingrate nicht ändern. Wenn Ihre Funktion von einem instrumentiertenService aufgerufen wird, werden von Aufrufen erzeugte Anforderungen, für die von diesem Service ein
154
AWS X-Ray EntwicklerhandbuchProtokollierung
Sampling durchgeführt wird, von Lambda aufgezeichnet. Bei aktiver Nachverfolgung ohne vorhandenenNachverfolgungs-Header trifft Lambda die Sampling-Entscheidung.
Nachdem Sie Ihre Regeln definiert haben, verwenden Sie xray.Configure, um sie zu Ihrer Go-Anwendung hinzuzufügen.
Example main.go – Konfigurieren der Samplingregeln
func init() { ss, err := sampling.NewLocalizedStrategyFromFilePath("conf/sampling.json")
if err != nil { panic(err) }
xray.Configure(xray.Config{ SamplingStrategy: ss, })}
ProtokollierungSie können die Protokollebene mit xray.Configure ändern und formatieren.
Example main.go
func main() { http.Handle("/", xray.Handler(xray.NewFixedSegmentNamer("MyApp"), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
xray.Configure(xray.Config{ LogLevel: "warn", LogFormat: "[%Level] [%Time] %Msg%n" })
w.Write([]byte("Hello!")) })))
http.ListenAndServe(":8000", nil)}
Weitere Informationen finden Sie unter Verwenden von "Configure" (p. 156).
UmgebungsvariablenSie können Umgebungsvariablen zum Konfigurieren des X-Ray SDK für Go verwenden. Das SDKunterstützt die folgenden Variablen.
• AWS_XRAY_TRACING_NAME – Legen Sie den Service-Namen fest, der vom SDK für Segmenteverwendet wird.
• AWS_XRAY_DAEMON_ADDRESS – Legen Sie den Host und den Port des X-Ray-Daemon-Listeners fest.Standardmäßig sendet das SDK Ablaufverfolgungsdaten an 127.0.0.1:2000. Verwenden Sie dieseVariable, wenn Sie den Daemon so konfiguriert haben, dass er einen anderen Port überwacht (p. 115),oder wenn er auf einem anderen Host ausgeführt wird.
Umgebungsvariablen überschreiben äquivalente Werte im Code.
155
AWS X-Ray EntwicklerhandbuchVerwenden von "Configure"
Verwenden von "Configure"Sie können das X-Ray SDK für Go auch mithilfe der Configure-Methode konfigurieren. Configurebenötigt ein Argument, ein Config-Objekt, mit folgenden optionalen Feldern.
DaemonAddr
Diese Zeichenfolge legt den Host und den Port des X-Ray-Daemon-Listeners fest. Wenn dies nichtfestgelegt ist, verwendet X-Ray den Wert der Umgebungsvariablen AWS_XRAY_DAEMON_ADDRESS.Wenn dieser Wert nicht festgelegt ist, wird "127.0.0.1:2000" verwendet.
ServiceVersion
Diese Zeichenfolge legt die Service-Version fest. Wenn dies nicht festgelegt ist, verwendet X-Ray dieleere Zeichenfolge ("").
SamplingStrategy
Das SamplingStrategy-Objekt legt fest, welche Ihrer Anwendungsaufrufe verfolgt werden. Wenndies nicht festgelegt ist, verwendet X-Ray ein LocalizedSamplingStrategy-Objekt, wobei die inxray/resources/DefaultSamplingRules.json definierte Strategie angewendet wird.
StreamingStrategy
Dieses StreamingStrategy-Objekt legt fest, ob ein Segment gestreamt werden soll, wennRequiresStreaming den Wert true zurückgibt. Wenn dies nicht festgelegt ist, verwendet X-Ray einDefaultStreamingStrategy-Objekt, das ein gesampeltes Segment streamt, wenn die Anzahl derUntersegmente größer als 20 ist.
ExceptionFormattingStrategy
Dieses ExceptionFormattingStrategy-Objekt legt fest, auf welche Weise verschiedeneAusnahmen gehandhabt werden sollen. Wenn dies nicht festgelegt ist, verwendet X-Ray einDefaultExceptionFormattingStrategy-Objekt mit einem XrayError vom Typ error, dieFehlermeldung und ein Stacktrace.
LogLevel
Diese Zeichenfolge legt die standardmäßige Protokollebene für Ihre Anwendung fest. Sie können diesauf "trace", "debug", "info", "warn" oder "error" festlegen. Wenn dies nicht festgelegt ist, verwendet X-Ray "info".
LogFormat
Diese Zeichenfolge legt das Format der Protokollnachrichten fest. Wenn dies nicht festgelegt ist,verwendet X-Ray "%Date(2006-01-02T15:04:05Z07:00) [%Level] %Msg%n".
Instrumentieren von eingehenden HTTP-Anforderungen mit dem X-Ray SDK für Go
Sie können mit dem X-Ray SDK eingehende HTTP-Anforderungen verfolgen, die Ihre Anwendung auf einerEC2 Instance in Amazon EC2, AWS Elastic Beanstalk oder Amazon ECS verarbeitet.
Verwenden Sie xray.Handler, um eingehende HTTP-Anforderungen zu instrumentieren. Das X-RaySDK für Go implementiert die standardmäßige http.Handler-Schnittstelle der Go-Bibliothek in derxay.Handler-Klasse, um Webanforderungen abzufangen. Die xay.Handler-Klasse umschließt denbereitgestellten http.Handler mit xray.Capture, wobei der Anfragekontext genutzt, eingehendeHeader analysiert und bei Bedarf Antwort-Header hinzugefügt werden, und legt HTTP-spezifischeAblaufverfolgungsfelder fest.
156
AWS X-Ray EntwicklerhandbuchKonfiguration einer Segmentbenennungsstrategie
Wenn Sie diese Klasse zur Verarbeitung von HTTP-Anforderungen und -Antworten verwenden, erzeugtdas X-Ray SDK für Go ein Segment für jede gesampelte Anfrage. Dieses Segment umfasst Dauer,Methode und Status der HTTP-Anforderung. Die zusätzliche Instrumentierung schafft Untersegmente zudiesem Segment.
Note
Lambda erstellt für AWS Lambda-Funktionen ein Segment für jede Anforderung, die per Samplingerfasst wurde. Weitere Informationen finden Sie unter AWS Lambda und AWS X-Ray (p. 229).
Das folgende Beispiel fängt Anfragen auf Port 8000 ab und gibt "Hello!" als Antwort zurück. Es erzeugt dasSegment myApp und instrumentiert Aufrufe über jede beliebige Anwendung.
Example main.go
func main() { http.Handle("/", xray.Handler(xray.NewFixedSegmentNamer("MyApp"), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.Write([]byte("Hello!")) })))
http.ListenAndServe(":8000", nil)}
Each segment has a name that identifies your application in the service map. The segment can be namedstatically, or you can configure the SDK to name it dynamically based on the host header in the incomingrequest. Dynamic naming lets you group traces based on the domain name in the request, and apply adefault name if the name doesn't match an expected pattern (for example, if the host header is forged).
Weitergeleitete Anfragen
Wenn ein Load Balancer oder ein anderer Mittler eine Anforderung an Ihre Anwendungweiterleitet, übernimmt X-Ray die Client-IP aus der X-Forwarded-For-Kopfzeile der Anforderungund nicht aus der Quell-IP im IP-Paket. Die für eine weitergeleitete Anforderung aufgezeichneteClient-IP kann gefälscht sein und ist daher nicht vertrauenswürdig.
When a request is forwarded, the SDK sets an additional field in the segment to indicate this. If the segmentcontains the field x_forwarded_for set to true, the client IP was taken from the X-Forwarded-Forheader in the HTTP request.
Der Handler erzeugt für jede eingehende Anfrage ein Segment mit einem http-Block mit folgendenInformationen:
• HTTP-Methode – GET, POST, PUT, DELETE usw.• Client-Adresse – Die IP-Adresse des Clients, der die Anforderung gesendet hat.• Antwortcode – Der HTTP-Antwortcode für die abgeschlossene Anforderung.• Dauer – Die Startzeit (zu der die Anforderung empfangen wurde) und die Endzeit (zu der die Antwort
gesendet wurde).• Nutzer-Agent — Der user-agent aus der Anfrage.• Inhaltslänge — Die content-length aus der Antwort.
Konfiguration einer SegmentbenennungsstrategieAWS X-Ray verwendet einen Servicenamen, um Ihre Anwendung zu identifizieren und sie von anderenAnwendungen, Datenbanken, externen APIs und AWS-Ressourcen zu unterscheiden, die Ihre Anwendung
157
AWS X-Ray EntwicklerhandbuchAWS SDK-Clients
nutzt. Wenn das X-Ray SDK Segmente für eingehende Anfragen generiert, zeichnet es den ServicenamenIhrer Anwendung im Feld name field (p. 73) auf.
Das X-Ray SDK kann Segmente nachdem Hostnamen im HTTP-Anfrageheader benennen. Dieser Headerkann jedoch gefälscht sein, was zu unerwarteten Knoten in Ihrer Service-Übersicht führen könnte. Und zuverhindern, dass das SDK Segmente aufgrund von Anforderungen mit gefälschten Host-Headern falschbenennt, müssen Sie einen standardmäßigen Namen für eingehende Anfragen angeben.
Wenn Ihre Anwendung Anfragen für mehrere Domänen bedient, können Sie das SDK so konfigurieren,dass es eine dynamische Benennungsstrategie verwendet, um dies in den Segmentnamen zuberücksichtigen. Eine dynamische Benennungsstrategie erlaubt es dem SDK, den Host-Namen beiAnfragen zu verwenden, die einem erwarteten Muster entsprechen, und den standardmäßigen Namen fürsolche zu vergeben, die es nicht tun.
Beispielsweise haben Sie vielleicht eine einzelne Anwendung, die Anfragen für drei Subdomänen bedient,– www.example.com, api.example.com und static.example.com. Sie können eine dynamischeBenennungsstrategie mit dem Muster *.example.com verwenden, um Segmente für die einzelnenSubdomänen unterschiedlich zu benennen. Auf der Service-Übersicht werden dann drei Service-Knotenangezeigt. Wenn Ihre Anwendung Anfragen mit einem Hostnamen erhält, der diesem Muster nichtentspricht, sehen Sie auf der Service-Übersicht einen vierten Knoten mit einem von Ihnen festgelegtenAusweichnamen.
Wenn Sie denselben Namen für alle Anfragesegmente verwenden möchten, geben Sie bei der Erstellungdes Handlers den Namen Ihrer Anwendung ein, wie im vorherigen Abschnitt gezeigt.
Note
Sie können den mit der AWS_XRAY_TRACING_NAME-Umgebungsvariablen (p. 155) in Codedefinierten standardmäßigen Dienstnamen überschreiben.
Eine dynamische Benennungsstrategie definiert ein Muster, dem Hostnamen entsprechen sollten,sowie einen Standardnamen, der verwendet wird, wenn der Hostname in der HTTP-Anforderungnicht mit diesem Muster übereinstimmt. Um Segmente dynamisch zu benennen, verwenden SieNewDynamicSegmentNamer zur Konfiguration des Standardnamens und Musters zum Abgleich.
Example main.go
Wenn der Hostname in der Anforderung dem Muster *.example.com entspricht, verwenden Sie denHostnamen. Verwenden Sie andernfalls MyApp.
func main() { http.Handle("/", xray.Handler(xray.NewDynamicSegmentNamer("MyApp", "*.example.com"), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.Write([]byte("Hello!")) })))
http.ListenAndServe(":8000", nil)}
Ablaufverfolgung von AWS SDK-Aufrufen mit demX-Ray SDK für Go
Wenn Ihre Anwendung die AWS-Services aufruft, um Daten zu speichern, Daten in eine Warteschlange zuschreiben oder Benachrichtigungen zu senden, verfolgt das X-Ray SDK für Go die Aufrufe nachgelagertin Untersegmenten (p. 160). Verfolgte AWS-Services und -Ressourcen, auf die Sie innerhalb dieserServices zugreifen (z. B. ein Amazon S3-Bucket oder eine Amazon SQS-Warteschlange) erscheinen alsnachgelagerte Knoten in der Service-Übersicht der X-Ray-Konsole.
158
AWS X-Ray EntwicklerhandbuchAWS SDK-Clients
Um AWS SDK-Clients zu verfolgen, umschließen Sie das Client-Objekt mit dem xray.AWS()-Aufruf, wieim folgenden Beispiel dargestellt.
Example main.go
var dynamo *dynamodb.DynamoDBfunc main() { dynamo = dynamodb.New(session.Must(session.NewSession())) xray.AWS(dynamo.Client)}
Wenn Sie dann den AWS SDK-Client nutzen, verwenden Sie die Version withContext derAufrufmethode und übergeben Sie den context aus dem http.Request-Objekt, das an denHandler (p. 156) übergeben wurde.
Example main.go – AWS SDK-Aufruf
func listTablesWithContext(ctx context.Context) { output := dynamo.ListTablesWithContext(ctx, &dynamodb.ListTablesInput{}) doSomething(output)}
Bei allen Services wird der Name der aufgerufenen API in der X-Ray-Konsole angezeigt. Bei einerUntergruppe von Services fügt das X-Ray SDK Informationen zum Segment hinzu, um mehr Granularität inder Service-Übersicht zu erreichen.
Wenn Sie beispielsweise einen Aufruf mit einem instrumentierten DynamoDB-Client erstellen, fügt dasSDK für Aufrufe, die auf eine Tabelle abzielen, den Tabellennamen zu dem Segment hinzu. In der Konsolewerden die Tabellen als einzelne Knoten in der Service-Übersicht angezeigt, zusammen mit einemgenerischen DynamoDB-Knoten für Aufrufe, die nicht auf eine Tabelle abzielen.
Example Untersegment für einen Aufruf von DynamoDB zum Speichern eines Elements
{ "id": "24756640c0d0978a", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "DynamoDB", "namespace": "aws", "http": { "response": { "content_length": 60, "status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG", }}
Wenn Sie auf benannte Ressourcen zugreifen, werden durch Aufrufe der folgenden Services weitereKnoten in der Service-Übersicht erstellt. Durch Aufrufe, die keinen bestimmten Ressourcen gelten, wird eingenerischer Knoten für den Service erstellt.
• Amazon DynamoDB – Tabellenname• Amazon Simple Storage Service – Bucket und Schlüsselname• Amazon Simple Queue Service – Warteschlangenname
159
AWS X-Ray EntwicklerhandbuchAusgehende HTTP-Aufrufe
Ablaufverfolgung von Aufrufen nachgelagerterHTTP-Web-Services mit dem X-Ray SDK für Go
Wenn Ihre Anwendung Microservices oder öffentliche HTTP-APIs aufruft, können Sie den xray.Clientzum Instrumentieren dieser Aufrufe als Untersegmente Ihrer Go-Anwendung verwenden, wie im folgendenBeispiel dargestellt, bei dem http-client ein HTTP-Client ist.
Der Client erstellt eine flache Kopie des bereitgestellten HTTP-Clients, standardmäßighttp.DefaultClient, wobei der Roundtripper mit xray.RoundTripper umschlossen ist.
Example main.go – HTTP-Client
myClient := xray.Client(http-client)
Ablaufverfolgung von SQL-Abfragen mit dem X-RaySDK für Go
So können Sie SQL-Aufrufe von PostgreSQL oder MySQL rückverfolgen, die sql.Open-Aufrufevon xray.SQL ersetzen, wie im folgenden Beispiel dargestellt. Verwenden Sie URLs anstelle vonKonfigurationszeichenfolgen, wenn möglich.
Example main.go
func main() { db := xray.SQL("postgres", "postgres://user:password@host:port/db") row, _ := db.QueryRow("SELECT 1") // Use as normal}
Erstellen von benutzerdefinierten Untersegmentenmit dem X-Ray SDK für Go
Untersegmente erweitern das Segment (p. 20) eines Traces um Details zu erledigten Aufgaben, umAnforderungen zu senden. Jedesmal, wenn Sie einen Aufruf mit einem instrumentierten Client erstellen,erfasst das X-Ray SDK die in einem Untersegment erzeugten Informationen. Sie können zusätzlicheUntersegmente erstellten, um andere Untersegmente zu gruppieren, die Leistung eines Codeabschnitts zumessen oder Anmerkungen und Metadaten aufzuzeichnen.
Mit der Capture-Methode legen Sie ein Untersegment um eine Funktion herum an.
Example main.go – Benutzerdefiniertes Untersegment
func criticalSection(ctx context.Context) { //this is an example of a subsegment xray.Capture(ctx, "GameModel.saveGame", func(ctx1 context.Context) error { var err error
section.Lock() result := someLockedResource.Go() section.Unlock()
160
AWS X-Ray EntwicklerhandbuchAnmerkungen und Metadaten
xray.AddMetadata(ctx1, "ResourceResult", result) })
Der folgende Screenshot zeigt ein Beispiel dafür, wie das saveGame-Untersegment in Ablaufverfolgungenfür die Anwendung Scorekeep aussehen kann.
Hinzufügen von Anmerkungen und Metadaten zuSegmenten mit X-Ray SDK für Go
Mithilfe von Anmerkungen und Metadaten können Sie zusätzliche Informationen zu Anforderungen, derUmgebung oder Ihrer Anwendung aufzeichnen. Sie können den vom X-Ray SDK erstellten Segmentenoder den von Ihnen erstellten benutzerdefinierten Untersegmenten Anmerkungen und Metadatenhinzufügen.
Annotations are key-value pairs with string, number, or Boolean values. Annotations are indexed for usewith filter expressions (p. 39). Use annotations to record data that you want to use to group traces in theconsole, or when calling the GetTraceSummaries API.
Metadata are key-value pairs that can have values of any type, including objects and lists, but are notindexed for use with filter expressions. Use metadata to record additional data that you want stored in thetrace but don't need to use with search.
Zusätzlich zu Anmerkungen und Metadaten können Sie auch Benutzer-ID-Zeichenfolgen (p. 162) inSegmenten aufzeichnen. Benutzer-IDs werden in einem eigenen Feld aufgezeichnet und zur Sucheindiziert.
Abschnitte• Aufzeichnen von Anmerkungen mit dem X-Ray SDK für Go (p. 161)• Aufzeichnen von Metadaten mit dem X-Ray SDK für Go (p. 162)• Aufzeichnen von Benutzer-IDs mit dem X-Ray SDK für Go (p. 162)
Aufzeichnen von Anmerkungen mit dem X-Ray SDKfür GoVerwenden Sie Anmerkungen, um Informationen zu Segmenten, die zur Suche indiziert werden sollten,aufzuzeichnen.
161
AWS X-Ray EntwicklerhandbuchAufzeichnen von Metadaten mit dem X-Ray SDK für Go
Anmerkung zu Anforderungen
• Schlüssel – Bis zu 500 alphanumerische Zeichen. Keine Leerzeichen oder Symbole außer Unterstrichen.• Werte – bis zu 1,000 Unicode-Zeichen.• Einträge – Bis zu 50 Anmerkungen pro Ablaufverfolgung.
Um Anmerkungen aufzuzeichnen, rufen Sie AddAnnotation mit einer Zeichenfolge auf, die dieMetadaten enthält, die Sie dem Segment zuordnen möchten.
xray.AddAnnotation(context, "value", error)
Das SDK zeichnet Anmerkungen als Schlüssel-Wert-Paare in einem annotations-Objekt imSegmentdokument auf. Wenn AddAnnotation zweimal mit demselben Schlüssel aufgerufen wird, werdenzuvor aufgezeichnete Werte im selben Segment überschrieben.
Nutzen Sie das annotations.key-Schlüsselwort in einem Filterausdruck (p. 39), um Ablaufverfolgungendurch Anmerkungen mit bestimmten Werten zu finden.
Aufzeichnen von Metadaten mit dem X-Ray SDK fürGoVerwenden Sie Metadaten, um Segmentinformationen aufzuzeichnen, die nicht zur Suche indiziert werdenmüssen.
Um Metadaten aufzuzeichnen, rufen Sie AddMetadata mit einer Zeichenfolge auf, die die Metadatenenthält, die Sie dem Segment zuordnen möchten.
xray.AddMetadata(context, "value", error)
Aufzeichnen von Benutzer-IDs mit dem X-Ray SDK fürGoZeichnen Sie Benutzer-IDs in Anforderungssegmenten auf, um den Benutzer zu identifizieren, der dieAnforderung gesendet hat.
So zeichnen Sie Benutzer-IDs auf
1. Eine Referenz des aktuellen Segments finden Sie unter AWSXRay.
import ( "context" "github.com/aws/aws-xray-sdk-go/xray")
mySegment := xray.GetSegment(context)
2. Rufen Sie setUser mit einer Zeichenfolgen-ID des Benutzers auf, der die Anforderung gesendet hat.
mySegment.User = "U12345"
Nutzen Sie das user-Schlüsselwort in einem Filterausdruck (p. 39), um Ablaufverfolgungen einerBenutzer-ID zu finden.
162
AWS X-Ray Entwicklerhandbuch
Das X-Ray SDK for Node.jsDas X-Ray SDK for Node.js ist eine Bibliothek für Express-Webanwendungen und Node.js Lambda-Funktionen, die Klassen und Methoden zum Generieren und Senden von Ablaufverfolgungsdaten zumX-Ray-Daemon bereitstellen. Ablaufverfolgungsdaten umfassen Informationen zu eingehenden HTTP-Anforderungen, die von der Anwendung beantwortet werden, sowie Aufrufe, die die Anwendung annachgelagerte Services mit dem AWS SDK oder HTTP-Clients sendet.
Note
Das X-Ray SDK for Node.js ist ein Open-Source-Projekt. Sie können das Projekt auf GitHubverfolgen und Probleme und Pull-Anforderungen übermitteln: github.com/aws/aws-xray-sdk-node
Wenn Sie Express nutzen, beginnen Sie, indem Sie das SDK als Middleware (p. 168) auf IhremAnwendungsserver hinzufügen, um eingehende Anforderungen zu verfolgen. Der Middleware erstellt fürjede verfolgte Anforderung ein Segment (p. 20) und vervollständigt das Segment, nachdem die Antwortgesendet wurde. Während das Segment geöffnet ist, können Sie die SDK-Client-Methoden nutzen,um dem Segment Informationen hinzuzufügen, Untersegmente zu erstellen und nachgelagerte Aufruferückzuverfolgen. Das SDK erfasst auch automatisch Ausnahmen, die Ihre Anwendung ausgibt, währenddas Segment geöffnet ist.
Lambda liest für Lambda-Funktionen, die von instrumentalisierten Anwendungen oder Services aufgerufenwerden, den Nachverfolgungs-Header (p. 26) und verfolgt per Sampling erfasste Anforderungenautomatisch. Für andere Funktionen können Sie Lambda so konfigurieren (p. 229), dass für eingehendeAnforderungen Sampling und Nachverfolgung durchgeführt werden. In jedem Fall erstellt Lambda dasSegment und stellt es dem X-Ray SDK zur Verfügung.
Note
In Lambda ist das X-Ray SDK optional. Auch wenn Sie es nicht in Ihrer Funktion verwenden,enthält die Service-Map einen Knoten für den Lambda-Service sowie einen Knoten für jedeLambda-Funktion. Durch Hinzufügen des SDK können Sie Ihren Funktionscode instrumentieren,um dem von Lambda aufgezeichneten Funktionssegment Untersegmente hinzuzufügen. WeitereInformationen finden Sie unter AWS Lambda und AWS X-Ray (p. 229).
Verwenden Sie anschließend X-Ray SDK for Node.js, um Ihre AWS SDK for JavaScript in Node.js-Clients (p. 171) zu instrumentieren. Sobald Sie eine Anfrage stellen, um einen AWS-Service oder eineRessource mit einem instrumentierten Client rückzuverfolgen, zeichnet SDK in einem UntersegmentInformationen zu dieser Anfrage auf. AWS-Services und die Ressourcen, auf die Sie innerhalb der Serviceszugreifen, erscheinen in der Service-Übersicht als nachgelagerte Knoten, um Ihnen bei der Identifikationvon Fehlern und der Ablehnung von Problemen mit individuellen Verbindungen zu helfen.
Das X-Ray SDK for Node.js bietet auch eine Instrumentierung für nachgelagerte Aufrufe zu HTTP-Web-APIs und SQL-Anfragen an. Umhüllen Sie den HTTP-Client in der SDK-Erfassungsmethode (p. 172), umInformationen zu ausgehenden HTTP-Anforderungen aufzuzeichnen. Für SQL-Clients verwenden Sie dieCapture-Methode für Ihre Datenbank (p. 173).
Die Middleware wendet Samplingregeln auf eingehende Anforderungen an, um zu ermitteln, welcheAnforderungen rückverfolgt werden. Sie können X-Ray SDK for Node.js (p. 165) konfigurieren, um dasdas Samplingverhalten anzupassen oder Informationen zu den AWS-Rechenressourcen, auf denen IhreAnwendung ausgeführt wird, aufzuzeichnen.
Zeichnen Sie zusätzliche Informationen zu Anforderungen und den Aufgaben, die Ihre Anwendungausführt, in Anmerkungen und Metadaten (p. 175) auf. Anmerkungen sind einfache Schlüsselwertpaare,die für die Verwendung mit Filterausdrücken (p. 39) indiziert werden, damit Sie nach Ablaufverfolgen mitbestimmten Daten suchen können. Metadateneinträge sind weniger einschränkend und können ganzeObjekte und Arrays aufzeichnen – alle Daten, die in eine JSON zusammengefasst werden können.
163
AWS X-Ray EntwicklerhandbuchVoraussetzungen
Anmerkungen und Metadaten
Anmerkungen und Metadaten sind beliebiger Text, den Sie mit dem X-Ray-SDK zu Segmentenhinzufügen. Anmerkung werden für die Verwendung mit Filterausdrücken indiziert. Metadatawerden nicht indiziert, können aber im unformatierten Segment mit der X-Ray-Konsole oder -API angezeigt werden. Alle Personen, denen Sie Lesezugriff auf X-Ray gewähren, können dieseDaten anzeigen.
Wenn Sie viele instrumentierten Clients in Ihrem Code haben, kann ein einzelnes Anforderungssegmenteviele Untersegmente enthalten, eines für jeden Aufruf mit einem instrumentierten Client. Sie könnenUntersegmente organisieren und gruppieren, indem Sie Client-Aufrufe in benutzerdefiniertenUntersegmenten (p. 174) zusammenfassen. Sie können ein benutzerdefiniertes Untersegment für eineganze Funktion oder eine Code-Abschnitt erstellen und Metadaten und Anmerkungen im Untersegmentfesthalten, anstatt alles im übergeordneten Segment aufzuzeichnen.
Referenzdokumentation zu den SDK-Klassen und -Methoden finden Sie unter AWS X-Ray SDK for Node.jsAPI Reference.
VoraussetzungenDas X-Ray SDK for Node.js erfordert Node.js und folgende Bibliotheken:
• cls – 0.1.5• continuation-local-storage – 3.2.0• pkginfo – 0.4.0• underscore – 1.8.3
Das SDK zieht diese Bibliotheken bei der Installation in NPM ein.
Um AWS SDK-Clients rückzuverfolgen, benötigt X-Ray SDK for Node.js die Mindestversion von AWS SDKfor JavaScript in Node.js.
• aws-sdk – 2.7.15
AbhängigkeitsmanagementDas X-Ray SDK for Node.js ist über NPM verfügbar.
• Paket – aws-xray-sdk
Installieren Sie das SDK für eine lokale Bereitstellung in Ihrem Projektverzeichnis mit npm.
~/nodejs-xray$ npm install [email protected] ~/nodejs-xray### [email protected] ### [email protected] # ### [email protected] # # ### [email protected] # ### [email protected] ### [email protected] ### [email protected] ### [email protected] ### [email protected]
164
AWS X-Ray EntwicklerhandbuchKonfiguration
### [email protected] ### [email protected] ### [email protected] ### [email protected] ### [email protected] ### [email protected] ### [email protected]
Verwenden Sie die --save-Option zum Speichern von SDK in Abhängigkeit von package.json in IhrerAnwendung.
~/nodejs-xray$ npm install aws-xray-sdk [email protected] ~/nodejs-xray### [email protected]
Konfigurieren des X-Ray SDK for Node.jsSie können das X-Ray SDK for Node.js mit Plugins konfigurieren, um Informationen über den Service, überden Ihre Anwendung ausgeführt wird, zu berücksichtigen, das Standard-Samplingverhalten zu ändern oderSamplingregeln, die für Anforderungen an bestimmte Pfade gelten, hinzuzufügen.
Abschnitte• Service-Plugins (p. 165)• Samplingregeln (p. 166)• Protokollierung (p. 167)• X-Ray-Daemon-Adresse (p. 167)• Umgebungsvariablen (p. 168)
Service-PluginsUse plugins to record information about the service hosting your application.
Plugins
• Amazon EC2 – EC2Plugin fügt die Instance-ID und Availability Zone hinzu.• Elastic Beanstalk – ElasticBeanstalkPlugin fügt den Umgebungsnamen, die Versionsbezeichnung
und die Bereitstellungs-ID hinzu.• Amazon ECS – ECSPlugin fügt die Container-ID hinzu.
Um ein Plugin zu verwenden, konfigurieren Sie den X-Ray SDK for Node.js-Client mit der config-Methode.
Example app.js - Plugins
var AWSXRay = require('aws-xray-sdk');AWSXRay.config([AWSXRay.plugins.EC2Plugin,AWSXRay.plugins.ElasticBeanstalkPlugin]);
Das SDK verwendet auch Plug-in-Einstellungen, um das origin-Feld im Segment auszufüllen.Dies gibt den Typ der AWS-Ressource an, die Ihre Anwendung ausführt. Der Ressourcentypwird unter dem Namen der Anwendung in der Service-Übersicht angezeigt. Beispiel,AWS::ElasticBeanstalk::Environment.
165
AWS X-Ray EntwicklerhandbuchSamplingregeln
Wenn Sie mehrere Plug-ins verwenden, benutzt das SDK das zuletzt geladene Plug-in.
SamplingregelnDas SDK hat eine Sampling-Strategie, durch die bestimmt wird, welche Anfragen verfolgt werden.Standardmäßig zeichnet das SDK die erste Anfragen pro Sekunde und fünf Prozent aller weiterenAnfragen. auf. Sie können das Sampling-Verhalten des SDK durch die Anwendung von Regeln anpassen,die in einer lokalen Datei definiert sind.
Example sampling-rules.json
{ "version": 1, "rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 }}
In diesem Beispiel sind eine benutzerdefinierte Regel und eine Standardregel definiert. Diebenutzerdefinierte Regel wendet eine Abtastrate von fünf Prozent ohne minimale Anforderungsanzahlauf die Verfolgung von Pfaden unter /api/move/ an. Die Standardregel verfolgt die erste Anfragen proSekunde und 10 % aller weiteren Anfragen.
Das SDK wendet benutzerdefinierte Regeln in der Reihenfolge an, in der sie definiert sind. Wenn eineAnfrage mehreren benutzerdefinierten Regeln entspricht, wendet das SDK nur die erste Regel an.
In Lambda können Sie die Samplingrate nicht ändern. Wenn Ihre Funktion von einem instrumentiertenService aufgerufen wird, werden von Aufrufen erzeugte Anforderungen, für die von diesem Service einSampling durchgeführt wird, von Lambda aufgezeichnet. Bei aktiver Nachverfolgung ohne vorhandenenNachverfolgungs-Header trifft Lambda die Sampling-Entscheidung.
166
AWS X-Ray EntwicklerhandbuchProtokollierung
Weisen Sie das X-Ray SDK for Node.js an, Samplingregeln aus einer Datei mit setSamplingRules zuladen.
Example app.js – Sampling-Regeln aus einer Datei
var AWSXRay = require('aws-xray-sdk');AWSXRay.middleware.setSamplingRules('sampling-rules.json');
Sie können Ihre Regeln auch in Code definieren und als Objekt an setSamplingRules übergeben.
Example app.js – Sampling-Regeln aus einem Objekt
var AWSXRay = require('aws-xray-sdk');var rules = { "rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 }, "version": 1 }
AWSXRay.middleware.setSamplingRules(rules);
ProtokollierungZum Protokollieren der SDK-Ausgabe rufen Sie AWSXRay.setLogger(logger) auf, wobei logger einObjekt ist, dass Standard-Protokollierungsmethoden (warn, infousw.) bereitstellt.
Example app.js - Protokollierung mit Winston
var AWSXRay = require('aws-xray-sdk');var logger = require('winston');AWSXRay.setLogger(logger);AWSXRay.config([AWSXRay.plugins.EC2Plugin]);
Rufen Sie vor der Ausführung anderer Konfigurationsmethoden setLogger auf, um sicherzustellen, dassSie die Ausgabe dieser Vorgänge erfassen.
Konfigurieren Sie das SDK zur Ausgabe von Protokollen auf der Konsole ohne Verwendung derProtokollierungsbibliothek, verwenden Sie die AWS_XRAY_DEBUG_MODE Umgebungsvariable (p. 168).
X-Ray-Daemon-AdresseWenn der X-Ray-Daemon einen anderen Port oder Host als 127.0.0.1:2000 überwacht, können Sie dasX-Ray SDK for Node.js so konfigurieren, dass es Ablaufverfolgungsdaten an eine andere UDP-Adressesendet.
AWSXRay.setDaemonAddress('host:port');
Sie können den Host mit Namen oder IPv4-Adresse angeben.
Example app.js – Daemon-Adresse
var AWSXRay = require('aws-xray-sdk');AWSXRay.setDaemonAddress('daemonhost:8082');
167
AWS X-Ray EntwicklerhandbuchUmgebungsvariablen
Sie können die Daemon-Adresse auch festlegen, indem Sie die AWS_XRAY_DAEMON_ADDRESSUmgebungsvariable (p. 168) verwenden.
UmgebungsvariablenSie können Umgebungsvariablen zum Konfigurieren von X-Ray SDK for Node.js verwenden. Das SDKunterstützt die folgenden Variablen.
• AWS_XRAY_TRACING_NAME – Legen Sie einen Dienstnamen fest, der vom SDK für Segmente verwendetwird. Überschreibt den für die Express-Middleware festgelegten (p. 168) Segmentnamen.
• AWS_XRAY_DAEMON_ADDRESS – Legen Sie den Host und den Port des X-Ray-Daemon-Listeners fest.Standardmäßig sendet das SDK Ablaufverfolgungsdaten an 127.0.0.1:2000. Verwenden Sie dieseVariable, wenn Sie den Daemon so konfiguriert haben, dass er einen anderen Port überwacht (p. 115),oder wenn er auf einem anderen Host ausgeführt wird.
• AWS_XRAY_CONTEXT_MISSING – Set to LOG_ERROR to avoid throwing exceptions when yourinstrumented code attempts to record data when no segment is open.
Valid Values
• RUNTIME_ERROR – Throw a runtime exception (default).• LOG_ERROR – Log an error and continue.
Errors related to missing segments or subsegments can occur when you attempt to use an instrumentedclient in startup code that runs when no request is open, or in code that spawns a new thread.
• AWS_XRAY_DEBUG_MODE – Wird auf TRUE festgelegt, um das SDK auf Ausgabe von Protokollen auf derKonsole zu konfigurieren, anstatt einen Logger zu konfigurieren (p. 167).
Ablaufverfolgung eingehender Anforderungen mitdem X-Ray SDK for Node.js
Sie können mit dem X-Ray SDK for Node.js eingehende HTTP-Anfragen rückverfolgen, die Ihre Express-und Restify-Anwendungen auf einer EC2 Instance in Amazon EC2, AWS Elastic Beanstalk oder AmazonECS bereitstellen.
Das X-Ray SDK for Node.js bietet Middleware für Anwendungen, die die Express- und Restify-Frameworksverwenden. Wenn Sie die X-Ray Middleware zu Ihrer Anwendung hinzufügen, erstellt das X-Ray SDKfor Node.js ein Segment für jede stichprobenartig geprüfte Anforderung. Dieses Segment umfasst Dauer,Methode und Status der HTTP-Anforderung. Die zusätzliche Instrumentierung schafft Untersegmente zudiesem Segment.
Note
Lambda erstellt für AWS Lambda-Funktionen ein Segment für jede Anforderung, die per Samplingerfasst wurde. Weitere Informationen finden Sie unter AWS Lambda und AWS X-Ray (p. 229).
Each segment has a name that identifies your application in the service map. The segment can be namedstatically, or you can configure the SDK to name it dynamically based on the host header in the incomingrequest. Dynamic naming lets you group traces based on the domain name in the request, and apply adefault name if the name doesn't match an expected pattern (for example, if the host header is forged).
Weitergeleitete Anfragen
Wenn ein Load Balancer oder ein anderer Mittler eine Anforderung an Ihre Anwendungweiterleitet, übernimmt X-Ray die Client-IP aus der X-Forwarded-For-Kopfzeile der Anforderung
168
AWS X-Ray EntwicklerhandbuchNachverfolgung eingehender Anforderungen mit Express
und nicht aus der Quell-IP im IP-Paket. Die für eine weitergeleitete Anforderung aufgezeichneteClient-IP kann gefälscht sein und ist daher nicht vertrauenswürdig.
When a request is forwarded, the SDK sets an additional field in the segment to indicate this. If the segmentcontains the field x_forwarded_for set to true, the client IP was taken from the X-Forwarded-Forheader in the HTTP request.
Der Meldungshandler erzeugt für jede eingehende Anforderung ein Segment mit einem http-Block, derdie folgenden Informationen enthält:
• HTTP-Methode – GET, POST, PUT, DELETE usw.• Client-Adresse – Die IP-Adresse des Clients, der die Anforderung gesendet hat.• Antwortcode – Der HTTP-Antwortcode für die abgeschlossene Anforderung.• Dauer – Die Startzeit (zu der die Anforderung empfangen wurde) und die Endzeit (zu der die Antwort
gesendet wurde).• Nutzer-Agent — Der user-agent aus der Anfrage.• Inhaltslänge — Die content-length aus der Antwort.
Abschnitte• Nachverfolgung eingehender Anforderungen mit Express (p. 169)• Nachverfolgung eingehender Anforderungen mit Restify (p. 169)• Konfiguration einer Segmentbenennungsstrategie (p. 170)
Nachverfolgung eingehender Anforderungen mitExpressZum Verwenden der Express-Middleware initialisieren Sie den SDK-Client und nutzen Sie die Middleware,die von der express.openSegment-Funktion zurückgegeben wird, bevor Sie Ihre Routen festlegen.
Example app.js – Express
var app = express();
var AWSXRay = require('aws-xray-sdk');app.use(AWSXRay.express.openSegment('MyApp'));
app.get('/', function (req, res) { res.render('index');});
app.use(AWSXRay.express.closeSegment());
Nachdem Sie Ihre Routen festgelegt haben, verwenden Sie die Ausgabe von express.closeSegmentwie gezeigt, um vom X-Ray SDK for Node.js gemeldete Fehler zu beheben.
Nachverfolgung eingehender Anforderungen mitRestifyUm die Restify-Middleware zu verwenden, initialisieren Sie den SDK-Client und führen Sie enable aus.Übergeben Sie den Namen Ihres Restify-Servers und des Segments.
169
AWS X-Ray EntwicklerhandbuchKonfiguration einer Segmentbenennungsstrategie
Example app.js – Restify
var AWSXRay = require('aws-xray-sdk');var AWSXRayRestify = require('aws-xray-sdk-restify');
var restify = require('restify');var server = restify.createServer();AWSXRayRestify.enable(server, 'MyApp'));
server.get('/', function (req, res) { res.render('index');});
Konfiguration einer SegmentbenennungsstrategieAWS X-Ray verwendet einen Servicenamen, um Ihre Anwendung zu identifizieren und sie von anderenAnwendungen, Datenbanken, externen APIs und AWS-Ressourcen zu unterscheiden, die Ihre Anwendungnutzt. Wenn das X-Ray SDK Segmente für eingehende Anfragen generiert, zeichnet es den ServicenamenIhrer Anwendung im Feld name field (p. 73) auf.
Das X-Ray SDK kann Segmente nachdem Hostnamen im HTTP-Anfrageheader benennen. Dieser Headerkann jedoch gefälscht sein, was zu unerwarteten Knoten in Ihrer Service-Übersicht führen könnte. Und zuverhindern, dass das SDK Segmente aufgrund von Anforderungen mit gefälschten Host-Headern falschbenennt, müssen Sie einen standardmäßigen Namen für eingehende Anfragen angeben.
Wenn Ihre Anwendung Anfragen für mehrere Domänen bedient, können Sie das SDK so konfigurieren,dass es eine dynamische Benennungsstrategie verwendet, um dies in den Segmentnamen zuberücksichtigen. Eine dynamische Benennungsstrategie erlaubt es dem SDK, den Host-Namen beiAnfragen zu verwenden, die einem erwarteten Muster entsprechen, und den standardmäßigen Namen fürsolche zu vergeben, die es nicht tun.
Beispielsweise haben Sie vielleicht eine einzelne Anwendung, die Anfragen für drei Subdomänen bedient,– www.example.com, api.example.com und static.example.com. Sie können eine dynamischeBenennungsstrategie mit dem Muster *.example.com verwenden, um Segmente für die einzelnenSubdomänen unterschiedlich zu benennen. Auf der Service-Übersicht werden dann drei Service-Knotenangezeigt. Wenn Ihre Anwendung Anfragen mit einem Hostnamen erhält, der diesem Muster nichtentspricht, sehen Sie auf der Service-Übersicht einen vierten Knoten mit einem von Ihnen festgelegtenAusweichnamen.
Wenn Sie denselben Namen für alle Segmente verwenden möchten, geben Sie bei der Initialisierung derMiddleware den Namen Ihrer Anwendung, wie in den vorherigen Abschnitten gezeigt, ein.
Note
Sie können den mit der AWS_XRAY_TRACING_NAME-Umgebungsvariablen (p. 168) in Codedefinierten standardmäßigen Dienstnamen überschreiben.
Eine dynamische Benennungsstrategie definiert ein Muster, dem Hostnamen entsprechen sollten,sowie einen Standardnamen, der verwendet wird, wenn der Hostname in der HTTP-Anforderungnicht mit diesem Muster übereinstimmt. Zur dynamischen Segmentbenennung verwenden SieAWSXRay.middleware.enableDynamicNaming.
Example app.js - Dynamische Segmentnamen
Wenn der Hostname in der Anforderung dem Muster *.example.com entspricht, verwenden Sie denHostnamen. Verwenden Sie andernfalls MyApp.
var app = express();
170
AWS X-Ray EntwicklerhandbuchAWS SDK-Clients
var AWSXRay = require('aws-xray-sdk');app.use(AWSXRay.express.openSegment('MyApp'));AWSXRay.middleware.enableDynamicNaming('*.example.com'); app.get('/', function (req, res) { res.render('index');});
app.use(AWSXRay.express.closeSegment());
Verfolgen von AWS SDK-Aufrufen mit dem X-RaySDK for Node.js
Wenn Ihre Anwendung die AWS-Services aufruft, um Daten zu speichern, Daten in eine Warteschlangezu schreiben oder Benachrichtigungen zu senden, verfolgt das X-Ray SDK for Node.js die Aufrufe innachgelagerten Untersegmenten (p. 174). Verfolgte AWS-Services und -Ressourcen, auf die Sieinnerhalb dieser Services zugreifen (z. B. ein Amazon S3-Bucket oder eine Amazon SQS-Warteschlange)erscheinen als nachgelagerte Knoten in der Service-Übersicht der X-Ray-Konsole.
Sie können alle AWS SDK-Clients instrumentieren, indem Sie Ihre aws-sdk require-Anweisung in einenAufruf an AWSXRay.captureAWS verpacken.
Example app.js - AWS SDK-Instrumentierung
var AWS = AWSXRay.captureAWS(require('aws-sdk'));
Um einzelne Clients zu instrumentieren, verpacken Sie Ihren AWS SDK-Client in einen Anruf anAWSXRay.captureAWSClient. Instrumentieren Sie beispielsweise einen AmazonDynamoDB-Client wiefolgt:
Example app.js - DynamoDB Client-Werkzeuge
var AWSXRay = require('aws-xray-sdk');... var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
Bei allen Services wird der Name der aufgerufenen API in der X-Ray-Konsole angezeigt. Bei einerUntergruppe von Services fügt das X-Ray SDK Informationen zum Segment hinzu, um mehr Granularität inder Service-Übersicht zu erreichen.
Wenn Sie beispielsweise einen Aufruf mit einem instrumentierten DynamoDB-Client erstellen, fügt dasSDK für Aufrufe, die auf eine Tabelle abzielen, den Tabellennamen zu dem Segment hinzu. In der Konsolewerden die Tabellen als einzelne Knoten in der Service-Übersicht angezeigt, zusammen mit einemgenerischen DynamoDB-Knoten für Aufrufe, die nicht auf eine Tabelle abzielen.
Example Untersegment für einen Aufruf von DynamoDB zum Speichern eines Elements
{ "id": "24756640c0d0978a", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "DynamoDB",
171
AWS X-Ray EntwicklerhandbuchAusgehende HTTP-Aufrufe
"namespace": "aws", "http": { "response": { "content_length": 60, "status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG", }}
Wenn Sie auf benannte Ressourcen zugreifen, werden durch Aufrufe der folgenden Services weitereKnoten in der Service-Übersicht erstellt. Durch Aufrufe, die keinen bestimmten Ressourcen gelten, wird eingenerischer Knoten für den Service erstellt.
• Amazon DynamoDB – Tabellenname• Amazon Simple Storage Service – Bucket und Schlüsselname• Amazon Simple Queue Service – Warteschlangenname
Nachverfolgen von Aufrufen nachgelagerter HTTP-Web-Services mit dem X-Ray SDK for Node.js
Wenn Ihre Anwendung Microservices oder öffentliche HTTP-APIs aufruft, können Sie diese Aufrufe mitdem X-Ray SDK for Node.js-Client instrumentieren und die API der Service-Grafik als nachgelagertenService hinzufügen.
Übergeben Sie Ihren http oder https-Client an die X-Ray SDK for Node.js captureHTTPs-Methode zurNachverfolgung ausgehender Aufrufe.
Example app.js - HTTP-Client
var AWSXRay = require('aws-xray-sdk');var http = AWSXRay.captureHTTPs(require('http'));
Zur Aktivierung der Nachverfolgung auf allen HTTP-Clients rufen Sie captureHTTPsGlobal auf, bevorSie http laden.
Example app.js – HTTP-Client (Global)
var AWSXRay = require('aws-xray-sdk');AWSXRay.captureHTTPsGlobal(require('http'));var http = require('http');
Wenn Sie einen Aufruf an eine nachgelagerte Web-API instrumentieren, erfasst das X-Ray SDK for Node.jsein Untersegment mit Informationen über die HTTP-Anforderung und Antwort. X-Ray verwendet dasUntersegment, um ein abgeleitetes Segment für die entfernte API zu generieren.
Example Untersegment für einen nachgelagerten HTTP-Aufruf
{
172
AWS X-Ray EntwicklerhandbuchSQL-Abfragen
"id": "004f72be19cddc2a", "start_time": 1484786387.131, "end_time": 1484786387.501, "name": "names.example.com", "namespace": "remote", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } }}
Example Abgeleitetes Segment für einen nachgelagerten HTTP-Anruf
{ "id": "168416dc2ea97781", "name": "names.example.com", "trace_id": "1-5880168b-fd5153bb58284b67678aa78c", "start_time": 1484786387.131, "end_time": 1484786387.501, "parent_id": "004f72be19cddc2a", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } }, "inferred": true}
Ablaufverfolgung von SQL-Abfragen mit X-Ray SDKfor Node.js
Instrumentieren Sie SQL-Datenbankabfragen, indem Sie Ihren SQL-Client in die entsprechende X-RaySDK for Node.js Client-Methode verpacken.
• PostgreSQL – AWSXRay.capturePostgres()
var AWSXRay = require('aws-xray-sdk');var pg = AWSXRay.capturePostgres(require('pg'));var client = new pg.Client();
• MySQL – AWSXRay.captureMySQL()
var AWSXRay = require('aws-xray-sdk');var mysql = AWSXRay.captureMySQL(require('mysql'));...var connection = mysql.createConnection(config);
173
AWS X-Ray EntwicklerhandbuchBenutzerdefinierte Untersegmente
Wenn Sie mit einem instrumentierten Client SQL-Abfragen machen, zeichnet X-Ray SDK for Node.js ineinem Untersegment Informationen über die Verbindung und die Abfrage auf.
Erstellen von benutzerdefinierten Untersegmentenmit dem X-Ray SDK for Node.js
Untersegmente erweitern das Segment (p. 20) eines Traces um Details zu erledigten Aufgaben, umAnforderungen zu senden. Jedesmal, wenn Sie einen Aufruf mit einem instrumentierten Client erstellen,erfasst das X-Ray SDK die in einem Untersegment erzeugten Informationen. Sie können zusätzlicheUntersegmente erstellten, um andere Untersegmente zu gruppieren, die Leistung eines Codeabschnitts zumessen oder Anmerkungen und Metadaten aufzuzeichnen.
Um ein benutzerdefiniertes Untersegment für eine Funktion zu erstellen, die Aufrufe des nachgelagertenService vornimmt, verwenden Sie die captureAsyncFunc-Funktion.
Example app.js - Benutzerdefinierte Untersegmente
var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));
app.get('/', function (req, res) { var host = 'api.example.com';
AWSXRay.captureAsyncFunc('send', function(subsegment) { sendRequest(host, function() { console.log('rendering!'); res.render('index'); subsegment.close(); }); });});
app.use(AWSXRay.express.closeSegment());
function sendRequest(host, cb) { var options = { host: host, path: '/', };
var callback = function(response) { var str = '';
response.on('data', function (chunk) { str += chunk; });
response.on('end', function () { cb(); }); }
http.request(options, callback).end();};
In diesem Beispiel erstellt die Anwendung ein benutzerdefiniertes Untersegment namens send für Aufrufeder sendRequest-Funktion. captureAsyncFunc übergibt ein Untersegment, das Sie innerhalb derCallback-Funktion schließen müssen, wenn die asynchronen Aufrufe der Funktion abgeschlossen sind.
174
AWS X-Ray EntwicklerhandbuchAnmerkungen und Metadaten
Für synchrone Funktionen können Sie die captureFunc-Funktion verwenden, mit der das Untersegmentautomatisch geschlossen wird, sobald der Funktionsblock ausgeführt wurde.
Beim Erstellen eines Untersegments innerhalb eines Segments oder eines anderen Untersegmentsgeneriert das X-Ray SDK for Node.js eine ID dafür und erfasst die Start- und Endzeit.
Example Untersegment mit Metadaten
"subsegments": [{ "id": "6f1605cd8a07cb70", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "Custom subsegment for UserModel.saveUser function", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } },
Hinzufügen von Anmerkungen und Metadaten zuSegmenten mit dem X-Ray SDK for Node.js
Mithilfe von Anmerkungen und Metadaten können Sie zusätzliche Informationen zu Anforderungen, derUmgebung oder Ihrer Anwendung aufzeichnen. Sie können den vom X-Ray SDK erstellten Segmentenoder den von Ihnen erstellten benutzerdefinierten Untersegmenten Anmerkungen und Metadatenhinzufügen.
Annotations are key-value pairs with string, number, or Boolean values. Annotations are indexed for usewith filter expressions (p. 39). Use annotations to record data that you want to use to group traces in theconsole, or when calling the GetTraceSummaries API.
Metadata are key-value pairs that can have values of any type, including objects and lists, but are notindexed for use with filter expressions. Use metadata to record additional data that you want stored in thetrace but don't need to use with search.
Abschnitte• Aufzeichnen von Anmerkungen mit dem X-Ray SDK for Node.js (p. 175)• Aufzeichnen von Metadaten mit dem X-Ray SDK for Node.js (p. 176)
Aufzeichnen von Anmerkungen mit dem X-Ray SDKfor Node.jsVerwenden Sie Anmerkungen, um Informationen zu Segmenten oder Untersegmenten, die zur Sucheindiziert werden sollten, aufzuzeichnen.
Anmerkung zu Anforderungen
• Schlüssel – Bis zu 500 alphanumerische Zeichen. Keine Leerzeichen oder Symbole außer Unterstrichen.• Werte – bis zu 1,000 Unicode-Zeichen.• Einträge – Bis zu 50 Anmerkungen pro Ablaufverfolgung.
175
AWS X-Ray EntwicklerhandbuchAufzeichnen von Metadaten mit dem X-Ray SDK for Node.js
So zeichnen Sie Anmerkungen auf
1. Erhalten Sie eine Referenz zum aktuellen Segment oder Untersegment.
var AWSXRay = require('aws-xray-sdk');...var document = AWSXRay.getSegment();
2. Rufen Sie addAnnotation mit einem Aktivierungsschlüssel und einem booleschen Wert oder einemZeichenfolgenwert auf.
document.addAnnotation("mykey", "my value");
Das SDK zeichnet Anmerkungen als Schlüssel-Wert-Paare in einem annotations-Objekt imSegmentdokument auf. Wenn addAnnotation zweimal mit demselben Schlüssel aufgerufen wird, werdenzuvor aufgezeichnete Werte im gleichen Segment oder Untersegment überschrieben.
Nutzen Sie das annotations.key-Schlüsselwort in einem Filterausdruck (p. 39), um Ablaufverfolgungendurch Anmerkungen mit bestimmten Werten zu finden.
Example app.js – Anmerkungen
var AWS = require('aws-sdk');var AWSXRay = require('aws-xray-sdk');var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());...app.post('/signup', function(req, res) { var item = { 'email': {'S': req.body.email}, 'name': {'S': req.body.name}, 'preview': {'S': req.body.previewAccess}, 'theme': {'S': req.body.theme} };
var seg = AWSXRay.getSegment(); seg.addAnnotation('theme', req.body.theme); ddb.putItem({ 'TableName': ddbTable, 'Item': item, 'Expected': { email: { Exists: false } } }, function(err, data) {...
Aufzeichnen von Metadaten mit dem X-Ray SDK forNode.jsVerwenden Sie Metadaten, um Segment- oder Untersegmentinformationen aufzuzeichnen, die nicht zurSuche indiziert werden müssen. Metadatenwerte sind Zeichenfolgen, Zahlen, boolesche Werte oder andereObjekte, die in Form eines JSON-Objekts oder eines Arrays angeordnet sein können.
So zeichnen Sie Metadaten auf
1. Erhalten Sie eine Referenz zum aktuellen Segment oder Untersegment.
var AWSXRay = require('aws-xray-sdk');...
176
AWS X-Ray EntwicklerhandbuchAufzeichnen von Metadaten mit dem X-Ray SDK for Node.js
var document = AWSXRay.getSegment();
2. Rufen Sie addMetadata mit einem Zeichenfolgenschlüssel, einem booleschen Wert, einerZeichenfolge oder einem Objektwert und einem Zeichenfolgen-Namespace auf.
document.addMetadata("my key", "my value", "my namespace");
oder
Rufen Sie addMetadata nur mit einem Aktivierungsschlüssel und einem Wert auf.
document.addMetadata("my key", "my value");
Wenn Sie keinen Namespace angeben, verwendet SDK default. Wenn addMetadata zweimal mitdemselben Schlüssel aufgerufen wird, werden zuvor aufgezeichnete Werte im gleichen Segment oderUntersegment überschrieben.
177
AWS X-Ray Entwicklerhandbuch
AWS X-Ray-SDK für PythonDas X-Ray SDK für Python ist eine Bibliothek für Python-Webanwendungen, die Klassen undMethoden zum Generieren und Senden von Ablaufverfolgungsdaten zum X-Ray-Daemon bereitstellt.Ablaufverfolgungsdaten enthalten Informationen zu eingehenden HTTP-Anforderungen, die von derAnwendung verarbeitet werden, sowie Aufrufen, die Anwendung an nachgelagerten Services mithilfe desAWS SDK, von HTTP-Clients oder einer SQL-Datenbankanbindung vornimmt. Sie können Segmente auchmanuell erstellen und Debug-Informationen Anmerkungen und Metadaten hinzufügen.
Sie können das SDK mit pip herunterladen.
$ pip install aws-xray-sdk
Note
Das X-Ray SDK für Python ist ein Open-Source-Projekt. Sie können das Projekt auf GitHubverfolgen und Probleme und Pull-Anforderungen übermitteln: github.com/aws/aws-xray-sdk-python
Wenn Sie Django oder Flask nutzen, beginnen Sie, indem Sie die SDK-Middleware zu Ihrer Anwendunghinzufügen (p. 185), um eingehende Anforderungen zu verfolgen. Der Middleware erstellt für jedeverfolgte Anforderung ein Segment (p. 20) und vervollständigt das Segment, nachdem die Antwortgesendet wurde. Während das Segment geöffnet ist, können Sie die SDK-Client-Methoden nutzen,um dem Segment Informationen hinzuzufügen, Untersegmente zu erstellen und nachgelagerte Aufruferückzuverfolgen. Das SDK erfasst auch automatisch Ausnahmen, die Ihre Anwendung ausgibt, währenddas Segment geöffnet ist. Bei anderen Anwendungen können Sie Segmente manuell erstellen (p. 187).
Lambda liest für Lambda-Funktionen, die von instrumentalisierten Anwendungen oder Services aufgerufenwerden, den Nachverfolgungs-Header (p. 26) und verfolgt per Sampling erfasste Anforderungenautomatisch. Für andere Funktionen können Sie Lambda so konfigurieren (p. 229), dass für eingehendeAnforderungen Sampling und Nachverfolgung durchgeführt werden. In jedem Fall erstellt Lambda dasSegment und stellt es dem X-Ray SDK zur Verfügung.
Note
In Lambda ist das X-Ray SDK optional. Auch wenn Sie es nicht in Ihrer Funktion verwenden,enthält die Service-Map einen Knoten für den Lambda-Service sowie einen Knoten für jedeLambda-Funktion. Durch Hinzufügen des SDK können Sie Ihren Funktionscode instrumentieren,um dem von Lambda aufgezeichneten Funktionssegment Untersegmente hinzuzufügen. WeitereInformationen finden Sie unter AWS Lambda und AWS X-Ray (p. 229).
Ein Beispiel für eine in Lambda instrumentierte Python-Funktion finden Sie unter Worker (p. 100).
Verwenden Sie als Nächstes das X-Ray SDK für Python, um nachgelagerte Aufrufe zu instrumentieren,indem Sie die von Ihrer Anwendung genutzten Bibliotheken patchen (p. 188). Das SDK unterstützt diefolgenden Bibliotheken.
Unterstützte Bibliotheken
• botocore, boto3 – Instrumentiert AWS SDK for Python (Boto)-Clients.• pynamodb – Instrumentiert die Version von PynamoDB des Amazon DynamoDB-Clients.
178
AWS X-Ray EntwicklerhandbuchVoraussetzungen
• aiobotocore, aioboto3 – Instrumentiert asyncio-integrierte Versionen von SDK for Python-Clients.• requests, aiohttp – Instrumentiert High-Level-HTTP-Clients.• httplib, http.client – Instrumentiert Low-Level-HTTP-Clients und die übergeordneten Bibliotheken,
die von ihnen Gebrauch machen.• sqlite3 – Instrumentieren von SQLite-Clients.• mysql-connector-python – Instrumentieren von MySQL-Clients.
Immer, wenn Ihre Anwendung AWS, eine SQL-Datenbank oder andere HTTP-Services aufruft, zeichnetdas SDK Informationen über den Aufruf in einem Untersegment auf. AWS-Services und die Ressourcen,auf die Sie innerhalb der Services zugreifen, erscheinen in der Service-Übersicht als nachgelagerteKnoten, um Ihnen bei der Identifikation von Fehlern und der Ablehnung von Problemen mit individuellenVerbindungen zu helfen.
Sobald Sie die ersten Schritte mit dem SDK gemacht haben, können Sie das Verhalten durch dieKonfiguration von Recorder und Middleware (p. 180) individualisieren. Sie können Plugins zumFesthalten von Daten über die Datenverarbeitungsressourcen, auf denen Ihre Anwendung ausgeführt wird,hinzufügen, das Samplingverhalten durch Samplingregeln anpassen und Protokollebenen einrichten, ummehr oder weniger Informationen von dem SDK in Ihren Anwendungsprotokollen zu sehen.
Zeichnen Sie zusätzliche Informationen zu Anforderungen und den Aufgaben, die Ihre Anwendungausführt, in Anmerkungen und Metadaten (p. 193) auf. Anmerkungen sind einfache Schlüsselwertpaare,die für die Verwendung mit Filterausdrücken (p. 39) indiziert werden, damit Sie nach Ablaufverfolgen mitbestimmten Daten suchen können. Metadateneinträge sind weniger einschränkend und können ganzeObjekte und Arrays aufzeichnen – alle Daten, die in eine JSON zusammengefasst werden können.
Anmerkungen und Metadaten
Anmerkungen und Metadaten sind beliebiger Text, den Sie mit dem X-Ray-SDK zu Segmentenhinzufügen. Anmerkung werden für die Verwendung mit Filterausdrücken indiziert. Metadatawerden nicht indiziert, können aber im unformatierten Segment mit der X-Ray-Konsole oder -API angezeigt werden. Alle Personen, denen Sie Lesezugriff auf X-Ray gewähren, können dieseDaten anzeigen.
Wenn Sie viele instrumentierten Clients in Ihrem Code haben, kann ein einzelnes Anforderungssegmenteviele Untersegmente enthalten, eines für jeden Aufruf mit einem instrumentierten Client. Sie könnenUntersegmente organisieren und gruppieren, indem Sie Client-Aufrufe in benutzerdefiniertenUntersegmenten (p. 192) zusammenfassen. Sie können ein benutzerdefiniertes Untersegment für diegesamte Funktion oder einen beliebigen Bereich des Codes erstellen. Sie können dann Metadaten undAnmerkungen im Untersegment aufzeichnen, anstatt alles in das übergeordnete Segment zu schreiben.
Die Referenzdokumentation zu den SDK-Klassen und -Methoden finden Sie unter Referenz zum AWS X-Ray-SDK für Python-API.
VoraussetzungenDas X-Ray SDK für Python unterstützt die folgenden Sprachen und Bibliotheksversionen.
• Python – 2.7, 3.4 und höher• Django – 1.10 und höher• Flask – 0.10 und höher• aiohttp – 2.3.0 und höher• AWS SDK for Python (Boto) – 1.4.0 und höher
179
AWS X-Ray EntwicklerhandbuchAbhängigkeitsmanagement
• botocore – 1.5.0 und höher
AbhängigkeitsmanagementDas X-Ray SDK für Python ist über pip verfügbar.
• Paket – aws-xray-sdk
Fügen Sie das SDK in Ihrer requirements.txt-Datei als abhängige Komponente hinzu.
Example requirements.txt
aws-xray-sdk==1.0boto3==1.4.4botocore==1.5.55Django==1.11.3
Wenn Sie Elastic Beanstalk verwenden, um Ihre Anwendung bereitzustellen, installiert Elastic Beanstalkautomatisch alle Pakete in requirements.txt.
Konfigurieren des X-Ray SDK für PythonDas X-Ray SDK für Python verfügt über eine Klasse mit dem Namen xray_recorder, die die globaleAufzeichnung bereitstellt. Sie können die globale Aufzeichnung so konfigurieren, dass die Middleware, dieSegmente für eingehende HTTP-Aufrufe erstellt, angepasst wird.
Abschnitte• Service-Plugins (p. 180)• Samplingregeln (p. 182)• Protokollierung (p. 183)• Konfiguration des Recorders im Code (p. 183)• Konfigurieren des Recorders mit Django (p. 183)• Umgebungsvariablen (p. 184)
Service-PluginsUse plugins to record information about the service hosting your application.
Plugins
• Amazon EC2 – EC2Plugin fügt die Instance-ID und Availability Zone hinzu.• Elastic Beanstalk – ElasticBeanstalkPlugin fügt den Umgebungsnamen, die Versionsbezeichnung
und die Bereitstellungs-ID hinzu.• Amazon ECS – ECSPlugin fügt die Container-ID hinzu.
180
AWS X-Ray EntwicklerhandbuchService-Plugins
Um ein Plugin zu verwenden, rufen Sie configure im xray_recorder auf.
from aws_xray_sdk.core import xray_recorderfrom aws_xray_sdk.core import patch_all
xray_recorder.configure(aws_xray_tracing_name='My app')plugins = ('ElasticBeanstalkPlugin', 'EC2Plugin')xray_recorder.configure(plugins=plugins)patch_all()
Sie können auch Umgebungsvariablen (p. 184), die Vorrang über Werte im Code haben, zurKonfiguration des Recorders verwenden.
Konfigurieren Sie Plugins vor Patch-Bibliotheken (p. 180), um nachgeschaltete Aufrufe aufzuzeichnen.
Das SDK verwendet auch Plug-in-Einstellungen, um das origin-Feld im Segment auszufüllen.Dies gibt den Typ der AWS-Ressource an, die Ihre Anwendung ausführt. Der Ressourcentypwird unter dem Namen der Anwendung in der Service-Übersicht angezeigt. Beispiel,AWS::ElasticBeanstalk::Environment.
181
AWS X-Ray EntwicklerhandbuchSamplingregeln
Wenn Sie mehrere Plug-ins verwenden, benutzt das SDK das zuletzt geladene Plug-in.
SamplingregelnDas SDK hat eine Sampling-Strategie, durch die bestimmt wird, welche Anfragen verfolgt werden.Standardmäßig zeichnet das SDK die erste Anfragen pro Sekunde und fünf Prozent aller weiterenAnfragen. auf. Sie können das Sampling-Verhalten des SDK durch die Anwendung von Regeln anpassen,die in einer lokalen Datei definiert sind.
Example sampling-rules.json
{ "version": 1, "rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 }}
In diesem Beispiel sind eine benutzerdefinierte Regel und eine Standardregel definiert. Diebenutzerdefinierte Regel wendet eine Abtastrate von fünf Prozent ohne minimale Anforderungsanzahlauf die Verfolgung von Pfaden unter /api/move/ an. Die Standardregel verfolgt die erste Anfragen proSekunde und 10 % aller weiteren Anfragen.
Das SDK wendet benutzerdefinierte Regeln in der Reihenfolge an, in der sie definiert sind. Wenn eineAnfrage mehreren benutzerdefinierten Regeln entspricht, wendet das SDK nur die erste Regel an.
In Lambda können Sie die Samplingrate nicht ändern. Wenn Ihre Funktion von einem instrumentiertenService aufgerufen wird, werden von Aufrufen erzeugte Anforderungen, für die von diesem Service einSampling durchgeführt wird, von Lambda aufgezeichnet. Bei aktiver Nachverfolgung ohne vorhandenenNachverfolgungs-Header trifft Lambda die Sampling-Entscheidung.
182
AWS X-Ray EntwicklerhandbuchProtokollierung
Um Samplingregeln zu konfigurieren, rufen Sie xray_recorder.configure auf, wie im folgendenBeispiel dargestellt, wobei der Begriff Regeln entweder ein Wörterbuch mit Regeln oder den absolutenPfad zu einer JSON-Datei mit Samplingregeln bezeichnet.
xray_recorder.configure(sampling_rules=rules)
Sie können auch die globale Aufzeichnung so konfigurieren, dass das Sampling deaktiviert und alleeingehenden Anfragen instrumentiert werden.
Example main.py – Deaktivieren des Samplings
xray_recorder.configure(sampling=False)
ProtokollierungDas SDK verwendet das integrierte logging-Modul von Python. Erhalten Sie eine Referenz zum Loggerfür die aws_xray_sdk-Klasse und rufen Sie darauf setLevel auf, um die verschiedenen Protokollebenenfür die Bibliothek und den Rest Ihrer Anwendung zu konfigurieren.
Example app.py – Protokollierung
logging.basicConfig(level='WARNING')logging.getLogger('aws_xray_sdk').setLevel(logging.DEBUG)
Verwenden Sie Debug-Protokolle, um Probleme wie nicht geschlossene Untersegmente zu identifizieren,wenn Sie Untersegmente manuell generieren (p. 192).
Konfiguration des Recorders im CodeZusätzliche Einstellungen finden Sie in der configure-Methode auf xray_recorder.
• context_missing – Auf LOG_ERROR einstellen, um das Auslösen von Ausnahmen zu vermeiden,wenn Ihr instrumentierter Code versucht, Daten aufzuzeichnen, wenn kein Segment geöffnet ist.
• daemon_address – Legen Sie den Host und den Port des X-Ray-Daemon-Listeners fest.• service – Legen Sie einen Dienstnamen fest, der vom SDK für Segmente verwendet wird.• plugins – Zeichnen Sie Informationen zu den AWS-Ressourcen Ihrer Anwendung auf.• sampling – Auf False einstellen, um das Sampling zu deaktivieren.• sampling_rules – Legen Sie den Pfad der JSON-Datei mit Ihren Samplingregeln (p. 182) fest.
Example main.py – Deaktivieren von Ausnahmen ohne Kontext
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(context_missing='LOG_ERROR')
Konfigurieren des Recorders mit DjangoWenn Sie das Django-Framework verwenden, können Sie die settings.py-Datei von Django zumKonfigurieren von Optionen in der globalen Aufzeichnung verwenden.
183
AWS X-Ray EntwicklerhandbuchUmgebungsvariablen
• AUTO_INSTRUMENT (Nur Django) – Zeichnen Sie Untersegmente auf für integrierte Datenbank- undVorlagenwiedergabevorgänge.
• AWS_XRAY_CONTEXT_MISSING – Auf LOG_ERROR einstellen, um das Auslösen von Ausnahmen zuvermeiden, wenn Ihr instrumentierter Code versucht, Daten aufzuzeichnen, wenn kein Segment geöffnetist.
• AWS_XRAY_DAEMON_ADDRESS – Legen Sie den Host und den Port des X-Ray-Daemon-Listeners fest.• AWS_XRAY_TRACING_NAME – Legen Sie einen Dienstnamen fest, der vom SDK für Segmente verwendet
wird.• PLUGINS – Zeichnen Sie Informationen zu den AWS-Ressourcen Ihrer Anwendung auf.• SAMPLING – Auf False einstellen, um das Sampling zu deaktivieren.• SAMPLING_RULES – Legen Sie den Pfad der JSON-Datei mit Ihren Samplingregeln (p. 182) fest.
Um die Konfiguration des Recorders in settings.py zu aktivieren, fügen Sie die Django-Middleware zurListe der installierten Apps hinzu.
Example settings.py – Installierte Apps
INSTALLED_APPS = [ ... 'django.contrib.sessions', 'aws_xray_sdk.ext.django',]
Konfigurieren Sie die verfügbaren Einstellungen in einer Liste mit dem Namen XRAY_RECORDER.
Example settings.py – Installierte Apps
XRAY_RECORDER = { 'AUTO_INSTRUMENT': True, 'AWS_XRAY_CONTEXT_MISSING': 'LOG_ERROR', 'AWS_XRAY_DAEMON_ADDRESS': '127.0.0.1:5000', 'AWS_XRAY_TRACING_NAME': 'My application', 'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin', 'ECSPlugin'), 'SAMPLING': False,}
UmgebungsvariablenSie können Umgebungsvariablen zum Konfigurieren von X-Ray SDK für Python verwenden. Das SDKunterstützt die folgenden Variablen:
• AWS_XRAY_TRACING_NAME – Legen Sie einen Dienstnamen fest, der vom SDK für Segmente verwendetwird. Überschreibt den für die Segmentbenennungsstrategie (p. 187) des Servlet-Filters festgelegtenDienstnamen.
• AWS_XRAY_DAEMON_ADDRESS – Legen Sie den Host und den Port des X-Ray-Daemon-Listeners fest.Standardmäßig sendet das SDK Ablaufverfolgungsdaten an 127.0.0.1:2000. Verwenden Sie dieseVariable, wenn Sie den Daemon so konfiguriert haben, dass er einen anderen Port überwacht (p. 115),oder wenn er auf einem anderen Host ausgeführt wird.
• AWS_XRAY_CONTEXT_MISSING – Set to LOG_ERROR to avoid throwing exceptions when yourinstrumented code attempts to record data when no segment is open.
Valid Values
• RUNTIME_ERROR – Throw a runtime exception (default).
184
AWS X-Ray EntwicklerhandbuchEingehende Anforderungen
• LOG_ERROR – Log an error and continue.
Errors related to missing segments or subsegments can occur when you attempt to use an instrumentedclient in startup code that runs when no request is open, or in code that spawns a new thread.
Umgebungsvariablen überschreiben Werte im Code.
Ablaufverfolgung eingehender Anfragen mit der X-Ray SDK für Python-Middleware
Wenn Sie Django oder Flask verwenden, nutzen Sie die Django-Middleware (p. 186) oder die Flask-Middleware (p. 186), um eingehende HTTP-Anforderungen zu instrumentieren. Wenn Sie die Middlewarezu Ihrer Anwendung hinzufügen und einen Segmentnamen festlegen, erstellt das X-Ray SDK für Pythonein Segment für jede gesampelte Anfrage. Dieses Segment umfasst Dauer, Methode und Status der HTTP-Anforderung. Die zusätzliche Instrumentierung schafft Untersegmente zu diesem Segment.
Note
Lambda erstellt für AWS Lambda-Funktionen ein Segment für jede Anforderung, die per Samplingerfasst wurde. Weitere Informationen finden Sie unter AWS Lambda und AWS X-Ray (p. 229).
Ein Beispiel für eine in Lambda instrumentierte Python-Funktion finden Sie unter Worker (p. 100).
Für Skripts oder Python-Anwendungen auf anderen Frameworks können Sie Segmente manuellerstellen (p. 187).
Each segment has a name that identifies your application in the service map. The segment can be namedstatically, or you can configure the SDK to name it dynamically based on the host header in the incomingrequest. Dynamic naming lets you group traces based on the domain name in the request, and apply adefault name if the name doesn't match an expected pattern (for example, if the host header is forged).
Weitergeleitete Anfragen
Wenn ein Load Balancer oder ein anderer Mittler eine Anforderung an Ihre Anwendungweiterleitet, übernimmt X-Ray die Client-IP aus der X-Forwarded-For-Kopfzeile der Anforderungund nicht aus der Quell-IP im IP-Paket. Die für eine weitergeleitete Anforderung aufgezeichneteClient-IP kann gefälscht sein und ist daher nicht vertrauenswürdig.
When a request is forwarded, the SDK sets an additional field in the segment to indicate this. If the segmentcontains the field x_forwarded_for set to true, the client IP was taken from the X-Forwarded-Forheader in the HTTP request.
Die Middleware erzeugt für jede eingehende Anfrage ein Segment mit einem http-Block mit folgendenInformationen:
• HTTP-Methode – GET, POST, PUT, DELETE usw.• Client-Adresse – Die IP-Adresse des Clients, der die Anforderung gesendet hat.• Antwortcode – Der HTTP-Antwortcode für die abgeschlossene Anforderung.• Dauer – Die Startzeit (zu der die Anforderung empfangen wurde) und die Endzeit (zu der die Antwort
gesendet wurde).• Nutzer-Agent — Der user-agent aus der Anfrage.• Inhaltslänge — Die content-length aus der Antwort.
185
AWS X-Ray EntwicklerhandbuchHinzufügen der Middleware zu Ihrer Anwendung (Django)
Abschnitte• Hinzufügen der Middleware zu Ihrer Anwendung (Django) (p. 186)• Hinzufügen der Middleware zu Ihrer Anwendung (Flask) (p. 186)• Manuelle Instrumentierung von Python-Code (p. 187)• Konfiguration einer Segmentbenennungsstrategie (p. 187)
Hinzufügen der Middleware zu Ihrer Anwendung(Django)Fügen Sie die Middleware zur MIDDLEWARE-Liste in Ihrer settings.py-Datei hinzu. Die X-Ray-Middleware sollte die erste Zeile in Ihrer settings.py-Datei darstellen, um sicherzugehen, dassAnfragen, die in anderen Middlewares fehlschlagen, aufgezeichnet werden.
Example settings.py - X-Ray SDK für Python-Middleware
MIDDLEWARE = [ 'aws_xray_sdk.ext.django.middleware.XRayMiddleware', 'django.middleware.security.SecurityMiddleware', 'django.contrib.sessions.middleware.SessionMiddleware', 'django.middleware.common.CommonMiddleware', 'django.middleware.csrf.CsrfViewMiddleware', 'django.contrib.auth.middleware.AuthenticationMiddleware', 'django.contrib.messages.middleware.MessageMiddleware', 'django.middleware.clickjacking.XFrameOptionsMiddleware']
Konfigurieren Sie einen Segmentnamen in Ihrer settings.py-Datei (p. 183).
Example settings.py – Segmentname
XRAY_RECORDER = {, 'AWS_XRAY_TRACING_NAME': 'My application', 'PLUGINS': ('EC2Plugin'),}
Dadurch wird der X-Ray-Recorder angewiesen, Anfragen, die von Ihrer Django-Anwendung verarbeitetwerden, mit der Standard-Samplingrate nachzuverfolgen. Sie können den Recorder in Ihrer Django-Einstellungsdatei konfigurieren (p. 183), um benutzerdefinierte Samplingregeln anzuwenden oder andereEinstellungen zu ändern.
Hinzufügen der Middleware zu Ihrer Anwendung(Flask)Um Ihre Flask-Anwendung zu instrumentieren, konfigurieren Sie zunächst einen Segmentnamen imxray_recorder. Verwenden Sie dann die XRayMiddleware-Funktion zum Patchen Ihrer Flask-Anwendung im Code.
Example app.py
from aws_xray_sdk.core import xray_recorderfrom aws_xray_sdk.ext.flask.middleware import XRayMiddleware
186
AWS X-Ray EntwicklerhandbuchManuelle Instrumentierung von Python-Code
app = Flask(__name__)
xray_recorder.configure(service='My application')XRayMiddleware(app, xray_recorder)
Dadurch wird der X-Ray-Recorder angewiesen, Anfragen, die von Ihrer Flask-Anwendung verarbeitetwerden, mit der Standard-Samplingrate nachzuverfolgen. Sie können den Recorder im Codekonfigurieren (p. 183), um benutzerdefinierte Samplingregeln anzuwenden oder andere Einstellungen zuändern.
Manuelle Instrumentierung von Python-CodeWenn Sie weder Django noch Flask verwenden, können Sie Segmente manuell erstellen. Sie können einSegment für jede eingehende Anforderung erstellen. Alternativ können Sie auch Segmente um gepatchteHTTP- oder AWS-SDK-Clients herum erstellen, um Kontext für den Recorder bereitzustellen, damitUntersegmente hinzugefügt werden können.
Example main.py – manuelle Instrumentierung
from aws_xray_sdk.core import xray_recorder
# Start a segmentsegment = xray_recorder.begin_segment('segment_name')# Start a subsegmentsubsegment = xray_recorder.begin_subsegment('subsegment_name')
# Add metadata and annotationssegment.put_metadata('key', dict, 'namespace')subsegment.put_annotation('key', 'value')
# Close the subsegment and segmentxray_recorder.end_subsegment()xray_recorder.end_segment()
Konfiguration einer SegmentbenennungsstrategieAWS X-Ray verwendet einen Servicenamen, um Ihre Anwendung zu identifizieren und sie von anderenAnwendungen, Datenbanken, externen APIs und AWS-Ressourcen zu unterscheiden, die Ihre Anwendungnutzt. Wenn das X-Ray SDK Segmente für eingehende Anfragen generiert, zeichnet es den ServicenamenIhrer Anwendung im Feld name field (p. 73) auf.
Das X-Ray SDK kann Segmente nachdem Hostnamen im HTTP-Anfrageheader benennen. Dieser Headerkann jedoch gefälscht sein, was zu unerwarteten Knoten in Ihrer Service-Übersicht führen könnte. Und zuverhindern, dass das SDK Segmente aufgrund von Anforderungen mit gefälschten Host-Headern falschbenennt, müssen Sie einen standardmäßigen Namen für eingehende Anfragen angeben.
Wenn Ihre Anwendung Anfragen für mehrere Domänen bedient, können Sie das SDK so konfigurieren,dass es eine dynamische Benennungsstrategie verwendet, um dies in den Segmentnamen zuberücksichtigen. Eine dynamische Benennungsstrategie erlaubt es dem SDK, den Host-Namen beiAnfragen zu verwenden, die einem erwarteten Muster entsprechen, und den standardmäßigen Namen fürsolche zu vergeben, die es nicht tun.
Beispielsweise haben Sie vielleicht eine einzelne Anwendung, die Anfragen für drei Subdomänen bedient,– www.example.com, api.example.com und static.example.com. Sie können eine dynamischeBenennungsstrategie mit dem Muster *.example.com verwenden, um Segmente für die einzelnenSubdomänen unterschiedlich zu benennen. Auf der Service-Übersicht werden dann drei Service-Knotenangezeigt. Wenn Ihre Anwendung Anfragen mit einem Hostnamen erhält, der diesem Muster nicht
187
AWS X-Ray EntwicklerhandbuchPatchen von Bibliotheken
entspricht, sehen Sie auf der Service-Übersicht einen vierten Knoten mit einem von Ihnen festgelegtenAusweichnamen.
Wenn Sie denselben Namen für alle Anfragesegmente verwenden möchten, geben Sie bei derKonfiguration des Recorders den Namen Ihrer Anwendung, wie in den vorherigen Abschnitten (p. 186)gezeigt, ein.
Eine dynamische Benennungsstrategie definiert ein Muster, dem Hostnamen entsprechen sollten, sowieeinen Standardnamen, der verwendet wird, wenn der Hostname in der HTTP-Anforderung nicht mit diesemMuster übereinstimmt. Zur dynamischen Segmentbenennung fügen Sie die DYNAMIC_NAMING-Einstellungzu Ihrer settings.py (p. 183)-Datei hinzu.
Example settings.py – Dynamische Benennung
XRAY_RECORDER = { 'AUTO_INSTRUMENT': True, 'AWS_XRAY_TRACING_NAME': 'My application', 'DYNAMIC_NAMING': '*.example.com', 'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin'),}
Sie können "*" im Muster verwenden für die Übereinstimmung mit einer beliebigen Zeichenfolge oder"?" für die Übereinstimmung mit einem beliebigen Zeichen. Für Flask konfigurieren Sie den Recorder imCode (p. 183).
Example main.py – Segmentname
from aws_xray_sdk.core import xray_recorderxray_recorder.configure(service='My application')xray_recorder.configure(dynamic_naming='*.example.com')
Note
Sie können den mit der AWS_XRAY_TRACING_NAME-Umgebungsvariablen (p. 184) in Codedefinierten standardmäßigen Dienstnamen überschreiben.
Patchen von Bibliotheken zum Instrumentieren vonnachgelagerten Aufrufen
Um nachgelagerte Aufrufe zu instrumentieren, verwenden Sie das X-Ray SDK für Python, um die vonIhrer Anwendung genutzten Bibliotheken zu patchen. Das X-Ray SDK für Python kann die folgendenBibliotheken patchen.
Unterstützte Bibliotheken
• botocore, boto3 – Instrumentiert AWS SDK for Python (Boto)-Clients.• pynamodb – Instrumentiert die Version von PynamoDB des Amazon DynamoDB-Clients.• aiobotocore, aioboto3 – Instrumentiert asyncio-integrierte Versionen von SDK for Python-Clients.• requests, aiohttp – Instrumentiert High-Level-HTTP-Clients.• httplib, http.client – Instrumentiert Low-Level-HTTP-Clients und die übergeordneten Bibliotheken,
die von ihnen Gebrauch machen.• sqlite3 – Instrumentieren von SQLite-Clients.
188
AWS X-Ray EntwicklerhandbuchAblaufverfolgungskontext für Asynchronous Work
• mysql-connector-python – Instrumentieren von MySQL-Clients.
Wenn Sie eine gepatchte Bibliothek verwenden, erstellt das X-Ray SDK für Python ein Untersegment fürden Aufruf und zeichnet Informationen aus der Anfrage und Antwort auf. Für das SDK muss ein Segmentzur Verfügung stehen, damit es ein Untersegment aus der SDK-Middleware oder aus AWS Lambdaerstellen kann.
Note
Wenn Sie SQLAlchemy ORM verwenden, können Sie Ihre SQL-Abfragen instrumentieren,indem Sie die SDK-Version der Sitzungs- und Abfrageklassen von SQLAlchemy importieren.Anweisungen hierzu finden Sie unter Verwenden von SQLAlchemy ORM.
Um alle verfügbaren Bibliotheken zu patchen, verwenden Sie die patch_all-Funktion inaws_xray_sdk.core.
Example main.py – Patchen aller unterstützten Bibliotheken
import boto3import botocoreimport requestsimport sqlite3
from aws_xray_sdk.core import xray_recorderfrom aws_xray_sdk.core import patch_all
patch_all()
Um einzelne Bibliotheken zu patchen, rufen Sie patch mit einem Tupel von Bibliothekennamen auf.
Example main.py – Patchen bestimmter Bibliotheken
import boto3import botocoreimport requestsimport mysql-connector-python
from aws_xray_sdk.core import xray_recorderfrom aws_xray_sdk.core import patch
libraries = ('botocore', 'mysql')patch(libraries)
Note
In einigen Fällen stimmt der Schlüssel, mit dem Sie eine Bibliothek patchen, nicht mit dem Namender Bibliothek überein. Einige Schlüssel dienen als Aliase für eine oder mehrere Bibliotheken.
Aliase für Bibliotheken
• httplib – httplib und http.client• mysql – mysql-connector-python
Ablaufverfolgungskontext für Asynchronous WorkBei asyncio integrierten Bibliotheken und wenn Sie Untersegmente für asynchrone Funktionenerstellen (p. 192) möchten, müssen Sie das X-Ray SDK für Python ebenfalls mit einem asynchronen
189
AWS X-Ray EntwicklerhandbuchAWS SDK-Clients
Kontext konfigurieren. Importieren Sie die Klasse AsyncContext und leiten Sie eine Instance davon anden X-Ray Recorder weiter.
Example main.py – Patchen von aioboto3
import asyncioimport aioboto3import requests
from aws_xray_sdk.core.async_context import AsyncContextfrom aws_xray_sdk.core import xray_recorderxray_recorder.configure(service='my_service', context=AsyncContext())from aws_xray_sdk.core import patch
libraries = ('aioboto3')patch(libraries)
Ablaufverfolgung von AWS SDK-Aufrufen mit demX-Ray SDK für Python
Wenn Ihre Anwendung die AWS-Services aufruft, um Daten zu speichern, Daten in eine Warteschlangezu schreiben oder Benachrichtigungen zu senden, verfolgt das X-Ray SDK für Python die Aufrufenachgelagert in Untersegmenten (p. 192). Verfolgte AWS-Services und -Ressourcen, auf die Sieinnerhalb dieser Services zugreifen (z. B. ein Amazon S3-Bucket oder eine Amazon SQS-Warteschlange)erscheinen als nachgelagerte Knoten in der Service-Übersicht der X-Ray-Konsole.
Das X-Ray SDK für Python instrumentiert automatisch alle AWS SDK-Clients beim Patchen der botocore-Bibliothek (p. 188). Einzelne Clients können nicht instrumentiert werden.
Bei allen Services wird der Name der aufgerufenen API in der X-Ray-Konsole angezeigt. Bei einerUntergruppe von Services fügt das X-Ray SDK Informationen zum Segment hinzu, um mehr Granularität inder Service-Übersicht zu erreichen.
Wenn Sie beispielsweise einen Aufruf mit einem instrumentierten DynamoDB-Client erstellen, fügt dasSDK für Aufrufe, die auf eine Tabelle abzielen, den Tabellennamen zu dem Segment hinzu. In der Konsolewerden die Tabellen als einzelne Knoten in der Service-Übersicht angezeigt, zusammen mit einemgenerischen DynamoDB-Knoten für Aufrufe, die nicht auf eine Tabelle abzielen.
Example Untersegment für einen Aufruf von DynamoDB zum Speichern eines Elements
{ "id": "24756640c0d0978a", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "DynamoDB", "namespace": "aws", "http": { "response": { "content_length": 60, "status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG", }
190
AWS X-Ray EntwicklerhandbuchAusgehende HTTP-Aufrufe
}
Wenn Sie auf benannte Ressourcen zugreifen, werden durch Aufrufe der folgenden Services weitereKnoten in der Service-Übersicht erstellt. Durch Aufrufe, die keinen bestimmten Ressourcen gelten, wird eingenerischer Knoten für den Service erstellt.
• Amazon DynamoDB – Tabellenname• Amazon Simple Storage Service – Bucket und Schlüsselname• Amazon Simple Queue Service – Warteschlangenname
Nachverfolgen von Aufrufen nachgelagerter HTTP-Web-Services mit dem X-Ray SDK für Python
Wenn Ihre Anwendung Microservices oder öffentliche HTTP-APIs aufruft, können Sie diese Aufrufemit X-Ray SDK für Python instrumentieren und die API der Service-Grafik als nachgelagerten Servicehinzufügen.
Um HTTP-Clients zu instrumentieren, patchen Sie die Bibliothek (p. 188), mit der Sie ausgehendeAufrufe durchführen. Wenn Sie requests oder den integrierten HTTP-Client von Python verwenden,brauchen Sie nichts weiter zu tun. Bei aiohttp müssen Sie zudem den Recorder mit einem asynchronenKontext (p. 189) konfigurieren.
Wenn Sie die aiohttp 3-Client-API verwenden, müssen Sie auch die ClientSession mit einer Instanceder Nachverfolgungskonfiguration konfigurieren, die vom SDK bereitgestellt wird.
Example aiohttp 3 Client-API
from aws_xray_sdk.ext.aiohttp.client import aws_xray_trace_config
async def foo(): trace_config = aws_xray_trace_config() async with ClientSession(loop=loop, trace_configs=[trace_config]) as session: async with session.get(url) as resp await resp.read()
Wenn Sie einen Aufruf an eine nachgelagerte Web-API instrumentieren, erfasst das X-Ray SDK für Pythonein Untersegment mit Informationen über die HTTP-Anforderung und -Antwort. X-Ray verwendet dasUntersegment, um ein abgeleitetes Segment für die entfernte API zu generieren.
Example Untersegment für einen nachgelagerten HTTP-Aufruf
{ "id": "004f72be19cddc2a", "start_time": 1484786387.131, "end_time": 1484786387.501, "name": "names.example.com", "namespace": "remote", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 }
191
AWS X-Ray EntwicklerhandbuchBenutzerdefinierte Untersegmente
}}
Example Abgeleitetes Segment für einen nachgelagerten HTTP-Anruf
{ "id": "168416dc2ea97781", "name": "names.example.com", "trace_id": "1-5880168b-fd5153bb58284b67678aa78c", "start_time": 1484786387.131, "end_time": 1484786387.501, "parent_id": "004f72be19cddc2a", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } }, "inferred": true}
Erstellen von benutzerdefinierten Untersegmentenmit dem X-Ray SDK für Python
Untersegmente erweitern das Segment (p. 20) eines Traces um Details zu erledigten Aufgaben, umAnforderungen zu senden. Jedesmal, wenn Sie einen Aufruf mit einem instrumentierten Client erstellen,erfasst das X-Ray SDK die in einem Untersegment erzeugten Informationen. Sie können zusätzlicheUntersegmente erstellten, um andere Untersegmente zu gruppieren, die Leistung eines Codeabschnitts zumessen oder Anmerkungen und Metadaten aufzuzeichnen.
Um Untersegmente zu verwalten, verwenden Sie die Methoden begin_subsegment undend_subsegment.
Example main.py – Benutzerdefiniertes Untersegment
from aws_xray_sdk.core import xray_recorder
subsegment = xray_recorder.begin_subsegment('annotations')subsegment.put_annotation('id', 12345)xray_recorder.end_subsegment()
Um ein Untersegment für eine synchrone Funktion zu erstellen, verwenden Sie den@xray_recorder.capture-Decorator. Sie können einen Namen für das Untersegment an dieErfassungsfunktion übergeben oder diesen weglassen und den Funktionsnamen verwenden.
Example main.py – Funktionsuntersegment
from aws_xray_sdk.core import xray_recorder
@xray_recorder.capture('## create_user')def create_user():...
192
AWS X-Ray EntwicklerhandbuchAnmerkungen und Metadaten
Verwenden Sie bei einer asynchronen Funktion den @xray_recorder.capture_async-Decorator undübergeben Sie einen asynchronen Kontext an den Recorder.
Example main.py – asynchrones Funktionsuntersegment
from aws_xray_sdk.core.async_context import AsyncContextfrom aws_xray_sdk.core import xray_recorderxray_recorder.configure(service='my_service', context=AsyncContext())
@xray_recorder.capture_async('## create_user')async def create_user(): ...
async def main(): await myfunc()
Beim Erstellen eines Untersegments innerhalb eines Segments oder eines anderen Untersegmentsgeneriert das X-Ray SDK für Python eine ID dafür und erfasst die Start- und Endzeit.
Example Untersegment mit Metadaten
"subsegments": [{ "id": "6f1605cd8a07cb70", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "Custom subsegment for UserModel.saveUser function", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } },
Hinzufügen von Anmerkungen und Metadaten zuSegmenten mit dem X-Ray SDK für Python
Mithilfe von Anmerkungen und Metadaten können Sie zusätzliche Informationen zu Anforderungen, derUmgebung oder Ihrer Anwendung aufzeichnen. Sie können den vom X-Ray SDK erstellten Segmentenoder den von Ihnen erstellten benutzerdefinierten Untersegmenten Anmerkungen und Metadatenhinzufügen.
Annotations are key-value pairs with string, number, or Boolean values. Annotations are indexed for usewith filter expressions (p. 39). Use annotations to record data that you want to use to group traces in theconsole, or when calling the GetTraceSummaries API.
Metadata are key-value pairs that can have values of any type, including objects and lists, but are notindexed for use with filter expressions. Use metadata to record additional data that you want stored in thetrace but don't need to use with search.
Zusätzlich zu Anmerkungen und Metadaten können Sie auch Benutzer-ID-Zeichenfolgen (p. 195) inSegmenten aufzeichnen. Benutzer-IDs werden in einem eigenen Feld aufgezeichnet und zur Sucheindiziert.
Abschnitte• Aufzeichnen von Anmerkungen mit dem X-Ray SDK für Python (p. 194)• Aufzeichnen von Metadaten mit dem X-Ray SDK für Python (p. 194)
193
AWS X-Ray EntwicklerhandbuchAufzeichnen von Anmerkungenmit dem X-Ray SDK für Python
• Aufzeichnen von Benutzer-IDs mit dem X-Ray SDK für Python (p. 195)
Aufzeichnen von Anmerkungen mit dem X-Ray SDKfür PythonVerwenden Sie Anmerkungen, um Informationen zu Segmenten oder Untersegmenten, die zur Sucheindiziert werden sollten, aufzuzeichnen.
Anmerkung zu Anforderungen
• Schlüssel – Bis zu 500 alphanumerische Zeichen. Keine Leerzeichen oder Symbole außer Unterstrichen.• Werte – bis zu 1,000 Unicode-Zeichen.• Einträge – Bis zu 50 Anmerkungen pro Ablaufverfolgung.
So zeichnen Sie Anmerkungen auf
1. Eine Referenz des aktuellen Segments oder Untersegments finden Sie unter xray_recorder.
from aws_xray_sdk.core import xray_recorder ... document = xray_recorder.current_segment()
oder
from aws_xray_sdk.core import xray_recorder ... document = xray_recorder.current_subsegment()
2. Rufen Sie put_annotation mit einem Aktivierungsschlüssel und einem booleschen Wert oder einemZeichenfolgenwert auf.
document.put_annotation("mykey", "my value");
Alternativ können Sie auch die put_annotation-Methode im xray_recorder verwenden. Mit dieserMethode werden Anmerkungen zum aktuellen Untersegment oder zum Segment aufgezeichnet, wenn keinUntersegment geöffnet ist.
xray_recorder.put_annotation("mykey", "my value");
Das SDK zeichnet Anmerkungen als Schlüssel-Wert-Paare in einem annotations-Objekt imSegmentdokument auf. Wenn put_annotation zweimal mit demselben Schlüssel aufgerufen wird,werden zuvor aufgezeichnete Werte im gleichen Segment oder Untersegment überschrieben.
Nutzen Sie das annotations.key-Schlüsselwort in einem Filterausdruck (p. 39), um Ablaufverfolgungendurch Anmerkungen mit bestimmten Werten zu finden.
Aufzeichnen von Metadaten mit dem X-Ray SDK fürPythonVerwenden Sie Metadaten, um Segment- oder Untersegmentinformationen aufzuzeichnen, die nicht zurSuche indiziert werden müssen. Metadatenwerte sind Zeichenfolgen, Zahlen, boolesche Werte oder andereObjekte, die in Form eines JSON-Objekts oder eines Arrays angeordnet sein können.
194
AWS X-Ray EntwicklerhandbuchAufzeichnen von Benutzer-IDsmit dem X-Ray SDK für Python
So zeichnen Sie Metadaten auf
1. Eine Referenz des aktuellen Segments oder Untersegments finden Sie unter xray_recorder.
from aws_xray_sdk.core import xray_recorder ... document = xray_recorder.current_segment()
oder
from aws_xray_sdk.core import xray_recorder ... document = xray_recorder.current_subsegment()
2. Rufen Sie put_metadata mit einem Zeichenfolgenschlüssel, einem booleschen Wert, einer Zahl,einer Zeichenfolge oder einem Objektwert und einem Zeichenfolgen-Namespace auf.
document.put_metadata("my key", "my value", "my namespace");
oder
Rufen Sie put_metadata nur mit einem Aktivierungsschlüssel und einem Wert auf.
document.put_metadata("my key", "my value");
Alternativ können Sie auch die put_metadata-Methode auf xray_recorder verwenden. Mit dieserMethode werden Metadaten zum aktuellen Untersegment oder zum Segment aufgezeichnet, wenn keinUntersegment geöffnet ist.
xray_recorder.put_metadata("my key", "my value");
Wenn Sie keinen Namespace angeben, verwendet SDK default. Wenn put_metadata zweimal mitdemselben Schlüssel aufgerufen wird, werden zuvor aufgezeichnete Werte im gleichen Segment oderUntersegment überschrieben.
Aufzeichnen von Benutzer-IDs mit dem X-Ray SDK fürPythonZeichnen Sie Benutzer-IDs in Anforderungssegmenten auf, um den Benutzer zu identifizieren, der dieAnforderung gesendet hat.
So zeichnen Sie Benutzer-IDs auf
1. Eine Referenz des aktuellen Segments finden Sie unter xray_recorder.
from aws_xray_sdk.core import xray_recorder ... document = xray_recorder.current_segment()
2. Rufen Sie setUser mit einer Zeichenfolgen-ID des Benutzers auf, der die Anforderung gesendet hat.
document.set_user("U12345");
Sie können set_user in Ihrem Controller aufrufen, um die Benutzer-ID aufzuzeichnen, sobald dieAnwendung mit der Bearbeitung einer Anfrage beginnt.
195
AWS X-Ray EntwicklerhandbuchAufzeichnen von Benutzer-IDsmit dem X-Ray SDK für Python
Nutzen Sie das user-Schlüsselwort in einem Filterausdruck (p. 39), um Ablaufverfolgungen einerBenutzer-ID zu finden.
196
AWS X-Ray Entwicklerhandbuch
AWS X-Ray SDK für RubyDas X-Ray SDK ist eine Bibliothek für Ruby-Webanwendungen, die Klassen und Methodenzum Generieren und Senden von Ablaufverfolgungsdaten zum X-Ray-Daemon bereitstellt.Ablaufverfolgungsdaten enthalten Informationen zu eingehenden HTTP-Anforderungen, die von derAnwendung verarbeitet werden, sowie Aufrufen, die Anwendung an nachgelagerten Services mithilfe desAWS SDK, von HTTP-Clients oder eines Active Record-Clients vornimmt. Sie können Segmente auchmanuell erstellen und Debug-Informationen Anmerkungen und Metadaten hinzufügen.
Sie können das SDK herunterladen, indem Sie es Ihrer Gemfile-Datei hinzufügen und bundle installausführen.
Example Gemfile
gem 'aws-xray-sdk'
Wenn Sie Rails verwenden, beginnen Sie damit, die X-Ray SDK-Middleware hinzuzufügen (p. 203), umeingehende Anforderungen zu verfolgen. Ein Anforderungsfilter erstellt ein Segment (p. 20). Währenddas Segment geöffnet ist, können Sie die SDK-Client-Methoden nutzen, um dem Segment Informationenhinzuzufügen, Untersegmente zu erstellen und nachgelagerte Aufrufe rückzuverfolgen. Das SDK erfasstauch automatisch Ausnahmen, die Ihre Anwendung ausgibt, während das Segment geöffnet ist. Beianderen Anwendungen als Rails können Sie Segmente manuell erstellen (p. 204).
Anschließend verwenden Sie das X-Ray SDK, um Ihre AWS SDK for Ruby-, HTTP- und SQL-Clients zuinstrumentieren, indem Sie den Recorder so konfigurieren (p. 206), dass die zugehörigen Bibliothekengepatcht werden. Sobald Sie eine Anfrage stellen, um einen AWS-Service oder eine Ressource mit eineminstrumentierten Client rückzuverfolgen, zeichnet SDK in einem Untersegment Informationen zu dieserAnfrage auf. AWS-Services und die Ressourcen, auf die Sie innerhalb der Services zugreifen, erscheinenin der Service-Übersicht als nachgelagerte Knoten, um Ihnen bei der Identifikation von Fehlern und derAblehnung von Problemen mit individuellen Verbindungen zu helfen.
Sobald Sie die ersten Schritte mit dem SDK gemacht haben, können Sie das Verhalten durch dieKonfiguration des Recorders (p. 198) individualisieren. Sie können Plugins zum Festhalten von Datenüber die Datenverarbeitungsressourcen, auf denen Ihre Anwendung ausgeführt wird, hinzufügen, dasSamplingverhalten durch Samplingregeln anpassen und einen Logger bereitstellen, um mehr oder wenigerInformationen von dem SDK in Ihren Anwendungsprotokollen zu sehen.
Zeichnen Sie zusätzliche Informationen zu Anforderungen und den Aufgaben, die Ihre Anwendungausführt, in Anmerkungen und Metadaten (p. 208) auf. Anmerkungen sind einfache Schlüsselwertpaare,die für die Verwendung mit Filterausdrücken (p. 39) indiziert werden, damit Sie nach Ablaufverfolgen mitbestimmten Daten suchen können. Metadateneinträge sind weniger einschränkend und können ganzeObjekte und Arrays aufzeichnen – alle Daten, die in eine JSON zusammengefasst werden können.
Anmerkungen und Metadaten
Anmerkungen und Metadaten sind beliebiger Text, den Sie mit dem X-Ray-SDK zu Segmentenhinzufügen. Anmerkung werden für die Verwendung mit Filterausdrücken indiziert. Metadatawerden nicht indiziert, können aber im unformatierten Segment mit der X-Ray-Konsole oder -API angezeigt werden. Alle Personen, denen Sie Lesezugriff auf X-Ray gewähren, können dieseDaten anzeigen.
197
AWS X-Ray EntwicklerhandbuchVoraussetzungen
Wenn Sie viele instrumentierten Clients in Ihrem Code haben, kann ein einzelnes Anforderungssegmenteviele Untersegmente enthalten, eines für jeden Aufruf mit einem instrumentierten Client. Sie könnenUntersegmente organisieren und gruppieren, indem Sie Client-Aufrufe in benutzerdefiniertenUntersegmenten (p. 207) zusammenfassen. Sie können ein benutzerdefiniertes Untersegment für eineganze Funktion oder eine Code-Abschnitt erstellen und Metadaten und Anmerkungen im Untersegmentfesthalten, anstatt alles im übergeordneten Segment aufzuzeichnen.
Die Referenzdokumentation zu den SDK-Klassen und -Methoden finden Sie unter Referenz zum AWS X-Ray-SDK für Ruby-API.
VoraussetzungenDas X-Ray SDK erfordert Ruby 2.3 oder höher und ist kompatibel mit den folgenden Bibliotheken:
• AWS SDK for Ruby-Version 3.0 oder höher• Rails Version 5.1 oder höher
Konfigurieren des X-Ray SDK für RubyDas X-Ray SDK für Ruby verfügt über eine Klasse mit dem Namen XRay.recorder, die die globaleAufzeichnung bereitstellt. Sie können die globale Aufzeichnung so konfigurieren, dass die Middleware, dieSegmente für eingehende HTTP-Aufrufe erstellt, angepasst wird.
Abschnitte• Service-Plugins (p. 198)• Samplingregeln (p. 200)• Protokollierung (p. 201)• Konfiguration des Recorders im Code (p. 202)• Konfigurieren des Recorders mit Rails (p. 202)• Umgebungsvariablen (p. 203)
Service-PluginsUse plugins to record information about the service hosting your application.
Plugins
• Amazon EC2 – ec2 fügt die Instance-ID und Availability Zone hinzu.• Elastic Beanstalk – elastic_beanstalk fügt den Umgebungsnamen, die Versionsbezeichnung und
die Bereitstellungs-ID hinzu.• Amazon ECS – ecs fügt die Container-ID hinzu.
198
AWS X-Ray EntwicklerhandbuchService-Plugins
Um Plugins verwenden zu können, geben Sie sie in dem Konfigurationsobjekt an, das sie dem Recorderübergeben.
Example main.rb – Plugin-Konfiguration
my_plugins = %I[ec2 elastic_beanstalk]
config = { plugins: my_plugins, name: 'my app',}
XRay.recorder.configure(config)
Sie können auch Umgebungsvariablen (p. 203), die Vorrang über Werte im Code haben, zurKonfiguration des Recorders verwenden.
Das SDK verwendet auch Plug-in-Einstellungen, um das origin-Feld im Segment auszufüllen.Dies gibt den Typ der AWS-Ressource an, die Ihre Anwendung ausführt. Der Ressourcentypwird unter dem Namen der Anwendung in der Service-Übersicht angezeigt. Beispiel,AWS::ElasticBeanstalk::Environment.
199
AWS X-Ray EntwicklerhandbuchSamplingregeln
Wenn Sie mehrere Plug-ins verwenden, benutzt das SDK das zuletzt geladene Plug-in.
SamplingregelnDas SDK hat eine Sampling-Strategie, durch die bestimmt wird, welche Anfragen verfolgt werden.Standardmäßig zeichnet das SDK die erste Anfragen pro Sekunde und fünf Prozent aller weiterenAnfragen. auf. Sie können das Sampling-Verhalten des SDK durch die Anwendung von Regeln anpassen,die in einer lokalen Datei definiert sind.
Example sampling-rules.json
{ "version": 1, "rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 }}
In diesem Beispiel sind eine benutzerdefinierte Regel und eine Standardregel definiert. Diebenutzerdefinierte Regel wendet eine Abtastrate von fünf Prozent ohne minimale Anforderungsanzahlauf die Verfolgung von Pfaden unter /api/move/ an. Die Standardregel verfolgt die erste Anfragen proSekunde und 10 % aller weiteren Anfragen.
Das SDK wendet benutzerdefinierte Regeln in der Reihenfolge an, in der sie definiert sind. Wenn eineAnfrage mehreren benutzerdefinierten Regeln entspricht, wendet das SDK nur die erste Regel an.
Um Samplingregeln zu konfigurieren, definieren Sie einen Hash für das Dokument im Konfigurationsobjekt,das Sie dem Recorder übergeben.
Example main.rb – Konfigurieren der Samplingregeln
require 'aws-xray-sdk'
200
AWS X-Ray EntwicklerhandbuchProtokollierung
my_sampling_rules = { version: 1, default: { fixed_target: 1, rate: 0.1 }}config = { sampling_rules: my_sampling_rules, name: 'my app',}XRay.recorder.configure(config)
Speichern Sie die Samplingregeln unabhängig voneinander, definieren Sie den Hash in einer separatenDatei und fordern Sie die Datei an, damit er in Ihre Anwendung übernommen wird.
Example config/sampling-rules.rb
my_sampling_rules = { version: 1, default: { fixed_target: 1, rate: 0.1 }}
Example main.rb – Samplingregeln aus einer Datei
require 'aws-xray-sdk'require config/sampling-rules.rb
config = { sampling_rules: my_sampling_rules, name: 'my app',}XRay.recorder.configure(config)
Sie können auch die globale Aufzeichnung so konfigurieren, dass das Sampling deaktiviert und alleeingehenden Anfragen instrumentiert werden.
Example main.rb – Deaktivieren des Samplings
require 'aws-xray-sdk'config = { sampling: false, name: 'my app',}XRay.recorder.configure(config)
ProtokollierungStandardmäßig gibt der Recorder Ereignisse auf Informationsebene in $stdout aus. Sie können dieProtokollierung anpassen, indem Sie einen Logger in dem Konfigurationsobjekt definieren, das Sie demRecorder übergeben.
Example main.rb – Protokollierung
require 'aws-xray-sdk'
201
AWS X-Ray EntwicklerhandbuchKonfiguration des Recorders im Code
config = { logger: my_logger, name: 'my app',}XRay.recorder.configure(config)
Verwenden Sie Debug-Protokolle, um Probleme wie nicht geschlossene Untersegmente zu identifizieren,wenn Sie Untersegmente manuell generieren (p. 207).
Konfiguration des Recorders im CodeZusätzliche Einstellungen finden Sie in der configure-Methode auf XRay.recorder.
• context_missing – Auf LOG_ERROR einstellen, um das Auslösen von Ausnahmen zu vermeiden,wenn Ihr instrumentierter Code versucht, Daten aufzuzeichnen, wenn kein Segment geöffnet ist.
• daemon_address – Legen Sie den Host und den Port des X-Ray-Daemon-Listeners fest.• name – Legen Sie einen Dienstnamen fest, der vom SDK für Segmente verwendet wird.• naming_pattern – Legen Sie ein Domänennamensmuster fest, um eine dynamische Benennung zu
verwenden (p. 205).• plugins – Zeichnen Sie Informationen zu den AWS-Ressourcen Ihrer Anwendung mit Plugins (p. 198)
auf.• sampling – Auf false einstellen, um das Sampling zu deaktivieren.• sampling_rules – Legen Sie den Hash mit Ihren Samplingregeln (p. 200) fest.
Example main.py – Deaktivieren von Ausnahmen ohne Kontext
require 'aws-xray-sdk'config = { context_missing: LOG_ERROR}
XRay.recorder.configure(config)
Konfigurieren des Recorders mit RailsWenn Sie das Rails-Framework verwenden, können Sie die Optionen für den globalen Recorder ineiner Ruby-Datei unter app_root/initializers konfigurieren. Das X-Ray-SDK unterstützt einenzusätzlichen Konfigurationsschlüssel für die Verwendung mit Rails.
• active_record – Auf true setzen, um Untersegmente für Active Record-Datenbanktransaktionenaufzuzeichnen.
Konfigurieren Sie die verfügbaren Einstellungen in einem Konfigurationsobjekt mit dem NamenRails.application.config.xray.
Example config/initializers/aws_xray.rb
Rails.application.config.xray = { name: 'my app', patch: %I[net_http aws_sdk], active_record: true}
202
AWS X-Ray EntwicklerhandbuchUmgebungsvariablen
UmgebungsvariablenSie können Umgebungsvariablen zum Konfigurieren von X-Ray SDK für Ruby verwenden. Das SDKunterstützt die folgenden Variablen:
• AWS_XRAY_TRACING_NAME – Legen Sie einen Dienstnamen fest, der vom SDK für Segmente verwendetwird. Überschreibt den für die Segmentbenennungsstrategie (p. 205) des Servlet-Filters festgelegtenDienstnamen.
• AWS_XRAY_DAEMON_ADDRESS – Legen Sie den Host und den Port des X-Ray-Daemon-Listeners fest.Standardmäßig sendet das SDK Ablaufverfolgungsdaten an 127.0.0.1:2000. Verwenden Sie dieseVariable, wenn Sie den Daemon so konfiguriert haben, dass er einen anderen Port überwacht (p. 115),oder wenn er auf einem anderen Host ausgeführt wird.
• AWS_XRAY_CONTEXT_MISSING – Set to LOG_ERROR to avoid throwing exceptions when yourinstrumented code attempts to record data when no segment is open.
Valid Values
• RUNTIME_ERROR – Throw a runtime exception (default).• LOG_ERROR – Log an error and continue.
Errors related to missing segments or subsegments can occur when you attempt to use an instrumentedclient in startup code that runs when no request is open, or in code that spawns a new thread.
Umgebungsvariablen überschreiben Werte im Code.
Ablaufverfolgung eingehender Anfragen mit der X-Ray SDK für Ruby-Middleware
Sie können mit dem X-Ray SDK eingehende HTTP-Anforderungen verfolgen, die Ihre Anwendung auf einerEC2 Instance in Amazon EC2, AWS Elastic Beanstalk oder Amazon ECS verarbeitet.
Wenn Sie Rails einsetzen, verwenden Sie die Rails-Middleware, um eingehenden HTTP-Anforderungenzu instrumentieren. Wenn Sie die Middleware zu Ihrer Anwendung hinzufügen und einen Segmentnamenfestlegen, erstellt das X-Ray SDK für Ruby ein Segment für jede gesampelte Anfrage. Alle durch einezusätzliche Instrumentierung erstellten Segmente werden zu Untersegmenten des Segments aufAnfrageebene, das Informationen über die HTTP-Anforderung und Antwort bereitstellt. Diese Informationenumfassen Dauer, Methode und Status der Anfrage.
Each segment has a name that identifies your application in the service map. The segment can be namedstatically, or you can configure the SDK to name it dynamically based on the host header in the incomingrequest. Dynamic naming lets you group traces based on the domain name in the request, and apply adefault name if the name doesn't match an expected pattern (for example, if the host header is forged).
Weitergeleitete Anfragen
Wenn ein Load Balancer oder ein anderer Mittler eine Anforderung an Ihre Anwendungweiterleitet, übernimmt X-Ray die Client-IP aus der X-Forwarded-For-Kopfzeile der Anforderungund nicht aus der Quell-IP im IP-Paket. Die für eine weitergeleitete Anforderung aufgezeichneteClient-IP kann gefälscht sein und ist daher nicht vertrauenswürdig.
When a request is forwarded, the SDK sets an additional field in the segment to indicate this. If the segmentcontains the field x_forwarded_for set to true, the client IP was taken from the X-Forwarded-Forheader in the HTTP request.
203
AWS X-Ray EntwicklerhandbuchVerwenden der Rails-Middleware
Die Middleware erzeugt für jede eingehende Anfrage ein Segment mit einem http-Block mit folgendenInformationen:
• HTTP-Methode – GET, POST, PUT, DELETE usw.• Client-Adresse – Die IP-Adresse des Clients, der die Anforderung gesendet hat.• Antwortcode – Der HTTP-Antwortcode für die abgeschlossene Anforderung.• Dauer – Die Startzeit (zu der die Anforderung empfangen wurde) und die Endzeit (zu der die Antwort
gesendet wurde).• Nutzer-Agent — Der user-agent aus der Anfrage.• Inhaltslänge — Die content-length aus der Antwort.
Verwenden der Rails-MiddlewareUm die Middleware zu verwenden, aktualisieren Sie Ihre Gemfile-Datei, sodass sie das geforderte railtieenthält.
Example Gemfile – Rails
gem 'aws-xray-sdk', require: ['aws-xray-sdk/facets/rails/railtie']
Um die Middleware zu verwenden, müssen Sie auch den Recorder mit einem Namenkonfigurieren (p. 202), der die Anwendung in der Service-Map darstellt.
Example config/initializers/aws_xray.rb
Rails.application.config.xray = { name: 'my app'}
Code manuell instrumentierenWenn Sie Rails nicht verwenden, erstellen Sie Segmente manuell. Sie können ein Segment für jedeeingehende Anforderung erstellen. Alternativ können Sie auch Segmente um gepatchte HTTP- oderAWS-SDK-Clients herum erstellen, um Kontext für den Recorder bereitzustellen, damit Untersegmentehinzugefügt werden können.
# Start a segmentsegment = XRay.recorder.begin_segment 'my_service'# Start a subsegmentsubsegment = XRay.recorder.begin_subsegment 'outbound_call', namespace: 'remote'
# Add metadata or annotation here if necessarymy_annotations = { k1: 'v1', k2: 1024}segment.annotations.update my_annotations
# Add metadata to default namespacesubsegment.metadata[:k1] = 'v1'
# Set user for the segment (subsegment is not supported)segment.user = 'my_name'
204
AWS X-Ray EntwicklerhandbuchKonfiguration einer Segmentbenennungsstrategie
# End segment/subsegmentXRay.recorder.end_subsegmentXRay.recorder.end_segment
Konfiguration einer SegmentbenennungsstrategieAWS X-Ray verwendet einen Servicenamen, um Ihre Anwendung zu identifizieren und sie von anderenAnwendungen, Datenbanken, externen APIs und AWS-Ressourcen zu unterscheiden, die Ihre Anwendungnutzt. Wenn das X-Ray SDK Segmente für eingehende Anfragen generiert, zeichnet es den ServicenamenIhrer Anwendung im Feld name field (p. 73) auf.
Das X-Ray SDK kann Segmente nachdem Hostnamen im HTTP-Anfrageheader benennen. Dieser Headerkann jedoch gefälscht sein, was zu unerwarteten Knoten in Ihrer Service-Übersicht führen könnte. Und zuverhindern, dass das SDK Segmente aufgrund von Anforderungen mit gefälschten Host-Headern falschbenennt, müssen Sie einen standardmäßigen Namen für eingehende Anfragen angeben.
Wenn Ihre Anwendung Anfragen für mehrere Domänen bedient, können Sie das SDK so konfigurieren,dass es eine dynamische Benennungsstrategie verwendet, um dies in den Segmentnamen zuberücksichtigen. Eine dynamische Benennungsstrategie erlaubt es dem SDK, den Host-Namen beiAnfragen zu verwenden, die einem erwarteten Muster entsprechen, und den standardmäßigen Namen fürsolche zu vergeben, die es nicht tun.
Beispielsweise haben Sie vielleicht eine einzelne Anwendung, die Anfragen für drei Subdomänen bedient,– www.example.com, api.example.com und static.example.com. Sie können eine dynamischeBenennungsstrategie mit dem Muster *.example.com verwenden, um Segmente für die einzelnenSubdomänen unterschiedlich zu benennen. Auf der Service-Übersicht werden dann drei Service-Knotenangezeigt. Wenn Ihre Anwendung Anfragen mit einem Hostnamen erhält, der diesem Muster nichtentspricht, sehen Sie auf der Service-Übersicht einen vierten Knoten mit einem von Ihnen festgelegtenAusweichnamen.
Wenn Sie denselben Namen für alle Anfragesegmente verwenden möchten, geben Sie bei derKonfiguration des Recorders den Namen Ihrer Anwendung, wie in den vorherigen Abschnitten (p. 204)gezeigt, ein.
Eine dynamische Benennungsstrategie definiert ein Muster, dem Hostnamen entsprechen sollten, sowieeinen Standardnamen, der verwendet wird, wenn der Hostname in der HTTP-Anforderung nicht mit diesemMuster übereinstimmt. Um Segmente dynamisch zu benennen, geben Sie ein Namensmuster im Config-Hash an.
Example main.rb – Dynamische Benennung
config = { naming_pattern: '*mydomain*', name: 'my app',}
XRay.recorder.configure(config)
Sie können "*" im Muster verwenden für die Übereinstimmung mit einer beliebigen Zeichenfolge oder "?" fürdie Übereinstimmung mit einem beliebigen Zeichen.
Note
Sie können den mit der AWS_XRAY_TRACING_NAME-Umgebungsvariablen (p. 203) in Codedefinierten standardmäßigen Dienstnamen überschreiben.
205
AWS X-Ray EntwicklerhandbuchPatchen von Bibliotheken
Patchen von Bibliotheken zum Instrumentieren vonnachgelagerten Aufrufen
Um nachgelagerte Aufrufe zu instrumentieren, verwenden Sie das X-Ray SDK für Ruby, um die von IhrerAnwendung genutzten Bibliotheken zu patchen. Das X-Ray SDK für Ruby kann die folgenden Bibliothekenpatchen.
Unterstützte Bibliotheken
• net/http – Instrumentieren von HTTP-Clients.• aws-sdk – Instrumentieren von AWS SDK for Ruby-Clients.
Wenn Sie eine gepatchte Bibliothek verwenden, erstellt das X-Ray SDK für Ruby ein Untersegment fürden Aufruf und zeichnet Informationen aus der Anfrage und Antwort auf. Für das SDK muss ein Segmentzur Verfügung stehen, damit es ein Untersegment aus der SDK-Middleware oder einem Aufruf vonXRay.recorder.begin_segment erstellen kann.
Um Bibliotheken zu patchen, geben Sie sie in dem Konfigurationsobjekt an, das sie dem X-Ray-Recorderübergeben.
Example main.rb – Bibliotheken patchen
require 'aws-xray-sdk'
config = { name: 'my app', patch: %I[net_http aws_sdk]}
XRay.recorder.configure(config)
Verfolgen von AWS SDK-Aufrufen mit dem X-RaySDK für Ruby
Wenn Ihre Anwendung die AWS-Services aufruft, um Daten zu speichern, Daten in eine Warteschlangezu schreiben oder Benachrichtigungen zu senden, verfolgt das X-Ray SDK für Ruby die Aufrufe innachgelagerten Untersegmenten (p. 207). Verfolgte AWS-Services und -Ressourcen, auf die Sieinnerhalb dieser Services zugreifen (z. B. ein Amazon S3-Bucket oder eine Amazon SQS-Warteschlange)erscheinen als nachgelagerte Knoten in der Service-Übersicht der X-Ray-Konsole.
Das X-Ray SDK für Ruby instrumentiert automatisch alle AWS SDK-Clients beim Patchen der aws-sdk-Bibliothek (p. 206). Einzelne Clients können nicht instrumentiert werden.
Bei allen Services wird der Name der aufgerufenen API in der X-Ray-Konsole angezeigt. Bei einerUntergruppe von Services fügt das X-Ray SDK Informationen zum Segment hinzu, um mehr Granularität inder Service-Übersicht zu erreichen.
Wenn Sie beispielsweise einen Aufruf mit einem instrumentierten DynamoDB-Client erstellen, fügt dasSDK für Aufrufe, die auf eine Tabelle abzielen, den Tabellennamen zu dem Segment hinzu. In der Konsolewerden die Tabellen als einzelne Knoten in der Service-Übersicht angezeigt, zusammen mit einemgenerischen DynamoDB-Knoten für Aufrufe, die nicht auf eine Tabelle abzielen.
206
AWS X-Ray EntwicklerhandbuchBenutzerdefinierte Untersegmente
Example Untersegment für einen Aufruf von DynamoDB zum Speichern eines Elements
{ "id": "24756640c0d0978a", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "DynamoDB", "namespace": "aws", "http": { "response": { "content_length": 60, "status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG", }}
Wenn Sie auf benannte Ressourcen zugreifen, werden durch Aufrufe der folgenden Services weitereKnoten in der Service-Übersicht erstellt. Durch Aufrufe, die keinen bestimmten Ressourcen gelten, wird eingenerischer Knoten für den Service erstellt.
• Amazon DynamoDB – Tabellenname• Amazon Simple Storage Service – Bucket und Schlüsselname• Amazon Simple Queue Service – Warteschlangenname
Erstellen von benutzerdefinierten Untersegmentenmit dem X-Ray SDK
Untersegmente erweitern das Segment (p. 20) eines Traces um Details zu erledigten Aufgaben, umAnforderungen zu senden. Jedesmal, wenn Sie einen Aufruf mit einem instrumentierten Client erstellen,erfasst das X-Ray SDK die in einem Untersegment erzeugten Informationen. Sie können zusätzlicheUntersegmente erstellten, um andere Untersegmente zu gruppieren, die Leistung eines Codeabschnitts zumessen oder Anmerkungen und Metadaten aufzuzeichnen.
Um Untersegmente zu verwalten, verwenden Sie die Methoden begin_subsegment undend_subsegment.
subsegment = XRay.recorder.begin_subsegment name: 'annotations', namespace: 'remote'my_annotations = { id: 12345 }subsegment.annotations.update my_annotationsXRay.recorder.end_subsegment
Um ein Subsegment für eine Funktion zu erstellen, kapseln Sie es in einen Aufruf vonXRay.recorder.capture ein.
XRay.recorder.capture('name_for_subsegment') do |subsegment| resp = myfunc() # myfunc is your function subsegment.annotations.update k1: 'v1' respend
207
AWS X-Ray EntwicklerhandbuchAnmerkungen und Metadaten
Beim Erstellen eines Untersegments innerhalb eines Segments oder eines anderen Untersegmentsgeneriert das X-Ray SDK eine ID dafür und erfasst die Start- und Endzeit.
Example Untersegment mit Metadaten
"subsegments": [{ "id": "6f1605cd8a07cb70", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "Custom subsegment for UserModel.saveUser function", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } },
Hinzufügen von Anmerkungen und Metadaten zuSegmenten mit X-Ray SDK für Ruby
Mithilfe von Anmerkungen und Metadaten können Sie zusätzliche Informationen zu Anforderungen, derUmgebung oder Ihrer Anwendung aufzeichnen. Sie können den vom X-Ray SDK erstellten Segmentenoder den von Ihnen erstellten benutzerdefinierten Untersegmenten Anmerkungen und Metadatenhinzufügen.
Annotations are key-value pairs with string, number, or Boolean values. Annotations are indexed for usewith filter expressions (p. 39). Use annotations to record data that you want to use to group traces in theconsole, or when calling the GetTraceSummaries API.
Metadata are key-value pairs that can have values of any type, including objects and lists, but are notindexed for use with filter expressions. Use metadata to record additional data that you want stored in thetrace but don't need to use with search.
Zusätzlich zu Anmerkungen und Metadaten können Sie auch Benutzer-ID-Zeichenfolgen (p. 210) inSegmenten aufzeichnen. Benutzer-IDs werden in einem eigenen Feld aufgezeichnet und zur Sucheindiziert.
Abschnitte• Aufzeichnung von Anmerkungen mit X-Ray SDK für Ruby (p. 208)• Aufzeichnung von Metadaten mit X-Ray SDK für Ruby (p. 209)• Aufzeichnen von Benutzer-IDs mit dem X-Ray SDK für Ruby (p. 210)
Aufzeichnung von Anmerkungen mit X-Ray SDK fürRubyVerwenden Sie Anmerkungen, um Informationen zu Segmenten oder Untersegmenten, die zur Sucheindiziert werden sollten, aufzuzeichnen.
Anmerkung zu Anforderungen
• Schlüssel – Bis zu 500 alphanumerische Zeichen. Keine Leerzeichen oder Symbole außer Unterstrichen.• Werte – bis zu 1,000 Unicode-Zeichen.
208
AWS X-Ray EntwicklerhandbuchAufzeichnung von Metadaten mit X-Ray SDK für Ruby
• Einträge – Bis zu 50 Anmerkungen pro Ablaufverfolgung.
So zeichnen Sie Anmerkungen auf
1. Eine Referenz des aktuellen Segments oder Untersegments finden Sie unter xray_recorder.
require 'aws-xray-sdk'...document = XRay.recorder.current_segment
oder
require 'aws-xray-sdk'...document = XRay.recorder.current_subsegment
2. Rufen Sie update mit einem Hash-Wert auf.
my_annotations = { id: 12345 }document.annotations.update my_annotations
Das SDK zeichnet Anmerkungen als Schlüssel-Wert-Paare in einem annotations-Objekt imSegmentdokument auf. Wenn add_annotations zweimal mit demselben Schlüssel aufgerufen wird,werden zuvor aufgezeichnete Werte im gleichen Segment oder Untersegment überschrieben.
Nutzen Sie das annotations.key-Schlüsselwort in einem Filterausdruck (p. 39), um Ablaufverfolgungendurch Anmerkungen mit bestimmten Werten zu finden.
Aufzeichnung von Metadaten mit X-Ray SDK für RubyVerwenden Sie Metadaten, um Segment- oder Untersegmentinformationen aufzuzeichnen, die nicht zurSuche indiziert werden müssen. Metadatenwerte sind Zeichenfolgen, Zahlen, boolesche Werte oder andereObjekte, die in Form eines JSON-Objekts oder eines Arrays angeordnet sein können.
So zeichnen Sie Metadaten auf
1. Eine Referenz des aktuellen Segments oder Untersegments finden Sie unter xray_recorder.
require 'aws-xray-sdk'...document = XRay.recorder.current_segment
oder
require 'aws-xray-sdk'...document = XRay.recorder.current_subsegment
2. Rufen Sie metadata mit einem Zeichenfolgenschlüssel, einem booleschen Wert, einer Zahl, einerZeichenfolge oder einem Objektwert und einem Zeichenfolgen-Namespace auf.
my_metadata = { my_namespace: { key: 'value' }
209
AWS X-Ray EntwicklerhandbuchAufzeichnen von Benutzer-IDs mit dem X-Ray SDK für Ruby
}subsegment.metadata my_metadata
Wenn metadata zweimal mit demselben Schlüssel aufgerufen wird, werden zuvor aufgezeichnete Werteim gleichen Segment oder Untersegment überschrieben.
Aufzeichnen von Benutzer-IDs mit dem X-Ray SDK fürRubyZeichnen Sie Benutzer-IDs in Anforderungssegmenten auf, um den Benutzer zu identifizieren, der dieAnforderung gesendet hat.
So zeichnen Sie Benutzer-IDs auf
1. Eine Referenz des aktuellen Segments finden Sie unter xray_recorder.
require 'aws-xray-sdk'...document = XRay.recorder.current_segment
2. Setzen Sie das Benutzerfeld auf dem Segment auf eine Zeichenfolgen-ID des Benutzers, der dieAnforderung gesendet hat.
segment.user = 'U12345'
Sie können den Benutzern in Ihren Controllern festlegen, um die Benutzer-ID aufzuzeichnen, sobald dieAnwendung mit der Bearbeitung einer Anfrage beginnt.
Nutzen Sie das user-Schlüsselwort in einem Filterausdruck (p. 39), um Ablaufverfolgungen einerBenutzer-ID zu finden.
210
AWS X-Ray Entwicklerhandbuch
AWS X-Ray-SDK für .NETDas X-Ray SDK for .NET ist eine Bibliothek zur Instrumentierung von C# .NET-Webanwendungen, .NETCore-Webanwendungen und .NET Core-Funktionen in AWS Lambda. Es stellt Klassen und Methoden zurVerfügung, um Trace-Daten zu erzeugen und an den X-Ray-Daemon (p. 112) zu senden. Diese umfassenInformationen zu eingehenden Anforderungen, die von der Anwendung verarbeitet werden, sowie Aufrufe,die die Anwendung an nachgelagerte AWS-Services, HTTP-Web-APIs und SQL-Datenbanken sendet.
Note
Das X-Ray SDK for .NET ist ein Open-Source-Projekt. Sie können das Projekt auf GitHubverfolgen und Probleme und Pull-Anforderungen übermitteln: github.com/aws/aws-xray-sdk-dotnet
Für Webanwendungen fügen Sie zunächst einen Message Handler zu Ihrer Web-Konfigurationhinzu (p. 217), um eingehende Anforderungen zu verfolgen. Der Message Handler erstellt für jederückverfolgte Anforderung ein Segment (p. 20) und vervollständigt das Segment, nachdem die Antwortgesendet wurde. Während das Segment geöffnet ist, können Sie die SDK-Client-Methoden nutzen,um dem Segment Informationen hinzuzufügen, Untersegmente zu erstellen und nachgelagerte Aufruferückzuverfolgen. Das SDK erfasst auch automatisch Ausnahmen, die Ihre Anwendung ausgibt, währenddas Segment geöffnet ist.
Lambda liest für Lambda-Funktionen, die von instrumentalisierten Anwendungen oder Services aufgerufenwerden, den Nachverfolgungs-Header (p. 26) und verfolgt per Sampling erfasste Anforderungenautomatisch. Für andere Funktionen können Sie Lambda so konfigurieren (p. 229), dass für eingehendeAnforderungen Sampling und Nachverfolgung durchgeführt werden. In jedem Fall erstellt Lambda dasSegment und stellt es dem X-Ray SDK zur Verfügung.
Note
In Lambda ist das X-Ray SDK optional. Auch wenn Sie es nicht in Ihrer Funktion verwenden,enthält die Service-Map einen Knoten für den Lambda-Service sowie einen Knoten für jedeLambda-Funktion. Durch Hinzufügen des SDK können Sie Ihren Funktionscode instrumentieren,um dem von Lambda aufgezeichneten Funktionssegment Untersegmente hinzuzufügen. WeitereInformationen finden Sie unter AWS Lambda und AWS X-Ray (p. 229).
Verwenden Sie anschließend X-Ray SDK for .NET, um Ihre AWS SDK for .NET-Clients zuinstrumentalisieren (p. 219). Sobald Sie eine Anfrage stellen, um einen AWS-Service oder eineRessource mit einem instrumentierten Client rückzuverfolgen, zeichnet SDK in einem UntersegmentInformationen zu dieser Anfrage auf. AWS-Services und die Ressourcen, auf die Sie innerhalb der Serviceszugreifen, erscheinen in der Service-Übersicht als nachgelagerte Knoten, um Ihnen bei der Identifikationvon Fehlern und der Ablehnung von Problemen mit individuellen Verbindungen zu helfen.
Das X-Ray SDK for .NET bietet auch eine Instrumentierung für nachgelagerte Aufrufe zu HTTP-Web-APIs (p. 220) und SQL-Datenbanken (p. 222) an. Die GetResponseTraced-Erweiterungsmethodefür System.Net.HttpWebRequest verfolgt ausgehende HTTP-Aufrufe. Sie können die SqlCommand-Version von X-Ray SDK for .NET verwenden, um SQL-Abfragen zu instrumentieren.
Sobald Sie die ersten Schritte mit dem SDK gemacht haben, können Sie das Verhalten durch dieKonfiguration des Rekorders und des Message Handlers (p. 212) individualisieren. Sie können Pluginszum Festhalten von Daten über die Datenverarbeitungsressourcen, auf denen Ihre Anwendung ausgeführtwird, hinzufügen, das Samplingverhalten durch Samplingregeln anpassen und Protokollebenen einrichten,um mehr oder weniger Informationen von dem SDK in Ihren Anwendungsprotokollen zu sehen.
Zeichnen Sie zusätzliche Informationen zu Anforderungen und den Aufgaben, die Ihre Anwendungausführt, in Anmerkungen und Metadaten (p. 223) auf. Anmerkungen sind einfache Schlüsselwertpaare,die für die Verwendung mit Filterausdrücken (p. 39) indiziert werden, damit Sie nach Ablaufverfolgen mitbestimmten Daten suchen können. Metadateneinträge sind weniger einschränkend und können ganzeObjekte und Arrays aufzeichnen – alle Daten, die in eine JSON zusammengefasst werden können.
211
AWS X-Ray EntwicklerhandbuchVoraussetzungen
Anmerkungen und Metadaten
Anmerkungen und Metadaten sind beliebiger Text, den Sie mit dem X-Ray-SDK zu Segmentenhinzufügen. Anmerkung werden für die Verwendung mit Filterausdrücken indiziert. Metadatawerden nicht indiziert, können aber im unformatierten Segment mit der X-Ray-Konsole oder -API angezeigt werden. Alle Personen, denen Sie Lesezugriff auf X-Ray gewähren, können dieseDaten anzeigen.
Wenn Sie viele instrumentierten Clients in Ihrem Code haben, kann ein einzelnes Anforderungssegmenteviele Untersegmente enthalten, eines für jeden Aufruf mit einem instrumentierten Client. Sie könnenUntersegmente organisieren und gruppieren, indem Sie Client-Aufrufe in benutzerdefiniertenUntersegmenten (p. 223) zusammenfassen. Sie können ein benutzerdefiniertes Untersegment für eineganze Funktion oder eine Code-Abschnitt erstellen und Metadaten und Anmerkungen im Untersegmentfesthalten, anstatt alles im übergeordneten Segment aufzuzeichnen.
Referenzdokumentation zu den SDK-Klassen und -Methoden finden Sie unter:
• Referenz zur AWS X-Ray SDK for .NET-API• Referenz zur AWS X-Ray SDK for .NET Core-API
Das Paket unterstützt sowohl .NET als auch .NET Core. Die verwendeten Klassen sind jedochunterschiedlich. Beispiele in diesem Kapitel verweisen auf die .NET API-Referenz, es sei denn, die Klasseist für .NET Core spezifisch.
VoraussetzungenFür das X-Ray SDK for .NET sind .NET Framework und AWS SDK for .NET erforderlich.
Für .NET Core-Anwendungen und -Funktionen erfordert das SDK .NET Core 2.0 oder höher.
Hinzufügen des X-Ray SDK for .NET zu IhrerAnwendung
Verwenden Sie NuGet, um das X-Ray SDK for .NET zu Ihrer Anwendung hinzuzufügen.
Installieren Sie das X-Ray SDK for .NET mit NuGet Package Manager in Visual Studio wie folgt:
1. Wählen Sie Tools (Tools), NuGet Package Manager (NuGet-Paketmanager), Manage NuGetPackages for Solution (NuGet-Pakete für Lösungen verwalten) aus.
2. Suchen Sie nach AWSXRayRecorder.3. Wählen sie das Paket und dann Install.
Konfigurieren des X-Ray SDK for .NETSie können das X-Ray SDK for .NET mit Plugins konfigurieren, um Informationen über den Service, überden Ihre Anwendung ausgeführt wird, zu berücksichtigen, das Standard-Samplingverhalten zu ändern oderSamplingregeln, die für Anforderungen an bestimmte Pfade gelten, hinzuzufügen.
Für .NET-Webanwendungen fügen Sie dem Abschnitt appSettings Ihrer Web.config-Datei Schlüsselhinzu.
212
AWS X-Ray EntwicklerhandbuchPlugins
Example Web.config
<configuration> <appSettings> <add key="AWSXRayPlugins" value="EC2Plugin"/> <add key="SamplingRuleManifest" value="sampling-rules.json"/> </appSettings></configuration>
Erstellen Sie für .NET Core eine Datei mit dem Namen appsettings.json mit einem Top-Level-Schlüssel namens XRay.
Example appsettings.json
{ "XRay": { "AWSXRayPlugins": "EC2Plugin", "SamplingRuleManifest": "sampling-rules.json" }}
Erstellen Sie dann in Ihrem Anwendungscode ein Konfigurationsobjekt und verwenden Sie es, um den X-Ray-Recorder zu initialisieren. Führen Sie dies aus, bevor Sie den Recorder initialisieren (p. 218).
Example Program.cs – .NET Core-Konfiguration
using Amazon.XRay.Recorder.Core;...AWSXRayRecorder.InitializeInstance(configuration);
Wenn Sie eine .NET-Core-Webanwendung instrumentieren, können Sie das Konfigurationsobjekt auch beider Konfiguration des Message-Handlers (p. 218) an die UseXRay-Methode übergeben. Für Lambda-Funktionen verwenden Sie, wie oben gezeigt, die Methode InitializeInstance.
Weitere Informationen zur .NET Core-Konfigurations-API finden Sie unter Konfigurieren einer ASP.NETCore-App bei docs.microsoft.com.
Abschnitte• Plugins (p. 213)• Samplingregeln (p. 214)• Protokollierung (.NET) (p. 215)• Protokollierung (.NET Core) (p. 215)• Umgebungsvariablen (p. 216)
PluginsVerwenden Sie Plugins zum Hinzufügen von Daten über den Service, der Ihre Anwendung hostet.
Plugins
• Amazon EC2 – EC2Plugin fügt die Instance-ID und Availability Zone hinzu.• Elastic Beanstalk – ElasticBeanstalkPlugin fügt den Umgebungsnamen, die Versionsbezeichnung
und die Bereitstellungs-ID hinzu.• Amazon ECS – ECSPlugin fügt die Container-ID hinzu.
213
AWS X-Ray EntwicklerhandbuchSamplingregeln
Um ein Plugin zu verwenden, konfigurieren Sie den X-Ray SDK for .NET-Client, indem Sie dieAWSXRayPlugins-Einstellung hinzufügen. Wenn mehrere Plugins auf Ihre Anwendung zutreffen, gebenSie alle Plugins in der gleichen Einstellung an (getrennt durch Kommata).
Example Web.config – Plugins
<configuration> <appSettings> <add key="AWSXRayPlugins" value="EC2Plugin,ElasticBeanstalkPlugin"/> </appSettings></configuration>
Example appsettings.json – Plugins
{ "XRay": { "AWSXRayPlugins": "EC2Plugin,ElasticBeanstalkPlugin" }}
SamplingregelnDas SDK hat eine Sampling-Strategie, durch die bestimmt wird, welche Anfragen verfolgt werden.Standardmäßig zeichnet das SDK die erste Anfragen pro Sekunde und fünf Prozent aller weiterenAnfragen. auf. Sie können das Sampling-Verhalten des SDK durch die Anwendung von Regeln anpassen,die in einer lokalen Datei definiert sind.
Example sampling-rules.json
{ "version": 1, "rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 }}
In diesem Beispiel sind eine benutzerdefinierte Regel und eine Standardregel definiert. Diebenutzerdefinierte Regel wendet eine Abtastrate von fünf Prozent ohne minimale Anforderungsanzahlauf die Verfolgung von Pfaden unter /api/move/ an. Die Standardregel verfolgt die erste Anfragen proSekunde und 10 % aller weiteren Anfragen.
Das SDK wendet benutzerdefinierte Regeln in der Reihenfolge an, in der sie definiert sind. Wenn eineAnfrage mehreren benutzerdefinierten Regeln entspricht, wendet das SDK nur die erste Regel an.
In Lambda können Sie die Samplingrate nicht ändern. Wenn Ihre Funktion von einem instrumentiertenService aufgerufen wird, werden von Aufrufen erzeugte Anforderungen, für die von diesem Service einSampling durchgeführt wird, von Lambda aufgezeichnet. Bei aktiver Nachverfolgung ohne vorhandenenNachverfolgungs-Header trifft Lambda die Sampling-Entscheidung.
214
AWS X-Ray EntwicklerhandbuchProtokollierung (.NET)
Weisen Sie X-Ray SDK for .NET an, Samplingregeln aus einer Datei mit der EinstellungSamplingRuleManifest zu laden.
Example Web.config – Samplingregeln
<configuration> <appSettings> <add key="SamplingRuleManifest" value="sampling-rules.json"/> </appSettings></configuration>
Example appsettings.json – Sampling-Regeln
{ "XRay": { "SamplingRuleManifest": "sampling-rules.json" }}
Protokollierung (.NET)X-Ray SDK for .NET verwendet das gleiche Protokollierungsverfahren wie AWS SDK for .NET. Wenn SieIhre Anwendung bereits zur Protokollierung von AWS SDK for .NET-Ausgaben konfiguriert haben, gilt diegleiche Konfiguration für Ausgaben von X-Ray SDK for .NET.
Zum Konfigurieren von Protokollierung fügen Sie einen Konfigurationsabschnitt mit dem Namen aws IhrerApp.config-Datei oder Web.config-Datei hinzu.
Example Web.config – Protokollierung
...<configuration> <configSections> <section name="aws" type="Amazon.AWSSection, AWSSDK.Core"/> </configSections> <aws> <logging logTo="Log4Net"/> </aws></configuration>
Weitere Informationen finden Sie unter Konfigurieren Ihrer AWS SDK for .NET-Anwendung im AWS SDKfor .NET-Entwicklerhandbuch.
Protokollierung (.NET Core)Für .NET Core-Anwendungen unterstützt das X-Ray-SDK die Protokollierungsoptionen im AWS SDKfor .NET LoggingOptions-Enum. Um die Protokollierung zu konfigurieren, übergeben Sie der MethodeRegisterLogger eine dieser Optionen.
AWSXRayRecorder.RegisterLogger(LoggingOptions.Console);
Um beispielsweise log4net zu verwenden, erstellen Sie eine Konfigurationsdatei, die den Logger, dasAusgabeformat und den Speicherort der Datei definiert.
Example log4net.config
<?xml version="1.0" encoding="utf-8" ?>
215
AWS X-Ray EntwicklerhandbuchUmgebungsvariablen
<log4net> <appender name="FileAppender" type="log4net.Appender.FileAppender,log4net"> <file value="c:\logs\sdk-log.txt" /> <layout type="log4net.Layout.PatternLayout"> <conversionPattern value="%date [%thread] %level %logger - %message%newline" /> </layout> </appender> <logger name="Amazon"> <level value="DEBUG" /> <appender-ref ref="FileAppender" /> </logger></log4net>
Erstellen Sie dann den Logger und übernehmen Sie die Konfiguration in Ihren Programmcode.
Example Program.cs – Protokollierung
using log4net;using Amazon.XRay.Recorder.Core;
class Program{ private static ILog log; static Program() { var logRepository = LogManager.GetRepository(Assembly.GetEntryAssembly()); XmlConfigurator.Configure(logRepository, new FileInfo("log4net.config")); log = LogManager.GetLogger(typeof(Program)); AWSXRayRecorder.RegisterLogger(LoggingOptions.Log4Net); } static void Main(string[] args) { ... }}
Weitere Informationen zur Konfiguration von log4net finden Sie unter Konfiguration auf logging.apache.org.
UmgebungsvariablenSie können Umgebungsvariablen zum Konfigurieren von X-Ray SDK for .NET verwenden. Das SDKunterstützt die folgenden Variablen.
• AWS_XRAY_TRACING_NAME – Legen Sie einen Dienstnamen fest, der vom SDK für Segmente verwendetwird. Überschreibt den für die Segmentbenennungsstrategie (p. 218) des Servlet-Filters festgelegtenDienstnamen.
• AWS_XRAY_DAEMON_ADDRESS – Legen Sie den Host und den Port des X-Ray-Daemon-Listeners fest.Standardmäßig sendet das SDK Ablaufverfolgungsdaten an 127.0.0.1:2000. Verwenden Sie dieseVariable, wenn Sie den Daemon so konfiguriert haben, dass er einen anderen Port überwacht (p. 115),oder wenn er auf einem anderen Host ausgeführt wird.
• AWS_XRAY_CONTEXT_MISSING – Set to LOG_ERROR to avoid throwing exceptions when yourinstrumented code attempts to record data when no segment is open.
Valid Values• RUNTIME_ERROR – Throw a runtime exception (default).• LOG_ERROR – Log an error and continue.
Errors related to missing segments or subsegments can occur when you attempt to use an instrumentedclient in startup code that runs when no request is open, or in code that spawns a new thread.
216
AWS X-Ray EntwicklerhandbuchEingehende Anforderungen
Instrumentieren von eingehenden HTTP-Anforderungen mit X-Ray SDK for .NET
Sie können mit dem X-Ray SDK eingehende HTTP-Anforderungen verfolgen, die Ihre Anwendung auf einerEC2 Instance in Amazon EC2, AWS Elastic Beanstalk oder Amazon ECS verarbeitet.
Verwenden Sie einen Meldungs-Handler, um eingehende HTTP-Anforderungen zu instrumentieren. WennSie den X-Ray-Meldungshandler Ihrer Anwendung hinzufügen, erstellt X-Ray SDK for .NET ein Segmentfür jede stichprobenartig geprüfte Anforderung. Dieses Segment umfasst Dauer, Methode und Status derHTTP-Anforderung. Die zusätzliche Instrumentierung schafft Untersegmente zu diesem Segment.
Note
Lambda erstellt für AWS Lambda-Funktionen ein Segment für jede Anforderung, die per Samplingerfasst wurde. Weitere Informationen finden Sie unter AWS Lambda und AWS X-Ray (p. 229).
Each segment has a name that identifies your application in the service map. The segment can be namedstatically, or you can configure the SDK to name it dynamically based on the host header in the incomingrequest. Dynamic naming lets you group traces based on the domain name in the request, and apply adefault name if the name doesn't match an expected pattern (for example, if the host header is forged).
Weitergeleitete Anfragen
Wenn ein Load Balancer oder ein anderer Mittler eine Anforderung an Ihre Anwendungweiterleitet, übernimmt X-Ray die Client-IP aus der X-Forwarded-For-Kopfzeile der Anforderungund nicht aus der Quell-IP im IP-Paket. Die für eine weitergeleitete Anforderung aufgezeichneteClient-IP kann gefälscht sein und ist daher nicht vertrauenswürdig.
Der Meldungshandler erzeugt für jede eingehende Anforderung ein Segment mit einem http-Block, derdie folgenden Informationen enthält:
• HTTP-Methode – GET, POST, PUT, DELETE usw.• Client-Adresse – Die IP-Adresse des Clients, der die Anforderung gesendet hat.• Antwortcode – Der HTTP-Antwortcode für die abgeschlossene Anforderung.• Dauer – Die Startzeit (zu der die Anforderung empfangen wurde) und die Endzeit (zu der die Antwort
gesendet wurde).• Nutzer-Agent — Der user-agent aus der Anfrage.• Inhaltslänge — Die content-length aus der Antwort.
Abschnitte• Instrumentierung eingehender Anforderungen (.NET) (p. 217)• Instrumentierung eingehender Anforderungen (.NET Core) (p. 218)• Konfiguration einer Segmentbenennungsstrategie (p. 218)
Instrumentierung eingehender Anforderungen (.NET)Um die von Ihrer Anwendung verarbeiteten Anforderungen zu instrumentieren, rufen Sie in der MethodeInit Ihrer global.asax-Datei die Methode RegisterXRay auf.
Example global.asax – Meldungshandler
using System.Web.Http;Verwendung von Amazon.XRay.Recorder.Handlers.AspNet;
217
AWS X-Ray EntwicklerhandbuchInstrumentierung eingehender Anforderungen (.NET Core)
namespace SampleEBWebApplication{ public class MvcApplication : System.Web.HttpApplication { public override void Init() { base.Init(); AWSXRayASPNET.RegisterXRay(this, "MyApp"); } }}
Instrumentierung eingehender Anforderungen (.NETCore)Um die von Ihrer Anwendung verarbeiteten Anforderungen zu instrumentieren, rufen Sie in derMethode Configure Ihrer Startup-Klasse die Methoden UseExceptionHandler, UseXRay undUseStaticFiles auf.
Example Startup.cs
using Microsoft.AspNetCore.Builder;
public void Configure(IApplicationBuilder app, IHostingEnvironment env) { app.UseExceptionHandler("/Error"); app.UseXRay("MyApp"); app.UseStaticFiles(); app.UseMVC(); }
Rufen Sie nach UseExceptionHandler immer UseXRay auf, um Ausnahmen aufzuzeichnen. Wenn Sieeine andere Middleware verwenden, aktivieren Sie diese nach dem Aufruf von UseXRay.
Die UseXRay-Methode kann außerdem ein Konfigurationsobjekt (p. 212) als zweites Argumententgegennehmen.
app.UseXRay("MyApp", configuration);
Konfiguration einer SegmentbenennungsstrategieAWS X-Ray verwendet einen Servicenamen, um Ihre Anwendung zu identifizieren und sie von anderenAnwendungen, Datenbanken, externen APIs und AWS-Ressourcen zu unterscheiden, die Ihre Anwendungnutzt. Wenn das X-Ray SDK Segmente für eingehende Anfragen generiert, zeichnet es den ServicenamenIhrer Anwendung im Feld name field (p. 73) auf.
Das X-Ray SDK kann Segmente nachdem Hostnamen im HTTP-Anfrageheader benennen. Dieser Headerkann jedoch gefälscht sein, was zu unerwarteten Knoten in Ihrer Service-Übersicht führen könnte. Und zuverhindern, dass das SDK Segmente aufgrund von Anforderungen mit gefälschten Host-Headern falschbenennt, müssen Sie einen standardmäßigen Namen für eingehende Anfragen angeben.
Wenn Ihre Anwendung Anfragen für mehrere Domänen bedient, können Sie das SDK so konfigurieren,dass es eine dynamische Benennungsstrategie verwendet, um dies in den Segmentnamen zuberücksichtigen. Eine dynamische Benennungsstrategie erlaubt es dem SDK, den Host-Namen beiAnfragen zu verwenden, die einem erwarteten Muster entsprechen, und den standardmäßigen Namen fürsolche zu vergeben, die es nicht tun.
218
AWS X-Ray EntwicklerhandbuchAWS SDK-Clients
Beispielsweise haben Sie vielleicht eine einzelne Anwendung, die Anfragen für drei Subdomänen bedient,– www.example.com, api.example.com und static.example.com. Sie können eine dynamischeBenennungsstrategie mit dem Muster *.example.com verwenden, um Segmente für die einzelnenSubdomänen unterschiedlich zu benennen. Auf der Service-Übersicht werden dann drei Service-Knotenangezeigt. Wenn Ihre Anwendung Anfragen mit einem Hostnamen erhält, der diesem Muster nichtentspricht, sehen Sie auf der Service-Übersicht einen vierten Knoten mit einem von Ihnen festgelegtenAusweichnamen.
Wenn Sie denselben Namen für alle Segmente verwenden möchten, geben Sie bei der Initialisierung desMessage-Handlers den Namen Ihrer Anwendung, wie im vorherigen Abschnitt (p. 217) gezeigt, ein. Dieshat den gleichen Effekt wie das Anlegen eines FixedSegmentNamingStrategy und das Übergeben andie RegisterXRay-Methode.
AWSXRayASPNET.RegisterXRay(this, new FixedSegmentNamingStrategy("MyApp"));
Note
Sie können den mit der AWS_XRAY_TRACING_NAME-Umgebungsvariablen (p. 216) in Codedefinierten standardmäßigen Dienstnamen überschreiben.
Eine dynamische Benennungsstrategie definiert ein Muster, dem Hostnamen entsprechen sollten,sowie einen Standardnamen, der verwendet wird, wenn der Hostname in der HTTP-Anforderungnicht mit diesem Muster übereinstimmt. Zur dynamischen Segmentbenennung erstellen Sie eineDynamicSegmentNamingStrategy und übergeben diese an die RegisterXRay-Methode.
AWSXRayASPNET.RegisterXRay(this, new DynamicSegmentNamingStrategy("MyApp", "*.example.com"));
Instrumentieren von nachgelagerten Aufrufen derAWS-Services
Sie können Ihre gesamten AWS SDK for .NET-Clients instrumentieren, indem Sie sieRegisterXRayForAllServices vor deren Erstellung aufrufen.
Example SampleController.cs – DynamoDB-Clientinstrumentierung
using Amazon;using Amazon.Util;using Amazon.DynamoDBv2;using Amazon.DynamoDBv2.DocumentModel;using Amazon.XRay.Recorder.Core;using Amazon.XRay.Recorder.Handlers.AwsSdk;
namespace SampleEBWebApplication.Controllers{ public class SampleController : ApiController { AWSSDKHandler.RegisterXRayForAllServices(); private static readonly Lazy<AmazonDynamoDBClient> LazyDdbClient = new Lazy<AmazonDynamoDBClient>(() => { var client = new AmazonDynamoDBClient(EC2InstanceMetadata.Region ?? RegionEndpoint.USEast1); return client; });
219
AWS X-Ray EntwicklerhandbuchAusgehende HTTP-Aufrufe
Um Clients nur für einige Services zu instrumentieren, rufen Sie RegisterXRay stattRegisterXRayForAllServices auf. Ersetzen Sie den markierten Text durch den Namen der Client-Schnittstelle des Services.
AWSSDKHandler.RegisterXRay<IAmazonDynamoDB>()
Bei allen Services wird der Name der aufgerufenen API in der X-Ray-Konsole angezeigt. Bei einerUntergruppe von Services fügt das X-Ray SDK Informationen zum Segment hinzu, um mehr Granularität inder Service-Übersicht zu erreichen.
Wenn Sie beispielsweise einen Aufruf mit einem instrumentierten DynamoDB-Client erstellen, fügt dasSDK für Aufrufe, die auf eine Tabelle abzielen, den Tabellennamen zu dem Segment hinzu. In der Konsolewerden die Tabellen als einzelne Knoten in der Service-Übersicht angezeigt, zusammen mit einemgenerischen DynamoDB-Knoten für Aufrufe, die nicht auf eine Tabelle abzielen.
Example Untersegment für einen Aufruf von DynamoDB zum Speichern eines Elements
{ "id": "24756640c0d0978a", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "DynamoDB", "namespace": "aws", "http": { "response": { "content_length": 60, "status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG", }}
Wenn Sie auf benannte Ressourcen zugreifen, werden durch Aufrufe der folgenden Services weitereKnoten in der Service-Übersicht erstellt. Durch Aufrufe, die keinen bestimmten Ressourcen gelten, wird eingenerischer Knoten für den Service erstellt.
• Amazon DynamoDB – Tabellenname• Amazon Simple Storage Service – Bucket und Schlüsselname• Amazon Simple Queue Service – Warteschlangenname
Nachverfolgen von Aufrufen nachgelagerter HTTP-Web-Services mit dem X-Ray SDK for .NET
Wenn Ihre Anwendung Microservices oder öffentliche HTTP-APIs aufruft, können Sie dieseAufrufe mit der GetResponseTraced-Erweiterungsmethode des X-Ray SDK for .NET fürSystem.Net.HttpWebRequest instrumentieren und die API der Service-Grafik als nachgelagertenService hinzufügen.
Example HttpWebRequest
using System.Net;
220
AWS X-Ray EntwicklerhandbuchAusgehende HTTP-Aufrufe
using Amazon.XRay.Recorder.Core;using Amazon.XRay.Recorder.Handlers.System.Net;
private void MakeHttpRequest(){ HttpWebRequest request = (HttpWebRequest)WebRequest.Create("http://names.example.com/api"); request.GetResponseTraced();}
Für asynchrone Aufrufe verwenden Sie GetAsyncResponseTraced.
request.GetAsyncResponseTraced();
Zeichnen Sie bei der Verwendung von system.net.http.httpclient Aufrufe mit dem delegierendenHttpClientXRayTracingHandler-Handler auf.
Example HttpClient
using System.Net.Http;using Amazon.XRay.Recorder.Core;using Amazon.XRay.Recorder.Handlers.System.Net;
private void MakeHttpRequest(){ var httpClient = new HttpClient(new HttpClientXRayTracingHandler(new HttpClientHandler())); httpClient.GetAsync(URL);}
Wenn Sie einen Aufruf einer nachgelagerten Web-API instrumentieren, erfasst das X-Ray SDK for .NETein Untersegment mit Informationen über die HTTP-Anforderung und Antwort. X-Ray verwendet dasUntersegment, um ein abgeleitetes Segment für die API zu generieren.
Example Untersegment für einen nachgelagerten HTTP-Aufruf
{ "id": "004f72be19cddc2a", "start_time": 1484786387.131, "end_time": 1484786387.501, "name": "names.example.com", "namespace": "remote", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } }}
Example Abgeleitetes Segment für einen nachgelagerten HTTP-Anruf
{ "id": "168416dc2ea97781", "name": "names.example.com",
221
AWS X-Ray EntwicklerhandbuchSQL-Abfragen
"trace_id": "1-5880168b-fd5153bb58284b67678aa78c", "start_time": 1484786387.131, "end_time": 1484786387.501, "parent_id": "004f72be19cddc2a", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } }, "inferred": true}
Ablaufverfolgung von SQL-Abfragen mit X-Ray SDKfor .NET
Das SDK bietet eine Wrapper-Klasse für System.Data.SqlClient.SqlCommand mit dem NamenTraceableSqlCommand, die Sie anstelle von SqlCommand verwenden können. Initialisieren Sie einenSQL-Befehl mit der TraceableSqlCommand-Klasse des X-Ray SDK for .NET.
Example Controller.cs – SQL-Client-Instrumentierung
using Amazon;using Amazon.Util;using Amazon.XRay.Recorder.Core;using Amazon.XRay.Recorder.Handlers.SqlServer;
private void QuerySql(int id){ var connectionString = ConfigurationManager.AppSettings["RDS_CONNECTION_STRING"]; using (var sqlConnection = new SqlConnection(connectionString)) using (var sqlCommand = new TraceableSqlCommand("SELECT " + id, sqlConnection)) { sqlCommand.Connection.Open(); sqlCommand.ExecuteNonQuery(); }}
Mit der ExecuteReaderAsync-Methode können Sie die Abfrage auch asynchron ausführen.
Example Controller.cs – SQL-Client-Instrumentierung (asynchron)
using Amazon;using Amazon.Util;using Amazon.XRay.Recorder.Core;using Amazon.XRay.Recorder.Handlers.SqlServer;private void QuerySql(int id){ var connectionString = ConfigurationManager.AppSettings["RDS_CONNECTION_STRING"]; using (var sqlConnection = new SqlConnection(connectionString)) using (var sqlCommand = new TraceableSqlCommand("SELECT " + id, sqlConnection)) { await sqlCommand.ExecuteReaderAsync(); }
222
AWS X-Ray EntwicklerhandbuchBenutzerdefinierte Untersegmente
}
Erstellen zusätzlicher UntersegmenteUntersegmente erweitern das Segment (p. 20) eines Traces um Details zu erledigten Aufgaben, umAnforderungen zu senden. Jedesmal, wenn Sie einen Aufruf mit einem instrumentierten Client erstellen,erfasst das X-Ray SDK die in einem Untersegment erzeugten Informationen. Sie können zusätzlicheUntersegmente erstellten, um andere Untersegmente zu gruppieren, die Leistung eines Codeabschnitts zumessen oder Anmerkungen und Metadaten aufzuzeichnen.
Um Untersegmente zu verwalten, verwenden Sie die Methoden BeginSubsegment und EndSubsegment.Führen Sie die gewünschte Bearbeitung im Untersegment in einem try-Block aus und verwenden SieAddException, um Ausnahmen zu verfolgen. Rufen Sie EndSubsegment in einem finally-Block auf,um sicherzustellen, dass das Untersegment geschlossen ist.
Example Controller.cs – Benutzerdefiniertes Untersegment
AWSXRayRecorder.Instance.BeginSubsegment("custom method");try{ DoWork();}catch (Exception e){ AWSXRayRecorder.Instance.AddException(e);}finally{ AWSXRayRecorder.Instance.EndSubsegment();}
Beim Erstellen eines Untersegments innerhalb eines Segments oder eines anderen Untersegmentsgeneriert das X-Ray SDK for .NET eine ID dafür und erfasst die Start- und Endzeit.
Example Untersegment mit Metadaten
"subsegments": [{ "id": "6f1605cd8a07cb70", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "Custom subsegment for UserModel.saveUser function", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } },
Hinzufügen von Anmerkungen und Metadaten zuSegmenten mit dem X-Ray SDK for .NET
Mithilfe von Anmerkungen und Metadaten können Sie zusätzliche Informationen zu Anforderungen, derUmgebung oder Ihrer Anwendung aufzeichnen. Sie können den vom X-Ray SDK erstellten Segmentenoder den von Ihnen erstellten benutzerdefinierten Untersegmenten Anmerkungen und Metadatenhinzufügen.
223
AWS X-Ray EntwicklerhandbuchAufzeichnen von Anmerkungenmit dem X-Ray SDK for .NET
Annotations are key-value pairs with string, number, or Boolean values. Annotations are indexed for usewith filter expressions (p. 39). Use annotations to record data that you want to use to group traces in theconsole, or when calling the GetTraceSummaries API.
Metadata are key-value pairs that can have values of any type, including objects and lists, but are notindexed for use with filter expressions. Use metadata to record additional data that you want stored in thetrace but don't need to use with search.
Abschnitte• Aufzeichnen von Anmerkungen mit dem X-Ray SDK for .NET (p. 224)• Aufzeichnen von Metadaten mit dem X-Ray SDK for .NET (p. 224)
Aufzeichnen von Anmerkungen mit dem X-Ray SDKfor .NETVerwenden Sie Anmerkungen, um Informationen zu Segmenten oder Untersegmenten, die zur Sucheindiziert werden sollten, aufzuzeichnen.
Anmerkung zu Anforderungen
• Schlüssel – Bis zu 500 alphanumerische Zeichen. Keine Leerzeichen oder Symbole außer Unterstrichen.• Werte – bis zu 1,000 Unicode-Zeichen.• Einträge – Bis zu 50 Anmerkungen pro Ablaufverfolgung.
So zeichnen Sie Anmerkungen auf
1. Rufen Sie eine Instance von AWSXRayRecorder ab.
using Amazon.XRay.Recorder.Core;...AWSXRayRecorder recorder = AWSXRayRecorder.Instance;
2. Rufen Sie addAnnotation mit einem Zeichenfolgenschlüssel und einem booleschen, Int32-, Int64-,Double- oder Zeichenfolgenwert auf.
recorder.AddAnnotation("mykey", "my value");
Das SDK zeichnet Anmerkungen als Schlüssel-Wert-Paare in einem annotations-Objekt imSegmentdokument auf. Wenn addAnnotation zweimal mit demselben Schlüssel aufgerufen wird, werdenzuvor aufgezeichnete Werte im gleichen Segment oder Untersegment überschrieben.
Nutzen Sie das annotations.key-Schlüsselwort in einem Filterausdruck (p. 39), um Ablaufverfolgungendurch Anmerkungen mit bestimmten Werten zu finden.
Aufzeichnen von Metadaten mit dem X-Ray SDKfor .NETVerwenden Sie Metadaten, um Segment- oder Untersegmentinformationen aufzuzeichnen, die nicht zurSuche indiziert werden müssen. Metadatenwerte sind Zeichenfolgen, Zahlen, boolesche Werte oder andereObjekte, die in Form eines JSON-Objekts oder eines Arrays angeordnet sein können.
224
AWS X-Ray EntwicklerhandbuchAufzeichnen von Metadaten mit dem X-Ray SDK for .NET
So zeichnen Sie Metadaten auf
1. Rufen Sie eine Instance von AWSXRayRecorder ab.
using Amazon.XRay.Recorder.Core;...AWSXRayRecorder recorder = AWSXRayRecorder.Instance;
2. Rufen Sie AddMetadata mit einem Zeichenfolgen-Namespace, einem Zeichenfolgenschlüssel undeinem Objektwert auf.
segment.AddMetadata("my namespace", "my key", "my value");
oder
Rufen Sie putMetadata nur mit einem Aktivierungsschlüssel und einem Wert auf.
segment.AddMetadata("my key", "my value");
Wenn Sie keinen Namespace angeben, verwendet SDK default. Wenn AddMetadata zweimal mitdemselben Schlüssel aufgerufen wird, werden zuvor aufgezeichnete Werte im gleichen Segment oderUntersegment überschrieben.
225
AWS X-Ray EntwicklerhandbuchX-Ray SDK for Java
Fehlerbehebung bei AWS X-RayIn diesem Thema werden häufige Fehler und Probleme aufgeführt, die bei der Verwendung der X-Ray-API,-Konsole oder -SDKs auftreten können. Wenn Sie auf ein Problem stoßen, das hier nicht aufgeführt ist,können Sie die Schaltfläche Feedback auf dieser Seite verwenden, um es zu melden.
Abschnitte• X-Ray SDK for Java (p. 226)• X-Ray SDK for Node.js (p. 226)• Der X-Ray-Daemon (p. 227)
X-Ray SDK for JavaFehler: Ausnahme in Thread "Thread-1" com.amazonaws.xray.exceptions.SegmentNotFoundException:Beginnen mit Untersegment "AmazonSNS" fehlgeschlagen: Segment wurde nicht gefunden.
Dieser Fehler gibt an, dass das X-Ray-SDK versucht hat, einen ausgehenden Aufruf von AWSaufzuzeichnen, jedoch kein offenes Segment finden konnte. Dies kann in folgenden Situationen auftreten:
• Ein Servlet-Filter ist nicht konfiguriert – Das X-Ray-SDK erstellt Segmente für eingehende Anfragen miteinem Filter mit dem Namen AWSXRayServletFilter. Konfigurieren Sie einen Servlet-Filter (p. 135),um eingehende Anfragen zu instrumentieren.
• Sie verwenden instrumentierte Clients außerhalb von Servlet-Code – Wenn Sie einen instrumentiertenClient für Aufrufe im Startup-Code oder einem anderen Code verwenden, der nicht als Reaktion auf eineeingehende Anfrage ausgeführt wird, müssen Sie manuell ein Segment erstellen. Weitere Informationenfinden Sie unter Instrumentieren von Startup-Code (p. 103) Beispiele.
• Sie verwenden instrumentierte Clients in Auftragnehmer-Threads – Beim Erstellen eines neuenThreads verliert der X-Ray-Recorder seine Referenz zum offenen Segment. Sie können die MethodengetTraceEntity und setTraceEntity verwenden, um eine Referenz zum aktuellen Segment oderUntersegment zu erhalten (Entity), und sie innerhalb des Threads wieder an den Recorder übergeben.Ein Beispiel finden Sie unter Verwenden instrumentierter Clients in Auftragnehmer-Threads (p. 109).
X-Ray SDK for Node.jsProblem: CLS funktioniert nicht mit Sequelize
Übermitteln Sie den X-Ray SDK for Node.js-Namespace mit der cls-Methode an Sequelize.
var AWSXRay = require('aws-xray-sdk');const Sequelize = require('sequelize');Sequelize.cls = AWSXRay.getNamespace();const sequelize = new Sequelize('database', 'username', 'password');
Problem: CLS funktioniert nicht mit Bluebird
Verwenden Sie cls-bluebird, damit Bluebird mit CLS funktioniert.
var AWSXRay = require('aws-xray-sdk');var Promise = require('bluebird');
226
AWS X-Ray EntwicklerhandbuchDer X-Ray-Daemon
var clsBluebird = require('cls-bluebird');clsBluebird(AWSXRay.getNamespace());
Der X-Ray-DaemonProblem: Der Daemon verwendet die falschen Anmeldeinformationen
Der Daemon verwendet das AWS-SDK zum Laden von Anmeldeinformationen. Wenn SieAnmeldeinformationen mit mehreren Methoden bereitstellen, wird die Methode mit der höchsten Prioritätverwendet. Weitere Informationen finden Sie unter Ausführen des Daemons (p. 113).
227
AWS X-Ray EntwicklerhandbuchElastic Load Balancing
Integration von AWS X-Ray mitanderen AWS-Services
Andere AWS-Services bieten die Integration mit AWS X-Ray durch Hinzufügen eines Ablaufverfolgungs-Headers zu Anfragen, Ausführen des X-Ray-Daemons oder Treffen von Sampling-Entscheidungen undHochladen von Ablaufverfolgungsdaten auf X-Ray.
Note
Die X-Ray SDKs umfassen Plugins für zusätzliche Integration in AWS-Services. Beispielsweisekönnen Sie mit dem X-Ray SDK für das Elastic Beanstalk-Plugin von Java Informationen über dieElastic Beanstalk-Umgebung, einschließlich des Umgebungsnamens und der ID, hinzufügen, inder Ihre Anwendung ausgeführt wird.
Themen• Elastic Load Balancing and AWS X-Ray (p. 228)• AWS Lambda und AWS X-Ray (p. 229)• Amazon API Gateway und AWS X-Ray (p. 230)• Amazon Elastic Compute Cloud und AWS X-Ray (p. 230)• AWS Elastic Beanstalk und AWS X-Ray (p. 230)
Elastic Load Balancing and AWS X-RayElastic Load Balancing Application Load Balancers fügen eingehenden HTTP-Anforderungen eineAblaufverfolgungs-ID in einer Überschrift mit dem Namen X-Amzn-Trace-Id hinzu.
X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793
Format der Ablaufverfolgungs-ID
Eine trace_id besteht aus drei durch Bindestriche getrennte Zahlen. Beispiel, 1-58406520-a006649127e371903a2de979. Dies umfasst:
• Die Versionsnummer 1.• Die Zeit der ursprünglichen Anforderung als Zeit seit Unix-Epoche und in 8 Hexadezimalziffern
ausgedrückt.
Beispiel: 10:00 Uhr 1. Dezember 2016 PST entspricht einer Epoch-Zeit von 1480615200 Sekunden oderin hexadezimalen Ziffern ausgedrückt 58406520.
• Eine 96-Bit-Kennzeichnung für die Ablaufverfolgung, global eindeutig, in 24 Hexadezimalziffern.
Load Balancer senden keine Daten an X-Ray und werden nicht als Knoten in Ihrer Service-Übersichtangezeigt.
228
AWS X-Ray EntwicklerhandbuchLambda
Weitere Informationen finden Sie unter Request Tracing for Your Application Load Balancer imEntwicklerhandbuch für Elastic Load Balancing.
AWS Lambda und AWS X-RaySie können AWS X-Ray verwenden, um Ihre AWS Lambda-Funktionen zu verfolgen. Lambda führt denX-Ray-Daemon (p. 112) aus und zeichnet ein Segment mit Details über den Aufruf und die Ausführungder Funktion auf. Zur weiteren Instrumentierung können Sie das X-Ray-SDK mit Ihrer Funktion zurAufzeichnung ausgehender Anrufe und zum Hinzufügen von Anmerkungen und Metadaten bündeln.
Wenn Ihre Lambda-Funktion von einem anderen instrumentierten Service aufgerufen wird, verfolgtLambda bereits gesampelte Anforderungen, ohne dass eine zusätzliche Konfiguration erforderlich ist. DerUpstream-Service kann eine instrumentierte Webanwendung oder eine andere Lambda-Funktion sein. IhrService kann die Funktion direkt mit einem instrumentierten AWS SDK-Client oder durch Aufrufen einer APIGateway-API mit einem instrumentierten HTTP-Client aufrufen.
Wenn Ihre Lambda-Funktion nach einem bestimmten Zeitplan ausgeführt wird von einem Serviceaufgerufen wird, der nicht instrumentiert ist, können Sie Lambda so konfigurieren, dass Sie Aufrufe mitaktiver Ablaufverfolgung abfragen und aufzeichnen können.
Konfigurieren Sie die X-Ray-Integration für eine AWS Lambda-Funktion wie folgt:
1. Öffnen Sie die AWS Lambda-Konsole.2. Wählen Sie Ihre Funktion.3. Wählen Sie Konfiguration.4. Wählen Sie unter Debugging and error handling (Debugging und Fehlerbehandlung) die Option Enable
active tracing (Aktives Tracing aktivieren) aus.
Auf Laufzeiten mit einem entsprechenden X-Ray SDK führt Lambda auch den X-Ray-Daemon aus.
X-Ray SDKs in Lambda
• X-Ray SDK für Go – Go 1.7-Laufzeitumgebung und neuer• X-Ray SDK for Java – Java 8-Laufzeitumgebung• X-Ray SDK for Node.js – Node.js 4.3-Laufzeitumgebung und neuer• X-Ray SDK für Python – Python 2.7- und Python 3.6-Laufzeitumgebung und neuer• X-Ray SDK for .NET – .NET Core 2.0-Laufzeitumgebung und neuer
Um das X-Ray-SDK unter Lambda zu verwenden, bündeln Sie es bei jeder Erstellung einer neuen Versionmit Ihrem Funktionscode. Sie können Ihre Lambda-Funktionen mit denselben Methoden instrumentieren,die Sie für die Instrumentierung von Anwendungen auf anderen Services verwenden. Der Hauptunterschiedbesteht darin, dass Sie nicht das SDK dazu verwenden, eingehende Anforderungen zu instrumentieren,Samplingentscheidungen zu treffen und Segmente zu erstellen.
Der andere Unterschied zwischen der Instrumentierung von Lambda-Funktionen und vonWebanwendungen besteht darin, dass das von Lambda erstellte und an X-Ray gesendete Segmentnicht durch Ihren Funktionscode modifiziert werden kann. Sie können Untersegmente erstellen undAnmerkungen und Metadaten aufzeichnen. Sie können dem übergeordneten Segment jedoch keineAnmerkungen und Metadaten hinzufügen.
Weitere Informationen finden Sie unter Fehlerbehebung bei Lambda-basierten Anwendungen im AWSLambda-Entwicklerhandbuch.
229
AWS X-Ray EntwicklerhandbuchAPI Gateway
Amazon API Gateway und AWS X-RayAmazon API Gateway unterstützt eine Anfragenachverfolgung (p. 6) für AWS X-Ray. Ein API Gateway-Gateway fügt einen Ablaufverfolgungs-Header (p. 26) zu eingehenden HTTP-Anfragen hinzu, sofern sienicht bereits über einen verfügen.
X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793
Format der Ablaufverfolgungs-ID
Eine trace_id besteht aus drei durch Bindestriche getrennte Zahlen. Beispiel, 1-58406520-a006649127e371903a2de979. Dies umfasst:
• Die Versionsnummer 1.• Die Zeit der ursprünglichen Anforderung als Zeit seit Unix-Epoche und in 8 Hexadezimalziffern
ausgedrückt.
Beispiel: 10:00 Uhr 1. Dezember 2016 PST entspricht einer Epoch-Zeit von 1480615200 Sekunden oderin hexadezimalen Ziffern ausgedrückt 58406520.
• Eine 96-Bit-Kennzeichnung für die Ablaufverfolgung, global eindeutig, in 24 Hexadezimalziffern.
API Gateway trifft keine Samplingentscheidungen und sendet keine Ablaufverfolgungsdaten an X-Ray.Durch Hinzufügen des Ablaufverfolgungs-Headers zeichnet es jedoch die Zeit auf, zu der die Anforderungdas Gateway erreichte. Durch Vergleichen des Zeitstempels der Ablaufverfolgung mit dem Zeitstempel aufdem Segment, das durch den instrumentierten Service hinter dem Gateway gesendet wurde, können Siesehen, wie lange die Anfrage nach dem Eintreffen am Gateway brauchte, um Ihren Service zu erreichen.
Wenn sich Ihr Gateway hinter instrumentierten Services in Ihrer Anwendung befindet, überträgt dasGateway den Ablaufverfolgungs-Header an Ihre Backend-AWS Lambda-Funktionen oder Ihren HTTP-Service. Der Upstream-Service und der Service hinter dem Gateway sind über die Ablaufverfolgungs-IDmiteinander verbunden, das Gateway selbst erscheint in Ihrer Service-Übersicht jedoch nicht als Knoten.
Wenn Sie API Gateway zum Generieren eines Java-SDK für Ihre API verwenden, können Sie den SDK-Client instrumentieren, indem Sie mit dem Client-Builder genauso einen Anforderungshandler hinzufügen,wie Sie einen AWS SDK-Client manuell instrumentieren würden. Detaillierte Anweisungen finden Sie unterVerfolgen von AWS SDK-Aufrufen mit dem X-Ray SDK for Java (p. 138).
Amazon Elastic Compute Cloud und AWS X-RaySie können den X-Ray-Daemon in einer Amazon EC2 Instance mit einem Benutzerdatenskript installierenund ausführen. Detaillierte Anweisungen finden Sie unter Ausführen des X-Ray-Daemons in AmazonEC2 (p. 123).
Verwenden Sie ein Instance-Profil, um dem Daemon die Berechtigung zum Hochladen vonAblaufverfolgungsdaten auf X-Ray zu erteilen. Weitere Informationen finden Sie unter Erteilen derBerechtigung zum Senden von Daten an X-Ray für den Daemon (p. 114).
AWS Elastic Beanstalk und AWS X-RayIn AWS Elastic Beanstalk-Plattformen ist der X-Ray-Daemon enthalten. Sie können den Daemonausführen, (p. 120) indem Sie eine Option in der Elastic Beanstalk-Konsole festlegen oder eineKonfigurationsdatei verwenden.
230
AWS X-Ray EntwicklerhandbuchElastic Beanstalk
Auf der Java SE-Plattform können Sie eine Buildfile-Datei zur Erstellung Ihrer Anwendung mit einer Maven-oder Gradle-Instance verwenden. Das X-Ray SDK for Java und AWS SDK for Java sind von Mavenverfügbar, sodass Sie nur Ihren Anwendungscode bereitstellen und die Anwendung in einer einzelnenInstanz erstellen können, damit Sie nicht alle Abhängigkeiten bündeln und hochladen müssen.
Sie können mithilfe von Elastic Beanstalk-Umgebungseigenschaften das X-Ray-SDK konfigurieren. DasVerfahren, mit dem Elastic Beanstalk Umgebungseigenschaften an Ihre Anwendung übergibt, variiert jenach Plattform. Verwenden Sie die Umgebungsvariablen des X-Ray-SDK oder Systemeigenschaften, jenach Ihrer Plattform.
• Node.js-Plattform – Verwenden Sie Umgebungsvariablen (p. 168)• Java SE-Plattform – Verwenden Sie Umgebungsvariablen (p. 134)• Tomcat-Plattform – Verwenden Sie Systemeigenschaften (p. 135)
Weitere Informationen finden Sie unter Konfigurieren der AWS X-Ray-Fehlersuche im Entwicklerhandbuchfür AWS Elastic Beanstalk.
231