> ## 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.
# Traces
> Récupérez des performance samples et des error traces depuis le terminal, puis inspectez leurs span trees jusqu'à un span individuel.
Vous pouvez localiser les performance actions et error incidents associés à un trace.
Utilisez les commandes `samples` ou `traces` (alias) pour récupérer des samples individuels depuis les données de tracing d'AppSignal. Les traces montrent ce qui s'est passé pendant une request, un job ou l'exécution d'un script, et peuvent afficher le trace derrière une exception.
Listez les traces, puis ouvrez-en un pour voir son span tree et inspecter les timings, tags et attributes d'un span individuel.
La commande est disponible sous le nom `samples` ou `traces`. `appsignal-cli traces list` et `appsignal-cli samples list` font la même chose. Cette page utilise `traces` partout.
Les traces sont récupérées via la REST tracing API d'AppSignal en utilisant votre compte connecté, donc authentifiez d'abord la CLI. Voir [Authentification](/cli/authentication).
## Options communes
Chaque commande `traces` identifie une application et utilise votre organisation par défaut sauf indication contraire :
| Drapeau | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `--app ` | Nom de l'application (ajoutez `--environment` lorsque plusieurs applications partagent le nom) |
| `--environment ` | Environment, utilisé avec `--app`, comme `production` ou `development` |
| `--app-id ` | ID de l'application (une longue chaîne hexadécimale obtenue via `appsignal-cli apps list`), à la place de `--app` et `--environment` |
| `--org ` | Slug de l'organisation (utilise votre organisation par défaut si omis) |
## Trouver un trace à partir d'un incident
La plupart des investigations commencent par un incident, pas par un trace ID. Ces étapes vous mènent d'un numéro d'incident au span tree d'une seule request, en suivant une `PaymentDeclinedException` Laravel sur `POST /checkout` (exception incident 9).
### 1. Lisez le digest de l'incident
Les error traces sont regroupées par exception digest. Lisez le digest depuis l'incident, ou copiez-le depuis l'AppSignal app :
```sh Shell theme={null}
appsignal-cli incidents show --app "MyApp" --environment development \
--number 9 --output json
```
Le digest se trouve dans le champ `digests` :
```json theme={null}
{
"incident": {
"number": 9,
"exceptionName": "App\\Exceptions\\PaymentDeclinedException",
"exceptionMessage": "Card was declined: insufficient_funds (amount $129.99)",
"actionNames": ["POST /checkout"],
"namespace": "Laravel Service/web",
"digests": ["3377052059360943972"]
}
}
```
### 2. Listez les traces pour ce digest
Passez le digest à `traces errors`. Chaque ligne correspond à une occurrence capturée :
```sh Shell theme={null}
appsignal-cli traces errors --app "MyApp" --environment development \
--digest 3377052059360943972
```
```
Error traces for digest 3377052059360943972
+----------------------------------+----------+--------------------------+----------------+
| TRACE ID | DURATION | TIME | ACTION |
+----------------------------------+----------+--------------------------+----------------+
| 92240dcdb4face2e36c8ba47372b50f1 | 466.0ms | 2026-06-24T11:30:45.376Z | POST /checkout |
| 964fccaae622462e39c7b2f14238cc5a | 970.0ms | 2026-06-24T11:30:34.867Z | POST /checkout |
| 781e8f5fec07ffa849c5bc5e7b8eaaa2 | 683.0ms | 2026-06-24T11:29:03.529Z | POST /checkout |
+----------------------------------+----------+--------------------------+----------------+
3 error trace(s) found.
```
Copiez le trace ID que vous souhaitez inspecter.
### 3. Inspectez le trace
Passez le numéro d'incident et le trace ID à `traces show-incident` :
```sh Shell theme={null}
appsignal-cli traces show-incident --app "MyApp" --environment development \
--number 9 --trace-id 92240dcdb4face2e36c8ba47372b50f1
```
```
Span tree for sample/trace 92240dcdb4face2e36c8ba47372b50f1
POST /checkout [server] 466.0ms 1 event(s) !! App\Exceptions\PaymentDeclinedException span:7a6bfdf173a4b5ed
SELECT * FROM carts WHERE user_id = ? [internal] 7.0ms span:c215afea3041cb8d
SELECT * FROM cart_items WHERE cart_id = ? [internal] 18.0ms span:567513335ff37ff6
stripe.charge [client] 334.0ms span:9b280149985e2272
INSERT INTO orders (...) VALUES (...) [internal] 15.0ms span:a30563643f738120
mail.send [internal] 78.0ms span:966158dc67ebaaa1
Total spans: 6
Error spans: 1
Slowest span: POST /checkout (466.0ms)
```
Le `!!` marque le span qui a levé l'exception : ici, `POST /checkout` juste après le `stripe.charge` de 334 ms. Pour inspecter un span en entier, ajoutez `--span-id` avec la valeur de son `span:`. Voir [inspecter un span individuel](#inspecter-un-span-individuel).
Ces étapes commencent à partir d'un exception incident. Si vous partez d'autre chose, utilisez la commande correspondante :
* **Un performance incident :** `traces incident --number ` liste ses traces sans digest. Voir [pour un incident](#pour-un-incident).
* **Un namespace et une action connus :** `traces list --namespace --action `. Voir [pour une action](#pour-une-action).
## Lister les traces
Trois commandes listent les traces, selon votre point de départ : une performance action, un incident ou un exception digest. Chacune renvoie un tableau de trace IDs que vous pouvez ensuite passer aux commandes d'inspection de la section suivante.
### Pour une action
Listez les performance samples récents pour un namespace et une action :
```sh Shell theme={null}
appsignal-cli traces list --app "MyApp" --environment development \
--namespace "Laravel Service/web" --action "GET /products"
```
```
Performance samples/traces for Laravel Service/web / GET /products
Time range: 2026-07-02T00:00:00Z to 2026-07-03T00:00:00Z
+----------------------------------+-----------+----------------------+---------------+
| TRACE ID | DURATION | TIME | ACTION |
+----------------------------------+-----------+----------------------+---------------+
| a1b2c3d4e5f60718293a4b5c6d7e8f90 | 1120.0ms | 2026-07-02T14:12:07Z | GET /products |
| 3c4d5e6f708192a3b4c5d6e7f8091a2b | 842.0ms | 2026-07-02T14:03:51Z | GET /products |
| 9f8e7d6c5b4a30291827a6b5c4d3e2f1 | 631.0ms | 2026-07-02T13:58:19Z | GET /products |
+----------------------------------+-----------+----------------------+---------------+
3 sample(s)/trace(s) found.
```
`list` requiert `--namespace`, `--action` et une application (`--app` ou `--app-id`), et prend ces options supplémentaires :
| Drapeau | Description |
| ------------------------ | ---------------------------------------------------------------------------------------- |
| `--namespace ` | Namespace dans lequel chercher, par exemple `web`, `background`, `graphql` (obligatoire) |
| `--action ` | Action pour laquelle récupérer les traces, par exemple `GET /products` (obligatoire) |
| `--start ` | Heure de début, par exemple `2025-01-15T00:00:00Z` (par défaut, il y a 24 heures) |
| `--end ` | Heure de fin (par défaut, maintenant) |
| `--min-duration-ms ` | Ne renvoie que les traces d'au moins cette durée en millisecondes |
| `--limit ` | Nombre maximum de traces à renvoyer (1–100, par défaut 25) |
| `--page-all` | Récupérer toutes les traces dans la plage, en ignorant `--limit` |
`--namespace` est le [namespace](/application/namespaces) AppSignal qui regroupe l'action, généralement `web`, `background`, `rake`, `runner` ou `graphql`. Votre application peut également définir des namespaces personnalisés. Si vous n'êtes pas sûr du namespace auquel appartient une action, utilisez plutôt `traces incident --number ` : il lit les noms de namespace et d'action directement depuis le performance incident, vous n'avez donc pas à les fournir vous-même.
### Pour un incident
Sautez la recherche par namespace et action et listez les samples derrière un performance incident par son numéro :
```sh Shell theme={null}
appsignal-cli traces incident --app "MyApp" --environment development --number 17
```
Si l'incident couvre plusieurs actions, les résultats sont regroupés par action. Passez `--action` pour restreindre la recherche à l'une d'elles. En plus des options communes, `incident` prend :
| Drapeau | Description |
| ------------------------ | ---------------------------------------------------------------------------------- |
| `--number ` | Numéro du performance incident (obligatoire) |
| `--action ` | Restreindre la recherche à une seule action lorsque l'incident en compte plusieurs |
| `--start ` | Heure de début (par défaut, il y a 24 heures) |
| `--end ` | Heure de fin (par défaut, maintenant) |
| `--min-duration-ms ` | Ne renvoie que les traces d'au moins cette durée en millisecondes |
| `--limit ` | Nombre maximum de traces par action (1–100, par défaut 25) |
| `--page-all` | Récupérer toutes les traces pour chaque action, en ignorant `--limit` |
### Error traces pour une exception
Listez les error traces derrière une exception, identifiée par son digest :
```sh Shell theme={null}
appsignal-cli traces errors --app "MyApp" --environment development \
--digest 3377052059360943972
```
```
Error traces for digest 3377052059360943972
+----------------------------------+----------+--------------------------+----------------+
| TRACE ID | DURATION | TIME | ACTION |
+----------------------------------+----------+--------------------------+----------------+
| 92240dcdb4face2e36c8ba47372b50f1 | 466.0ms | 2026-06-24T11:30:45.376Z | POST /checkout |
+----------------------------------+----------+--------------------------+----------------+
1 error trace(s) found.
```
`errors` requiert `--digest` et une application (`--app` ou `--app-id`), et prend également `--limit` (1–100, par défaut 25) et `--page-all`. Trouvez le digest sur l'exception incident dans l'AppSignal app UI, ou utilisez `traces show-incident` dans la section suivante pour éviter complètement le digest.
## Inspecter un trace
Une fois que vous avez un trace ID, ouvrez-le pour voir le span tree : chaque span avec son kind, sa durée, son nombre d'events et toute exception, suivi d'un résumé. Trois commandes font cela, correspondant aux trois façons dont vous avez listé le trace.
### À partir d'une action
Affichez un performance trace par son namespace, son action et son trace ID :
```sh Shell theme={null}
appsignal-cli traces show --app "MyApp" --environment development \
--namespace "Laravel Service/background" --action "ProcessPaymentJob" \
--trace-id 8b75a80874e7c930c7d1d28c96d82e6c
```
```
Span tree for sample/trace 8b75a80874e7c930c7d1d28c96d82e6c
ProcessPaymentJob [consumer] 537.0ms 1 event(s) !! App\Exceptions\PaymentGatewayTimeoutException span:6a1d23690f4aff3d
SELECT * FROM payments WHERE id = ? [internal] 8.0ms span:8988f5f9e1155049
stripe.capture [client] 518.0ms span:f403c766e07bc10e
Total spans: 3
Error spans: 1
Slowest span: ProcessPaymentJob (537.0ms)
```
L'indentation montre la structure parent-enfant des spans. Un span portant une exception est marqué avec `!!` et le type d'exception.
### À partir d'un exception digest
Affichez un error trace par son digest et son trace ID :
```sh Shell theme={null}
appsignal-cli traces show-error --app "MyApp" --environment development \
--digest 3377052059360943972 \
--trace-id 92240dcdb4face2e36c8ba47372b50f1
```
Utilisez les trace IDs renvoyés par `traces errors` (ou par `traces incident` pour un exception incident).
### À partir d'un numéro d'incident
Lorsque vous disposez d'un numéro d'incident plutôt que d'un namespace, d'une action ou d'un digest, `show-incident` vérifie l'incident pour vous : à partir du numéro, il recherche le namespace et l'action (ou le digest), vous n'avez donc pas à les fournir. Vous choisissez toujours quel trace inspecter avec `--trace-id`, donc listez d'abord les traces de l'incident avec `traces incident` :
```sh Shell theme={null}
appsignal-cli traces show-incident --app "MyApp" --environment development \
--number 17 --trace-id a1b2c3d4e5f60718293a4b5c6d7e8f90
```
### Inspecter un span individuel
Ajoutez `--span-id` à n'importe laquelle des commandes `show` pour afficher les détails complets d'un span au lieu du tree : ses timings, son status, ses tags, ses span attributes, ses events et ses resource attributes.
```sh Shell theme={null}
appsignal-cli traces show --app "MyApp" --environment development \
--namespace "Laravel Service/web" --action "GET /products" \
--trace-id a1b2c3d4e5f60718293a4b5c6d7e8f90 \
--span-id 1b2c3d4e5f607182
```
Prenez le span ID dans la valeur `span:` à la fin de chaque ligne du span tree. Si l'ID n'est pas dans le trace, la CLI liste ceux qui sont disponibles :
```
Error: Span 1b2c3d4e5f607182 not found in trace a1b2c3d4e5f60718293a4b5c6d7e8f90. Rerun without `--span-id` to see available span IDs.
```
### Données sensibles
Par défaut, les commandes `show` omettent les HTTP headers, les paramètres de request, les données de session et les paramètres de fonction. Ajoutez `--include-sensitive` pour les afficher :
```sh Shell theme={null}
appsignal-cli traces show --app "MyApp" --environment development \
--namespace "Laravel Service/web" --action "GET /products" \
--trace-id a1b2c3d4e5f60718293a4b5c6d7e8f90 \
--span-id 0a1b2c3d4e5f6071 --include-sensitive
```
`--include-sensitive` peut afficher des données personnelles et des secrets capturés dans une request. Soyez prudent lorsque vous partagez la sortie ou la redirigez vers un autre outil.
## Plage temporelle et pagination
`list`, `incident` et les commandes `show` de performance remontent de 24 heures par défaut. Élargissez ou déplacez la fenêtre avec `--start` et `--end` (ISO 8601, par exemple `2025-01-15T00:00:00Z`). Si un trace est plus ancien que la fenêtre par défaut, une recherche par ID indique qu'il n'a pas été trouvé : relancez avec un `--start` antérieur.
`--limit` plafonne un listage jusqu'à 100 traces (25 par défaut). Pour récupérer toutes les traces de la plage à la place, utilisez `--page-all`, qui ignore `--limit`.
## Sortie JSON
* Ajoutez le drapeau global `--output json` (ou `--format json`) pour des résultats lisibles par machine.
* Les commandes de listage (`traces list`, `traces incident`, `traces errors`) renvoient un tableau `traces`.
* Les commandes `show` (`traces show`, `traces show-error`, `traces show-incident`) renvoient le `trace_id` et ses `spans`, plus un unique `span` lorsque vous passez `--span-id`.
* Cela s'applique aussi bien aux performance samples qu'aux error traces, et se combine avec `--page-all` pour paginer sur tous les résultats.
* Les résultats (le JSON) sont écrits sur stdout tandis que les messages de statut sont écrits sur stderr, donc rediriger la sortie vers un autre outil ne mélange jamais de texte non-JSON.
```sh Shell theme={null}
appsignal-cli --output json traces list --app "MyApp" --environment development \
--namespace "Laravel Service/web" --action "GET /products" --page-all
```
## Étapes suivantes
Vous avez retracé une request lente ou une erreur jusqu'à son trace ? Ouvrez les [incidents](/cli/incidents) associés pour les trier, ou parcourez vos [logs](/cli/logs) pour obtenir plus de contexte.