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 für Python **Anmerkung** X-Ray SDK/Daemon Wartungshinweis — Am 25. Februar 2026 wechselt AWS X-Ray SDKs/Daemon es in den Wartungsmodus, in dem X-Ray SDK- und Daemon-Versionen 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 Instrumentation zu OpenTelemetry Instrumentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Das X-Ray SDK für Python 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-python-configuration-plugins) + [Regeln für die Probenahme](#xray-sdk-python-configuration-sampling) + [Protokollierung](#xray-sdk-python-configuration-logging) + [Konfiguration des Recorders im Code](#xray-sdk-python-middleware-configuration-code) + [Konfigurieren des Recorders mit Django](#xray-sdk-python-middleware-configuration-django) + [Umgebungsvariablen](#xray-sdk-python-configuration-envvars) ## Service-Plugins Wird verwendet`plugins`, um Informationen über den Dienst aufzuzeichnen, der Ihre Anwendung hostet. **Plugins** + Amazon EC2 — `EC2Plugin` fügt die Instance-ID, die Availability Zone und die CloudWatch Logs-Gruppe hinzu. + Elastic Beanstalk — `ElasticBeanstalkPlugin` fügt den Umgebungsnamen, die Versionsbezeichnung und die Bereitstellungs-ID hinzu. + Amazon ECS — `ECSPlugin` fügt die Container-ID hinzu. ![Segmentieren Sie Ressourcendaten mit Amazon EC2- und Elastic Beanstalk-Plugins.](http://docs.aws.amazon.com/de_de/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-python09.png) 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** Da `plugins` sie als Tupel übergeben werden, sollten Sie bei der Angabe eines einzelnen Plugins unbedingt ein abschließendes Zeichen `,` angeben. Beispiel: `plugins = ('EC2Plugin',)` Sie können auch [Umgebungsvariablen](#xray-sdk-python-configuration-envvars), die Vorrang über Werte im Code haben, zur Konfiguration des Recorders verwenden. Konfigurieren Sie Plugins vor [Patch-Bibliotheken](xray-sdk-python-patching.md), um nachgeschaltete Aufrufe aufzuzeichnen. Das SDK verwendet auch Plugin-Einstellungen, um das `origin` Feld für das 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, an die Traces gesendet X-Ray werden. [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 keine Sampling-Regeln abrufen kann, kehrt es zu einer lokalen Standardregel zurück, die jede Sekunde die erste Anfrage und fünf Prozent aller zusätzlichen Anfragen pro Host vorsieht. X-Ray Dies kann der Fall sein, wenn der Host nicht berechtigt ist, Sampling-APIs 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, unter `/api/move/` denen Pfade verfolgt werden müssen. 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. Wenn aktiviert AWS Lambda, können Sie die Samplerate nicht ändern. Wenn Ihre Funktion von einem instrumentierten Dienst aufgerufen wird, werden Aufrufe, die Anfragen generierten, die von diesem Dienst abgetastet wurden, von Lambda aufgezeichnet. Wenn aktives Tracing aktiviert ist und kein Tracing-Header vorhanden ist, trifft Lambda die Stichprobenentscheidung. Um Backup-Sampling-Regeln zu konfigurieren, rufen Sie`xray_recorder.configure`, wie im folgenden Beispiel gezeigt, auf, wobei entweder ein Regelwörterbuch oder der absolute Pfad zu einer JSON-Datei {{rules}} steht, die Sampling-Regeln enthält. ``` 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. **Example main.py — Sampling deaktivieren** ``` xray_recorder.configure(sampling=False) ``` ## Protokollierung Das SDK verwendet das in Python integrierte `logging` Modul mit einer `WARNING` Standard-Protokollierungsebene. 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. **Example 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](xray-sdk-python-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, obwohl kein Segment geöffnet ist. + `daemon_address`— Legt den Host und den Port des X-Ray Daemon-Listeners fest. + `service`— Legen Sie einen Dienstnamen fest, den das SDK für Segmente verwendet. + `plugins`— Notieren Sie Informationen über die AWS Ressourcen Ihrer Anwendung. + `sampling`— Auf einstellen, `False` um die Probenahme zu deaktivieren. + `sampling_rules`— Legen Sie den Pfad der JSON-Datei fest, die Ihre [Sampling-Regeln](#xray-sdk-python-configuration-sampling) enthält. **Example main.py — Deaktiviert Ausnahmen, die im Kontext fehlen** ``` 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) — Zeichnet Untersegmente für integrierte Datenbank- und Vorlagen-Rendering-Operationen auf. + `AWS_XRAY_CONTEXT_MISSING`— Auf einstellen, um `LOG_ERROR` zu vermeiden, dass Ausnahmen ausgelöst werden, 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`— Legen Sie einen Dienstnamen fest, den das SDK für Segmente verwendet. + `PLUGINS`— Notieren Sie Informationen über die AWS Ressourcen Ihrer Anwendung. + `SAMPLING`— Auf einstellen, `False` um die Probenahme zu deaktivieren. + `SAMPLING_RULES`— Legen Sie den Pfad der JSON-Datei fest, die Ihre [Sampling-Regeln](#xray-sdk-python-configuration-sampling) enthält. Um die Konfiguration des Recorders in `settings.py` zu aktivieren, fügen Sie die Django-Middleware zur Liste der installierten Apps hinzu. **Example 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`. **Example 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 verwenden, um das X-Ray SDK für Python 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 Servicenamen, den Sie programmgesteuert festgelegt haben. + `AWS_XRAY_SDK_ENABLED`— Wenn auf gesetzt`false`, wird das SDK deaktiviert. 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 `127.0.0.1:2000` das SDK sowohl Trace-Daten (UDP) als auch Sampling-Daten (TCP). 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. **Format** + **Derselbe Port** — `{{address}}:{{port}}` + **Verschiedene Anschlüsse** — `tcp:{{address}}:{{port}} udp:{{address}}:{{port}}` + `AWS_XRAY_CONTEXT_MISSING`— Auf einstellen, `RUNTIME_ERROR` um Ausnahmen auszulösen, 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`— Einen 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.