View a markdown version of this page

AWS X-Ray SDK für Python - AWS X-Ray
VoraussetzungenAbhängigkeitsmanagement

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.

AWS X-Ray SDK für Python

Anmerkung

X-Ray SDK/Daemon Wartungshinweis — Am 25. Februar 2026 wechselt der in den AWS X-Ray SDKs/Daemon Wartungsmodus, in dem die 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 Wir empfehlen die Migration zu OpenTelemetry. Weitere Informationen zur Migration zu OpenTelemetry finden Sie unter Migration von X-Ray Instrumentierung zu OpenTelemetry Instrumentierung.

Das X-Ray SDK für Python ist eine Bibliothek für Python-Webanwendungen, die Klassen und Methoden zum Generieren und Senden von Trace-Daten an den X-Ray Daemon bereitstellt. Zu den Trace-Daten gehören Informationen über eingehende HTTP-Anfragen, die von der Anwendung bedient werden, sowie über Aufrufe, die die Anwendung mithilfe des AWS SDK, HTTP-Clients oder eines SQL-Datenbank-Connectors an nachgelagerte Dienste sendet. Sie können Segmente auch manuell erstellen und Debug-Informationen Anmerkungen und Metadaten hinzufügen.

Sie können das SDK mit pip herunterladen.

$ pip install aws-xray-sdk
Anmerkung

Das X-Ray SDK für Python ist ein Open-Source-Projekt. Du kannst das Projekt verfolgen und Issues und Pull Requests auf GitHub Github einreichen. com/aws/aws-xray-sdk-python

Wenn Sie Django oder Flask nutzen, beginnen Sie, indem Sie die SDK-Middleware zu Ihrer Anwendung hinzufügen, um eingehende Anforderungen zu verfolgen. Der Middleware erstellt für jede verfolgte Anforderung ein Segment und vervollständigt das Segment, nachdem die Antwort gesendet wurde. Während das Segment geöffnet ist, können Sie die SDK-Client-Methoden nutzen, um dem Segment Informationen hinzuzufügen, Untersegmente zu erstellen und nachgelagerte Aufrufe rückzuverfolgen. Das SDK erfasst auch automatisch Ausnahmen, die Ihre Anwendung ausgibt, während das Segment geöffnet ist. Bei anderen Anwendungen können Sie Segmente manuell erstellen.

Bei Lambda-Funktionen, die von einer instrumentierten Anwendung oder einem Dienst aufgerufen werden, liest Lambda den Tracing-Header und verfolgt automatisch gesampelte Anfragen. Ablaufverfolgungs-Header Für andere Funktionen können Sie Lambda so konfigurieren, dass eingehende Anfragen abgetastet und nachverfolgt werden. In beiden Fällen erstellt Lambda das Segment und stellt es dem X-Ray SDK zur Verfügung.

Anmerkung

Auf Lambda ist das X-Ray SDK optional. Wenn Sie es nicht in Ihrer Funktion verwenden, enthält Ihre Service Map dennoch einen Knoten für den Lambda-Service und einen für jede Lambda-Funktion. Durch Hinzufügen des SDK können Sie Ihren Funktionscode so instrumentieren, dass Untersegmente zu dem von Lambda aufgezeichneten Funktionssegment hinzugefügt werden. Weitere Informationen finden Sie unter AWS Lambda und AWS X-Ray.

Ein Beispiel Worker für eine Python-Funktion, die in Lambda instrumentiert ist, finden Sie hier.

Verwenden Sie als Nächstes das X-Ray SDK für Python, um Downstream-Aufrufe zu instrumentieren, indem Sie die Bibliotheken Ihrer Anwendung patchen. Das SDK unterstützt die folgenden Bibliotheken.

Unterstützte Bibliotheken

  • botocore, boto3 — AWS SDK for Python (Boto) Instrument-Kunden.

  • pynamodb— Die Version des Amazon DynamoDB-Clients von Instrument PynamoDB.

  • aiobotocore, aioboto3 — In Instrument Asyncio integrierte Versionen des SDK für Python-Clients (Boto3).

  • requests, aiohttp — Instrumenten-HTTP-Clients auf hoher Ebene.

  • httplib, http.client — Instrumentiere HTTP-Clients auf niedriger Ebene und die übergeordneten Bibliotheken, die sie verwenden.

  • sqlite3— Instrument SQLite-Clients.

  • mysql-connector-python— Instrument MySQL-Clients.

  • pg8000— Instrument Pure-Python PostgreSQL-Schnittstelle.

  • psycopg2— Instrument PostgreSQL-Datenbankadapter.

  • pymongo— Instrument MongoDB-Clients.

  • pymysql— Instrument PyMy SQL-basierte Clients für MySQL und MariaDB.

Immer wenn Ihre Anwendung Aufrufe an AWS eine SQL-Datenbank oder andere HTTP-Dienste tätigt, zeichnet das SDK Informationen über den Aufruf in einem Untersegment auf. AWS-Services und die Ressourcen, auf die Sie innerhalb der Dienste zugreifen, werden in der Trace-Map als Downstream-Knoten angezeigt, sodass Sie Fehler und Drosselungsprobleme bei einzelnen Verbindungen leichter erkennen können.

Nachdem Sie mit der Verwendung des SDK begonnen haben, passen Sie sein Verhalten an, indem Sie den Rekorder und die Middleware konfigurieren. Sie können Plugins zum Festhalten von Daten über die Datenverarbeitungsressourcen, auf denen Ihre Anwendung ausgeführt wird, hinzufügen, das Samplingverhalten durch Samplingregeln anpassen und Protokollebenen einrichten, um mehr oder weniger Informationen von dem SDK in Ihren Anwendungsprotokollen zu sehen.

Zeichnen Sie zusätzliche Informationen zu Anforderungen und den Aufgaben, die Ihre Anwendung ausführt, in Anmerkungen und Metadaten auf. Anmerkungen sind einfache Schlüsselwertpaare, die für die Verwendung mit Filterausdrücken indiziert werden, damit Sie nach Ablaufverfolgen mit bestimmten Daten suchen können. Metadateneinträge sind weniger einschränkend und können ganze Objekte und Arrays aufzeichnen – alle Daten, die in eine JSON zusammengefasst werden können.

Anmerkungen und Metadaten

Anmerkungen und Metadaten sind beliebiger Text, den Sie mit dem SDK zu Segmenten hinzufügen. X-Ray Anmerkungen werden für die Verwendung mit Filterausdrücken indexiert. Metadaten werden nicht indexiert, können aber im Rohsegment mit der X-Ray Konsole oder der API angezeigt werden. Jeder, dem Sie Lesezugriff gewähren, X-Ray kann diese Daten sehen.

Wenn Sie viele instrumentierten Clients in Ihrem Code haben, kann ein einzelnes Anforderungssegmente viele Untersegmente enthalten, eines für jeden Aufruf mit einem instrumentierten Client. Sie können Untersegmente organisieren und gruppieren, indem Sie Client-Aufrufe in benutzerdefinierten Untersegmenten zusammenfassen. Sie können ein benutzerdefiniertes Untersegment für die gesamte Funktion oder einen beliebigen Bereich des Codes erstellen. Sie können dann Metadaten und Anmerkungen im Untersegment aufzeichnen, anstatt alles in das übergeordnete Segment zu schreiben.

Eine Referenzdokumentation für die Klassen und Methoden des SDK finden Sie in der AWS X-Ray SDK for Python API Reference.

Voraussetzungen

Das X-Ray SDK für Python unterstützt die folgenden Sprach- und Bibliotheksversionen.

  • Python — 2.7, 3.4 und neuer

  • Django — 1.10 und neuer

  • Flask — 0.10 und neuer

  • aiohttp — 2.3.0 und neuer

  • AWS SDK for Python (Boto)— 1.4.0 und neuer

  • botocore — 1.5.0 und neuer

  • enum — 0.4.7 und neuer, für Python-Versionen 3.4.0 und älter

  • jsonpickle — 1.0.0 und neuer

  • setuptools — 40.6.3 und neuer

  • wrapt — 1.11.0 und neuer

Abhängigkeitsmanagement

Das X-Ray SDK für Python ist verfügbar unter. pip

  • Paket — aws-xray-sdk

Fügen Sie das SDK in Ihrer requirements.txt-Datei als abhängige Komponente hinzu.

Beispiel requirements.txt
aws-xray-sdk==2.4.2
boto3==1.4.4
botocore==1.5.55
Django==1.11.3

Wenn Sie Elastic Beanstalk für die Bereitstellung Ihrer Anwendung verwenden, installiert Elastic Beanstalk alle Pakete automatisch. requirements.txt