L’inclusion d’une instrumentation personnalisée dans votre application peut être utile pour identifier les lignes de code spécifiques à l’origine de problèmes de performance.
AppSignal pour Python utilise les objets tracer d’OpenTelemetry ; vous pouvez en savoir plus sur les traces Python dans le Cookbook Python d’OpenTelemetry.
Les traces sont constituées d’un ou plusieurs spans. On peut considérer une trace comme un graphe acyclique orienté (DAG) de spans :
Des attributs spécifiques à AppSignal doivent être ajoutés à un span pour qu’il soit correctement analysé par AppSignal. Notre ensemble de méthodes helper peut être utilisé pour définir ces attributs.
Cette documentation explique comment créer des instrumentations personnalisées en définissant des attributs spécifiques à AppSignal dans les spans de votre application Python.
Créer un span
Lorsque vous ajoutez une instrumentation personnalisée, importez d’abord le module trace d’OpenTelemetry dans le fichier auquel vous souhaitez ajouter l’instrumentation.
from opentelemetry import trace
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("Span name"):
# Here you can execute your app logic
# And set AppSignal span details:
from appsignal import set_category
set_category("category.name")
Scripts ponctuels et serverless
Lorsque vous exécutez des scripts ponctuels ou des fonctions serverless, vous devez initialiser manuellement AppSignal et l’arrêter à la fin pour vous assurer qu’aucune donnée n’est perdue. Le helper stop arrêtera proprement le processus d’agent et attendra un certain temps pour s’assurer que toutes les données sont envoyées aux serveurs AppSignal.
appsignal = Appsignal(
active=True,
name="My Python App",
push_api_key="YOUR_PUSH_API_KEY",
)
appsignal.start()
# Your code here along with the instrumentation
# ...
appsignal.stop()
Méthodes helper
Les méthodes helper décrites dans cette section ne sont pas compatibles avec le
collector AppSignal. set_category
La catégorie du span est le nom qui apparaît dans la chronologie des événements de performance pour les traces. Elle est également utilisée pour regrouper les spans afin de créer une répartition par groupe sur la page de détail de l’échantillon.
from appsignal import set_category
set_category("category.name")
set_category("query.users")
set_category("update.users")
set_category("view.users")
.) pour exprimer l’héritage hiérarchique de l’événement, avec l’unité la plus élevée en dernier. Pour plus d’informations sur les catégories de span, veuillez consulter le guide sur les noms d’événements.
set_name
Plus de détails peuvent être ajoutés au span ; ils sont visibles au survol de l’événement dans la chronologie des événements. Le nom du span est utilisé pour fournir plus d’informations sur l’événement, telles que « Fetch users », la base de données depuis laquelle les utilisateurs sont récupérés ou l’URL qui a été demandée.
from appsignal import set_name
set_name("Fetch users")
start_as_current_span a été appelée sera utilisée.
set_body
🔐 N’envoyez pas d’informations personnelles identifiables (PII) à AppSignal. Filtrez les PII (par exemple, noms, e-mails) et utilisez un identifiant, un hash ou un identifiant pseudonymisé à la place.
Pour les entités couvertes par la HIPAA, plus d’informations sur la signature d’un Business Associate Agreement (BAA) sont disponibles dans notre documentation Business Add-Ons. set_sql_body à la place.
from appsignal import set_body
set_body("Span body")
set_sql_body
Disponible depuis le package Python 0.3.2.
set_body, mais est spécialisé pour les requêtes SQL. Toute requête SQL définie comme corps avec cet attribut sera assainie pour éviter d’envoyer des données PII (Personal Identifiable Information) à nos serveurs.
Voir le helper set_body pour plus de détails sur le fonctionnement de l’attribut body.
Lorsque les helpers set_body et set_sql_body sont tous deux appelés sur le même span, la valeur du helper set_sql_body est prioritaire et la valeur du helper set_body sera ignorée.
from appsignal import set_sql_body
set_body("SELECT * FROM users")
set_root_name
Cet attribut s’applique à l’ensemble de la trace. Il peut être défini sur un span enfant et n’a pas besoin d’être défini sur le span parent le plus haut. Cet attribut ne peut être défini qu’une seule fois par trace. S’il est défini plusieurs fois, seul l’attribut d’un seul span de la trace est appliqué.
set_root_name.
Utilisez un nom d’action suffisamment générique pour regrouper toutes les traces de cette partie de l’application, sans signaler des noms différents à chaque fois. Définissez GET /users/:id (où :id est le nom du paramètre d’URL) comme nom d’action, au lieu de GET /users/123 (où 123 est la valeur réelle fournie dans la requête). Ce dernier signalerait un nouvel incident pour chaque requête unique.
from appsignal import set_root_name
set_root_name("GET /custom")
# With URL parameters
set_root_name("GET /users/:id")
Exemple de cas d’utilisation
Votre application a un endpoint appelé GET /coffee.
def coffee(request):
return render(request, "coffee.html", {})
GET /coffee, mais votre endpoint gère plusieurs actions : coffee?action=buy et coffee?action=sell.
Bien qu’ils utilisent tous l’endpoint GET /coffee, ils sont conceptuellement très différents et il serait donc logique qu’ils soient regroupés séparément dans AppSignal plutôt que dans le même échantillon GET /coffee. Pour ce faire, vous pouvez utiliser le helper set_root_name :
from appsignal import set_root_name
def coffee(request):
if request.GET.action == "buy":
set_root_name("Buy coffee")
# Buy coffee...
elif request.GET.action == "sell":
set_root_name("Sell coffee")
# Sell coffee...
return render(request, "coffee.html", {})
set_root_name modifiera le nom du span racine, regroupant les échantillons des requêtes coffee?action=buy et coffee?action=sell en actions distinctes :
Autres données de trace
Pour personnaliser encore davantage les données stockées sur la trace, veuillez consulter nos guides sur le Tagging et la Personnalisation des données pour ajouter des tags, des paramètres, des données de session, des données personnalisées et plus encore. 