> ## 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 abfragen
Lesen Sie verteilte Tracing-Daten mit der [Public API (V2)](/api/v2/overview):
Listen Sie Performance- und Error-Traces auf, holen Sie die Spans eines einzelnen
Traces, untersuchen Sie aggregierte Aktionen und Service-Abhängigkeiten und
analysieren Sie langsame Ereignisse. Alle Endpunkte authentifizieren sich mit
Ihrem persönlichen API-Token. Die Trace-Endpunkte verwenden ein `site_ids`-Array,
sodass sie in einer einzigen Anfrage über mehrere Sites hinweg suchen können.
Die meisten Listen- und Detail-Endpunkte teilen sich den `TracesQuery`-Body und
geben entweder [Trace-Zusammenfassungen](#trace-summary-fields) oder
[Spans](#span-fields) zurück, die am Ende dieser Seite beschrieben werden.
## Einen Trace lokalisieren
Finden Sie die Performance-Aktionen und Error-Incidents, in denen ein Trace über
Sites hinweg erscheint.
```shell Endpoint theme={null}
POST /api/v2/tracing/locator
```
Der Request-Body nimmt `site_ids` (ein String-Array) und `trace_id` (einen
String) entgegen. Zurück erhalten Sie eine `TraceLocation` mit
`performance`-Einträgen (`site_id`, `namespace`, `action_name`) und
`errors`-Einträgen (`site_id`, `incident_number`, `exception_name`).
## Die Spans eines Traces abrufen
Gibt jeden Span in einem Trace zurück.
```shell Endpoint theme={null}
POST /api/v2/tracing/trace
```
Der Request-Body nimmt `site_ids` (ein String-Array) und `trace_id` (einen String)
entgegen und gibt ein Array von [Spans](#span-fields) zurück.
```json body.json theme={null}
{
"site_ids": ["YOUR-SITE-ID"],
"trace_id": "YOUR-TRACE-ID"
}
```
Die Endpunkte `POST /api/v2/tracing/trace/performance` und
`POST /api/v2/tracing/trace/error` geben die [Spans](#span-fields) eines
Performance- oder Error-Traces über den [`TracesQuery`](#tracesquery)-Body zurück.
## Traces auflisten
Listen Sie Performance- oder Error-Traces auf.
```shell Endpoints theme={null}
POST /api/v2/tracing/traces/performance
POST /api/v2/tracing/traces/errors
```
Beide nehmen den [`TracesQuery`](#tracesquery)-Body entgegen und geben ein Array
von [Trace-Zusammenfassungen](#trace-summary-fields) zurück.
```json body.json theme={null}
{
"site_ids": ["YOUR-SITE-ID"],
"action_name": "POST /api/users",
"namespace": "web",
"from": "2026-06-22T00:00:00Z",
"to": "2026-06-22T23:59:59Z",
"pagination": { "per_page": 50, "order": "DESC", "cursor": "Time" }
}
```
`pagination` nimmt `per_page`, `order` und einen `cursor`-Schlüssel entgegen.
Setzen Sie `cursor` auf `Time`, um nach Trace-Zeit zu paginieren, oder auf
`Duration`, um nach Gesamtdauer des Traces zu paginieren.
### TracesQuery
| Feld | Typ | Erforderlich | Beschreibung |
| ------------- | ----------------- | ------------ | -------------------------------------------------------------------------- |
| `site_ids` | string\[] | Ja | Abzufragende Sites. |
| `pagination` | object | Ja | Paginierungseinstellungen. Setzen Sie `cursor` auf `Time` oder `Duration`. |
| `digests` | string\[] | Nein | Nach Trace-Digests filtern. |
| `action_name` | string | Nein | Nach Aktionsname filtern. |
| `namespace` | string | Nein | Nach Namespace filtern. |
| `query` | string | Nein | Freitext-Suchabfrage. |
| `duration` | number (ms) | Nein | Filter für Mindestdauer. |
| `from` | string (ISO 8601) | Nein | Start des Zeitbereichs. |
| `to` | string (ISO 8601) | Nein | Ende des Zeitbereichs. |
| `ttl` | number | Nein | Aufbewahrungsgrenze in Sekunden. |
## Performance-Aktionen auflisten
Listen Sie Performance-Aktionen mit aggregierten Metriken auf.
```shell Endpoint theme={null}
POST /api/v2/tracing/actions
```
Der Request-Body nimmt `site_id`, `from`, `to` sowie die optionalen Filter
`namespaces` (Array), `revision` und `action` entgegen. Zurück erhalten Sie ein
Array von Aktionszeilen, jede mit `namespace`, `action`, `digest`, `mean` (ms),
`throughput`, `error_rate` (0–100) und `has_npo` (ob eine N+1-Abfrage erkannt wurde).
## Service-Abhängigkeits-Edges
Bilden Sie verteilte Tracing-Beziehungen zwischen Aktionen und Services ab.
```shell Endpoints theme={null}
POST /api/v2/tracing/action_edges
POST /api/v2/tracing/site_edges
```
`action_edges` gibt die `upstream`- (Aufrufer) und `downstream`-Edges (Aufgerufene)
für eine fokussierte Aktion zurück. Sein Body nimmt `site_id`, `namespace` (in
der Form `"/"`, etwa `"PublicApi/web"`), `action`, `from` und
`to` entgegen.
`site_edges` gibt `upstream`-, `downstream`- und `internal`-Edges für eine
fokussierte Site zurück. Sein Body nimmt `site_id`, `from` und `to` entgegen.
Jede Edge meldet den `service` des Peers, die Anfrage-`count`, `error_count`,
`mean` (ms) und `p_90`/`p_95`-Dauern. Action-Edges enthalten zusätzlich den
`namespace` des Peers, `action`, Span-Arten und `edge_type` (`SYNC` oder `ASYNC`).
## Langsame Ereignisse
Analysieren Sie langsame Operationen innerhalb von Traces, etwa langsame
Datenbankabfragen.
```shell Endpoints theme={null}
POST /api/v2/tracing/slow_events
POST /api/v2/tracing/slow_events/actions
```
`slow_events` gibt aggregierte langsame Ereignisse zurück. Sein Body nimmt
`site_id`, `from`, `to`, ein optionales `span_kind`, `wanted_attributes`,
`excluded_attributes` und ein `limit` (Standard: 100) entgegen. Jedes Ergebnis hat
einen `digest`, `count`, `mean` (ms), einen `impact`-Score und `attributes`.
`slow_events/actions` listet die Aktionen auf, in denen ein langsames Ereignis
nach `digest` erscheint. Sein Body nimmt `site_id`, `from`, `to` und `digest`
entgegen. Jedes Ergebnis hat einen `action_name`, `namespace`, `count`, `trace_id`
und `start_time`.
## Felder der Trace-Zusammenfassung
Die Listen-Endpunkte geben Trace-Zusammenfassungen mit diesen Feldern zurück:
| Feld | Typ | Beschreibung |
| ------------- | ----------------- | -------------------------------------------------------------- |
| `trace_id` | string | Bezeichner für den gesamten Trace. |
| `span_id` | string | Bezeichner für den Root-Span. |
| `site_id` | string | Site, zu der der Trace gehört. |
| `namespace` | string | Namespace, etwa `web` oder `background`. |
| `action_name` | string | Aktionsname, etwa `POST /api/users`. |
| `revision` | string | Deploy-Revision, die zum Zeitpunkt der Aufzeichnung aktiv war. |
| `time` | string (ISO 8601) | Zeitpunkt, zu dem der Trace endete. |
| `duration` | number | Gesamtdauer in Millisekunden. |
| `tags` | object | Benutzerdefinierte Tags aus Span-Attributen. |
| `has_npo` | boolean | Ob eine N+1-Abfrage erkannt wurde. |
## Span-Felder
Die Trace-Detail-Endpunkte geben Spans zurück. Jeder Span enthält Timing
(`start_time`, `end_time`, `duration` in ms), Identität (`trace_id`, `span_id`,
`parent_span_id`, `digest`) und Kontext (`service_name`, `namespace`, `revision`,
`action_name`, `span_name`, `span_kind`, `scope_name`, `scope_version`). Der Status
wird mit `status_code` (etwa `OK` oder `ERROR`) und `status_message` gemeldet.
Strukturierte Details werden als Objekte und Arrays zurückgegeben:
`resource_attributes` und `span_attributes` (Objekte), `events` (mit
`events.timestamp`, `events.name` und `events.attributes`-Arrays) und `links`
(mit `links.trace_id`, `links.span_id`, `links.trace_state` und
`links.attributes`-Arrays). `subtrace_root` gibt an, ob der Span eine separate
Service-Grenze einleitet.