Żądania, odpowiedzi i kody błędów API telemetrii

API telemetrii to JSON przez HTTP pod adresem https://api.logbrew.co. Publiczne SDK wysyłają zarządzane przez siebie paczki do POST /v1/events. Własne klienty natywne wysyłają natywne koperty do POST /api/telemetry/ingest. Obie trasy wysyłania wymagają tokena bearer wysyłania przypisanego do projektu. Odczyty i zmiany należące do konta używają tokena bearer konta. Nigdy nie używaj tokena bearer konta ani sesji przeglądarki jako konfiguracji SDK lub wysyłania. Nigdy nie wysyłaj tokena bearer wysyłania do trasy odczytu.

Wyślij żądanie o ograniczonym zakresie

Zanim klient wyśle żądanie, przejdź przez tę listę kontrolną:

Wybierz trasę i metodę HTTP z tabeli endpointów.
Użyj właściwego tokena bearer: tokena bearer wysyłania do przyjmowania danych, a tokena bearer konta do wszystkiego innego.
Wybierz zakres projektu, który obsługuje trasa. Nie poszerzaj zakresu po pustej odpowiedzi.
Dodawaj tylko parametry zapytania, które trasa przyjmuje. Zobacz Filtry zapytań.
Wysyłaj Content-Type: application/json, gdy trasa ma treść JSON.
Zanim ponowisz żądanie, odczytaj status HTTP i treść odpowiedzi.
Nie umieszczaj tokenów bearer, biletów podglądu na żywo ani pełnych treści odpowiedzi w logach i promptach agentów.

Endpointy

Przyjmowanie danych

Metoda	Ścieżka	Przeznaczenie
`POST`	`/v1/events`	Przyjmuje paczki, które budują i wysyłają publiczne SDK LogBrew.
`POST`	`/api/telemetry/ingest`	Przyjmuje natywne koperty telemetrii z własnego klienta.

Paczki /v1/events niech buduje SDK. Nie twórz ich ręcznie. Natywną kopertę opisuje strona Integracja SDK.

Odczyty telemetrii

Metoda	Ścieżka	Przeznaczenie
`GET`	`/api/logs`	Wyświetl listę logów strukturalnych.
`GET`	`/api/logs/{log_id}`	Odczytaj jeden log.
`GET`	`/api/logs/attributes`	Wyświetl ścieżki i typy atrybutów logów, które może przeszukiwać filtr.
`GET`	`/api/telemetry/issues`	Wyświetl zgrupowane problemy.
`GET`	`/api/telemetry/issues/{issue_id}`	Odczytaj jeden zgrupowany problem.
`GET`	`/api/telemetry/issues/{issue_id}/events`	Wyświetl wystąpienia jednego zgrupowanego problemu.
`PATCH`	`/api/telemetry/issues/{issue_id}`	Zaktualizuj status, priorytet lub przypisanie jednego problemu.
`POST`	`/api/telemetry/issues/bulk`	Zaktualizuj status, priorytet lub przypisanie w 1–100 problemach jednego projektu.
`GET`	`/api/telemetry/issues/assignees`	Wyświetl konta i zespoły, którym można przypisywać problemy w jednym projekcie.
`GET`	`/api/telemetry/issues/{issue_id}/owners`	Wyświetl proponowanych właścicieli jednego problemu.
`GET`, `PUT`	`/api/telemetry/issues/ownership`	Odczytaj lub ustaw reguły własności i tekst CODEOWNERS jednego projektu.
`GET`	`/api/telemetry/issues/{issue_id}/activity`	Odczytaj historię zmian jednego problemu.
`GET`	`/api/telemetry/issues/notifications`	Wyświetl problemy, które inni przypisali tobie lub twoim zespołom.
`POST`	`/api/telemetry/issues/notifications/read`	Oznacz swoje powiadomienia o problemach jako przeczytane.
`PUT`	`/api/telemetry/issues/{issue_id}/triage-rule`	Ustaw regułę ważności dla problemu.
`PUT`	`/api/logs/{log_id}/triage-rule`	Ustaw regułę ważności i stan ignorowania dla logów, które pasują do danego logu.
`GET`	`/api/telemetry/traces`	Wyszukaj ślady w zakresie projektu.
`GET`	`/api/telemetry/traces/{trace_id}`	Wyświetl spany jednego śladu.
`GET`	`/api/telemetry/traces/{trace_id}/summary`	Odczytaj ograniczone podsumowanie jednego śladu.
`GET`	`/api/telemetry/actions`	Wyświetl akcje produktowe.
`GET`	`/api/telemetry/metrics`	Wyświetl próbki metryk.
`GET`	`/api/telemetry/metrics/series`	Odczytaj jedną metrykę jako przedziały czasu.
`GET`	`/api/telemetry/releases`	Wyświetl podsumowania wydań.
`GET`	`/api/telemetry/summary/volume`	Odczytaj liczby sygnałów jednego projektu jako przedziały czasu.

Wdrożenia

Metoda	Ścieżka	Polecenie CLI
`PUT`	`/api/telemetry/deployments/{deployment_id}`	`logbrew deploy`
`GET`	`/api/telemetry/deployments/{deployment_id}?project_id=<project-uuid>`	Brak
`GET`	`/api/telemetry/deployments?project_id=<project-uuid>`	Brak

Zapisz wdrożenie z automatyzacji wydań po jego sukcesie lub niepowodzeniu. Treść PUT zawiera project_id, release, environment, service_name, status (succeeded lub failed), started_at, finished_at i opcjonalne commit_sha. Użyj tych samych wartości release, environment i service_name, które wysyła SDK. Konto musi być właścicielem projektu. deployment_id to twoje własne ID wdrożenia. Ponowienie z tym samym ID i tą samą treścią zwraca zapisane wdrożenie. To samo ID z inną treścią kończy się błędem 409 i idempotency_conflict. Dla innego wdrożenia użyj nowego ID.

Analizy

Każda trasa analizy zwraca ograniczony pakiet dowodów dla jednego obiektu analizy. Polecenie CLI logbrew explain odczytuje te trasy i weryfikuje odpowiedź.

Metoda	Ścieżka	Polecenie CLI
`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`

Analityka produktowa

Metoda	Ścieżka	Polecenie CLI
`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`

Trasy analityki POST przyjmują treść JSON, a nie parametry zapytania. Zobacz Analityka produktowa.

Podgląd na żywo

Metoda	Ścieżka	Przeznaczenie
`POST`	`/api/feed/ticket`	Utwórz krótkotrwały bilet podglądu na żywo z tokenem bearer konta.
`GET`	`/api/feed/live?ticket=<ticket>`	Otwórz połączenie WebSocket z tym biletem.

Konto i logowanie

Trasy wykorzystania, limitów, subskrypcji i wylogowania opisuje strona API konta.

Kody statusu sukcesu

Operacja	Status sukcesu
Przyjmowanie danych, odczyty, aktualizacje problemów, reguły, wdrożenia, analityka i bilety podglądu na żywo	`200 OK`
Połączenie podglądu na żywo	`101 Switching Protocols`, a potem wiadomości WebSocket

Odpowiedź 200 nie dowodzi, że dowody są kompletne. Odczytaj w odpowiedzi pola pokrycia, obcięcia i statusu.

Filtry zapytań i paginacja

Każda trasa odczytu przyjmuje własne parametry zapytania. Przyjazne aliasy, takie jak project, trace i user, nie są parametrami zapytania. Trasy list domyślnie zwracają samą tablicę, a z pagination=cursor – kopertę z kursorem. Lista wdrożeń zawsze zwraca obiekt strony. Zobacz Filtry zapytań.

Odpowiedzi i błędy

Formaty odpowiedzi pokazują po jednym przykładzie dla każdej rodziny odpowiedzi.
Błędy API zawierają kody błędów i kroki naprawcze.

Odczytaj code przed komunikatem dla człowieka. Używaj next_action do sterowania programem, a next jako wskazówki dla człowieka. Nie parsuj treści error ani next.

Zaktualizuj problemy

Te żądania używają tokena bearer konta. Celowo różni się on od LOGBREW_INGEST_BEARER. Konto musi mieć uprawnienie do zarządzania problemami w projekcie, do którego należy problem. Jeśli go nie ma, żądanie kończy się błędem 403 i forbidden. To samo uprawnienie obejmuje zmiany statusu, priorytetu i przypisania oraz reguły problemów i logów. Każde żądanie ustawia co najmniej 1 z tych pól:

Pole	Wartości
`status`	`unresolved`, `resolved` lub `archived`. `ignored` to starsza nazwa `archived`.
`priority`	`high`, `medium` lub `low`.
`assignee`	ID użytkownika, `me` dla zalogowanego konta, `team:<team_id>` dla zespołu albo `none`, aby usunąć przypisanie.

Żądanie bez żadnego z tych pól kończy się błędem 422 i validation_failed. Problem może być przypisany najwyżej do 1 konta albo 1 zespołu. Konto musi mieć dostęp do odczytu projektu, a zespół musi należeć do organizacji projektu. W przeciwnym razie żądanie kończy się błędem 422 i validation_failed, a LogBrew niczego nie zmienia. Konta, które możesz przypisać, pobierzesz zgodnie z sekcją Wyświetl konta i zespoły do przypisania. Każda inna wartość assignee też kończy się błędem 422 i validation_failed. Priorytet ustawiony ręcznie się nie zmienia. Bez ręcznie ustawionego priorytetu priorytet wynika z ważności problemu: error i critical dają high, warning daje medium, a info daje low. Pole, które ma już żądaną wartość, się nie zmienia. Po przekroczeniu limitu czasu możesz wysłać to samo żądanie ponownie. Przekroczenie limitu czasu nie dowodzi, że zmiana nie nastąpiła. Zanim wyślesz inną zmianę, odczytaj problem ponownie.

Zaktualizuj jeden problem

Dodaj response_version=4, aby dostać w odpowiedzi archived, priorytet i przypisanie. W wersji 4 assignee ma postać { "type": "user", "user_id", "name", "email" }, { "type": "team", "team_id", "slug", "name" } albo null. Wersja 3 pokazuje przypisanie do zespołu jako 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" }'

Odpowiedź to zaktualizowany problem. Zobacz przykłady odpowiedzi ze statusem problemu.

Zaktualizuj wiele problemów naraz

Wyślij project_id i od 1 do 100 różnych ID problemów z tego projektu:

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>"
  }'

Żądanie stosuje tę samą zmianę do każdego problemu. Odpowiedź ma project_id i results, z 1 wynikiem dla każdego ID problemu, w kolejności z żądania. Każdy wynik ma issue_id, outcome i issue. issue to bieżący problem w wersji odpowiedzi 3 albo null dla not_found. Dodaj "response_version": 2 do treści żądania, aby dostać każdy problem w wersji odpowiedzi 4.

`outcome`	Znaczenie
`updated`	LogBrew zastosował zmianę.
`unchanged`	Problem miał już żądane wartości.
`not_found`	Projekt nie ma problemu o tym ID. LogBrew niczego dla niego nie zmienił.

Pusta lista, więcej niż 100 ID lub powtórzone ID kończą się błędem 422 i validation_failed. Większy zbiór podziel na kilka żądań. Jeśli konto nie może odczytać projektu, żądanie kończy się błędem 404 i not_found.

Wyświetl konta i zespoły do przypisania

Wyślij ID projektu, aby dostać każde konto, któremu można przypisywać problemy w tym projekcie:

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

Lista zawiera każde konto, które może odczytywać projekt. Każdy wpis ma user_id, name i email. name ma wartość null, gdy konto nie ma nazwy. Dodaj response_version=2, aby dostać też teams: każdy zespół organizacji projektu, z polami team_id, slug i name. Zobacz odpowiedź z listą kont i zespołów do przypisania. Tę listę może pobrać każde konto, które może odczytywać projekt. Jeśli konto nie może odczytać projektu, żądanie kończy się błędem 404 i not_found. Gdy członek traci dostęp do projektu, przypisane do niego problemy nie pokazują przypisania. Jeśli członek odzyska dostęp, problemy znowu go pokazują, chyba że ktoś w międzyczasie zmienił lub usunął przypisanie.

Własność i proponowani właściciele

GET /api/telemetry/issues/ownership?project_id=<project-uuid> zwraca rules, codeowners, updated_at i unresolved_owners. Może je odczytać każde konto, które może odczytywać projekt. PUT z project_id oraz rules, codeowners lub obydwoma polami zastępuje ten tekst i wymaga uprawnienia do zarządzania problemami. Pole, które pominiesz, zachowuje swój tekst, a pusty ciąg znaków go czyści. Każdy tekst może mieć najwyżej 128 KiB. Nieprawidłowy tekst kończy się błędem 422 ze wskazaniem wiersza. GET /api/telemetry/issues/{issue_id}/owners?response_version=2 zwraca suggested_assignee, owners i inputs. Każdy właściciel ma type (user lub team), source (ownership_rule, codeowners lub recent_activity), rule, line i matched. Wersja 1, domyślna, wyświetla tylko konta.

Historia problemu

GET /api/telemetry/issues/{issue_id}/activity?response_version=2 zwraca activity, od najnowszych wpisów, oraz next_cursor. Każdy wpis ma type (status, priority, assigned, unassigned, severity_rule lub first_seen), value, actor_id, actor, assignee_id, assignee, team i at. limit przyjmuje wartości od 1 do 200, domyślnie 50. Aby pobrać następną stronę, wyślij cursor_time i cursor_id z next_cursor.

Powiadomienia

GET /api/telemetry/issues/notifications zwraca notifications, unread, read_at i next_cursor. Każde powiadomienie to przypisanie problemu tobie lub twojemu zespołowi przez inne konto. POST /api/telemetry/issues/notifications/read z pustym obiektem JSON lub z read_at przesuwa twój znacznik odczytu. Znacznik nigdy nie cofa się.

Ustaw reguły problemów i logów

Reguła zmienia sposób, w jaki LogBrew pokazuje pasujące sygnały. Nie usuwa danych. Zarejestrowane severity pozostaje bez zmian, a odpowiedź pokazuje regułę w triage.

Żądanie	Treść JSON
`PUT /api/telemetry/issues/{issue_id}/triage-rule`	`{ "severity": "<value>" }`
`PUT /api/logs/{log_id}/triage-rule`	`{ "severity": "<value>", "ignored": true }`

severity ma wartość info, warning, error, critical lub source. source usuwa nadpisanie i znowu pokazuje zarejestrowaną ważność. W regule logów ignored: true ukrywa pasujące logi na domyślnej liście logów. Odczytasz je przez status=ignored lub status=all. Reguła dotyczy przechowywanych i przyszłych pasujących sygnałów. Inna wartość kończy się błędem 422 i validation_failed.

Nie wysyłaj pustych wydań. LogBrew je odrzuca, aby śledzenie wydań pozostało wiarygodne.

​Wyślij żądanie o ograniczonym zakresie

​Endpointy

​Przyjmowanie danych

​Odczyty telemetrii

​Wdrożenia

​Analizy

​Analityka produktowa

​Podgląd na żywo

​Konto i logowanie

​Kody statusu sukcesu

​Filtry zapytań i paginacja

​Odpowiedzi i błędy

​Zaktualizuj problemy

​Zaktualizuj jeden problem

​Zaktualizuj wiele problemów naraz

​Wyświetl konta i zespoły do przypisania

​Własność i proponowani właściciele

​Historia problemu

​Powiadomienia

​Ustaw reguły problemów i logów

Wyślij żądanie o ograniczonym zakresie

Endpointy

Przyjmowanie danych

Odczyty telemetrii

Wdrożenia

Analizy

Analityka produktowa

Podgląd na żywo

Konto i logowanie

Kody statusu sukcesu

Filtry zapytań i paginacja

Odpowiedzi i błędy

Zaktualizuj problemy

Zaktualizuj jeden problem

Zaktualizuj wiele problemów naraz

Wyświetl konta i zespoły do przypisania

Własność i proponowani właściciele

Historia problemu

Powiadomienia

Ustaw reguły problemów i logów