> ## 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
> Fetch performance samples and error traces from the terminal, then inspect their span trees down to a single span.
You can locate performance actions and error incidents associated with a trace.
Use the `samples` or `traces` commands (aliases) to fetch individual samples from AppSignal's tracing data. Traces show what happened during a request, job, or script run, and they can show the trace behind an exception.
List traces, then open one to view its span tree and inspect a single span's timings, tags, and attributes.
The command is available as `samples` or `traces`. `appsignal-cli traces list` and `appsignal-cli samples list` do the same thing. This page uses `traces` throughout.
Traces are retrieved through AppSignal's REST tracing API using your signed-in account, so authenticate the CLI first. See [Authentication](/cli/authentication).
## Common options
Every `traces` command identifies one application, and uses your default organization unless you tell it otherwise:
| Flag | Description |
| --------------------- | --------------------------------------------------------------------------------------------------------------- |
| `--app ` | Application name (add `--environment` when more than one app shares the name) |
| `--environment ` | Environment, used with `--app`, such as `production` or `development` |
| `--app-id ` | The app's ID (a long hexadecimal string from `appsignal-cli apps list`), instead of `--app` and `--environment` |
| `--org ` | Organization slug (uses your default if omitted) |
## Find a trace from an incident
Most investigations start from an incident, not a trace ID. These steps take you from an incident number to a single request's span tree, following a Laravel `PaymentDeclinedException` on `POST /checkout` (exception incident 9).
### 1. Read the incident's digest
Error traces are grouped by an exception digest. Read the digest from the incident, or copy it from the AppSignal app:
```sh Shell theme={null}
appsignal-cli incidents show --app "MyApp" --environment development \
--number 9 --output json
```
The digest is in the `digests` field:
```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. List the traces for that digest
Pass the digest to `traces errors`. Each row is one captured occurrence:
```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.
```
Copy the trace ID you want to inspect.
### 3. Inspect the trace
Pass the incident number and trace ID to `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)
```
The `!!` marks the span that raised the exception: here, `POST /checkout` right after the 334 ms `stripe.charge`. To inspect one span in full, add `--span-id` with the value from its `span:`. See [inspect a single span](#inspect-a-single-span).
These steps start from an exception incident. If you are starting from something else, use the matching command:
* **A performance incident:** `traces incident --number ` lists its traces without a digest. See [for an incident](#for-an-incident).
* **A known namespace and action:** `traces list --namespace --action `. See [for an action](#for-an-action).
## List traces
Three commands list traces, depending on what you start from: a performance action, an incident, or an exception digest. Each returns a table of trace IDs you can then pass to the inspect commands in the following section.
### For an action
List the recent performance samples for one namespace and 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` requires `--namespace`, `--action`, and an app (`--app` or `--app-id`), and takes these extra options:
| Flag | Description |
| ------------------------ | ---------------------------------------------------------------------- |
| `--namespace ` | Namespace to search in, e.g. `web`, `background`, `graphql` (required) |
| `--action ` | Action to fetch traces for, e.g. `GET /products` (required) |
| `--start ` | Start time, e.g. `2025-01-15T00:00:00Z` (defaults to 24 hours ago) |
| `--end ` | End time (defaults to now) |
| `--min-duration-ms ` | Only return traces at least this many milliseconds long |
| `--limit ` | Maximum traces to return (1–100, default 25) |
| `--page-all` | Fetch every trace in the range, ignoring `--limit` |
`--namespace` is the AppSignal [namespace](/application/namespaces) that groups the action, commonly `web`, `background`, `rake`, `runner`, or `graphql`. Your app may also define custom namespaces. If you are not sure which namespace an action belongs to, use `traces incident --number ` instead: it reads the namespace and action names straight from the performance incident, so you do not have to supply them yourself.
### For an incident
Skip the namespace and action lookup and list the samples behind a performance incident by its number:
```sh Shell theme={null}
appsignal-cli traces incident --app "MyApp" --environment development --number 17
```
If the incident spans several actions, the results are grouped by action. Pass `--action` to restrict the lookup to one of them. On top of the common options, `incident` takes:
| Flag | Description |
| ------------------------ | --------------------------------------------------------------- |
| `--number ` | Performance incident number (required) |
| `--action ` | Restrict the lookup to one action when the incident has several |
| `--start ` | Start time (defaults to 24 hours ago) |
| `--end ` | End time (defaults to now) |
| `--min-duration-ms ` | Only return traces at least this many milliseconds long |
| `--limit ` | Maximum traces per action (1–100, default 25) |
| `--page-all` | Fetch every trace for each action, ignoring `--limit` |
### Error traces for an exception
List the error traces behind an exception, identified by its 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` requires `--digest` and an app (`--app` or `--app-id`), and also takes `--limit` (1–100, default 25) and `--page-all`. Find the digest on the exception incident in the AppSignal app UI, or use `traces show-incident` in the following section to skip the digest entirely.
## Inspect a trace
Once you have a trace ID, open it to see the span tree: each span with its kind, duration, event count, and any exception, followed by a summary. Three commands do this, matching the three ways you listed the trace.
### From an action
Show a performance trace by its namespace, action, and 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)
```
Indentation shows the parent–child structure of the spans. A span carrying an exception is marked with `!!` and the exception type.
### From an exception digest
Show an error trace by its digest and trace ID:
```sh Shell theme={null}
appsignal-cli traces show-error --app "MyApp" --environment development \
--digest 3377052059360943972 \
--trace-id 92240dcdb4face2e36c8ba47372b50f1
```
Use the trace IDs returned by `traces errors` (or by `traces incident` for an exception incident).
### From an incident number
When you have an incident number rather than a namespace, action, or digest, `show-incident` checks the incident for you: from the number it looks up the namespace and action (or digest) so you do not have to supply them. You still choose which trace to inspect with `--trace-id`, so list the incident's traces first with `traces incident`:
```sh Shell theme={null}
appsignal-cli traces show-incident --app "MyApp" --environment development \
--number 17 --trace-id a1b2c3d4e5f60718293a4b5c6d7e8f90
```
### Inspect a single span
Add `--span-id` to any of the show commands to print one span's full detail instead of the tree: its timings, status, tags, span attributes, events, and 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
```
Take the span ID from the `span:` value at the end of each line in the span tree. If the ID isn't in the trace, the CLI lists what's available:
```
Error: Span 1b2c3d4e5f607182 not found in trace a1b2c3d4e5f60718293a4b5c6d7e8f90. Rerun without `--span-id` to see available span IDs.
```
### Sensitive data
By default, the show commands omit HTTP headers, request parameters, session data, and function parameters. Add `--include-sensitive` to show them:
```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` can print personal data and secrets captured in a request. Take care when sharing the output or piping it into another tool.
## Time range and pagination
`list`, `incident`, and the performance show commands look back 24 hours by default. Widen or move the window with `--start` and `--end` (ISO 8601, for example `2025-01-15T00:00:00Z`). If a trace is older than the default window, a lookup by ID reports that it wasn't found: rerun with an earlier `--start`.
`--limit` restricts a listing to at most 100 traces (25 by default). To fetch every trace in the range instead, use `--page-all`, which ignores `--limit`.
## JSON output
* Add the global `--output json` (or `--format json`) flag for machine-readable results.
* List commands (`traces list`, `traces incident`, `traces errors`) return a `traces` array.
* Show commands (`traces show`, `traces show-error`, `traces show-incident`) return the `trace_id` and its `spans`, plus a single `span` when you pass `--span-id`.
* This applies to both performance samples and error traces, and combines with `--page-all` to page through every result.
* Results (the JSON) are written to stdout while status messages are written to stderr, so piping the output to another tool never mixes in non-JSON text.
```sh Shell theme={null}
appsignal-cli --output json traces list --app "MyApp" --environment development \
--namespace "Laravel Service/web" --action "GET /products" --page-all
```
## Next steps
Tracked a slow request or an error back to its trace? Open the related [incidents](/cli/incidents) to triage them, or work through your [logs](/cli/logs) for more context.