Zum Hauptinhalt springen
Das Einbinden benutzerdefinierter Instrumentierung in Ihre Anwendung kann hilfreich sein, um die spezifischen Codezeilen zu identifizieren, die Performance-Probleme verursachen. AppSignal für Python verwendet OpenTelemetry-Tracer-Objekte; weitere Informationen zu Python-Traces finden Sie im Python Cookbook von OpenTelemetry. Traces bestehen aus einem oder mehreren Spans. Ein Trace kann als gerichteter azyklischer Graph (DAG) von Spans betrachtet werden: Trace-Diagramm AppSignal-spezifische Attribute müssen einem Span hinzugefügt werden, damit er von AppSignal erfolgreich geparst werden kann. Mit unserem Satz von Helper-Methoden können diese Attribute gesetzt werden. Diese Dokumentation erklärt, wie Sie benutzerdefinierte Instrumentierungen erstellen, indem Sie AppSignal-spezifische Attribute in den Spans Ihrer Python-Anwendung setzen.

Einen Span erstellen

Importieren Sie beim Hinzufügen benutzerdefinierter Instrumentierung zunächst das OpenTelemetry-Trace-Modul in die Datei, der Sie Instrumentierung hinzufügen möchten.
Erstellen Sie dann mit diesem Trace-Modul einen neuen Span:
Sobald Sie den Span abgerufen haben, können Sie unsere Helper-Methoden verwenden, um die erforderlichen Attribute zuzuweisen. Weitere Informationen zum Erstellen und Abrufen von Spans finden Sie im Python Cookbook von OpenTelemetry.

Einmalige Aufrufe und Serverless

Wenn Sie einmalige Skripte oder Serverless-Funktionen ausführen, müssen Sie AppSignal manuell initialisieren und am Ende stoppen, um sicherzustellen, dass keine Daten verloren gehen. Der Helper stop beendet den Agent-Prozess sauber und wartet eine Weile, um sicherzustellen, dass alle Daten an die AppSignal-Server gesendet werden.

Helper-Methoden

Die in diesem Abschnitt beschriebenen Helper-Methoden sind nicht mit dem AppSignal Collector kompatibel.
Die folgenden Helper-Methoden setzen AppSignal-spezifische Attribute auf Spans, die helfen, Spans zu gruppieren und ihre Darstellung in AppSignal zu verbessern. Andere Attribute werden von AppSignal auf Spans nicht unterstützt.

set_category

Die Span-Kategorie ist der Name, der im Performance-Event-Timeline für Traces erscheint. Sie wird auch verwendet, um Spans zu gruppieren und auf der Sample-Detailseite eine Aufschlüsselung pro Gruppe zu erstellen.
Die Kategorie ist eine Zeichenkette, die das untergeordnete Span-Event und die Gruppe enthält. Die Kategorie sollte einen Punkt (.) verwenden, um die hierarchische Vererbung des Events auszudrücken, wobei die höchste Einheit zuletzt steht. Weitere Informationen zu Span-Kategorien finden Sie im Leitfaden für Event-Namen.

set_name

Dem Span können weitere Details hinzugefügt werden, die sichtbar sind, wenn Sie mit dem Mauszeiger über das Event in der Event-Timeline fahren. Der Span-Name wird verwendet, um weitere Informationen über das Event bereitzustellen, beispielsweise „Fetch users”, die Datenbank, aus der sie abgerufen werden, oder die angeforderte URL.
Wenn diese Methode nicht aufgerufen wird, wird der Wert verwendet, mit dem start_as_current_span aufgerufen wurde.

set_body

🔐 Senden Sie keine personenbezogenen Daten (Personal Identifiable Information, PII) an AppSignal. Filtern Sie PII (z. B. Namen, E-Mail-Adressen) und verwenden Sie stattdessen eine ID, einen Hash oder einen pseudonymisierten Bezeichner.

Für HIPAA-pflichtige Stellen finden Sie weitere Informationen zum Abschluss eines Business Associate Agreement (BAA) in unserer Business Add-Ons-Dokumentation.
Der Body des Spans kann zusätzliche Informationen über das Event enthalten, etwa den HTTP-Request, den verbundenen Host usw. Stellen Sie sicher, dass Sie die Informationen bereinigen, bevor Sie sie dem Span hinzufügen, damit keine personenbezogenen Daten an AppSignal gesendet werden. Diese Informationen sind für den Span sichtbar, wenn Sie mit dem Mauszeiger über die Event-Timeline fahren. Um SQL-Abfragen im Body des Spans zu speichern, verwenden Sie stattdessen den Helper set_sql_body.

set_sql_body

Verfügbar ab Python-Paket 0.3.2.
Setzen Sie eine SQL-Abfrage als Body des Spans, wie sie in der Performance-Event-Timeline in der Detailansicht des Incident-Samples erscheint. Dies ist ähnlich zum Helper set_body, aber spezialisiert auf SQL-Abfragen. Jede mit diesem Attribut als Body gesetzte SQL-Abfrage wird bereinigt, um zu vermeiden, dass personenbezogene Daten (PII) an unsere Server gesendet werden. Weitere Details zur Funktionsweise des Body-Attributs finden Sie beim Helper set_body. Wenn sowohl der set_body- als auch der set_sql_body-Helper auf demselben Span aufgerufen werden, ist der Wert des set_sql_body-Helpers maßgeblich und der Wert des set_body-Helpers wird ignoriert.

set_root_name

Dieses Attribut gilt für den gesamten Trace. Es kann an einem untergeordneten Span gesetzt werden und muss nicht am obersten übergeordneten Span gesetzt werden. Dieses Attribut kann nur einmal pro Trace gesetzt werden. Wenn es mehrfach gesetzt wird, wird nur das Attribut eines einzigen Spans im Trace angewendet.
Jeder Trace wird unter einem HTTP-Endpunkt, einem Worker-Namen für Hintergrundjobs oder einem Task-Namen gruppiert. Wir nennen diese Gruppe den „Action-Namen”. Um diesen Action-Namen für den gesamten Trace zu ändern, verwenden Sie den Helper set_root_name. Verwenden Sie einen Action-Namen, der allgemein genug ist, um alle Traces aus diesem Teil der App zu gruppieren, ohne jedes Mal unterschiedliche Namen zu melden. Setzen Sie GET /users/:id (wobei :id der Name des URL-Parameters ist) als Action-Namen anstelle von GET /users/123 (wobei 123 der tatsächliche Wert im Request ist). Letzteres würde für jeden eindeutigen Request einen neuen Incident melden.

Beispielanwendungsfall

Ihre Anwendung hat einen Endpunkt namens GET /coffee.
Alle Anfragen an diesen Endpunkt erzeugen Samples namens GET /coffee, aber Ihr Endpunkt behandelt mehrere Aktionen: coffee?action=buy und coffee?action=sell. Span ohne Root-Name Obwohl alle den Endpunkt GET /coffee verwenden, sind sie konzeptionell sehr unterschiedlich und es wäre daher sinnvoll, sie in AppSignal getrennt zu gruppieren, anstatt im selben GET /coffee-Sample. Dafür können Sie den Helper set_root_name verwenden:
Die Verwendung von set_root_name ändert den Namen des Root-Spans und gruppiert die Samples für die Anfragen coffee?action=buy und coffee?action=sell in getrennte Aktionen: Root-Name-Span

Andere Trace-Daten

Um die im Trace gespeicherten Daten noch weiter anzupassen, lesen Sie bitte unsere Leitfäden zu Tagging und Datenanpassung, um Tags, Parameter, Sitzungsdaten, benutzerdefinierte Daten und mehr hinzuzufügen.