Zum Hauptinhalt springen
Lesen Sie verteilte Tracing-Daten mit der Public API (V2). Alle Endpunkte authentifizieren sich mit Ihrem persönlichen API-Token. Diese Seite erklärt, wie die Tracing-Endpunkte zusammenspielen. Alle Felder jeder Anfrage und Antwort finden Sie in der Referenz der Tracing-Endpunkte. Einige Endpunkte nehmen ein site_ids-Array entgegen, sodass sie in einer einzigen Anfrage über mehrere Sites hinweg suchen können. Die anderen nehmen eine einzelne site_id entgegen.

Einen Trace lokalisieren

Finden Sie die Performance-Aktionen und Error-Incidents, in denen ein Trace über Sites hinweg erscheint.
Der Request-Body nimmt site_ids (ein String-Array) und trace_id (einen String) entgegen. Die Antwort enthält performance-Einträge mit namespace und action_name sowie errors-Einträge mit incident_number und exception_name. Jeder errors-Eintrag hat außerdem incident_digests. Übergeben Sie diese als digests an die Error-Trace-Endpunkte.

Die Spans eines Traces abrufen

Gibt jeden Span in einem Trace zurück.
Der Request-Body nimmt site_ids (ein String-Array) und trace_id (einen String) entgegen. Um auch Spans aus anderen Traces zurückzugeben, die auf diesen verweisen, setzen Sie include_linked_spans auf true.
Zwei weitere Endpunkte geben die Spans eines Traces zurück, ohne seine ID zu benötigen:
  • POST /api/v2/tracing/trace/performance nimmt einen action_name und einen namespace entgegen.
  • POST /api/v2/tracing/trace/error nimmt die digests eines Error-Incidents entgegen.
Beide geben den neuesten passenden Trace zurück. Um stattdessen einen bestimmten abzurufen, fügen Sie seine trace_id hinzu.

Traces auflisten

Listen Sie Performance- oder Error-Traces auf.
Die beiden Endpunkte nehmen unterschiedliche Filter entgegen:
  • traces/performance benötigt einen action_name und einen namespace. Fügen Sie duration_ms hinzu, um nur Traces aufzulisten, die mindestens so lange dauern. Fügen Sie from und to hinzu, um einen Zeitbereich festzulegen.
  • traces/errors benötigt die digests der Error-Incidents. Es hat keinen Zeitbereich.
Beide akzeptieren eine optionale query, um nach Revision oder Tag zu filtern, und beide benötigen ein pagination-Objekt.
pagination benötigt alle drei dieser Felder:
  • per_page: wie viele Traces pro Seite zurückgegeben werden, bis zu 100.
  • order: ASC oder DESC.
  • cursor: { "time": null }, um nach Trace-Zeit zu sortieren, oder { "duration": null }, um nach Trace-Dauer zu sortieren. null beginnt bei der ersten Seite.
Jeder Trace in der Antwort hat eine trace_id, die Zeit time, zu der der Trace begann, und seine Gesamtdauer duration in Millisekunden.
Um nach einem Tag zu filtern, das eine vollständige ID enthält, verwenden Sie =, wie in tag.request_id=<id>. Ein : ist eine viel langsamere Teilstring-Suche: Sie liest jeden Span mit diesem Tag im Zeitbereich. Wenn eine solche Anfrage einen 429 erhält und der Wert eine UUID ist, zeigt die suggestion der Antwort die =-Form.

Traces durchsuchen

Durchsuchen Sie Fehler- und Performance-Daten über Sites hinweg, nach Aktion, Exception, Tag oder Nachricht.
Der Body benötigt site_ids: mindestens eine Site, alle im selben Account. Die optionale query trifft so:
  • Einzelne Wörter treffen einen Aktionsnamen, Exception-Namen oder Tag-Wert exakt, als eine Phrase.
  • action:, error: und tag: treffen jeweils ein Feld exakt.
  • message: trifft eine Phrase aus ganzen Wörtern, ohne Berücksichtigung der Groß-/Kleinschreibung.
Setzen Sie Werte, die Leerzeichen enthalten, in Anführungszeichen. Um die Ergebnisse einzugrenzen, fügen Sie einen namespace, einen from- und to-Bereich oder eine kind hinzu. kind ist all (Standard), exception oder performance. from ist standardmäßig der Beginn der Aufbewahrung Ihres Accounts, to standardmäßig der aktuelle Zeitpunkt. Die Antwort enthält bis zu limit Ergebnisse, die neuesten zuerst. limit ist standardmäßig 50 und auf 2.000 begrenzt. Jedes Ergebnis ist ein Incident-Digest eines passenden Spans, daher kann eine trace_id mehrfach erscheinen.

Performance-Aktionen auflisten

Listen Sie Performance-Aktionen mit aggregierten Metriken auf.
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.
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. Bei beiden ist from inklusiv und to exklusiv. 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, die Span-Arten caller_kind und callee_kind sowie edge_type (SYNC oder ASYNC).

Langsame Ereignisse

Analysieren Sie langsame Operationen innerhalb von Traces, etwa langsame Datenbankabfragen.
slow_events gibt bis zu 100 aggregierte langsame Ereignisse zurück. Sein Body nimmt site_id, from, to und wanted_attributes entgegen. Sie können außerdem diese Filter hinzufügen:
  • span_kind: nur eine Art von Span einbeziehen: Client, Server, Internal, Producer oder Consumer.
  • excluded_attributes: Spans auslassen, die einen der aufgeführten Attributschlüssel haben.
wanted_attributes benennt die Span-Attribute, die zurückgegeben werden. Gruppieren Sie sie unter selbst gewählten, kleingeschriebenen Namen, etwa payload. Jede Gruppe ist entweder Required oder Optional:
  • Required bezieht nur Spans ein, bei denen mindestens einer der aufgeführten Schlüssel einen Wert hat.
  • Optional gibt den Wert zurück, wenn er gesetzt ist, und filtert keine Spans.
Wenn eine Gruppe mehrere Schlüssel aufführt, gibt sie den Wert des ersten Schlüssels zurück, der einen hat. Neben Span-Attributschlüsseln kann eine Gruppe appsignal.library aufführen. Es gibt die Bibliothek zurück, mit der AppSignal den Span instrumentiert hat, etwa active_record, und ist bei anderen Spans leer. Zum Beispiel gibt "system": { "Optional": ["db.system.name", "db.system", "appsignal.library"] } das Datenbanksystem zurück, wenn der Span eines aufzeichnet, und andernfalls die Bibliothek. Spans, die vor Ende Juli 2026 gespeichert wurden, geben es leer zurück. Die Anfrage benötigt mindestens eine Required-Gruppe, sonst gibt sie einen 400 zurück. Diese Anfrage listet langsame Datenbankabfragen mit dem Abfragetext und dem Datenbanksystem auf:
Jedes Ergebnis hat einen digest, count, mean (ms) und einen impact-Score. Jede Gruppe in wanted_attributes kommt als eigener Schlüssel zurück, etwa "payload": "SELECT * FROM users WHERE id = ?". slow_events/actions listet die Aktionen auf, in denen ein langsames Ereignis erscheint. Sein Body nimmt site_id, from, to und den digest aus slow_events entgegen. Jedes Ergebnis hat einen action_name, namespace und count sowie die trace_id und start_time des neuesten Vorkommens.

Top-Ereignisse nach Gruppe

Ordnen Sie die Ereignisse in einer oder mehreren Ereignisgruppen, etwa active_record-Abfragen, nach Gesamtzeit, mittlerer Dauer oder Durchsatz.
Der Body nimmt site_id, from, to und groups entgegen: mindestens eine Ereignisgruppe, etwa ["active_record", "moped"]. AppSignal erweitert from und to auf ganze resolution-Intervalle. order ordnet die Ereignisse nach IMPACT (Standard), MEAN oder THROUGHPUT. limit akzeptiert 1 bis 1.000 Zeilen und ist standardmäßig 1.000. Jede Zeile hat den digest, die group und den name des Ereignisses, etwa sql.active_record. Sie hat einen title und einen body, etwa den Abfragetext. Außerdem hat sie den count, die mittlere Dauer mean in Millisekunden und den impact: die insgesamt verbrachte Zeit, count mal mean. Einige Ereignisse werden nach dem Ranking ausgelassen, daher können weniger Zeilen als limit zurückkommen.

Error-Incidents untersuchen

Zählen Sie die Fehler jedes Incidents, und sehen Sie dann, was die Incidents gemeinsam haben.
tracing/errors zählt Fehler pro Incident. Sein Body nimmt site_id, from und to entgegen, und Sie können nach namespaces und revision filtern. Jede Zeile hat einen incident_digest, dessen namespace und neueste revision sowie einen error_count. Die Antwort enthält jeden passenden Incident, unsortiert. Um die Incidents mit den meisten Fehlern zu finden, sortieren Sie die Zeilen nach error_count. metadata_distributions schlüsselt Incidents nach ihren Metadaten auf, etwa hostname. Sein Body nimmt site_id, die einzubeziehenden incident_digests, from und group_by entgegen:
  • KEY listet jeden Metadaten-Schlüssel mit seinen total Vorkommen und der Anzahl unique Werte auf.
  • VALUE listet die Werte des Schlüssels auf, den Sie in metadata_key setzen. In jeder Zeile enthält key den Wert und value, wie oft er vorkommt.
to ist standardmäßig der aktuelle Zeitpunkt. limit akzeptiert 1 bis 1.000 Zeilen. Im VALUE-Modus ist es standardmäßig 10 Zeilen, im KEY-Modus gibt es standardmäßig keine Begrenzung. Um die Traces hinter einem Incident zu sehen, übergeben Sie seinen Digest an traces/errors oder trace/error.