> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Requêtes de traces
Lisez les données de traçage distribué avec l'[API publique
(V2)](/api/v2/overview) : 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](#trace-summary-fields),
soit des [spans](#span-fields), 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.
```shell Endpoint theme={null}
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.
```shell Endpoint theme={null}
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](#span-fields).
```json body.json theme={null}
{
"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](#span-fields) d'une
trace de performance ou d'erreur en utilisant le corps
[`TracesQuery`](#tracesquery).
## Lister les traces
Listez les traces de performance ou d'erreur.
```shell Endpoints theme={null}
POST /api/v2/tracing/traces/performance
POST /api/v2/tracing/traces/errors
```
Les deux prennent le corps [`TracesQuery`](#tracesquery) et renvoient un
tableau de [résumés de trace](#trace-summary-fields).
```json body.json theme={null}
{
"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.
```shell Endpoint theme={null}
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.
```shell Endpoints theme={null}
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 `"/"`, 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.
```shell Endpoints theme={null}
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.