Zum Hauptinhalt springen
Sie können Performance Actions und Error Incidents finden, die einem Trace zugeordnet sind. Verwenden Sie die Befehle samples oder traces (Aliase), um einzelne Samples aus den Tracing-Daten von AppSignal abzurufen. Traces zeigen, was während einer Request, eines Jobs oder einer Skriptausführung passiert ist, und sie können den Trace hinter einer Exception anzeigen. Listen Sie Traces auf und öffnen Sie dann einen, um dessen Span Tree anzuzeigen und die Timings, Tags und Attributes eines einzelnen Spans zu prüfen. Der Befehl ist als samples oder traces verfügbar. appsignal-cli traces list und appsignal-cli samples list bewirken dasselbe. Diese Seite verwendet durchgehend traces.
Traces werden über die REST tracing API von AppSignal mit Ihrem angemeldeten Konto abgerufen. Authentifizieren Sie die CLI daher zuerst. Siehe Authentifizierung.

​
Allgemeine Optionen

Jeder traces-Befehl identifiziert eine Anwendung und verwendet Ihre Standard-Organisation, sofern Sie es ihm nicht anders mitteilen:
FlagBeschreibung
--app <name>Anwendungsname (fügen Sie --environment hinzu, wenn mehr als eine App den Namen teilt)
--environment <env>Environment, wird mit --app verwendet, wie production oder development
--app-id <id>Die ID der App (eine lange hexadezimale Zeichenkette aus appsignal-cli apps list), anstelle von --app und --environment
--org <slug>Organisations-Slug (verwendet Ihren Standard, wenn weggelassen)

​
Einen Trace über einen Incident finden

Die meisten Untersuchungen beginnen bei einem Incident, nicht bei einer Trace-ID. Diese Schritte führen Sie von einer Incident-Nummer zum Span Tree einer einzelnen Request, anhand einer Laravel PaymentDeclinedException auf POST /checkout (Exception Incident 9).

​
1. Lesen Sie den Digest des Incidents

Error Traces werden nach einem Exception Digest gruppiert. Lesen Sie den Digest aus dem Incident oder kopieren Sie ihn aus der AppSignal-App:
Shell
appsignal-cli incidents show --app "MyApp" --environment development \
  --number 9 --output json
Der Digest steht im Feld 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. Listen Sie die Traces für diesen Digest auf

Übergeben Sie den Digest an traces errors. Jede Zeile ist ein erfasstes Vorkommen:
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.
Kopieren Sie die Trace-ID, die Sie prüfen möchten.

​
3. Prüfen Sie den Trace

Übergeben Sie die Incident-Nummer und die Trace-ID an 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)
Das !! markiert den Span, der die Exception ausgelöst hat: hier POST /checkout direkt nach dem 334 ms langen stripe.charge. Um einen Span vollständig zu prüfen, fügen Sie --span-id mit dem Wert aus dessen span: hinzu. Siehe einen einzelnen Span prüfen. Diese Schritte beginnen bei einem Exception Incident. Wenn Sie von etwas anderem ausgehen, verwenden Sie den passenden Befehl:
  • Ein Performance Incident: traces incident --number <N> listet dessen Traces ohne Digest auf. Siehe für einen Incident.
  • Ein bekannter Namespace und eine bekannte Action: traces list --namespace <name> --action <name>. Siehe für eine Action.

​
Traces auflisten

Drei Befehle listen Traces auf, je nachdem, wovon Sie ausgehen: von einer Performance Action, einem Incident oder einem Exception Digest. Jeder gibt eine Tabelle von Trace-IDs zurück, die Sie dann an die Inspect-Befehle im folgenden Abschnitt übergeben können.

​
Für eine Action

Listen Sie die aktuellen Performance Samples für einen Namespace und eine Action auf:
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 erfordert --namespace, --action und eine App (--app oder --app-id) und nimmt diese zusätzlichen Optionen:
FlagBeschreibung
--namespace <name>Namespace, in dem gesucht wird, z. B. web, background, graphql (erforderlich)
--action <name>Action, für die Traces abgerufen werden, z. B. GET /products (erforderlich)
--start <ISO8601>Startzeit, z. B. 2025-01-15T00:00:00Z (Standard: vor 24 Stunden)
--end <ISO8601>Endzeit (Standard: jetzt)
--min-duration-ms <ms>Nur Traces zurückgeben, die mindestens so viele Millisekunden lang sind
--limit <N>Maximale Anzahl zurückzugebender Traces (1–100, Standard 25)
--page-allJeden Trace im Bereich abrufen, --limit ignorierend
--namespace ist der AppSignal-Namespace, der die Action gruppiert, gewöhnlich web, background, rake, runner oder graphql. Ihre App kann auch eigene Namespaces definieren. Wenn Sie nicht sicher sind, zu welchem Namespace eine Action gehört, verwenden Sie stattdessen traces incident --number <N>: es liest die Namespace- und Action-Namen direkt vom Performance Incident, sodass Sie sie nicht selbst angeben müssen.

​
Für einen Incident

Überspringen Sie die Namespace- und Action-Suche und listen Sie die Samples hinter einem Performance Incident anhand seiner Nummer auf:
Shell
appsignal-cli traces incident --app "MyApp" --environment development --number 17
Wenn sich der Incident über mehrere Actions erstreckt, werden die Ergebnisse nach Action gruppiert. Übergeben Sie --action, um die Suche auf eine davon zu beschränken. Zusätzlich zu den allgemeinen Optionen nimmt incident:
FlagBeschreibung
--number <N>Nummer des Performance Incidents (erforderlich)
--action <name>Die Suche auf eine Action beschränken, wenn der Incident mehrere hat
--start <ISO8601>Startzeit (Standard: vor 24 Stunden)
--end <ISO8601>Endzeit (Standard: jetzt)
--min-duration-ms <ms>Nur Traces zurückgeben, die mindestens so viele Millisekunden lang sind
--limit <N>Maximale Traces pro Action (1–100, Standard 25)
--page-allJeden Trace für jede Action abrufen, --limit ignorierend

​
Error Traces für eine Exception

Listen Sie die Error Traces hinter einer Exception auf, identifiziert über ihren 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 erfordert --digest und eine App (--app oder --app-id) und nimmt außerdem --limit (1–100, Standard 25) und --page-all. Finden Sie den Digest auf dem Exception Incident in der AppSignal-App-UI oder verwenden Sie traces show-incident im folgenden Abschnitt, um den Digest komplett zu überspringen.

​
Einen Trace prüfen

Sobald Sie eine Trace-ID haben, öffnen Sie sie, um den Span Tree zu sehen: jeden Span mit seiner Art, Dauer, Anzahl der Events und einer möglichen Exception, gefolgt von einer Zusammenfassung. Drei Befehle erledigen dies, passend zu den drei Möglichkeiten, den Trace aufzulisten.

​
Aus einer Action

Zeigen Sie einen Performance Trace anhand seines Namespaces, seiner Action und Trace-ID an:
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)
Die Einrückung zeigt die Eltern-Kind-Struktur der Spans. Ein Span, der eine Exception trägt, wird mit !! und dem Exception-Typ gekennzeichnet.

​
Aus einem Exception Digest

Zeigen Sie einen Error Trace anhand seines Digests und seiner Trace-ID an:
Shell
appsignal-cli traces show-error --app "MyApp" --environment development \
  --digest 3377052059360943972 \
  --trace-id 92240dcdb4face2e36c8ba47372b50f1
Verwenden Sie die Trace-IDs, die von traces errors (oder von traces incident für einen Exception Incident) zurückgegeben werden.

​
Aus einer Incident-Nummer

Wenn Sie eine Incident-Nummer statt eines Namespaces, einer Action oder eines Digests haben, prüft show-incident den Incident für Sie: anhand der Nummer sucht es den Namespace und die Action (oder den Digest) heraus, sodass Sie sie nicht selbst angeben müssen. Sie wählen weiterhin mit --trace-id aus, welchen Trace Sie prüfen möchten, listen Sie also zunächst die Traces des Incidents mit traces incident auf:
Shell
appsignal-cli traces show-incident --app "MyApp" --environment development \
  --number 17 --trace-id a1b2c3d4e5f60718293a4b5c6d7e8f90

​
Einen einzelnen Span prüfen

Fügen Sie --span-id zu einem der Show-Befehle hinzu, um die vollständigen Details eines Spans anstelle des Trees auszugeben: seine Timings, Status, Tags, Span Attributes, Events und Resource Attributes.
Shell
appsignal-cli traces show --app "MyApp" --environment development \
  --namespace "Laravel Service/web" --action "GET /products" \
  --trace-id a1b2c3d4e5f60718293a4b5c6d7e8f90 \
  --span-id 1b2c3d4e5f607182
Entnehmen Sie die Span-ID dem span:-Wert am Ende jeder Zeile im Span Tree. Wenn die ID nicht im Trace enthalten ist, listet die CLI auf, was verfügbar ist: 
Error: Span 1b2c3d4e5f607182 not found in trace a1b2c3d4e5f60718293a4b5c6d7e8f90. Rerun without `--span-id` to see available span IDs.

​
Sensible Daten

Standardmäßig lassen die Show-Befehle HTTP Headers, Request-Parameter, Session-Daten und Funktionsparameter weg. Fügen Sie --include-sensitive hinzu, um sie anzuzeigen:
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 kann personenbezogene Daten und Geheimnisse ausgeben, die in einer Request erfasst wurden. Seien Sie vorsichtig, wenn Sie die Ausgabe teilen oder in ein anderes Tool weiterleiten.

​
Zeitbereich und Paginierung

list, incident und die Performance-Show-Befehle schauen standardmäßig 24 Stunden zurück. Erweitern oder verschieben Sie das Fenster mit --start und --end (ISO 8601, zum Beispiel 2025-01-15T00:00:00Z). Wenn ein Trace älter als das Standardfenster ist, meldet eine Suche per ID, dass er nicht gefunden wurde: führen Sie ihn mit einem früheren --start erneut aus. --limit begrenzt eine Auflistung auf bis zu 100 Traces (standardmäßig 25). Um stattdessen jeden Trace im Bereich abzurufen, verwenden Sie --page-all, das --limit ignoriert.

​
JSON-Ausgabe

  • Fügen Sie das globale Flag --output json (oder --format json) für maschinenlesbare Ergebnisse hinzu.
  • Die List-Befehle (traces list, traces incident, traces errors) geben ein traces-Array zurück.
  • Die Show-Befehle (traces show, traces show-error, traces show-incident) geben die trace_id und ihre spans zurück, plus einen einzelnen span, wenn Sie --span-id übergeben.
  • Dies gilt sowohl für Performance Samples als auch für Error Traces und lässt sich mit --page-all kombinieren, um durch jedes Ergebnis zu paginieren.
  • Ergebnisse (das JSON) werden nach stdout geschrieben, während Statusmeldungen nach stderr geschrieben werden, sodass beim Weiterleiten der Ausgabe an ein anderes Tool niemals Nicht-JSON-Text hineingemischt wird.
Shell
appsignal-cli --output json traces list --app "MyApp" --environment development \
  --namespace "Laravel Service/web" --action "GET /products" --page-all

​
Nächste Schritte

Eine langsame Request oder einen Fehler zu ihrem Trace zurückverfolgt? Öffnen Sie die zugehörigen Incidents, um sie zu triagieren, oder arbeiten Sie sich für mehr Kontext durch Ihre Logs.