Traces - AppSignal Documentation

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.

Options communes

Chaque commande traces identifie une application et utilise votre organisation par défaut sauf indication contraire :

Drapeau	Description
`--app <name>`	Nom de l’application (ajoutez `--environment` lorsque plusieurs applications partagent le nom)
`--environment <env>`	Environment, utilisé avec `--app`, comme `production` ou `development`
`--app-id <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>`	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 :

Shell

appsignal-cli incidents show --app "MyApp" --environment development \
  --number 9 --output json

Le digest se trouve dans le champ digests :

{
  "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 :

Shell

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 :

Shell

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. Ces étapes commencent à partir d’un exception incident. Si vous partez d’autre chose, utilisez la commande correspondante :

Un performance incident : traces incident --number <N> liste ses traces sans digest. Voir pour un incident.
Un namespace et une action connus : traces list --namespace <name> --action <name>. Voir 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 :

Shell

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 <name>`	Namespace dans lequel chercher, par exemple `web`, `background`, `graphql` (obligatoire)
`--action <name>`	Action pour laquelle récupérer les traces, par exemple `GET /products` (obligatoire)
`--start <ISO8601>`	Heure de début, par exemple `2025-01-15T00:00:00Z` (par défaut, il y a 24 heures)
`--end <ISO8601>`	Heure de fin (par défaut, maintenant)
`--min-duration-ms <ms>`	Ne renvoie que les traces d’au moins cette durée en millisecondes
`--limit <N>`	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 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 <N> : 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 :

Shell

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 <N>`	Numéro du performance incident (obligatoire)
`--action <name>`	Restreindre la recherche à une seule action lorsque l’incident en compte plusieurs
`--start <ISO8601>`	Heure de début (par défaut, il y a 24 heures)
`--end <ISO8601>`	Heure de fin (par défaut, maintenant)
`--min-duration-ms <ms>`	Ne renvoie que les traces d’au moins cette durée en millisecondes
`--limit <N>`	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 :

Shell

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 :

Shell

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 :

Shell

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 :

Shell

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.

Shell

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 :

Shell

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.

Shell

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 associés pour les trier, ou parcourez vos logs pour obtenir plus de contexte.

​Options communes

​Trouver un trace à partir d’un incident

​1. Lisez le digest de l’incident

​2. Listez les traces pour ce digest

​3. Inspectez le trace

​Lister les traces

​Pour une action

​Pour un incident

​Error traces pour une exception

​Inspecter un trace

​À partir d’une action

​À partir d’un exception digest

​À partir d’un numéro d’incident

​Inspecter un span individuel

​Données sensibles

​Plage temporelle et pagination

​Sortie JSON

​Étapes suivantes

Options communes

Trouver un trace à partir d’un incident

1. Lisez le digest de l’incident

2. Listez les traces pour ce digest

3. Inspectez le trace

Lister les traces

Pour une action

Pour un incident

Error traces pour une exception

Inspecter un trace

À partir d’une action

À partir d’un exception digest

À partir d’un numéro d’incident

Inspecter un span individuel

Données sensibles

Plage temporelle et pagination

Sortie JSON

Étapes suivantes