Traces - AppSignal Documentation

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.

Gemeenschappelijke opties

Elk traces-commando identificeert één applicatie en gebruikt uw standaardorganisatie tenzij u anders aangeeft:

Flag	Beschrijving
`--app <name>`	Applicatienaam (voeg `--environment` toe wanneer meer dan één app de naam deelt)
`--environment <env>`	Environment, gebruikt met `--app`, zoals `production` of `development`
`--app-id <id>`	Het ID van de app (een lange hexadecimale string uit `appsignal-cli apps list`), in plaats van `--app` en `--environment`
`--org <slug>`	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:

Shell

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

De digest staat in het digests-veld:

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

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.

Kopieer de trace-ID die u wilt inspecteren.

3. Inspecteer de trace

Geef het incidentnummer en de trace-ID door aan 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)

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. Deze stappen beginnen vanuit een exception incident. Als u vanuit iets anders start, gebruik dan het bijbehorende commando:

Een performance incident: traces incident --number <N> lijst zijn traces zonder digest. Zie voor een incident.
Een bekende namespace en action: traces list --namespace <name> --action <name>. Zie 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:

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 vereist --namespace, --action en een app (--app of --app-id), en neemt deze aanvullende opties:

Flag	Beschrijving
`--namespace <name>`	Namespace om in te zoeken, bijv. `web`, `background`, `graphql` (verplicht)
`--action <name>`	Action om traces voor op te halen, bijv. `GET /products` (verplicht)
`--start <ISO8601>`	Starttijd, bijv. `2025-01-15T00:00:00Z` (standaard 24 uur geleden)
`--end <ISO8601>`	Eindtijd (standaard nu)
`--min-duration-ms <ms>`	Retourneer alleen traces die minstens dit aantal milliseconden lang zijn
`--limit <N>`	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 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 <N>: 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:

Shell

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 <N>`	Nummer van het performance incident (verplicht)
`--action <name>`	Beperk de opzoeking tot één action wanneer het incident er meerdere heeft
`--start <ISO8601>`	Starttijd (standaard 24 uur geleden)
`--end <ISO8601>`	Eindtijd (standaard nu)
`--min-duration-ms <ms>`	Retourneer alleen traces die minstens dit aantal milliseconden lang zijn
`--limit <N>`	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:

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

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)

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:

Shell

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:

Shell

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.

Shell

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:

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

Shell

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 om ze te triageren, of werk uw logs door voor meer context.

​Gemeenschappelijke opties

​Een trace vinden vanuit een incident

​1. Lees de digest van het incident

​2. Som de traces op voor die digest

​3. Inspecteer de trace

​Traces opsommen

​Voor een action

​Voor een incident

​Error traces voor een exception

​Een trace inspecteren

​Vanuit een action

​Vanuit een exception digest

​Vanuit een incidentnummer

​Één span inspecteren

​Gevoelige gegevens

​Tijdsbereik en paginering

​JSON-output

​Volgende stappen

Gemeenschappelijke opties

Een trace vinden vanuit een incident

1. Lees de digest van het incident

2. Som de traces op voor die digest

3. Inspecteer de trace

Traces opsommen

Voor een action

Voor een incident

Error traces voor een exception

Een trace inspecteren

Vanuit een action

Vanuit een exception digest

Vanuit een incidentnummer

Één span inspecteren

Gevoelige gegevens

Tijdsbereik en paginering

JSON-output

Volgende stappen