Traces - AppSignal Documentation

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.

Common options

Every traces command identifies one application, and uses your default organization unless you tell it otherwise:

Flag	Description
`--app <name>`	Application name (add `--environment` when more than one app shares the name)
`--environment <env>`	Environment, used with `--app`, such as `production` or `development`
`--app-id <id>`	The app’s ID (a long hexadecimal string from `appsignal-cli apps list`), instead of `--app` and `--environment`
`--org <slug>`	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:

Shell

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

The digest is in the digests field:

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

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.

Copy the trace ID you want to inspect.

3. Inspect the trace

Pass the incident number and trace ID to 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)

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. These steps start from an exception incident. If you are starting from something else, use the matching command:

A performance incident: traces incident --number <N> lists its traces without a digest. See for an incident.
A known namespace and action: traces list --namespace <name> --action <name>. See 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:

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 requires --namespace, --action, and an app (--app or --app-id), and takes these extra options:

Flag	Description
`--namespace <name>`	Namespace to search in, e.g. `web`, `background`, `graphql` (required)
`--action <name>`	Action to fetch traces for, e.g. `GET /products` (required)
`--start <ISO8601>`	Start time, e.g. `2025-01-15T00:00:00Z` (defaults to 24 hours ago)
`--end <ISO8601>`	End time (defaults to now)
`--min-duration-ms <ms>`	Only return traces at least this many milliseconds long
`--limit <N>`	Maximum traces to return (1–100, default 25)
`--page-all`	Fetch every trace in the range, ignoring `--limit`

--namespace is the AppSignal namespace 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 <N> 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:

Shell

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 <N>`	Performance incident number (required)
`--action <name>`	Restrict the lookup to one action when the incident has several
`--start <ISO8601>`	Start time (defaults to 24 hours ago)
`--end <ISO8601>`	End time (defaults to now)
`--min-duration-ms <ms>`	Only return traces at least this many milliseconds long
`--limit <N>`	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:

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

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)

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:

Shell

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:

Shell

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.

Shell

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:

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 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.

Shell

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 to triage them, or work through your logs for more context.

​Common options

​Find a trace from an incident

​1. Read the incident’s digest

​2. List the traces for that digest

​3. Inspect the trace

​List traces

​For an action

​For an incident

​Error traces for an exception

​Inspect a trace

​From an action

​From an exception digest

​From an incident number

​Inspect a single span

​Sensitive data

​Time range and pagination

​JSON output

​Next steps

Common options

Find a trace from an incident

1. Read the incident’s digest

2. List the traces for that digest

3. Inspect the trace

List traces

For an action

For an incident

Error traces for an exception

Inspect a trace

From an action

From an exception digest

From an incident number

Inspect a single span

Sensitive data

Time range and pagination

JSON output

Next steps