Konfigurieren des X-Ray-SDK für Python - 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 für Python

Das X-Ray-SDK für Python verfügt über eine Klasse namensxray_recorderdas stellt den globalen Rekorder zur Verfügung. 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 —EC2Pluginfügt die Instance-ID, die Availability Zone und die CloudWatch Logs Logs-Gruppe hinzu.

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

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


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

Um ein Plugin zu verwenden, rufen Sie configure im xray_recorder auf.

from aws_xray_sdk.core import xray_recorder from aws_xray_sdk.core import patch_all xray_recorder.configure(service='My app') plugins = ('ElasticBeanstalkPlugin', 'EC2Plugin') xray_recorder.configure(plugins=plugins) patch_all()
Anmerkung

Seitpluginswerden als Tupel übergeben, achten Sie darauf, dass Sie ein Trailing einschließen,wenn Sie ein einzelnes Plugin angeben. Beispiel, plugins = ('EC2Plugin',)

Sie können auch Umgebungsvariablen, die Vorrang über Werte im Code haben, zur Konfiguration des Recorders verwenden.

Konfigurieren Sie Plugins vor Patch-Bibliotheken, um nachgeschaltete Aufrufe aufzuzeichnen.

Das SDK verwendet auch Plugin-Einstellungen, um dieorigin-Feld im Segment. Dies zeigt den AWS-Ressourcentyp an, auf dem 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 bestimmt anhand der Samplingregeln, die Sie in der X-Ray-Konsole definieren, 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 Anfrage jede Sekunde und 10 Prozent aller zusätzlichen 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.

InAWS Lambdakönnen Sie die Abtastrate nicht ändern. Wenn Ihre Funktion von einem instrumentierten Dienst aufgerufen wird, werden Aufrufe, die Anfragen generiert haben, die von diesem Dienst abgetastet wurden, von Lambda aufgezeichnet. Wenn die aktive Ablaufverfolgung aktiviert ist und kein Tracing-Header vorhanden ist, trifft Lambda die Stichprobenentscheidung.

Um Sicherungsregeln zu konfigurieren, rufen Sie xray_recorder.configure auf, wie im folgenden Beispiel dargestellt, wobei der Begriff Regeln entweder ein Wörterbuch mit Regeln oder den absoluten Pfad zu einer JSON-Datei mit Samplingregeln bezeichnet.

xray_recorder.configure(sampling_rules=rules)

Um nur lokale Regeln zu verwenden, konfigurieren Sie den Recorder mit einer LocalSampler.

from aws_xray_sdk.core.sampling.local.sampler import LocalSampler xray_recorder.configure(sampler=LocalSampler())

Sie können auch die globale Aufzeichnung so konfigurieren, dass das Sampling deaktiviert und alle eingehenden Anfragen instrumentiert werden.

Beispiel main.py — Deaktivieren des Samplings

xray_recorder.configure(sampling=False)

Protokollierung

Das SDK verwendet Pythons integrierteloggingModul mit einem StandardwertWARNINGProtokollierungsebene. Erhalten Sie eine Referenz zum Logger für die aws_xray_sdk-Klasse und rufen Sie darauf setLevel auf, um die verschiedenen Protokollebenen für die Bibliothek und den Rest Ihrer Anwendung zu konfigurieren.

Beispiel app.py — Protokollierung

logging.basicConfig(level='WARNING') logging.getLogger('aws_xray_sdk').setLevel(logging.ERROR)

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.

  • service— Legt einen Servicenamen fest, der vom SDK für Segmente verwendet wird.

  • plugins— Zeichnen Sie Informationen zu Ihren Bewerbungen aufAWSRessourcen schätzen.

  • sampling— Stellen Sie aufFalseum das Sampling zu deaktivieren.

  • sampling_rules— Legen Sie den Pfad der JSON-Datei mit Ihrem festSamplingregelnaus.

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

Wenn Sie das Django-Framework verwenden, können Sie die settings.py-Datei von Django zum Konfigurieren von Optionen in der globalen Aufzeichnung verwenden.

  • AUTO_INSTRUMENT(Nur Django) — Zeichnen Sie Untersegmente auf für integrierte Datenbank- und Vorlagenwiedergabeeingänge.

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

  • AWS_XRAY_DAEMON_ADDRESS— Legt den Host und den Port des X-Ray-Daemon-Listeners fest.

  • AWS_XRAY_TRACING_NAME— Legt einen Servicenamen fest, der vom SDK für Segmente verwendet wird.

  • PLUGINS— Zeichnen Sie Informationen zu Ihren Bewerbungen aufAWSRessourcen schätzen.

  • SAMPLING— Stellen Sie aufFalseum das Sampling zu deaktivieren.

  • SAMPLING_RULES— Legen Sie den Pfad der JSON-Datei mit Ihrem festSamplingregelnaus.

Um die Konfiguration des Recorders in settings.py zu aktivieren, fügen Sie die Django-Middleware zur Liste der installierten Apps hinzu.

Beispiel settings.py — Installierte Apps

INSTALLED_APPS = [ ... 'django.contrib.sessions', 'aws_xray_sdk.ext.django', ]

Konfigurieren Sie die verfügbaren Einstellungen in einem dict-Objekt mit dem Namen XRAY_RECORDER.

Beispiel 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, }

Umgebungsvariablen

Sie können Umgebungsvariablen zum Konfigurieren des X-Ray-SDK für Python 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 Servicenamen, den Sie programmgesteuert festgelegt haben.

  • AWS_XRAY_SDK_ENABLED— Wenn eingestellt auffalse, deaktiviert das SDK. Das SDK ist standardmäßig aktiviert, es sei denn, die Umgebungsvariable ist auf „false“ festgelegt.

    • Wenn diese Option deaktiviert ist, generiert die globale Aufzeichnung automatisch Dummy-Segmente und Untersegmente, die nicht an den Daemon gesendet werden, und das automatische Patchen wird deaktiviert. Middlewares werden als Wrapper über der globalen Aufzeichnung geschrieben. Auch alle Generierungen von Segmenten und Untersegmenten über die Middleware werden zu Dummy-Segmenten und Dummy-Untersegmenten.

    • Legen Sie den Wert AWS_XRAY_SDK_ENABLED über die Umgebungsvariable oder durch direkte Interaktion mit dem Objekt global_sdk_config aus der aws_xray_sdk-Bibliothek fest. Einstellungen der Umgebungsvariablen überschreiben diese Interaktionen.

  • AWS_XRAY_DAEMON_ADDRESS— Legt den Host und den Port des X-Ray-Daemon-Listeners fest. Standardmäßig verwendet das SDK127.0.0.1:2000sowohl für Trace-Daten (UDP) als auch für Sampling (TCP). Verwenden Sie diese Variable, wenn Sie den Daemon konfiguriert habenhören Sie an einem anderen Portoder wenn es auf einem anderen Host läuft.

    Format

    • Gleicher Portaddress:port

    • Verschiedene Portstcp:address:port udp:address:port

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