Passer au contenu principal
Lisez les données de traçage distribué avec l’API publique (V2). Tous les points de terminaison s’authentifient avec votre jeton d’API personnel. Cette page explique comment les points de terminaison de traçage s’articulent. Pour chaque champ de chaque requête et réponse, consultez la référence des points de terminaison de traçage. Certains points de terminaison prennent un tableau site_ids, afin de pouvoir effectuer des recherches sur plusieurs sites en une seule requête. Les autres prennent un seul site_id.

Localiser une trace

Trouvez les actions de performance et les incidents d’erreur dans lesquels une trace apparaît, à travers les sites.
Le corps de la requête prend site_ids (un tableau de chaînes) et trace_id (une chaîne). La réponse contient des entrées performance, avec le namespace et l’action_name, et des entrées errors, avec l’incident_number et l’exception_name. Chaque entrée errors contient aussi des incident_digests. Passez-les comme digests aux points de terminaison de traces d’erreur.

Obtenir les spans d’une trace

Renvoie chaque span d’une trace.
Le corps de la requête prend site_ids (un tableau de chaînes) et trace_id (une chaîne). Pour renvoyer aussi les spans d’autres traces liées à celle-ci, définissez include_linked_spans sur true.
Deux autres points de terminaison renvoient les spans d’une trace sans avoir besoin de son ID :
  • POST /api/v2/tracing/trace/performance prend un action_name et un namespace.
  • POST /api/v2/tracing/trace/error prend les digests d’un incident d’erreur.
Les deux renvoient la trace correspondante la plus récente. Pour en récupérer une précise, ajoutez son trace_id.

Lister les traces

Listez les traces de performance ou d’erreur.
Les deux points de terminaison prennent des filtres différents :
  • traces/performance nécessite un action_name et un namespace. Ajoutez duration_ms pour ne lister que les traces d’au moins cette durée. Ajoutez from et to pour définir une plage temporelle.
  • traces/errors nécessite les digests des incidents d’erreur. Il n’a pas de plage temporelle.
Les deux acceptent une query optionnelle pour filtrer par révision ou par tag, et les deux nécessitent un objet pagination.
pagination nécessite ces trois champs :
  • per_page : combien de traces renvoyer par page, jusqu’à 100.
  • order : ASC ou DESC.
  • cursor : { "time": null } pour trier par heure de trace, ou { "duration": null } pour trier par durée de trace. null commence à la première page.
Chaque trace de la réponse a un trace_id, le time auquel la trace a commencé, et sa duration totale en millisecondes.
Pour filtrer sur un tag qui contient un ID complet, utilisez =, comme dans tag.request_id=<id>. Un : est une correspondance de sous-chaîne beaucoup plus lente : il lit chaque span ayant ce tag dans la plage temporelle. Si une telle requête reçoit un 429 et que la valeur est un UUID, la suggestion de la réponse montre la forme avec =.

Rechercher des traces

Recherchez des données d’erreur et de performance sur plusieurs sites, par action, exception, tag ou message.
Le corps nécessite site_ids : au moins un site, tous dans le même compte. La query optionnelle fonctionne ainsi :
  • Les mots isolés correspondent exactement à un nom d’action, un nom d’exception ou une valeur de tag, comme une seule phrase.
  • action:, error: et tag: correspondent exactement à un champ.
  • message: correspond à une phrase de mots entiers, sans tenir compte de la casse.
Mettez entre guillemets les valeurs contenant des espaces. Pour affiner les résultats, ajoutez un namespace, une plage from et to, ou un kind. kind vaut all (par défaut), exception ou performance. Par défaut, from correspond au début de la rétention de votre compte, et to à l’heure actuelle. La réponse contient jusqu’à limit résultats, les plus récents en premier. limit vaut 50 par défaut et est plafonné à 2 000. Chaque résultat est un digest d’incident d’un span correspondant, donc un trace_id peut apparaître plusieurs fois.

Lister les actions de performance

Listez les actions de performance avec des métriques agrégées.
Le corps de la requête prend site_id, from, to, et les filtres optionnels namespaces (tableau), revision et action. Vous obtenez en retour un tableau de lignes d’action, chacune avec namespace, action, digest, mean (ms), throughput, error_rate (0–100) et has_npo (indique si une requête N+1 a été détectée).

Arêtes de dépendances de services

Cartographiez les relations de traçage distribué entre les actions et les services.
action_edges renvoie les arêtes upstream (appelants) et downstream (appelés) pour une action ciblée. Son corps prend site_id, namespace (sous la forme "<service>/<namespace>", telle que "PublicApi/web"), action, from et to. site_edges renvoie les arêtes upstream, downstream et internal pour un site ciblé. Son corps prend site_id, from et to. Dans les deux cas, from est inclus et to est exclu. Chaque arête indique le service pair, le count de requêtes, error_count, mean (ms) et les durées p_90 / p_95. Les arêtes d’action incluent également les namespace et action pairs, les types de span caller_kind et callee_kind, et edge_type (SYNC ou ASYNC).

Événements lents

Analysez les opérations lentes au sein des traces, telles que les requêtes de base de données lentes.
slow_events renvoie jusqu’à 100 événements lents agrégés. Son corps prend site_id, from, to et wanted_attributes. Vous pouvez aussi ajouter ces filtres :
  • span_kind : n’inclure qu’un seul type de span : Client, Server, Internal, Producer ou Consumer.
  • excluded_attributes : exclure les spans qui ont l’une des clés d’attribut listées.
wanted_attributes nomme les attributs de span à renvoyer. Regroupez-les sous des noms en minuscules de votre choix, comme payload. Chaque groupe est soit Required, soit Optional :
  • Required n’inclut que les spans où au moins une des clés listées a une valeur.
  • Optional renvoie la valeur lorsqu’elle est définie, et ne filtre pas les spans.
Lorsqu’un groupe liste plusieurs clés, il renvoie la valeur de la première clé qui en a une. En plus des clés d’attribut de span, un groupe peut lister appsignal.library. Elle renvoie la bibliothèque avec laquelle AppSignal a instrumenté le span, comme active_record, et est vide pour les autres spans. Par exemple, "system": { "Optional": ["db.system.name", "db.system", "appsignal.library"] } renvoie le système de base de données lorsque le span en enregistre un, et la bibliothèque sinon. Les spans stockés avant fin juillet 2026 la renvoient vide. La requête nécessite au moins un groupe Required, sinon elle renvoie un 400. Cette requête liste les requêtes de base de données lentes, avec le texte de la requête et le système de base de données :
Chaque résultat a un digest, un count, une mean (ms) et un score d’impact. Chaque groupe de wanted_attributes est renvoyé sous sa propre clé, comme "payload": "SELECT * FROM users WHERE id = ?". slow_events/actions liste les actions dans lesquelles apparaît un événement lent. Son corps prend site_id, from, to et le digest issu de slow_events. Chaque résultat a un action_name, un namespace et un count, plus le trace_id et le start_time de l’occurrence la plus récente.

Principaux événements par groupe

Classez les événements d’un ou plusieurs groupes d’événements, comme les requêtes active_record, par temps total, durée moyenne ou débit.
Le corps prend site_id, from, to et groups : au moins un groupe d’événements, comme ["active_record", "moped"]. AppSignal étend from et to à des intervalles resolution complets. order classe les événements par IMPACT (par défaut), MEAN ou THROUGHPUT. limit accepte de 1 à 1 000 lignes et vaut 1 000 par défaut. Chaque ligne contient le digest, le group et le name de l’événement, comme sql.active_record. Elle contient un title, et un body tel que le texte de la requête. Elle contient aussi le count, la durée mean en millisecondes, et l’impact : le temps total passé, count fois mean. Certains événements sont écartés après le classement, donc moins de lignes que limit peuvent être renvoyées.

Examiner les incidents d’erreur

Comptez les erreurs de chaque incident, puis voyez ce que les incidents ont en commun.
tracing/errors compte les erreurs par incident. Son corps prend site_id, from et to, et vous pouvez filtrer par namespaces et revision. Chaque ligne contient un incident_digest, son namespace et sa dernière revision, et un error_count. La réponse inclut chaque incident correspondant, sans tri. Pour trouver les incidents ayant le plus d’erreurs, triez les lignes par error_count. metadata_distributions ventile les incidents selon leurs métadonnées, comme hostname. Son corps prend site_id, les incident_digests à inclure, from et group_by :
  • KEY liste chaque clé de métadonnées, avec son nombre total d’occurrences (total) et le nombre de valeurs uniques (unique).
  • VALUE liste les valeurs de la clé que vous définissez dans metadata_key. Dans chaque ligne, key contient la valeur et value le nombre de ses occurrences.
Par défaut, to correspond à l’heure actuelle. limit accepte de 1 à 1 000 lignes. Il vaut 10 lignes par défaut en mode VALUE, et aucune limite par défaut en mode KEY. Pour voir les traces derrière un incident, passez son digest à traces/errors ou trace/error.