> ## 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
> Rufen Sie Performance Samples und Error Traces vom Terminal aus ab und prüfen Sie deren Span Trees bis hinunter zu einem einzelnen Span.
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](/cli/authentication).
## Allgemeine Optionen
Jeder `traces`-Befehl identifiziert eine Anwendung und verwendet Ihre Standard-Organisation, sofern Sie es ihm nicht anders mitteilen:
| Flag | Beschreibung |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `--app ` | Anwendungsname (fügen Sie `--environment` hinzu, wenn mehr als eine App den Namen teilt) |
| `--environment ` | Environment, wird mit `--app` verwendet, wie `production` oder `development` |
| `--app-id ` | Die ID der App (eine lange hexadezimale Zeichenkette aus `appsignal-cli apps list`), anstelle von `--app` und `--environment` |
| `--org ` | 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:
```sh Shell theme={null}
appsignal-cli incidents show --app "MyApp" --environment development \
--number 9 --output json
```
Der Digest steht im Feld `digests`:
```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. Listen Sie die Traces für diesen Digest auf
Übergeben Sie den Digest an `traces errors`. Jede Zeile ist ein erfasstes Vorkommen:
```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.
```
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`:
```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)
```
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](#einen-einzelnen-span-pruefen).
Diese Schritte beginnen bei einem Exception Incident. Wenn Sie von etwas anderem ausgehen, verwenden Sie den passenden Befehl:
* **Ein Performance Incident:** `traces incident --number ` listet dessen Traces ohne Digest auf. Siehe [für einen Incident](#fuer-einen-incident).
* **Ein bekannter Namespace und eine bekannte Action:** `traces list --namespace --action `. Siehe [für eine Action](#fuer-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:
```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` erfordert `--namespace`, `--action` und eine App (`--app` oder `--app-id`) und nimmt diese zusätzlichen Optionen:
| Flag | Beschreibung |
| ------------------------ | ----------------------------------------------------------------------------------- |
| `--namespace ` | Namespace, in dem gesucht wird, z. B. `web`, `background`, `graphql` (erforderlich) |
| `--action ` | Action, für die Traces abgerufen werden, z. B. `GET /products` (erforderlich) |
| `--start ` | Startzeit, z. B. `2025-01-15T00:00:00Z` (Standard: vor 24 Stunden) |
| `--end ` | Endzeit (Standard: jetzt) |
| `--min-duration-ms ` | Nur Traces zurückgeben, die mindestens so viele Millisekunden lang sind |
| `--limit ` | Maximale Anzahl zurückzugebender Traces (1–100, Standard 25) |
| `--page-all` | Jeden Trace im Bereich abrufen, `--limit` ignorierend |
`--namespace` ist der AppSignal-[Namespace](/application/namespaces), 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 `: 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:
```sh Shell theme={null}
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`:
| Flag | Beschreibung |
| ------------------------ | ----------------------------------------------------------------------- |
| `--number ` | Nummer des Performance Incidents (erforderlich) |
| `--action ` | Die Suche auf eine Action beschränken, wenn der Incident mehrere hat |
| `--start ` | Startzeit (Standard: vor 24 Stunden) |
| `--end ` | Endzeit (Standard: jetzt) |
| `--min-duration-ms ` | Nur Traces zurückgeben, die mindestens so viele Millisekunden lang sind |
| `--limit ` | Maximale Traces pro Action (1–100, Standard 25) |
| `--page-all` | Jeden 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:
```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` 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:
```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)
```
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:
```sh Shell theme={null}
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:
```sh Shell theme={null}
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.
```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
```
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:
```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` 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.
```sh Shell theme={null}
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](/cli/incidents), um sie zu triagieren, oder arbeiten Sie sich für mehr Kontext durch Ihre [Logs](/cli/logs).