Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # AWS X-Ray SDK for Ruby **Anmerkung** SDK/Daemon X-Ray-Wartungshinweis — Am 25. Februar 2026 wechselt das AWS X-Ray SDKs/Daemon in den Wartungsmodus, in dem die Versionen von X-Ray SDK und Daemon auf Sicherheitsprobleme beschränkt AWS werden. Weitere Informationen zum Zeitplan für den Support finden Sie unter. [Zeitplan für die Support von X-Ray SDK und Daemon](xray-sdk-daemon-timeline.md) Wir empfehlen die Migration zu OpenTelemetry. Weitere Informationen zur Migration zu OpenTelemetry finden Sie unter [Migration von X-Ray-Instrumentierung zu OpenTelemetry Instrumentierung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Das X-Ray SDK ist eine Bibliothek für Ruby-Webanwendungen, die Klassen und Methoden zum Generieren und Senden von Trace-Daten an den X-Ray-Daemon bereitstellt. Zu den Trace-Daten gehören Informationen über eingehende HTTP-Anfragen, die von der Anwendung bedient werden, sowie über Aufrufe, die die Anwendung mithilfe des AWS SDK, HTTP-Clients oder eines Active-Record-Clients an nachgeschaltete Dienste sendet. 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. **Example Gemfile** ``` gem 'aws-sdk' ``` Wenn Sie Rails verwenden, fügen Sie zunächst [die X-Ray SDK-Middleware hinzu](xray-sdk-ruby-middleware.md), um eingehende Anfragen zu verfolgen. Ein Anforderungsfilter erstellt ein [Segment](xray-concepts.md#xray-concepts-segments). 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](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-manual). Verwenden Sie als Nächstes das X-Ray-SDK AWS SDK für Ruby, um Ihre HTTP- und SQL-Clients zu instrumentieren, indem [Sie den Rekorder so konfigurieren](xray-sdk-ruby-patching.md), dass er die zugehörigen Bibliotheken patcht. Immer wenn Sie mit einem instrumentierten Client einen Downstream AWS-Service oder eine Ressource aufrufen, zeichnet das SDK Informationen über den Aufruf in einem Untersegment auf. AWS-Services und die Ressourcen, auf die Sie innerhalb der Services zugreifen, werden in der Trace-Map als Downstream-Knoten angezeigt, sodass Sie Fehler und Drosselungsprobleme bei einzelnen Verbindungen leichter identifizieren können. Sobald Sie die ersten Schritte mit dem SDK gemacht haben, können Sie das Verhalten durch die [Konfiguration des Recorders](xray-sdk-ruby-configuration.md) 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](xray-sdk-ruby-segment.md) auf. Anmerkungen sind einfache Schlüsselwertpaare, die für die Verwendung mit [Filterausdrücken](xray-console-filters.md) 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 indexiert. Metadaten werden nicht indexiert, 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 einsehen. 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](xray-sdk-ruby-subsegments.md) 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. Eine Referenzdokumentation zu den Klassen und Methoden des SDK finden Sie in der [API-Referenz zum AWS X-Ray SDK for Ruby](https://docs.aws.amazon.com/xray-sdk-for-ruby/latest/reference). ## Voraussetzungen Das X-Ray SDK benötigt Ruby 2.3 oder höher und ist mit den folgenden Bibliotheken kompatibel: + AWS SDK für Ruby Version 3.0 oder höher + Rails Version 5.1 oder höher # Konfiguration des X-Ray-SDK SDK for Ruby **Anmerkung** SDK/Daemon X-Ray-Wartungshinweis — Am 25. Februar 2026 wechselt das AWS X-Ray SDKs/Daemon in den Wartungsmodus, in dem die Versionen von X-Ray SDK und Daemon auf Sicherheitsprobleme beschränkt AWS werden. Weitere Informationen zum Zeitplan für den Support finden Sie unter. [Zeitplan für die Support von X-Ray SDK und Daemon](xray-sdk-daemon-timeline.md) Wir empfehlen die Migration zu OpenTelemetry. Weitere Informationen zur Migration zu OpenTelemetry finden Sie unter [Migration von X-Ray-Instrumentierung zu OpenTelemetry Instrumentierung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Das X-Ray-SDK SDK for Ruby hat eine Klasse namens`XRay.recorder`, die den globalen Rekorder bereitstellt. Sie können die globale Aufzeichnung so konfigurieren, dass die Middleware, die Segmente für eingehende HTTP-Aufrufe erstellt, angepasst wird. **Topics** + [Service-Plugins](#xray-sdk-ruby-configuration-plugins) + [Regeln für die Probenahme](#xray-sdk-ruby-configuration-sampling) + [Protokollierung](#xray-sdk-ruby-configuration-logging) + [Konfiguration des Recorders im Code](#xray-sdk-ruby-configuration-code) + [Konfigurieren des Recorders mit Rails](#xray-sdk-ruby-middleware-configuration-rails) + [Umgebungsvariablen](#xray-sdk-ruby-configuration-envvars) ## Service-Plugins Wird verwendet`plugins`, um Informationen über den Dienst aufzuzeichnen, der Ihre Anwendung hostet. **Plugins** + Amazon EC2 — `ec2` fügt die Instance-ID und die 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. ![\[Segment - Scorekeep overview showing Elastic Beanstalk and EC2 deployment details.\]](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-python09.png) 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](#xray-sdk-ruby-configuration-envvars), die Vorrang über Werte im Code haben, zur Konfiguration des Recorders verwenden. Das SDK verwendet auch Plugin-Einstellungen, um das `origin` Feld im Segment festzulegen. Dies gibt den AWS Ressourcentyp an, auf dem Ihre Anwendung ausgeführt wird. Wenn Sie mehrere Plugins verwenden, verwendet das SDK die folgende Auflösungsreihenfolge, um den Ursprung zu bestimmen: ElasticBeanstalk > EKS > ECS > EC2. ## Regeln für die Probenahme Das SDK verwendet die Sampling-Regeln, die Sie in der X-Ray-Konsole definieren, um zu bestimmen, welche Anfragen aufgezeichnet werden sollen. Die Standardregel verfolgt die erste Anfrage jede Sekunde und fünf Prozent aller weiteren Anfragen aller Dienste, die Traces an X-Ray senden. [Erstellen Sie zusätzliche Regeln in der X-Ray-Konsole](xray-console-sampling.md), um die Menge der aufgezeichneten Daten für jede Ihrer Anwendungen anzupassen. Das SDK wendet benutzerdefinierte Regeln in der Reihenfolge an, in der sie definiert sind. Wenn eine Anfrage mehreren benutzerdefinierten Regeln entspricht, wendet das SDK nur die erste Regel an. **Anmerkung** Wenn das SDK X-Ray nicht erreichen kann, um Sampling-Regeln abzurufen, kehrt es zu einer lokalen Standardregel zurück, die die erste Anfrage pro Sekunde und fünf Prozent aller zusätzlichen Anfragen pro Host vorsieht. Dies kann passieren, wenn der Host nicht berechtigt ist APIs, Sampling aufzurufen, oder wenn er keine Verbindung zum X-Ray-Daemon herstellen kann, der als TCP-Proxy für API-Aufrufe durch das SDK fungiert. Sie können das SDK auch so konfigurieren, dass Sampling-Regeln aus einem JSON-Dokument geladen werden. Das SDK kann lokale Regeln als Backup für Fälle verwenden, in denen X-Ray Sampling nicht verfügbar ist, oder ausschließlich lokale Regeln verwenden. **Example sampling-rules.json** ``` { "version": 2, "rules": [ { "description": "Player moves.", "host": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 } } ``` In diesem Beispiel werden eine benutzerdefinierte Regel und eine Standardregel definiert. Die benutzerdefinierte Regel wendet eine Stichprobenrate von fünf Prozent an, ohne dass eine Mindestanzahl von Anfragen für Pfade verfolgt werden muss. `/api/move/` Die Standardregel verfolgt die erste Anfrage jede Sekunde und 10 Prozent der weiteren Anfragen. Der Nachteil der lokalen Definition von Regeln besteht darin, dass das feste Ziel von jeder Instanz des Rekorders unabhängig angewendet wird, anstatt vom X-Ray-Dienst verwaltet zu werden. Wenn Sie mehr Hosts bereitstellen, wird die feste Rate vervielfacht, wodurch es schwieriger wird, die Menge der aufgezeichneten Daten zu kontrollieren. Um Sicherungsregeln zu konfigurieren, definieren Sie einen Hash für das Dokument im Konfigurationsobjekt, das Sie dem Recorder übergeben. **Example main.rb — Konfiguration der Backup-Regeln** ``` require 'aws-xray-sdk' 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 separaten Datei 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 — Sampling-Regel 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) ``` Um nur lokale Regeln zu verwenden, fordern Sie die Samplingregeln an und konfigurieren den `LocalSampler`. **Example main.rb — Sampling mit lokalen Regeln** ``` require 'aws-xray-sdk' require 'aws-xray-sdk/sampling/local/sampler' config = { sampler: LocalSampler.new, name: 'my app', } XRay.recorder.configure(config) ``` Sie können auch die globale Aufzeichnung so konfigurieren, dass das Sampling deaktiviert und alle eingehenden Anfragen instrumentiert werden. **Example main.rb — Deaktiviert das Sampling** ``` require 'aws-xray-sdk' config = { sampling: false, name: 'my app', } XRay.recorder.configure(config) ``` ## Protokollierung Standardmäßig gibt der Recorder Ereignisse auf Informationsebene in `$stdout` aus. Sie können die Protokollierung anpassen, indem Sie einen [Logger](https://ruby-doc.org/stdlib-2.4.2/libdoc/logger/rdoc/Logger.html) in dem Konfigurationsobjekt definieren, das Sie dem Recorder übergeben. **Example main.rb — Protokollierung** ``` require 'aws-xray-sdk' 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](xray-sdk-ruby-subsegments.md). ## Konfiguration des Recorders im Code Zusätzliche Einstellungen finden Sie in der `configure`-Methode auf `XRay.recorder`. + `context_missing`— Auf einstellen, um `LOG_ERROR` zu verhindern, dass Ausnahmen ausgelöst werden, wenn Ihr instrumentierter Code versucht, Daten aufzuzeichnen, wenn kein Segment geöffnet ist. + `daemon_address`— Legt den Host und den Port des X-Ray-Daemon-Listeners fest. + `name`— Legen Sie einen Dienstnamen fest, den das SDK für Segmente verwendet. + `naming_pattern`— Legen Sie ein Domainnamenmuster fest, um [dynamische Benennung](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming) zu verwenden. + `plugins`— Erfassen Sie Informationen über die AWS Ressourcen Ihrer Anwendung mit [Plugins](#xray-sdk-ruby-configuration-plugins). + `sampling`— Auf einstellen, `false` um das Sampling zu deaktivieren. + `sampling_rules`— Legen Sie den Hash fest, der Ihre [Sampling-Regeln](#xray-sdk-ruby-configuration-sampling) enthält. **Example main.rb — Deaktiviert im Kontext fehlende Ausnahmen** ``` require 'aws-xray-sdk' config = { context_missing: 'LOG_ERROR' } XRay.recorder.configure(config) ``` ## Konfigurieren des Recorders mit Rails Wenn Sie das Rails-Framework verwenden, können Sie die Optionen für den globalen Recorder in einer Ruby-Datei unter `app_root/initializers` konfigurieren. Das X-Ray SDK unterstützt einen zusätzlichen Konfigurationsschlüssel für die Verwendung mit Rails. + `active_record`— Auf einstellen, `true` um Untersegmente für Active Record-Datenbanktransaktionen aufzuzeichnen. Konfigurieren Sie die verfügbaren Einstellungen in einem Konfigurationsobjekt mit dem Namen `Rails.application.config.xray`. **Example config/initializers/aws\$1xray.rb** ``` Rails.application.config.xray = { name: 'my app', patch: %I[net_http aws_sdk], active_record: true } ``` ## Umgebungsvariablen Sie können Umgebungsvariablen verwenden, um das X-Ray SDK for Ruby zu konfigurieren. Das SDK unterstützt die folgenden Variablen: + `AWS_XRAY_TRACING_NAME`— Legen Sie einen Dienstnamen fest, den das SDK für Segmente verwendet. Überschreibt den für die [Segmentbenennungsstrategie](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming) des Servlet-Filters festgelegten Dienstnamen. + `AWS_XRAY_DAEMON_ADDRESS`— Legt den Host und den Port des X-Ray-Daemon-Listeners fest. Standardmäßig sendet das SDK Trace-Daten an. `127.0.0.1:2000` Verwenden Sie diese Variable, wenn Sie den Daemon so konfiguriert haben, dass er [auf einem anderen Port lauscht](xray-daemon-configuration.md), oder wenn er auf einem anderen Host läuft. + `AWS_XRAY_CONTEXT_MISSING`— Legt fest, `RUNTIME_ERROR` dass Ausnahmen ausgelöst werden, wenn Ihr instrumentierter Code versucht, Daten aufzuzeichnen, obwohl kein Segment geöffnet ist. **Zulässige Werte** + `RUNTIME_ERROR`— Löst eine Laufzeitausnahme aus. + `LOG_ERROR`— Fehler protokollieren und fortfahren (Standard). + `IGNORE_ERROR`— Fehler ignorieren und fortfahren. Fehler im Zusammenhang mit fehlenden Segmenten oder Untersegmenten können auftreten, wenn Sie versuchen, einen instrumentierten Client in Startcode zu verwenden, der ausgeführt wird, wenn keine Anfrage geöffnet ist, oder in Code, der einen neuen Thread erzeugt. Umgebungsvariablen überschreiben Werte im Code. # Nachverfolgung eingehender Anfragen mit dem X-Ray-SDK SDK for Ruby Ruby-Middleware **Anmerkung** SDK/Daemon X-Ray-Wartungshinweis — Am 25. Februar 2026 wechselt das AWS X-Ray SDKs/Daemon in den Wartungsmodus, in dem die Versionen von X-Ray SDK und Daemon auf Sicherheitsprobleme beschränkt AWS werden. Weitere Informationen zum Zeitplan für den Support finden Sie unter. [Zeitplan für die Support von X-Ray SDK und Daemon](xray-sdk-daemon-timeline.md) Wir empfehlen die Migration zu OpenTelemetry. Weitere Informationen zur Migration zu OpenTelemetry finden Sie unter [Migration von X-Ray-Instrumentierung zu OpenTelemetry Instrumentierung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Sie können das X-Ray SDK verwenden, um eingehende HTTP-Anfragen zu verfolgen, die Ihre Anwendung auf einer EC2-Instance in Amazon EC2 oder Amazon ECS bearbeitet. AWS Elastic Beanstalk Wenn Sie Rails einsetzen, verwenden Sie die Rails-Middleware, um eingehenden HTTP-Anforderungen zu instrumentieren. Wenn Sie die Middleware zu Ihrer Anwendung hinzufügen und einen Segmentnamen konfigurieren, erstellt das X-Ray SDK for Ruby für jede gesampelte Anfrage ein Segment. Alle durch eine zusätzliche Instrumentierung erstellten Segmente werden zu Untersegmenten des Segments auf Anfrageebene, das Informationen über die HTTP-Anforderung und Antwort bereitstellt. Diese Informationen umfassen Dauer, Methode und Status der Anfrage. Jedes Segment hat einen Namen, der Ihre Anwendung in der Service Map identifiziert. Das Segment kann statisch benannt werden, oder Sie können das SDK so konfigurieren, dass es dynamisch auf der Grundlage des Host-Headers in der eingehenden Anfrage benannt wird. Mit der dynamischen Benennung können Sie Traces auf der Grundlage des Domainnamens in der Anfrage gruppieren und einen Standardnamen anwenden, wenn der Name nicht einem erwarteten Muster entspricht (z. B. wenn der Host-Header gefälscht ist). **Weitergeleitete Anfragen** Wenn ein Load Balancer oder ein anderer Vermittler eine Anfrage an Ihre Anwendung weiterleitet, nimmt X-Ray die Client-IP aus dem `X-Forwarded-For` Header in der Anfrage und nicht aus der Quell-IP im IP-Paket. Die Client-IP, die für eine weitergeleitete Anfrage aufgezeichnet wird, kann gefälscht sein und sollte daher nicht als vertrauenswürdig eingestuft werden. Wenn eine Anfrage weitergeleitet wird, legt das SDK ein zusätzliches Feld im Segment fest, um dies anzuzeigen. Wenn das Segment das Feld enthält, das auf `x_forwarded_for` gesetzt ist`true`, wurde die Client-IP aus dem `X-Forwarded-For` Header in der HTTP-Anfrage übernommen. Die Middleware erzeugt für jede eingehende Anfrage ein Segment mit einem `http`-Block mit folgenden Informationen: + **HTTP-Methode** — GET, POST, PUT, DELETE usw. + **Client-Adresse** — Die IP-Adresse des Clients, der die Anfrage gesendet hat. + **Antwortcode** — Der HTTP-Antwortcode für die abgeschlossene Anfrage. + **Timing** — Die Startzeit (als die Anfrage empfangen wurde) und die Endzeit (als die Antwort gesendet wurde). + **Benutzeragent** — Der `user-agent` aus der Anfrage. + **Länge des Inhalts** — Die Länge `content-length` der Antwort. ## Verwenden der Rails-Middleware Um die Middleware zu verwenden, aktualisieren Sie Ihre Gemfile-Datei, sodass sie das geforderte [railtie](http://api.rubyonrails.org/classes/Rails/Railtie.html) enthält. **Example Gemfile – Rails** ``` gem 'aws-xray-sdk', require: ['aws-xray-sdk/facets/rails/railtie'] ``` Um die Middleware verwenden zu können, müssen Sie [den Rekorder außerdem mit einem Namen konfigurieren](xray-sdk-ruby-configuration.md#xray-sdk-ruby-middleware-configuration-rails), der der Anwendung in der Trace-Map entspricht. **Example config/initializers/aws\$1xray.rb** ``` Rails.application.config.xray = { name: 'my app' } ``` ## Code manuell instrumentieren Wenn Sie Rails nicht verwenden, erstellen Sie Segmente manuell. Sie können für jede eingehende Anfrage ein Segment erstellen oder Segmente rund um gepatchte HTTP- oder AWS SDK-Clients erstellen, um dem Rekorder Kontext zum Hinzufügen von Untersegmenten zu bieten. ``` # Start a segment segment = XRay.recorder.begin_segment 'my_service' # Start a subsegment subsegment = XRay.recorder.begin_subsegment 'outbound_call', namespace: 'remote' # Add metadata or annotation here if necessary my_annotations = { k1: 'v1', k2: 1024 } segment.annotations.update my_annotations # Add metadata to default namespace subsegment.metadata[:k1] = 'v1' # Set user for the segment (subsegment is not supported) segment.user = 'my_name' # End segment/subsegment XRay.recorder.end_subsegment XRay.recorder.end_segment ``` ## Konfiguration einer Segmentbenennungsstrategie AWS X-Ray verwendet einen *Dienstnamen*, um Ihre Anwendung zu identifizieren und sie von den anderen Anwendungen, Datenbanken, externen AWS Ressourcen und Ressourcen zu unterscheiden APIs, die Ihre Anwendung verwendet. Wenn das X-Ray SDK Segmente für eingehende Anfragen generiert, zeichnet es den Dienstnamen Ihrer Anwendung im [Namensfeld des Segments auf](xray-api-segmentdocuments.md#api-segmentdocuments-fields). Das X-Ray SDK kann Segmente nach dem Hostnamen im HTTP-Anforderungsheader benennen. Dieser Header kann jedoch gefälscht sein, was zu unerwarteten Knoten in Ihrer Service Map führen kann. Um zu verhindern, dass das SDK Segmente aufgrund von Anfragen mit gefälschten Host-Headern falsch benennt, müssen Sie einen Standardnamen für eingehende Anfragen angeben. Wenn Ihre Anwendung Anfragen für mehrere Domänen bearbeitet, können Sie das SDK so konfigurieren, dass es eine dynamische Benennungsstrategie verwendet, um dies in Segmentnamen widerzuspiegeln. Eine dynamische Benennungsstrategie ermöglicht es dem SDK, den Hostnamen für Anfragen zu verwenden, die einem erwarteten Muster entsprechen, und den Standardnamen auf Anfragen anzuwenden, bei denen dies nicht der Fall ist. Beispielsweise können Sie über eine einzige Anwendung verfügen, die Anfragen an drei Subdomänen — `www.example.com``api.example.com`, und — bedient. `static.example.com` Sie können eine dynamische Benennungsstrategie mit dem Muster verwenden`*.example.com`, um Segmente für jede Subdomain mit einem anderen Namen zu identifizieren, was zu drei Dienstknoten auf der Service-Map führt. Wenn Ihre Anwendung Anfragen mit einem Hostnamen empfängt, der nicht dem Muster entspricht, wird auf der Service Map ein vierter Knoten mit einem von Ihnen angegebenen Fallback-Namen angezeigt. Wenn Sie denselben Namen für alle Anfragesegmente verwenden möchten, geben Sie bei der Konfiguration des Recorders den Namen Ihrer Anwendung, wie in den [vorherigen Abschnitten](#xray-sdk-ruby-middleware-rails) gezeigt, ein. Eine dynamische Benennungsstrategie definiert ein Muster, dem Hostnamen entsprechen sollten, sowie einen Standardnamen, der verwendet wird, wenn der Hostname in der HTTP-Anforderung nicht mit diesem Muster ü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 "\$1" im Muster verwenden, um eine Übereinstimmung mit einer beliebigen Zeichenfolge zu erzielen, oder "?" für die Übereinstimmung mit einem einzelnen Zeichen. **Anmerkung** Sie können den mit der `AWS_XRAY_TRACING_NAME`-[Umgebungsvariablen](xray-sdk-ruby-configuration.md#xray-sdk-ruby-configuration-envvars) in Code definierten standardmäßigen Dienstnamen überschreiben. # Patchen von Bibliotheken zum Instrumentieren von nachgelagerten Aufrufen **Anmerkung** SDK/Daemon X-Ray-Wartungshinweis — Am 25. Februar 2026 wechselt das AWS X-Ray SDKs/Daemon in den Wartungsmodus, in dem die Versionen von X-Ray SDK und Daemon auf Sicherheitsprobleme beschränkt AWS werden. Weitere Informationen zum Zeitplan für den Support finden Sie unter. [Zeitplan für die Support von X-Ray SDK und Daemon](xray-sdk-daemon-timeline.md) Wir empfehlen die Migration zu OpenTelemetry. Weitere Informationen zur Migration zu OpenTelemetry finden Sie unter [Migration von X-Ray-Instrumentierung zu OpenTelemetry Instrumentierung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Um Downstream-Aufrufe zu instrumentieren, verwenden Sie das X-Ray-SDK SDK for Ruby, um die Bibliotheken zu patchen, die Ihre Anwendung verwendet. Das X-Ray SDK for Ruby kann die folgenden Bibliotheken patchen. **Unterstützte Bibliotheken** + `[net/http](https://ruby-doc.org/stdlib-2.4.2/libdoc/net/http/rdoc/Net/HTTP.html)`— Instrumentieren Sie HTTP-Clients. + `[aws-sdk](https://aws.amazon.com/sdk-for-ruby)`— AWS SDK für Ruby Instrumentenkunden. Wenn Sie eine gepatchte Bibliothek verwenden, erstellt das X-Ray-SDK SDK for Ruby ein Untersegment für den Aufruf und zeichnet Informationen aus der Anfrage und Antwort auf. Für das SDK muss ein Segment zur Verfügung stehen, damit es ein Untersegment aus der SDK-Middleware oder einem Aufruf von `XRay.recorder.begin_segment` erstellen kann. Um Bibliotheken zu patchen, geben Sie sie im Konfigurationsobjekt an, das Sie an den X-Ray-Recorder übergeben. **Example main.rb — Patch-Bibliotheken** ``` 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-Ray SDK for Ruby **Anmerkung** SDK/Daemon X-Ray-Wartungshinweis — Am 25. Februar 2026 wechselt das AWS X-Ray SDKs/Daemon in den Wartungsmodus, in dem die Versionen von X-Ray SDK und Daemon auf Sicherheitsprobleme beschränkt AWS werden. Weitere Informationen zum Zeitplan für den Support finden Sie unter. [Zeitplan für die Support von X-Ray SDK und Daemon](xray-sdk-daemon-timeline.md) Wir empfehlen die Migration zu OpenTelemetry. Weitere Informationen zur Migration zu OpenTelemetry finden Sie unter [Migration von X-Ray-Instrumentierung zu OpenTelemetry Instrumentierung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Wenn Ihre Anwendung Aufrufe tätigt, um Daten AWS-Services zu speichern, in eine Warteschlange zu schreiben oder Benachrichtigungen zu senden, verfolgt das X-Ray SDK for Ruby die Aufrufe im Downstream in [Untersegmenten](xray-sdk-ruby-subsegments.md). Verfolgte Ressourcen AWS-Services und Ressourcen, auf die Sie innerhalb dieser Services zugreifen (z. B. ein Amazon S3 S3-Bucket oder eine Amazon SQS SQS-Warteschlange), werden als Downstream-Knoten auf der Trace-Map in der X-Ray-Konsole angezeigt. Das X-Ray-SDK SDK for Ruby instrumentiert automatisch alle AWS SDK-Clients, wenn Sie [die `aws-sdk` Bibliothek patchen](xray-sdk-ruby-patching.md). Einzelne Clients können nicht instrumentiert werden. Für alle Dienste können Sie den Namen der aufgerufenen API in der X-Ray-Konsole sehen. Für eine Teilmenge von Diensten fügt das X-Ray SDK dem Segment Informationen hinzu, um die Service Map detaillierter zu gestalten. Wenn Sie beispielsweise einen Aufruf mit einem instrumentierten DynamoDB-Client tätigen, fügt das SDK den Tabellennamen dem Segment für Aufrufe hinzu, die auf eine Tabelle abzielen. In der Konsole wird jede Tabelle als separater Knoten in der Service Map angezeigt, mit einem generischen 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 weitere Knoten in der Service-Übersicht erstellt. Durch Aufrufe, die keinen bestimmten Ressourcen gelten, wird ein generischer Knoten für den Service erstellt. + **Amazon DynamoDB — Tabellenname** + **Amazon Simple Storage Service** — Bucket und Schlüsselname + **Amazon Simple Queue Service** — Name der Warteschlange # Generieren benutzerdefinierter Untersegmente mit dem X-Ray SDK **Anmerkung** SDK/Daemon X-Ray-Wartungshinweis — Am 25. Februar 2026 wechselt das AWS X-Ray SDKs/Daemon in den Wartungsmodus, in dem die Versionen von X-Ray SDK und Daemon auf Sicherheitsprobleme beschränkt AWS werden. Weitere Informationen zum Zeitplan für den Support finden Sie unter. [Zeitplan für die Support von X-Ray SDK und Daemon](xray-sdk-daemon-timeline.md) Wir empfehlen die Migration zu OpenTelemetry. Weitere Informationen zur Migration zu OpenTelemetry finden Sie unter [Migration von X-Ray-Instrumentierung zu OpenTelemetry Instrumentierung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Untersegmente erweitern das [Segment](xray-concepts.md#xray-concepts-segments) eines Traces um Details über die Arbeit, die zur Bearbeitung einer Anfrage geleistet wurde. Jedes Mal, wenn Sie einen Anruf mit einem instrumentierten Client tätigen, zeichnet das X-Ray-SDK die in einem Untersegment generierten Informationen auf. Sie können zusätzliche Untersegmente erstellen, um andere Untersegmente zu gruppieren, die Leistung eines Codeabschnitts zu messen oder Anmerkungen und Metadaten aufzuzeichnen. Um Untersegmente zu verwalten, verwenden Sie die Methoden `begin_subsegment` und `end_subsegment`. ``` subsegment = XRay.recorder.begin_subsegment name: 'annotations', namespace: 'remote' my_annotations = { id: 12345 } subsegment.annotations.update my_annotations XRay.recorder.end_subsegment ``` Um ein Subsegment für eine Funktion zu erstellen, kapseln Sie es in einen Aufruf von `XRay.recorder.capture` ein. ``` XRay.recorder.capture('name_for_subsegment') do |subsegment| resp = myfunc() # myfunc is your function subsegment.annotations.update k1: 'v1' resp end ``` Wenn Sie ein Untersegment innerhalb eines Segments oder eines anderen Untersegments erstellen, generiert das X-Ray SDK eine ID dafür und zeichnet die Start- und Endzeit auf. **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 zu Segmenten mit dem X-Ray SDK for Ruby **Anmerkung** SDK/Daemon X-Ray-Wartungshinweis — Am 25. Februar 2026 wechselt das AWS X-Ray SDKs/Daemon in den Wartungsmodus, in dem die Versionen von X-Ray SDK und Daemon auf Sicherheitsprobleme beschränkt AWS werden. Weitere Informationen zum Zeitplan für den Support finden Sie unter. [Zeitplan für die Support von X-Ray SDK und Daemon](xray-sdk-daemon-timeline.md) Wir empfehlen die Migration zu OpenTelemetry. Weitere Informationen zur Migration zu OpenTelemetry finden Sie unter [Migration von X-Ray-Instrumentierung zu OpenTelemetry Instrumentierung](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Sie können zusätzliche Informationen über Anfragen, die Umgebung oder Ihre Anwendung mit Anmerkungen und Metadaten aufzeichnen. Sie können Anmerkungen und Metadaten zu den Segmenten hinzufügen, die das X-Ray SDK erstellt, oder zu benutzerdefinierten Untersegmenten, die Sie erstellen. **Anmerkungen** sind Schlüssel-Wert-Paare mit Zeichenfolgen-, Zahlen- oder booleschen Werten. [Anmerkungen sind für die Verwendung mit Filterausdrücken indexiert.](xray-console-filters.md) Berücksichtigen Sie Anmerkungen, um Daten zur Gruppierung von Ablaufverfolgungen in der Konsole zu verwenden, oder wenn Sie die [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html)-API aufrufen. **Metadaten** sind Schlüssel-Wert-Paare, die Werte beliebigen Typs enthalten können, einschließlich Objekte und Listen, aber nicht für die Verwendung mit Filterausdrücken indexiert sind. Verwenden Sie Metadaten, um zusätzliche Daten aufzuzeichnen, die Sie im Trace speichern möchten, aber nicht für die Suche verwenden müssen. Zusätzlich zu Anmerkungen und Metadaten können Sie auch [Benutzer-ID-Zeichenfolgen](#xray-sdk-ruby-segment-userid) in Segmenten aufzeichnen. Benutzer IDs werden in einem separaten Feld in Segmenten aufgezeichnet und für die Verwendung bei der Suche indexiert. **Topics** + [Anmerkungen mit dem X-Ray SDK for Ruby aufnehmen](#xray-sdk-ruby-segment-annotations) + [Metadaten mit dem X-Ray SDK for Ruby aufnehmen](#xray-sdk-ruby-segment-metadata) + [Benutzer IDs mit dem X-Ray SDK for Ruby aufnehmen](#xray-sdk-ruby-segment-userid) ## Anmerkungen mit dem X-Ray SDK for Ruby aufnehmen Verwenden Sie Anmerkungen, um Informationen zu Segmenten oder Untersegmenten, die zur Suche indiziert werden sollten, aufzuzeichnen. **Anmerkung zu Anforderungen** + **Schlüssel** — Der Schlüssel für eine X-Ray-Anmerkung kann bis zu 500 alphanumerische Zeichen enthalten. Sie können keine anderen Leerzeichen oder Symbole als einen Punkt oder Punkt (.) verwenden + **Werte** — Der Wert für eine X-Ray-Anmerkung kann bis zu 1.000 Unicode-Zeichen enthalten. + Die Anzahl der **Anmerkungen** — Sie können bis zu 50 Anmerkungen pro Spur verwenden. **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 ``` 1. Rufen Sie `update` mit einem Hash-Wert auf. ``` my_annotations = { id: 12345 } document.annotations.update my_annotations ``` Das folgende Beispiel zeigt, wie Sie `update` mit einem Annotationsschlüssel aufrufen, der einen Punkt enthält. ``` my_annotations = { testkey.test: 12345 } document.annotations.update my_annotations ``` Das SDK zeichnet Anmerkungen als Schlüssel-Wert-Paare in einem `annotations`-Objekt im Segmentdokument auf. Wenn `add_annotations` zweimal mit demselben Schlüssel aufgerufen wird, werden zuvor aufgezeichnete Werte im gleichen Segment oder Untersegment überschrieben. Nutzen Sie das `annotation[key]`-Schlüsselwort in einem [Filterausdruck](xray-console-filters.md), um Ablaufverfolgungen durch Anmerkungen mit bestimmten Werten zu finden. ## Metadaten mit dem X-Ray SDK for Ruby aufnehmen Verwenden Sie Metadaten, um Segment- oder Untersegmentinformationen aufzuzeichnen, die nicht zur Suche indiziert werden müssen. Metadatenwerte sind Zeichenfolgen, Zahlen, boolesche Werte oder andere Objekte, 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 ``` 1. Rufen Sie `metadata` mit einem Zeichenfolgenschlüssel, einem booleschen Wert, einer Zahl, einer Zeichenfolge oder einem Objektwert und einem Zeichenfolgen-Namespace auf. ``` my_metadata = { my_namespace: { key: 'value' } } subsegment.metadata my_metadata ``` Wenn `metadata` zweimal mit demselben Schlüssel aufgerufen wird, werden zuvor aufgezeichnete Werte im gleichen Segment oder Untersegment überschrieben. ## Benutzer IDs mit dem X-Ray SDK for Ruby aufnehmen Zeichnen Sie Segmente von Benutzern IDs auf Anfrage auf, um den Benutzer zu identifizieren, der die Anfrage gesendet hat. **Um den Benutzer aufzuzeichnen IDs** 1. Eine Referenz des aktuellen Segments finden Sie unter `xray_recorder`. ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_segment ``` 1. Setzen Sie das Benutzerfeld auf dem Segment auf eine Zeichenfolgen-ID des Benutzers, der die Anforderung gesendet hat. ``` segment.user = 'U12345' ``` Sie können den Benutzern in Ihren Controllern festlegen, um die Benutzer-ID aufzuzeichnen, sobald die Anwendung mit der Bearbeitung einer Anfrage beginnt. Nutzen Sie das `user`-Schlüsselwort in einem [Filterausdruck](xray-console-filters.md), um Ablaufverfolgungen einer Benutzer-ID zu finden.