Konfigurieren des X-Ray-SDK SDK for Ruby - AWS X-Ray

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.

Konfigurieren des X-Ray-SDK SDK for Ruby

Das X-Ray-SDK SDK for Ruby hat eine Klasse namensXRay.recorderdas stellt den globalen Rekorder bereit. Sie können die globale Aufzeichnung so konfigurieren, dass die Middleware, die Segmente für eingehende HTTP-Aufrufe erstellt, angepasst wird.

Service-Plugins

Verwenden vonpluginsum Informationen über den Service aufzuzeichnen, der Ihre Anwendung hostet.

Plug-ins

  • Amazon EC2 —ec2fügt die Instance-ID und Availability Zone hinzu.

  • Elastic Beanstalk —elastic_beanstalkfügt den Umgebungsnamen, die Versionsbezeichnung und die Bereitstellungs-ID hinzu.

  • Amazon ECS —ecsfügt die Container-ID hinzu.


        Segmentieren Sie Ressourcendaten mit Amazon EC2- und Elastic Beanstalk-Plugins.

Um Plugins verwenden zu können, geben Sie sie in dem Konfigurationsobjekt an, das sie dem Recorder übergeben.

Beispiel 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, die Vorrang über Werte im Code haben, zur Konfiguration des Recorders verwenden.

Das SDK verwendet auch Plugin-Einstellungen, um dieorigin-Feld im Segment. Dies zeigt den AWS-Ressourcentyp an, auf denen Ihre Anwendung ausgeführt wird. Der Ressourcentyp wird unter dem Namen Ihrer Anwendung in der Service-Map angezeigt. Zum Beispiel, AWS::ElasticBeanstalk::Environment.

Serviceknoten mit Ressourcentyp.

Wenn Sie mehrere Plugins verwenden, verwendet das SDK die folgende Auflösungsreihenfolge, um den Ursprung zu ermitteln: ElasticBeanstalk > EKS > ECS > EC2.

Samplingregeln

Das SDK verwendet die Samplingregeln, die Sie in der X-Ray-Konsole definieren, um zu bestimmen, welche Anforderungen aufgezeichnet werden sollen. Die Standardregel verfolgt die erste Anforderung jede Sekunde und fünf Prozent aller zusätzlichen Anfragen für alle Dienste, die Traces an X-Ray senden. Erstellen Sie zusätzliche Regeln in der X-Ray-Konsoleum die Menge der für jede Ihrer Anwendungen aufgezeichneten Daten anzupassen.

Das SDK wendet benutzerdefinierte Regeln in der Reihenfolge an, in der sie definiert sind. Wenn eine Anforderung mehreren benutzerdefinierten Regeln entspricht, wendet das SDK nur die erste Regel an.

Anmerkung

Wenn das SDK X-Ray nicht erreichen kann, um Stichprobenregeln zu erhalten, wird es auf eine lokale Standardregel der ersten Anforderung jede Sekunde und fünf Prozent aller zusätzlichen Anforderungen pro Host zurückgesetzt. Dies kann auftreten, wenn der Host keine Berechtigung zum Aufrufen von Sampling-APIs hat oder keine Verbindung zum X-Ray-Daemon herstellen kann, der als TCP-Proxy für API-Aufrufe des SDK fungiert.

Sie können das SDK auch so konfigurieren, dass es Samplingregeln aus einem JSON-Dokument lädt. 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.

Beispiel 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 wird eine benutzerdefinierte Regel und eine Standardregel definiert. Die benutzerdefinierte Regel wendet eine Abtastrate von fünf Prozent ohne Mindestanzahl von Anfragen an, die für Pfade unter/api/move/aus. Die Standardregel verfolgt die erste Anforderung jede Sekunde und 10 Prozent aller weiteren Anforderungen.

Der Nachteil der lokalen Definition von Regeln besteht darin, dass das feste Ziel von jeder Instanz des Recorders unabhängig angewendet wird, anstatt vom X-Ray-Dienst verwaltet zu werden. Wenn Sie mehr Hosts bereitstellen, wird der feste Zinssatz multipliziert, 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.

Beispiel main.rb — Konfiguration Backup Sicherheitsregel

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.

Beispiel config/sampling-rules.rb

my_sampling_rules = { version: 1, default: { fixed_target: 1, rate: 0.1 } }

Beispiel 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)

Um nur lokale Regeln zu verwenden, fordern Sie die Samplingregeln an und konfigurieren den LocalSampler.

Beispiel main.rb — lokale Sampling

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.

Beispiel main.rb — Deaktivieren des Samplings

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 in dem Konfigurationsobjekt definieren, das Sie dem Recorder übergeben.

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

Konfiguration des Recorders im Code

Zusätzliche Einstellungen finden Sie in der configure-Methode auf XRay.recorder.

  • context_missing— Stellen Sie aufLOG_ERRORum das Auslösen von Ausnahmen zu vermeiden, 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— Legt einen Servicenamen fest, der vom SDK für Segmente verwendet wird.

  • naming_pattern— Legen Sie ein zu verwendendes DomänennamensmusterDynamische Benennungaus.

  • plugins— Zeichnen Sie Informationen zu Ihren Bewerbungen aufAWSressourcen mitPluginsaus.

  • sampling— Stellen Sie auffalseum das Sampling zu deaktivieren.

  • sampling_rules— Legt den Hash mit Ihrem festSamplingregelnaus.

Beispiel main.rb — Deaktivieren von Ausnahmen ohne Kontext

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— Stellen Sie auftrueum Untersegmente für Active Record-Datenbanktransaktionen aufzuzeichnen.

Konfigurieren Sie die verfügbaren Einstellungen in einem Konfigurationsobjekt mit dem Namen Rails.application.config.xray.

Beispiel config/initializers/aws_xray.rb

Rails.application.config.xray = { name: 'my app', patch: %I[net_http aws_sdk], active_record: true }

Umgebungsvariablen

Sie können Umgebungsvariablen zum Konfigurieren des X-Ray-SDK SDK for Ruby verwenden. Das SDK unterstützt die folgenden Variablen:

  • AWS_XRAY_TRACING_NAME— Legt einen Servicenamen fest, der vom SDK für Segmente verwendet wird. Überschreibt den für die Segmentbenennungsstrategie 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 Ablaufverfolgungsdaten an127.0.0.1:2000aus. Verwenden Sie diese Variable, wenn Sie den Daemon konfiguriert habenhören Sie an einem anderen Portoder wenn es auf einem anderen Host läuft.

  • AWS_XRAY_CONTEXT_MISSING— Stellen Sie aufLOG_ERRORum das Auslösen von Ausnahmen zu vermeiden, wenn Ihr instrumentierter Code versucht, Daten aufzuzeichnen, wenn kein Segment geöffnet ist.

    Zulässige Werte

    • RUNTIME_ERROR— Löst eine Laufzeitausnahme (Standard).

    • LOG_ERROR— Protokollieren Sie einen Fehler und fahren Sie fort.

    Fehler aufgrund fehlender Segmente oder Untersegmente können auftreten, wenn Sie versuchen, einen instrumentierten Client in Startup-Code zu verwenden, der ausgeführt wird, wenn keine Anfrage geöffnet ist, oder in Code, der einen neuen Thread aufruft.

Umgebungsvariablen überschreiben Werte im Code.