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** 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 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. ![\[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 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 Plug-ins 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, 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 } } ``` Dieses Beispiel definiert eine benutzerdefinierte Regel und eine Standardregel. 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. 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`xray_recorder.configure`, rufen Sie, wie im folgenden Beispiel gezeigt, auf, wobei entweder *rules* ein Regelwörterbuch oder der absolute Pfad zu einer JSON-Datei mit Sampling-Regeln steht. ``` 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`— 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.