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. # 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.