> ## 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
> Haal performance samples en error traces op vanuit de terminal en inspecteer vervolgens hun span trees tot op één span.
U kunt performance actions en error incidents vinden die aan een trace gekoppeld zijn.
Gebruik de `samples`- of `traces`-commando's (aliassen) om individuele samples op te halen uit AppSignal's tracing-data. Traces tonen wat er gebeurde tijdens een request, job of scriptuitvoering, en ze kunnen de trace achter een exception tonen.
Som traces op en open er vervolgens één om de span tree te bekijken en de timings, tags en attributes van één span te inspecteren.
Het commando is beschikbaar als `samples` of `traces`. `appsignal-cli traces list` en `appsignal-cli samples list` doen hetzelfde. Deze pagina gebruikt overal `traces`.
Traces worden opgehaald via AppSignal's REST tracing API met uw ingelogde account, dus authenticeer eerst de CLI. Zie [Authenticatie](/cli/authentication).
## Gemeenschappelijke opties
Elk `traces`-commando identificeert één applicatie en gebruikt uw standaardorganisatie tenzij u anders aangeeft:
| Flag | Beschrijving |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `--app ` | Applicatienaam (voeg `--environment` toe wanneer meer dan één app de naam deelt) |
| `--environment ` | Environment, gebruikt met `--app`, zoals `production` of `development` |
| `--app-id ` | Het ID van de app (een lange hexadecimale string uit `appsignal-cli apps list`), in plaats van `--app` en `--environment` |
| `--org ` | Organisatie-slug (gebruikt uw standaard indien weggelaten) |
## Een trace vinden vanuit een incident
De meeste onderzoeken beginnen bij een incident, niet bij een trace-ID. Deze stappen brengen u van een incidentnummer naar de span tree van één request, aan de hand van een Laravel `PaymentDeclinedException` op `POST /checkout` (exception incident 9).
### 1. Lees de digest van het incident
Error traces worden gegroepeerd op exception digest. Lees de digest uit het incident, of kopieer deze uit de AppSignal-app:
```sh Shell theme={null}
appsignal-cli incidents show --app "MyApp" --environment development \
--number 9 --output json
```
De digest staat in het `digests`-veld:
```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. Som de traces op voor die digest
Geef de digest door aan `traces errors`. Elke rij is één vastgelegd voorkomen:
```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.
```
Kopieer de trace-ID die u wilt inspecteren.
### 3. Inspecteer de trace
Geef het incidentnummer en de trace-ID door aan `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)
```
De `!!` markeert de span die de exception heeft veroorzaakt: hier `POST /checkout`, direct na de 334 ms `stripe.charge`. Om één span volledig te inspecteren, voegt u `--span-id` toe met de waarde uit de `span:`. Zie [één span inspecteren](#één-span-inspecteren).
Deze stappen beginnen vanuit een exception incident. Als u vanuit iets anders start, gebruik dan het bijbehorende commando:
* **Een performance incident:** `traces incident --number ` lijst zijn traces zonder digest. Zie [voor een incident](#voor-een-incident).
* **Een bekende namespace en action:** `traces list --namespace --action `. Zie [voor een action](#voor-een-action).
## Traces opsommen
Drie commando's sommen traces op, afhankelijk van waar u begint: een performance action, een incident of een exception digest. Elk retourneert een tabel met trace-ID's die u vervolgens kunt doorgeven aan de inspect-commando's in de volgende sectie.
### Voor een action
Som de recente performance samples op voor één namespace en 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` vereist `--namespace`, `--action` en een app (`--app` of `--app-id`), en neemt deze aanvullende opties:
| Flag | Beschrijving |
| ------------------------ | --------------------------------------------------------------------------- |
| `--namespace ` | Namespace om in te zoeken, bijv. `web`, `background`, `graphql` (verplicht) |
| `--action ` | Action om traces voor op te halen, bijv. `GET /products` (verplicht) |
| `--start ` | Starttijd, bijv. `2025-01-15T00:00:00Z` (standaard 24 uur geleden) |
| `--end ` | Eindtijd (standaard nu) |
| `--min-duration-ms ` | Retourneer alleen traces die minstens dit aantal milliseconden lang zijn |
| `--limit ` | Maximaal aantal te retourneren traces (1–100, standaard 25) |
| `--page-all` | Haal elke trace in het bereik op, waarbij `--limit` wordt genegeerd |
`--namespace` is de AppSignal [namespace](/application/namespaces) die de action groepeert, gewoonlijk `web`, `background`, `rake`, `runner` of `graphql`. Uw app kan ook custom namespaces definiëren. Als u niet zeker weet tot welke namespace een action behoort, gebruik dan `traces incident --number `: dit leest de namespace- en action-namen direct uit het performance incident, zodat u ze niet zelf hoeft op te geven.
### Voor een incident
Sla de opzoeking van namespace en action over en som de samples achter een performance incident op op nummer:
```sh Shell theme={null}
appsignal-cli traces incident --app "MyApp" --environment development --number 17
```
Als het incident meerdere actions omvat, worden de resultaten per action gegroepeerd. Geef `--action` door om de opzoeking tot één ervan te beperken. Bovenop de gemeenschappelijke opties neemt `incident`:
| Flag | Beschrijving |
| ------------------------ | ------------------------------------------------------------------------- |
| `--number ` | Nummer van het performance incident (verplicht) |
| `--action ` | Beperk de opzoeking tot één action wanneer het incident er meerdere heeft |
| `--start ` | Starttijd (standaard 24 uur geleden) |
| `--end ` | Eindtijd (standaard nu) |
| `--min-duration-ms ` | Retourneer alleen traces die minstens dit aantal milliseconden lang zijn |
| `--limit ` | Maximaal aantal traces per action (1–100, standaard 25) |
| `--page-all` | Haal elke trace voor elke action op, waarbij `--limit` wordt genegeerd |
### Error traces voor een exception
Som de error traces op achter een exception, geïdentificeerd door de digest ervan:
```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` vereist `--digest` en een app (`--app` of `--app-id`), en neemt ook `--limit` (1–100, standaard 25) en `--page-all`. Vind de digest op het exception incident in de AppSignal-app-UI, of gebruik `traces show-incident` in de volgende sectie om de digest volledig over te slaan.
## Een trace inspecteren
Zodra u een trace-ID heeft, opent u deze om de span tree te zien: elke span met zijn kind, duur, aantal events en eventuele exception, gevolgd door een samenvatting. Drie commando's doen dit, overeenkomend met de drie manieren waarop u de trace opsomde.
### Vanuit een action
Toon een performance trace op basis van de namespace, action en trace-ID ervan:
```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)
```
Inspringing toont de ouder-kind-structuur van de spans. Een span die een exception draagt, wordt gemarkeerd met `!!` en het exception-type.
### Vanuit een exception digest
Toon een error trace op basis van de digest en trace-ID ervan:
```sh Shell theme={null}
appsignal-cli traces show-error --app "MyApp" --environment development \
--digest 3377052059360943972 \
--trace-id 92240dcdb4face2e36c8ba47372b50f1
```
Gebruik de trace-ID's die worden geretourneerd door `traces errors` (of door `traces incident` voor een exception incident).
### Vanuit een incidentnummer
Wanneer u een incidentnummer heeft in plaats van een namespace, action of digest, controleert `show-incident` het incident voor u: aan de hand van het nummer zoekt het de namespace en action (of digest) op, zodat u ze niet hoeft aan te leveren. U kiest nog steeds welke trace u wilt inspecteren met `--trace-id`, dus lijst eerst de traces van het incident op met `traces incident`:
```sh Shell theme={null}
appsignal-cli traces show-incident --app "MyApp" --environment development \
--number 17 --trace-id a1b2c3d4e5f60718293a4b5c6d7e8f90
```
### Één span inspecteren
Voeg `--span-id` toe aan elk van de show-commando's om de volledige details van één span te printen in plaats van de tree: de timings, status, tags, span-attributes, events en 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
```
Neem het span-ID van de `span:`-waarde aan het einde van elke regel in de span tree. Als het ID niet in de trace zit, somt de CLI op wat beschikbaar is:
```
Error: Span 1b2c3d4e5f607182 not found in trace a1b2c3d4e5f60718293a4b5c6d7e8f90. Rerun without `--span-id` to see available span IDs.
```
### Gevoelige gegevens
Standaard laten de show-commando's HTTP-headers, request-parameters, sessiegegevens en functieparameters weg. Voeg `--include-sensitive` toe om ze te tonen:
```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` kan persoonlijke gegevens en geheimen printen die in een request zijn vastgelegd. Wees voorzichtig bij het delen van de output of bij het doorsluizen ervan naar een andere tool.
## Tijdsbereik en paginering
`list`, `incident` en de performance show-commando's kijken standaard 24 uur terug. Verbreed of verplaats het venster met `--start` en `--end` (ISO 8601, bijvoorbeeld `2025-01-15T00:00:00Z`). Als een trace ouder is dan het standaardvenster, meldt een opzoeking op ID dat deze niet werd gevonden: voer opnieuw uit met een eerdere `--start`.
`--limit` beperkt een listing tot maximaal 100 traces (standaard 25). Om in plaats daarvan elke trace in het bereik op te halen, gebruikt u `--page-all`, dat `--limit` negeert.
## JSON-output
* Voeg de globale `--output json` (of `--format json`) flag toe voor machineleesbare resultaten.
* List-commando's (`traces list`, `traces incident`, `traces errors`) retourneren een `traces`-array.
* Show-commando's (`traces show`, `traces show-error`, `traces show-incident`) retourneren het `trace_id` en de bijbehorende `spans`, plus een enkele `span` wanneer u `--span-id` doorgeeft.
* Dit geldt voor zowel performance samples als error traces, en combineert met `--page-all` om door elk resultaat te pagineren.
* Resultaten (de JSON) worden naar stdout geschreven, terwijl statusberichten naar stderr worden geschreven, zodat het doorsluizen van de output naar een ander tool nooit niet-JSON tekst mengt.
```sh Shell theme={null}
appsignal-cli --output json traces list --app "MyApp" --environment development \
--namespace "Laravel Service/web" --action "GET /products" --page-all
```
## Volgende stappen
Een trage request of een fout teruggeleid naar de bijbehorende trace? Open de gerelateerde [incidents](/cli/incidents) om ze te triageren, of werk uw [logs](/cli/logs) door voor meer context.