Requêtes de traces - AppSignal Documentation

Lisez les données de traçage distribué avec l’API publique (V2) : listez les traces de performance et d’erreur, récupérez les spans d’une seule trace, inspectez les actions agrégées et les dépendances de services, et analysez les événements lents. Tous les points de terminaison s’authentifient avec votre jeton d’API personnel. Les points de terminaison de trace utilisent un tableau site_ids afin de pouvoir effectuer des recherches sur plusieurs sites en une seule requête. La plupart des points de terminaison de liste et de détail partagent le corps TracesQuery et renvoient soit des résumés de trace, soit des spans, décrits à la fin de cette page.

Localiser une trace

Trouvez les actions de performance et les incidents d’erreur dans lesquels une trace apparaît, à travers les sites.

POST /api/v2/tracing/locator

Le corps de la requête prend site_ids (un tableau de chaînes) et trace_id (une chaîne). En retour, vous obtenez un TraceLocation avec des entrées performance (site_id, namespace, action_name) et des entrées errors (site_id, incident_number, exception_name).

Obtenir les spans d’une trace

Renvoie chaque span d’une trace.

POST /api/v2/tracing/trace

Le corps de la requête prend site_ids (un tableau de chaînes) et trace_id (une chaîne), et renvoie un tableau de spans.

{
  "site_ids": ["YOUR-SITE-ID"],
  "trace_id": "YOUR-TRACE-ID"
}

Les points de terminaison POST /api/v2/tracing/trace/performance et POST /api/v2/tracing/trace/error renvoient les spans d’une trace de performance ou d’erreur en utilisant le corps TracesQuery.

Lister les traces

Listez les traces de performance ou d’erreur.

POST /api/v2/tracing/traces/performance
POST /api/v2/tracing/traces/errors

Les deux prennent le corps TracesQuery et renvoient un tableau de résumés de trace.

{
  "site_ids": ["YOUR-SITE-ID"],
  "action_name": "POST /api/users",
  "namespace": "web",
  "from": "2026-06-22T00:00:00Z",
  "to": "2026-06-22T23:59:59Z",
  "pagination": { "per_page": 50, "order": "DESC", "cursor": "Time" }
}

pagination prend per_page, order et une clé cursor. Définissez cursor sur Time pour paginer par heure de trace ou Duration pour paginer par durée totale de la trace.

TracesQuery

Champ	Type	Obligatoire	Description
`site_ids`	chaîne[]	Oui	Sites à interroger.
`pagination`	objet	Oui	Paramètres de pagination. Définissez `cursor` sur `Time` ou `Duration`.
`digests`	chaîne[]	Non	Filtrer par digests de trace.
`action_name`	chaîne	Non	Filtrer par nom d’action.
`namespace`	chaîne	Non	Filtrer par namespace.
`query`	chaîne	Non	Requête de recherche en texte libre.
`duration`	nombre (ms)	Non	Filtre de durée minimale.
`from`	chaîne (ISO 8601)	Non	Début de la plage temporelle.
`to`	chaîne (ISO 8601)	Non	Fin de la plage temporelle.
`ttl`	nombre	Non	Limite de rétention en secondes.

Lister les actions de performance

Listez les actions de performance avec des métriques agrégées.

POST /api/v2/tracing/actions

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.

POST /api/v2/tracing/action_edges
POST /api/v2/tracing/site_edges

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. 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, action, types de span pairs 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.

POST /api/v2/tracing/slow_events
POST /api/v2/tracing/slow_events/actions

slow_events renvoie les événements lents agrégés. Son corps prend site_id, from, to, un span_kind optionnel, wanted_attributes, excluded_attributes et une limit (par défaut 100). Chaque résultat a un digest, count, mean (ms), score d’impact et attributes. slow_events/actions liste les actions dans lesquelles un événement lent apparaît, par digest. Son corps prend site_id, from, to et digest. Chaque résultat a un action_name, namespace, count, trace_id et start_time.

Champs de résumé de trace

Les points de terminaison de liste renvoient des résumés de trace avec ces champs :

Champ	Type	Description
`trace_id`	chaîne	Identifiant pour toute la trace.
`span_id`	chaîne	Identifiant pour le span racine.
`site_id`	chaîne	Site auquel appartient la trace.
`namespace`	chaîne	Namespace, tel que `web` ou `background`.
`action_name`	chaîne	Nom de l’action, tel que `POST /api/users`.
`revision`	chaîne	Révision de déploiement active lors de l’enregistrement.
`time`	chaîne (ISO 8601)	Quand la trace s’est terminée.
`duration`	nombre	Durée totale en millisecondes.
`tags`	objet	Tags définis par l’utilisateur à partir des attributs de span.
`has_npo`	booléen	Indique si une requête N+1 a été détectée.

Champs de span

Les points de terminaison de détail de trace renvoient des spans. Chaque span inclut le timing (start_time, end_time, duration en ms), l’identité (trace_id, span_id, parent_span_id, digest) et le contexte (service_name, namespace, revision, action_name, span_name, span_kind, scope_name, scope_version). Le statut est rapporté avec status_code (comme OK ou ERROR) et status_message. Les détails structurés sont renvoyés sous forme d’objets et de tableaux : resource_attributes et span_attributes (objets), events (avec les tableaux events.timestamp, events.name et events.attributes) et links (avec les tableaux links.trace_id, links.span_id, links.trace_state et links.attributes). subtrace_root indique si le span commence une frontière de service distincte.

​Localiser une trace

​Obtenir les spans d’une trace

​Lister les traces

​TracesQuery

​Lister les actions de performance

​Arêtes de dépendances de services

​Événements lents

​Champs de résumé de trace

​Champs de span