AWS X-Ray SDK für Ruby

Das X-Ray SDK ist eine Bibliothek für Ruby-Webanwendungen, die Klassen und Methoden zum Generieren und Senden von Ablaufverfolgungsdaten an den X-Ray-Daemon bereitstellt. Trace-Daten enthalten Informationen über eingehende HTTP-Anfragen, die von der Anwendung bedient werden, und Aufrufe, die die Anwendung an nachgelagerte Services über das AWS SDK, HTTP-Clients oder einen aktiven Datensatzclient durchführt. Sie können Segmente auch manuell 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 install ausführen.

Beispiel Gemfile

gem 'aws-sdk'

Wenn Sie Rails verwenden, fügen Sie zunächst die X-Ray-SDK-Middleware hinzu, um eingehende Anfragen nachzuverfolgen. Ein Anforderungsfilter erstellt ein Segment. 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 Aufrufe rückzuverfolgen. Das SDK erfasst auch automatisch Ausnahmen, die Ihre Anwendung ausgibt, während das Segment geöffnet ist. Bei anderen Anwendungen als Rails können Sie Segmente manuell erstellen.

Verwenden Sie als Nächstes das X-Ray-SDK, um Ihre AWS SDK for Ruby-, HTTP- und SQL-Clients zu instrumentieren, indem Sie den Recorder so konfigurieren, dass er die zugehörigen Bibliotheken patcht. Jedes Mal, wenn Sie einen Aufruf an eine Downstream- AWS-Service oder -Ressource mit einem instrumentierten Client tätigen, zeichnet das SDK Informationen über den Aufruf in einem Untersegment auf. AWS-Services und die Ressourcen, auf die Sie innerhalb der Services zugreifen, werden als Downstream-Knoten auf der Ablaufverfolgungskarte angezeigt, um Ihnen zu helfen, Fehler und Drosselungsprobleme bei einzelnen Verbindungen zu identifizieren.

Sobald Sie die ersten Schritte mit dem SDK gemacht haben, können Sie das Verhalten durch die Konfiguration des Recorders individualisieren. Sie können Plugins zum Festhalten von Daten über die Datenverarbeitungsressourcen, auf denen Ihre Anwendung ausgeführt wird, hinzufügen, das Samplingverhalten durch Samplingregeln anpassen und einen Logger bereitstellen, 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 Anwendung ausführt, in Anmerkungen und Metadaten auf. Anmerkungen sind einfache Schlüsselwertpaare, die für die Verwendung mit Filterausdrücken indiziert werden, damit Sie nach Ablaufverfolgen mit bestimmten Daten suchen können. Metadateneinträge sind weniger einschränkend und können ganze Objekte und Arrays aufzeichnen – alle Daten, die in eine JSON zusammengefasst werden können.

Anmerkungen und Metadaten

Anmerkungen und Metadaten sind beliebiger Text, den Sie Segmenten mit dem X-Ray-SDK hinzufügen. Anmerkungen werden für die Verwendung mit Filterausdrücken indiziert. Metadaten werden nicht indiziert, können aber im Rohsegment mit der X-Ray-Konsole oder API angezeigt werden. Jeder, dem Sie Lesezugriff auf X-Ray gewähren, kann diese Daten anzeigen.

Wenn Sie viele instrumentierten Clients in Ihrem Code haben, kann ein einzelnes Anforderungssegmente viele Untersegmente enthalten, eines für jeden Aufruf mit einem instrumentierten Client. Sie können Untersegmente organisieren und gruppieren, indem Sie Client-Aufrufe in benutzerdefinierten Untersegmenten zusammenfassen. Sie können ein benutzerdefiniertes Untersegment für eine ganze Funktion oder eine Code-Abschnitt erstellen und Metadaten und Anmerkungen im Untersegment festhalten, anstatt alles im übergeordneten Segment aufzuzeichnen.

Referenzdokumentation zu den Klassen und Methoden des SDK finden Sie in der AWS X-Ray API-Referenz zum SDK für Ruby.

Voraussetzungen

Das X-Ray-SDK erfordert Ruby 2.3 oder höher und ist mit den folgenden Bibliotheken kompatibel:

• AWS SDK for Ruby Version 3.0 oder höher

• Rails Version 5.1 oder höher