Telemetrie-API: Anfragen, Antworten und Fehlercodes

Die Telemetrie-API ist JSON über HTTP unter https://api.logbrew.co. Öffentliche SDKs senden ihre verwalteten Batches an POST /v1/events. Eigene native Clients senden native Umschläge an POST /api/telemetry/ingest. Beide Ingest-Routen verlangen ein Ingest-Bearer-Token für das Projekt. Lesevorgänge und Änderungen am Konto nutzen ein Konto-Bearer-Token. Verwenden Sie ein Konto-Bearer-Token oder eine Browsersitzung nie als SDK- oder Ingest-Konfiguration. Senden Sie ein Ingest-Bearer-Token nie an eine Leseroute.

Begrenzte Anfrage senden

Gehen Sie diese Prüfliste durch, bevor ein Client eine Anfrage sendet:

Wählen Sie Route und HTTP-Methode aus der Endpunkt-Tabelle.
Verwenden Sie das richtige Bearer-Token: ein Ingest-Bearer-Token für die Signalaufnahme, ein Konto-Bearer-Token für alles andere.
Wählen Sie den Projektbereich, den die Route unterstützt. Erweitern Sie den Bereich nicht nach einer leeren Antwort.
Fügen Sie nur Query-Schlüssel hinzu, die die Route annimmt. Siehe Abfragefilter der Telemetrie-API.
Senden Sie Content-Type: application/json, wenn die Route einen JSON-Body hat.
Lesen Sie den HTTP-Status und den Antwort-Body, bevor Sie wiederholen.
Halten Sie Bearer-Tokens, Feed-Tickets und vollständige Antwort-Bodys aus Logs und Agenten-Prompts heraus.

Endpunkte

Signalaufnahme

Methode	Pfad	Zweck
`POST`	`/v1/events`	Batches aufnehmen, die öffentliche LogBrew-SDKs bauen und senden.
`POST`	`/api/telemetry/ingest`	Native Telemetrie-Umschläge von einem eigenen Client aufnehmen.

Lassen Sie das SDK die Batches für /v1/events bauen. Erstellen Sie sie nicht von Hand. Den nativen Umschlag beschreibt SDK-Integration.

Telemetrie lesen

Methode	Pfad	Zweck
`GET`	`/api/logs`	Strukturierte Logs auflisten.
`GET`	`/api/logs/{log_id}`	Ein Log lesen.
`GET`	`/api/logs/attributes`	Die Attributpfade und Typen von Logs auflisten, die ein Filter durchsuchen kann.
`GET`	`/api/telemetry/issues`	Gruppierte Issues auflisten.
`GET`	`/api/telemetry/issues/{issue_id}`	Ein gruppiertes Issue lesen.
`GET`	`/api/telemetry/issues/{issue_id}/events`	Die Vorkommen eines gruppierten Issues auflisten.
`PATCH`	`/api/telemetry/issues/{issue_id}`	Status, Priorität oder Zuweisung eines Issues ändern.
`POST`	`/api/telemetry/issues/bulk`	Status, Priorität oder Zuweisung von 1 bis 100 Issues in einem Projekt ändern.
`GET`	`/api/telemetry/issues/assignees`	Die Konten und Teams auflisten, denen in einem Projekt Issues zugewiesen werden können.
`GET`	`/api/telemetry/issues/{issue_id}/owners`	Die vorgeschlagenen zuständigen Konten und Teams eines Issues auflisten.
`GET`, `PUT`	`/api/telemetry/issues/ownership`	Die Zuständigkeitsregeln und den CODEOWNERS-Text eines Projekts lesen oder setzen.
`GET`	`/api/telemetry/issues/{issue_id}/activity`	Den Änderungsverlauf eines Issues lesen.
`GET`	`/api/telemetry/issues/notifications`	Die Issues auflisten, die andere Ihnen oder Ihren Teams zugewiesen haben.
`POST`	`/api/telemetry/issues/notifications/read`	Ihre Issue-Benachrichtigungen als gelesen markieren.
`PUT`	`/api/telemetry/issues/{issue_id}/triage-rule`	Die Schweregrad-Regel für ein Issue setzen.
`PUT`	`/api/logs/{log_id}/triage-rule`	Die Schweregrad-Regel und den Zustand „ignoriert“ für Logs setzen, die zu einem Log passen.
`GET`	`/api/telemetry/traces`	Traces in einem Projektbereich finden.
`GET`	`/api/telemetry/traces/{trace_id}`	Die Spans eines Trace auflisten.
`GET`	`/api/telemetry/traces/{trace_id}/summary`	Eine begrenzte Zusammenfassung eines Trace lesen.
`GET`	`/api/telemetry/actions`	Produktaktionen auflisten.
`GET`	`/api/telemetry/metrics`	Metrik-Stichproben auflisten.
`GET`	`/api/telemetry/metrics/series`	Eine Metrik als Zeitfenster lesen.
`GET`	`/api/telemetry/releases`	Release-Zusammenfassungen auflisten.
`GET`	`/api/telemetry/summary/volume`	Signalzahlen eines Projekts als Zeitfenster lesen.

Bereitstellungen

Methode	Pfad	CLI-Befehl
`PUT`	`/api/telemetry/deployments/{deployment_id}`	`logbrew deploy`
`GET`	`/api/telemetry/deployments/{deployment_id}?project_id=<project-uuid>`	Keiner
`GET`	`/api/telemetry/deployments?project_id=<project-uuid>`	Keiner

Erfassen Sie eine Bereitstellung aus Ihrer Release-Automatisierung, nachdem sie gelungen oder fehlgeschlagen ist. Der PUT-Body hat project_id, release, environment, service_name, status (succeeded oder failed), started_at, finished_at und optional commit_sha. Verwenden Sie dieselben Werte für release, environment und service_name, die Ihr SDK sendet. Das Projekt muss dem Konto gehören. deployment_id ist Ihre eigene ID für die Bereitstellung. Eine Wiederholung mit derselben ID und demselben Body gibt die gespeicherte Bereitstellung zurück. Dieselbe ID mit einem anderen Body schlägt mit 409 und idempotency_conflict fehl. Verwenden Sie für eine andere Bereitstellung eine neue ID.

Untersuchungen

Jede Untersuchungsroute gibt ein begrenztes Paket an Belegen für ein Subjekt zurück. Der Befehl logbrew explain der CLI liest diese Routen und prüft die Antwort.

Methode	Pfad	CLI-Befehl
`GET`	`/api/logs/{log_id}/investigation`	`logbrew explain log`
`GET`	`/api/telemetry/issues/{issue_id}/investigation`	`logbrew explain issue`
`GET`	`/api/telemetry/issues/{issue_id}/correction-verification`	`logbrew investigate issue <issue_id> verify`
`GET`	`/api/telemetry/traces/{trace_id}/investigation`	`logbrew explain trace`
`GET`	`/api/telemetry/traces/{trace_id}/spans/{span_id}/investigation`	`logbrew explain span`
`GET`	`/api/telemetry/actions/{action_id}/investigation`	`logbrew explain action`
`GET`	`/api/telemetry/metrics/investigation`	`logbrew explain metric`
`GET`	`/api/telemetry/releases/investigation`	`logbrew explain release`

Produktanalysen

Methode	Pfad	CLI-Befehl
`GET`	`/api/telemetry/analytics/overview`	`logbrew analytics overview`
`GET`	`/api/telemetry/analytics/properties`	`logbrew analytics properties`
`POST`	`/api/telemetry/analytics/funnel`	`logbrew analytics funnel`
`POST`	`/api/telemetry/analytics/retention`	`logbrew analytics retention`
`POST`	`/api/telemetry/analytics/lifecycle`	`logbrew analytics lifecycle`
`POST`	`/api/telemetry/analytics/paths`	`logbrew analytics paths`
`POST`	`/api/telemetry/analytics/segments/compare`	`logbrew analytics compare`

Die POST-Routen der Analysen nehmen einen JSON-Body an, keine Query-Schlüssel. Siehe Produktanalysen.

Live-Feed

Methode	Pfad	Zweck
`POST`	`/api/feed/ticket`	Ein kurzlebiges Live-Feed-Ticket mit einem Konto-Bearer-Token erstellen.
`GET`	`/api/feed/live?ticket=<ticket>`	Mit diesem Ticket eine WebSocket-Verbindung öffnen.

Konto und Anmeldung

Die Routen für Nutzung, Kontingent, Abo und Abmeldung stehen in der Konto-API.

Statuscodes bei Erfolg

Operation	Status bei Erfolg
Signalaufnahme, Lesevorgänge, Issue-Änderungen, Regeln, Bereitstellungen, Analysen und Feed-Tickets	`200 OK`
Live-Feed-Verbindung	`101 Switching Protocols`, danach WebSocket-Nachrichten

Eine Antwort 200 beweist nicht, dass die Belege vollständig sind. Lesen Sie die Felder für Abdeckung, Kürzung und Status in der Antwort.

Query-Filter und Paginierung

Jede Leseroute nimmt eigene Query-Schlüssel an. Kurze Aliasse wie project, trace und user sind keine Query-Schlüssel. Listenrouten geben standardmäßig ein einfaches Array zurück und mit pagination=cursor einen Cursor-Umschlag. Die Liste der Bereitstellungen gibt immer ein Seitenobjekt zurück. Siehe Abfragefilter der Telemetrie-API.

Antworten und Fehler

Antwortformate der Telemetrie-API zeigt ein Beispiel für jede Antwortfamilie.
API-Fehler listet Fehlercodes und Schritte zur Wiederherstellung auf.

Lesen Sie code vor der Nachricht für Menschen. Nutzen Sie next_action für das Programmverhalten und next als Hinweis für Menschen. Parsen Sie nicht den Wortlaut von error oder next.

Issues ändern

Diese Anfragen nutzen ein Konto-Bearer-Token. Es unterscheidet sich absichtlich von LOGBREW_INGEST_BEARER. Das Konto braucht die Berechtigung, Issues im Projekt des Issues zu verwalten. Fehlt sie, schlägt die Anfrage mit 403 und forbidden fehl. Dieselbe Berechtigung gilt für Änderungen an Status, Priorität und Zuweisung sowie für Issue- und Log-Regeln. Jede Anfrage setzt mindestens eines dieser Felder:

Feld	Werte
`status`	`unresolved`, `resolved` oder `archived`. `ignored` ist ein älterer Name für `archived`.
`priority`	`high`, `medium` oder `low`.
`assignee`	Eine Nutzer-ID, `me` für das angemeldete Konto, `team:<team_id>` für ein Team oder `none`, um die Zuweisung zu entfernen.

Eine Anfrage ohne eines dieser Felder schlägt mit 422 und validation_failed fehl. Ein Issue ist höchstens 1 Konto oder 1 Team zugewiesen. Ein Konto muss das Projekt lesen können, und ein Team muss zur Organisation des Projekts gehören. Sonst schlägt die Anfrage mit 422 und validation_failed fehl, und LogBrew ändert nichts. Die Konten, die Sie zuweisen können, liefert Zuweisbare Konten und Teams auflisten. Jeder andere Wert für assignee schlägt ebenfalls mit 422 und validation_failed fehl. Eine Priorität, die Sie setzen, bleibt fest. Ohne eine gesetzte Priorität folgt die Priorität dem Schweregrad des Issues: error und critical sind high, warning ist medium und info ist low. Ein Feld, das schon den angefragten Wert hat, ändert sich nicht. Nach einer Zeitüberschreitung können Sie dieselbe Anfrage erneut senden. Eine Zeitüberschreitung beweist nicht, dass die Änderung nicht stattgefunden hat. Lesen Sie das Issue erneut, bevor Sie eine andere Änderung senden.

Ein Issue ändern

Fügen Sie response_version=4 hinzu, um archived, die Priorität und die Zuweisung in der Antwort zu erhalten. In Version 4 ist assignee { "type": "user", "user_id", "name", "email" }, { "type": "team", "team_id", "slug", "name" } oder null. Version 3 zeigt ein zugewiesenes Team als null.

curl -X PATCH "$LOGBREW_API_URL/api/telemetry/issues/$ISSUE_ID?response_version=4" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  -H "Content-Type: application/json" \
  --data '{ "status": "archived", "priority": "low", "assignee": "me" }'

Die Antwort ist das geänderte Issue. Siehe Beispiele für Antworten zum Issue-Status.

Issues gesammelt ändern

Senden Sie project_id und 1 bis 100 verschiedene Issue-IDs aus diesem Projekt:

curl -X POST "$LOGBREW_API_URL/api/telemetry/issues/bulk" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  -H "Content-Type: application/json" \
  --data '{
    "project_id": "<project-uuid>",
    "issue_ids": ["<issue-uuid-1>", "<issue-uuid-2>"],
    "assignee": "<user-uuid>"
  }'

Die Anfrage wendet dieselbe Änderung auf jedes Issue an. Die Antwort hat project_id und results, mit 1 Ergebnis pro Issue-ID in der Reihenfolge der Anfrage. Jedes Ergebnis hat issue_id, outcome und issue. issue ist in Antwortversion 3 das aktuelle Issue oder null bei not_found. Fügen Sie dem Body "response_version": 2 hinzu, um jedes Issue in Antwortversion 4 zu erhalten.

`outcome`	Bedeutung
`updated`	LogBrew hat die Änderung angewendet.
`unchanged`	Das Issue hatte die angefragten Werte schon.
`not_found`	Das Projekt hat kein Issue mit dieser ID. LogBrew hat dafür nichts geändert.

Eine leere Liste, mehr als 100 IDs oder eine doppelte ID schlagen mit 422 und validation_failed fehl. Teilen Sie eine größere Menge auf mehrere Anfragen auf. Wenn das Konto das Projekt nicht lesen kann, schlägt die Anfrage mit 404 und not_found fehl.

Zuweisbare Konten und Teams auflisten

Senden Sie die Projekt-ID, um jedes Konto zu erhalten, dem in diesem Projekt Issues zugewiesen werden können:

curl "$LOGBREW_API_URL/api/telemetry/issues/assignees?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER"

Die Liste enthält jedes Konto, das das Projekt lesen kann. Jeder Eintrag hat user_id, name und email. name ist null, wenn das Konto keinen Namen hat. Mit response_version=2 erhalten Sie zusätzlich teams: jedes Team der Organisation des Projekts, mit team_id, slug und name. Siehe die Antwort mit der Liste zuweisbarer Konten und Teams. Jedes Konto, das das Projekt lesen kann, kann diese Liste abrufen. Wenn das Konto das Projekt nicht lesen kann, schlägt die Anfrage mit 404 und not_found fehl. Wenn ein Mitglied den Zugriff auf das Projekt verliert, zeigen die ihm zugewiesenen Issues keine Zuweisung. Erhält das Mitglied wieder Zugriff, zeigen die Issues es wieder an, außer jemand hat die Zuweisung in der Zwischenzeit geändert oder entfernt.

Zuständigkeitsregeln und Zuständigkeitsvorschläge

GET /api/telemetry/issues/ownership?project_id=<project-uuid> liefert rules, codeowners, updated_at und unresolved_owners. Jedes Konto, das das Projekt lesen kann, kann diese Werte lesen. PUT mit project_id und rules, codeowners oder beidem ersetzt diesen Text und braucht die Berechtigung, Issues zu verwalten. Ein Feld, das Sie weglassen, behält seinen Text. Ein leerer String löscht ihn. Jeder Text hat höchstens 128 KiB. Ungültiger Text schlägt mit 422 fehl und nennt die Zeile. GET /api/telemetry/issues/{issue_id}/owners?response_version=2 liefert suggested_assignee, owners und inputs. Jeder Eintrag hat type (user oder team), source (ownership_rule, codeowners oder recent_activity), rule, line und matched. Version 1, der Standard, listet nur Konten auf.

Verlauf eines Issues

GET /api/telemetry/issues/{issue_id}/activity?response_version=2 liefert activity, die neuesten Einträge zuerst, und next_cursor. Jeder Eintrag hat type (status, priority, assigned, unassigned, severity_rule oder first_seen), value, actor_id, actor, assignee_id, assignee, team und at. limit liegt zwischen 1 und 200, der Standard ist 50. Senden Sie cursor_time und cursor_id aus next_cursor, um die nächste Seite zu lesen.

Benachrichtigungen

GET /api/telemetry/issues/notifications liefert notifications, unread, read_at und next_cursor. Jede Benachrichtigung ist eine Zuweisung eines Issues an Sie oder Ihr Team durch ein anderes Konto. POST /api/telemetry/issues/notifications/read mit einem leeren JSON-Objekt oder mit read_at setzt Ihre Lesemarke weiter. Die Marke geht nie zurück.

Regeln für Issues und Logs setzen

Eine Regel ändert, wie LogBrew passende Signale zeigt. Sie löscht keine Daten. Der erfasste Wert severity bleibt unverändert, und die Antwort zeigt die Regel in triage.

Anfrage	JSON-Body
`PUT /api/telemetry/issues/{issue_id}/triage-rule`	`{ "severity": "<value>" }`
`PUT /api/logs/{log_id}/triage-rule`	`{ "severity": "<value>", "ignored": true }`

severity ist info, warning, error, critical oder source. source entfernt die Überschreibung und zeigt wieder den erfassten Schweregrad. Bei einer Log-Regel blendet ignored: true passende Logs aus der Standard-Log-Liste aus. Lesen Sie sie mit status=ignored oder status=all. Die Regel gilt für gespeicherte und künftige passende Signale. Ein anderer Wert schlägt mit 422 und validation_failed fehl.

Senden Sie keine leeren Releases. LogBrew lehnt sie ab, damit die Release-Verfolgung verlässlich bleibt.

​Begrenzte Anfrage senden

​Endpunkte

​Signalaufnahme

​Telemetrie lesen

​Bereitstellungen

​Untersuchungen

​Produktanalysen

​Live-Feed

​Konto und Anmeldung

​Statuscodes bei Erfolg

​Query-Filter und Paginierung

​Antworten und Fehler

​Issues ändern

​Ein Issue ändern

​Issues gesammelt ändern

​Zuweisbare Konten und Teams auflisten

​Zuständigkeitsregeln und Zuständigkeitsvorschläge

​Verlauf eines Issues

​Benachrichtigungen

​Regeln für Issues und Logs setzen

Begrenzte Anfrage senden

Endpunkte

Signalaufnahme

Telemetrie lesen

Bereitstellungen

Untersuchungen

Produktanalysen

Live-Feed

Konto und Anmeldung

Statuscodes bei Erfolg

Query-Filter und Paginierung

Antworten und Fehler

Issues ändern

Ein Issue ändern

Issues gesammelt ändern

Zuweisbare Konten und Teams auflisten

Zuständigkeitsregeln und Zuständigkeitsvorschläge

Verlauf eines Issues

Benachrichtigungen

Regeln für Issues und Logs setzen