Zum Hauptinhalt springen
Lesen Sie verteilte Tracing-Daten mit der Public API (V2): 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 oder Spans 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. 
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. 
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 zurück. 
{
  "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 eines Performance- oder Error-Traces über den TracesQuery-Body zurück.

​
Traces auflisten

Listen Sie Performance- oder Error-Traces auf. 
POST /api/v2/tracing/traces/performance
POST /api/v2/tracing/traces/errors
Beide nehmen den TracesQuery-Body entgegen und geben ein Array von Trace-Zusammenfassungen zurück. 
{
  "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

FeldTypErforderlichBeschreibung
site_idsstring[]JaAbzufragende Sites.
paginationobjectJaPaginierungseinstellungen. Setzen Sie cursor auf Time oder Duration.
digestsstring[]NeinNach Trace-Digests filtern.
action_namestringNeinNach Aktionsname filtern.
namespacestringNeinNach Namespace filtern.
querystringNeinFreitext-Suchabfrage.
durationnumber (ms)NeinFilter für Mindestdauer.
fromstring (ISO 8601)NeinStart des Zeitbereichs.
tostring (ISO 8601)NeinEnde des Zeitbereichs.
ttlnumberNeinAufbewahrungsgrenze in Sekunden.

​
Performance-Aktionen auflisten

Listen Sie Performance-Aktionen mit aggregierten Metriken auf. 
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. 
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 "<service>/<namespace>", 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. 
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:
FeldTypBeschreibung
trace_idstringBezeichner für den gesamten Trace.
span_idstringBezeichner für den Root-Span.
site_idstringSite, zu der der Trace gehört.
namespacestringNamespace, etwa web oder background.
action_namestringAktionsname, etwa POST /api/users.
revisionstringDeploy-Revision, die zum Zeitpunkt der Aufzeichnung aktiv war.
timestring (ISO 8601)Zeitpunkt, zu dem der Trace endete.
durationnumberGesamtdauer in Millisekunden.
tagsobjectBenutzerdefinierte Tags aus Span-Attributen.
has_npobooleanOb 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.