Format odpowiedzi API i przykłady odpowiedzi JSON

Ta strona pokazuje po jednym przykładzie każdego rodzaju odpowiedzi API telemetrii. Wszystkie wartości są syntetyczne. Kody błędów i sposoby naprawy opisuje strona Błędy API.

Jak odczytać odpowiedź

Odczytuj każdą odpowiedź w tej kolejności:

Sprawdź status HTTP.
Upewnij się, że treść ma strukturę, którą określa dana trasa.
Upewnij się, że każdy project_id mieści się w żądanym zakresie projektów.
Nie zmieniaj kanonicznych wartości wyliczeniowych ani identyfikatorów.
Wykonuj next_action tylko wtedy, gdy klient obsługuje jego code i target.
Rozróżniaj null, pominięte pole i pustą listę. To 3 różne stany.

Odpowiedź 200 OK może zawierać pustą listę. Pusta lista logów oznacza, że żaden log nie pasuje do żądania. Nie oznacza, że problemy, ślady lub akcje też są puste. Nie łącz sygnałów tylko dlatego, że mają zbliżone znaczniki czasu. Przechodź do śladu tylko wtedy, gdy odpowiedź zawiera jego dokładny trace_id. 404 i pusta lista to różne wyniki. Trasa listy zwraca [], gdy żaden rekord nie pasuje. Trasa szczegółów zwraca 404 z code: not_found, gdy nie znajduje rekordu dostępnego do odczytu. Żaden z tych wyników nie dowodzi, że przyjmowanie danych się nie powiodło.

Co wysyłać

Odpowiedzi są tak przydatne, jak telemetria, którą wysyłasz. Wysyłaj te wartości w każdej kopercie lub konfiguracji SDK:

release i environment.
Stałe nazwy usług, akcji i metryk.
Kontekst śladu, gdy logi, spany (pojedyncze mierzone operacje), akcje i problemy należą do tego samego żądania.
Kanoniczne wartości ważności: info, warning, error i critical.
Atrybuty pomocne w debugowaniu, bez sekretów i zbędnych danych osobowych.

Zobacz Integracja SDK i Kontrola rejestrowanych danych.

Odpowiedź przyjmowania danych

Publiczne SDK same odczytują odpowiedź POST /v1/events. Kod aplikacji nie musi jej obsługiwać.

Odpowiedź na paczkę SDK

Przyjęta paczka SDK zwraca 200 OK z liczbą przyjętych zdarzeń dla każdego strumienia:

{
  "issues": 1,
  "logs": 2,
  "trace_spans": 3,
  "actions": 1,
  "metrics": 1,
  "already_accepted": 0,
  "context_updated": true,
  "next": "review accepted telemetry in logs, issues, traces, actions, metrics, or live feed",
  "next_action": {
    "code": "review_ingested_telemetry",
    "target": "telemetry_reads"
  }
}

Pole	Znaczenie
`issues`, `logs`, `trace_spans`, `actions`, `metrics`	Zdarzenia z tej paczki, które LogBrew przyjął.
`already_accepted`	Zdarzenia, których ID LogBrew przyjął wcześniej. LogBrew nie zapisuje ich ponownie.
`context_updated`	`true`, gdy paczka zaktualizowała kontekst wydania lub środowiska.

Liczby dotyczą tylko tej paczki. Ponowienie paczki, którą LogBrew już przyjął, zwraca 0 dla każdego strumienia, a w already_accepted liczbę zdarzeń. Przy ponowieniu zachowaj oryginalne ID zdarzeń.

Odpowiedź na natywną kopertę

POST /api/telemetry/ingest zwraca 200 OK z liczbą przyjętych elementów dla każdego strumienia:

{
  "issues": 0,
  "logs": 1,
  "trace_spans": 0,
  "actions": 1,
  "already_accepted": 0,
  "next": "review accepted telemetry in logs, issues, traces, actions, or live feed",
  "next_action": {
    "code": "review_ingested_telemetry",
    "target": "telemetry_reads"
  }
}

Natywna odpowiedź nie ma pól metrics ani context_updated. Nie dodawaj ich. already_accepted liczy elementy, których id LogBrew przyjął wcześniej dla projektu. Zobacz bezpośrednie wysyłanie natywnej koperty.

Błędy przyjmowania danych

401 z code: ingest_key_invalid oznacza, że token bearer wysyłania został unieważniony, wygasł lub nie jest ważny dla projektu. W POST /v1/events brak tokena bearer albo token bearer, który nie jest kluczem wysyłania, zwraca 401 z code: unauthorized. Użyj aktualnego tokena bearer wysyłania przypisanego do projektu. Nie ponawiaj żądania z tokenem bearer konta. Odrzucona paczka SDK zwraca 422 z code: validation_failed:

{
  "error": "SDK event ids must be unique within a batch",
  "code": "validation_failed",
  "next": "send release/environment context plus issue, log, span, action, or metric events from a current LogBrew SDK",
  "next_action": {
    "code": "fix_request",
    "target": "request"
  }
}

Inne wartości error to między innymi SDK event batch requires at least one event i SDK event type is not supported by this ingest route. Sprawdź wersję SDK i konfigurację transportu. Nie wysyłaj pustej paczki. Nie zmieniaj typów ani ID zdarzeń tylko po to, aby paczka przeszła walidację. Żądanie z metodą inną niż POST zwraca 405 z code: method_not_allowed. Nieczytelna treść JSON zwraca code: invalid_json.

Format odpowiedzi list telemetrii

Trasy list domyślnie zwracają zwykłą tablicę JSON. Pusta lista w udanej odpowiedzi to []. Z pagination=cursor trasa zwraca kopertę (envelope). Klucz kolekcji odpowiada sygnałowi:

Trasa	Klucz kolekcji
`/api/logs`	`logs`
`/api/telemetry/issues`	`issues`
`/api/telemetry/issues/{issue_id}/events`	`events` oraz `issue_id` na najwyższym poziomie
`/api/telemetry/actions`	`actions`
`/api/telemetry/metrics`	`metrics`
`/api/telemetry/releases`	`releases`
`/api/telemetry/traces`	`traces` oraz `naming_quality` na najwyższym poziomie

next_cursor to obiekt z polami kontynuacji albo null na ostatniej stronie. Wiersze są posortowane od najnowszych. Zobacz paginację kursorową.

Odpowiedź z logami

Strona kursora z logami przy limit=1:

{
  "logs": [
    {
      "id": "150d1288-bec2-49ec-a036-3f7ac55f1b2d",
      "project_id": "123e4567-e89b-12d3-a456-426614174000",
      "level": "warning",
      "severity": "warning",
      "triage": {
        "effective_severity": "warning",
        "ignored": false,
        "rule_applied": false
      },
      "source": "runtime",
      "message": "checkout retry scheduled",
      "attributes": { "route": "/checkout" },
      "occurred_at": "2026-06-01T12:00:00Z",
      "environment": "production",
      "release": "api@1.2.3",
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
      "span_id": "00f067aa0ba902b7",
      "service_name": "checkout-api",
      "sdk_name": "@logbrew/node",
      "sdk_version": "0.1.8",
      "next_action": {
        "code": "inspect_trace",
        "target": "trace_summary"
      }
    }
  ],
  "next_cursor": {
    "time": "2026-06-01T12:00:00Z",
    "id": "150d1288-bec2-49ec-a036-3f7ac55f1b2d"
  }
}

Logi zawierają level dla zgodności i severity do wyświetlania. Oba pola mają wartość kanoniczną. triage zawiera wynik reguły ważności. Zobacz odpowiedzi reguł ważności. trace_id i span_id mają wartość null, gdy log nie jest powiązany ze śladem. Wtedy next_action to inspect_related_logs z celem telemetry_logs. Logi, problemy i akcje używają tych samych 2 par next_action. GET /api/logs/{log_id} zwraca jeden log w tej samej strukturze.

Odpowiedź z problemem

GET /api/telemetry/issues/{issue_id} zwraca jeden zgrupowany problem. Lista zwraca te same obiekty. Ten przykład używa domyślnej wersji odpowiedzi 1:

{
  "id": "9b2b4b3a-bd4e-4f85-a0f6-48118f037c17",
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "fingerprint": "payment-error",
  "severity": "error",
  "triage": {
    "effective_severity": "error",
    "ignored": false,
    "rule_applied": false
  },
  "title": "PaymentError",
  "message": "payment provider timed out",
  "stack_trace": null,
  "attributes": {},
  "environment": "production",
  "release": "checkout@1.2.3",
  "service_name": "checkout-api",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7",
  "next_action": {
    "code": "inspect_trace",
    "target": "trace_summary"
  },
  "status": "unresolved",
  "occurrence_count": 2,
  "first_seen_at": "2026-07-13T07:00:00Z",
  "last_seen_at": "2026-07-13T08:00:00Z"
}

W wersji 1 status to unresolved, resolved lub ignored. Dla zarchiwizowanego problemu triage.ignored ma wartość true. Pary next_action i odczyty, które po nich następują, opisuje przewodnik Zbadaj problem. first_seen_at i last_seen_at to czasy pierwszego i ostatniego wystąpienia. Nie zmieniają się po zmianie statusu. Niektóre pola pojawiają się tylko wtedy, gdy LogBrew ma dane:

Pole	Kiedy się pojawia
`span_id`	Problem jest powiązany ze spanem. W przeciwnym razie pole jest pominięte.
`diagnostics`	Ostatnie wystąpienie ma typ wyjątku lub breadcrumby. Zobacz historię wystąpień problemu.
`symbolication`	Tylko w `GET /api/telemetry/issues/{issue_id}`, gdy problem ma tożsamość artefaktu wydania. Zobacz Mapy źródeł JavaScript.

symbolication.status to resolved, invalid_metadata, artifact_not_found, source_not_resolved lub unavailable. Lista, zmiany statusu i zmiany reguł nie zwracają symbolication. Z response_version=2 problem ma te same pola, z następującymi zmianami:

Pole	Wartość w wersji 2
`status`	`unresolved`, `resolved` lub `archived`. Wersja 1 pokazuje `archived` jako `ignored`.
`priority`	`high`, `medium` lub `low`.
`priority_source`	`manual`, gdy priorytet ustawiła osoba. `derived`, gdy priorytet wynika z efektywnego poziomu ważności.

{
  "id": "9b2b4b3a-bd4e-4f85-a0f6-48118f037c17",
  "status": "archived",
  "severity": "error",
  "priority": "low",
  "priority_source": "manual"
}

Ten przykład pokazuje tylko część pól. Wyliczony priorytet to high dla error i critical, medium dla warning oraz low dla info. Korzysta z triage.effective_severity, więc reguła ważności problemu może go zmienić. Z response_version=3 problem ma wszystkie pola wersji 2 oraz assignee. assignee ma wartość null, gdy problem nie ma przypisania:

{
  "id": "9b2b4b3a-bd4e-4f85-a0f6-48118f037c17",
  "status": "unresolved",
  "priority": "high",
  "priority_source": "derived",
  "assignee": {
    "user_id": "5d6e7f80-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
    "name": "Ada Example",
    "email": "ada@example.com"
  }
}

Pole	Znaczenie
`assignee.user_id`	ID użytkownika przypisanego konta. Wysyłaj je jako `assignee` w filtrze lub zmianie.
`assignee.name`	Nazwa przypisanego konta albo `null`, gdy konto nie ma nazwy.
`assignee.email`	Adres e-mail przypisanego konta.

Problem nie pokazuje przypisania, gdy przypisany członek nie ma już dostępu do odczytu projektu. Z response_version=4 pole assignee ma też type. Przypisanie do konta (user) ma user_id, name i email, tak jak w wersji 3. Przypisanie do zespołu (team) ma team_id, slug i name. Wersja 3 pokazuje przypisanie do zespołu jako null. CLI żąda wersji 4:

{
  "assignee": {
    "type": "team",
    "team_id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "slug": "payments",
    "name": "Payments"
  }
}

Każda inna wartość response_version zwraca 422 z code: validation_failed. Strona kursora używa tej samej wersji dla każdego problemu w issues.

Odpowiedź z listą kont i zespołów do przypisania

GET /api/telemetry/issues/assignees?project_id=<project_id> zwraca każde konto, któremu można przypisywać problemy w projekcie:

{
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "assignees": [
    {
      "user_id": "5d6e7f80-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
      "name": "Ada Example",
      "email": "ada@example.com"
    },
    {
      "user_id": "0f1e2d3c-4b5a-4968-8776-655443322110",
      "name": null,
      "email": "sam@example.com"
    }
  ]
}

Dodaj response_version=2, aby dostać też teams: każdy zespół organizacji projektu z team_id, slug i name. Jeśli konto nie może odczytać projektu, trasa zwraca 404 z code: not_found.

Odpowiedź z akcją

{
  "id": "d8ee3a6f-3918-440b-96cb-14166419399a",
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "checkout_failed",
  "distinct_id": "user_123",
  "session_id": "session_456",
  "occurred_at": "2026-06-01T12:00:00Z",
  "properties": { "surface": "checkout" },
  "environment": "production",
  "release": "checkout@1.2.3",
  "service_name": "checkout-api",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7",
  "next_action": {
    "code": "inspect_trace",
    "target": "trace_summary"
  }
}

distinct_id śledzi jednego aktora lub jedną sesję. Traktuj distinct_id i session_id jako nieprzezroczyste identyfikatory (opaque). session_id i trace_id mają wartość null, gdy ich brakuje. span_id jest pomijany, gdy go brakuje. Akcja nie ma poziomu ważności. Zobacz Rejestrowanie zdarzeń produktowych.

Odpowiedź z metryką

{
  "id": "6f1c2d3e-4a5b-4c6d-8e7f-901234567890",
  "event_id": "metric-1",
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "http.server.duration",
  "kind": "histogram",
  "value": 12.5,
  "unit": "ms",
  "temporality": "delta",
  "attributes": {},
  "occurred_at": "2026-07-13T08:00:00Z",
  "environment": "production",
  "release": "checkout@1.2.3",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7",
  "service_name": "checkout-api",
  "sdk_name": "@logbrew/node",
  "sdk_version": "0.1.8"
}

Każdy element to jedna próbka. Nie używaj liczby próbek jako liczby zdarzeń ani użytkowników. unit, temporality, trace_id i span_id mają wartość null, gdy ich brakuje. Wartość null to nie zero.

Odpowiedź z wydaniem

{
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "release": "api@1.2.3",
  "environment": "production",
  "service_name": "checkout-api",
  "issue_count": 3,
  "log_count": 824,
  "trace_span_count": 421,
  "action_count": 19,
  "metric_count": 87,
  "first_seen_at": "2026-06-01T12:00:00Z",
  "last_seen_at": "2026-06-01T12:15:00Z",
  "trace_health": {
    "status": "errors_observed",
    "trace_count": 42,
    "error_trace_count": 3,
    "error_rate_basis_points": 714
  },
  "next_action": {
    "code": "inspect_release_issues",
    "target": "telemetry_issues"
  }
}

Jeden wiersz obejmuje jeden projekt, wydanie, środowisko i usługę. Jego liczby opisują tylko ten wiersz. trace_health.status to unknown, gdy wiersz nie ma śladów, a w pozostałych przypadkach no_errors_observed lub errors_observed. error_rate_basis_points to udział śladów ze spanem błędu, od 0 do 10000. To nie jest wskaźnik błędów dla wszystkich żądań. next_action wskazuje pierwszy typ sygnału, który ma dane, w tej kolejności:

`code`	`target`
`inspect_release_issues`	`telemetry_issues`
`inspect_release_traces`	`trace_explorer`
`inspect_release_logs`	`telemetry_logs`
`inspect_release_actions`	`telemetry_actions`
`inspect_release_metrics`	`telemetry_metrics`
`review_release_telemetry`	`telemetry_reads`

Zobacz Wydania.

Odpowiedź z wyszukiwania śladów

GET /api/telemetry/traces?pagination=cursor zwraca jeden wiersz dla każdego śladu oraz potwierdzenie naming_quality dla zwróconej strony:

{
  "traces": [
    {
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
      "project_ids": ["123e4567-e89b-12d3-a456-426614174000"],
      "root_span_name": "POST /checkout",
      "root_service_name": "checkout-api",
      "root_operation": "http.server",
      "span_count": 3,
      "error_span_count": 1,
      "service_count": 1,
      "started_at": "2026-06-01T12:00:00Z",
      "duration_ms": 45,
      "services": ["checkout-api"],
      "releases": ["checkout@1.2.3"],
      "environments": ["production"],
      "next_action": {
        "code": "inspect_trace",
        "target": "trace_summary"
      }
    }
  ],
  "next_cursor": null,
  "naming_quality": {
    "evaluated_traces": 1,
    "meaningful_name_traces": 1,
    "generic_name_traces": 0,
    "unmatched_route_traces": 0,
    "generic_operation_traces": 0,
    "truncated": false,
    "next_action": null
  }
}

naming_quality dotyczy tylko zwróconej strony. To nie jest wynik dla całego konta. truncated: true oznacza, że istnieje kolejna strona. Gdy strona ma ogólną nazwę, niedopasowaną trasę HTTP lub ogólną operację, next_action to improve_trace_naming z celem sdk_configuration. Bez pagination=cursor trasa zwraca zwykłą tablicę śladów bez naming_quality. next_cursor zawiera time i trace_id. Wyślij je jako cursor_time i cursor_trace_id. GET /api/telemetry/traces/{trace_id} zwraca spany jednego śladu. GET /api/telemetry/traces/{trace_id}/summary zwraca span główny, spany błędów, usługi, czas trwania i najwolniejszą ścieżkę, bez surowych atrybutów spanów. 404 z podsumowania oznacza, że żaden ślad nie pasuje do pełnego zakresu. Nie usuwaj filtrów, aby ponowić żądanie. Zobacz odpowiedzi ze spanami i podsumowaniem śladu.

Puste listy i brakujące rekordy

Odczyt listy może nie mieć dopasowań. Odczyt szczegółów działa według innych zasad:

Żądanie	Sukces	Brak rekordu dostępnego do odczytu
`GET /api/logs/{log_id}`	`200` z jednym logiem	`404` z `code: not_found`
`GET /api/telemetry/issues/{issue_id}`	`200` z jednym problemem	`404` z `code: not_found`
`GET /api/telemetry/issues/{issue_id}/events`	`200` z wystąpieniami	`404` z `code: not_found` na pierwszej stronie
`GET /api/telemetry/traces/{trace_id}`	`200` ze spanami	`200` z `[]`
`GET /api/telemetry/traces/{trace_id}/summary`	`200` z jednym podsumowaniem	`404` z `code: not_found`

Brakujący log zwraca taki 404:

{
  "error": "log not found",
  "code": "not_found",
  "next": "check the resource id or filters and retry",
  "next_action": {
    "code": "check_resource",
    "target": "resource"
  }
}

Brakujący problem używa "error": "issue not found". Brakujące podsumowanie śladu używa "error": "trace not found". Nieznane ID i ID, którego konto nie może odczytać, zwracają tę samą odpowiedź. Lista z jednym project_id, którego konto nie może odczytać, zwraca 200 z pustą listą. Sprawdź ID projektu, zanim zgłosisz, że danych nie ma.

Odrzucony wybór projektów

Listy logów, problemów, akcji, metryk, wydań i śladów przyjmują jeden projekt w project_id albo od 2 do 50 projektów w project_ids. Katalog atrybutów logów przyjmuje te same selektory. Historia wystąpień problemu ich nie przyjmuje. Żądanie z project_id i project_ids jednocześnie zwraca 422:

{
  "error": "project_id and project_ids are mutually exclusive",
  "code": "validation_failed",
  "next": "use project_id for one project, project_ids=uuid,uuid for two to fifty projects, or omit both for all readable projects",
  "next_action": {
    "code": "fix_request",
    "target": "request"
  }
}

project_ids z nieprawidłowym UUID, powtórzonym ID albo z mniej niż 2 lub więcej niż 50 ID również zwraca 422 z code: validation_failed. Jeśli konto nie może odczytać jednego projektu ze zbioru project_ids, całe żądanie zwraca 404. Nie zwraca pozostałych projektów jako wyniku częściowego:

{
  "error": "project selection not found",
  "code": "not_found",
  "next": "refresh readable projects and retry with only project IDs you can read",
  "next_action": {
    "code": "check_resource",
    "target": "resource"
  }
}

Pokaż błąd, a nie pustą listę ani zerową liczbę. Odczytaj listę projektów ponownie. Nie usuwaj projektu po cichu i nie ponawiaj żądania dla wszystkich projektów. Delegowane poświadczenie, na przykład połączenie MCP, zwraca 403 z code: forbidden dla projektu, którego to połączenie nie obejmuje. Zobacz zakres projektów.

Błędy kursora

Logi, problemy, akcje, metryki i wystąpienia problemów używają cursor_time i cursor_id. Odrzucony kursor zwraca 422 z code: validation_failed. Te błędy nie oznaczają, że lista jest pusta.

Żądanie	`error`
`pagination=cursor` tylko z 1 z 2 pól kursora	`cursor_time and cursor_id must be sent together`
`cursor_time`, który nie jest znacznikiem czasu RFC3339	`cursor_time must be an RFC3339 timestamp`
Pola kursora bez `pagination=cursor` albo z inną wartością `pagination`	`pagination must be cursor when cursor pagination is requested`

Na przykład:

{
  "error": "cursor_time and cursor_id must be sent together",
  "code": "validation_failed",
  "next": "send pagination=cursor alone for the first page, then send cursor_time and cursor_id together from next_cursor",
  "next_action": {
    "code": "fix_request",
    "target": "request"
  }
}

Skopiuj cały next_cursor z poprzedniej strony. Nie zastępuj cursor_time bieżącym czasem. Jeśli kursor zaginął, zacznij od nowa z pagination=cursor i pierwotnymi filtrami. Nieznany parametr zapytania lub wartość niewłaściwego typu zwraca 422 z "error": "invalid query parameters".

Odpowiedzi z kursorem wydań

Kursor wydań ma 5 pól. Udane żądanie bez dopasowań zwraca 200:

{
  "releases": [],
  "next_cursor": null
}

Gdy next_cursor nie jest null, wyślij wszystkie 5 wartości w następnym żądaniu:

Pole `next_cursor`	Parametr zapytania
`time`	`cursor_time`
`project_id`	`cursor_project_id`
`release`	`cursor_release`
`environment`	`cursor_environment`
`service_name`	`cursor_service_name`

cursor_project_id oznacza pozycję. Nie zastępuje project_id ani project_ids. Zachowaj pierwotne parametry projektu i filtrów. Zakoduj każdą wartość do użycia w URL (URL encoding). Z pagination=cursor niepełny kursor albo pusta wartość wydania, środowiska lub usługi zwraca 422 z "error": "all release cursor fields must be sent together". Nieprawidłowy cursor_time i brak pagination=cursor zwracają te same błędy co inne kursory.

Błędy wyszukiwania śladów

Te błędy dotyczą GET /api/telemetry/traces. Każdy zwraca 422 z code: validation_failed. Odrzucone żądanie to nie pusty wynik.

Żądanie	`error`
`status` inny niż `error` lub `ok`	`trace status must be error or ok`
`min_duration_ms` poniżej `0`	`minimum trace duration must not be negative`
Tylko 1 pole kursora albo pusty `cursor_trace_id`	`cursor_time and cursor_trace_id must be sent together`
`cursor_time`, który nie jest znacznikiem czasu RFC3339	`cursor_time must be an RFC3339 timestamp`
Pola kursora bez `pagination=cursor`	`pagination must be cursor when cursor pagination is requested`

Aby uwzględnić oba stany śladów, pomiń status. Dla następnej strony skopiuj next_cursor.time do cursor_time i next_cursor.trace_id do cursor_trace_id. Nie wysyłaj cursor_id dla strony śladów. Zobacz filtry śladów.

Historia wystąpień problemu

GET /api/telemetry/issues/{issue_id}/events odczytuje wystąpienia jednego zgrupowanego problemu. Użyj tokena bearer konta i ID zgrupowanego problemu. Trasa przyjmuje tylko pagination, cursor_time, cursor_id i limit. Nie przyjmuje filtrów projektu, czasu, wydania, środowiska ani ważności.

curl --get "https://api.logbrew.co/api/telemetry/issues/$ISSUE_ID/events" \
  --header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  --data-urlencode "pagination=cursor" \
  --data-urlencode "limit=1"

Pierwsza strona z jednym wystąpieniem i kursorem kontynuacji:

{
  "issue_id": "d1776d70-763c-47b5-a8f1-76f593221e2b",
  "events": [
    {
      "id": "db619770-1f7c-4bd5-8310-9f171df8af47",
      "issue_id": "d1776d70-763c-47b5-a8f1-76f593221e2b",
      "project_id": "123e4567-e89b-12d3-a456-426614174000",
      "severity": "error",
      "title": "Checkout failed",
      "message": "Checkout could not complete",
      "stack_trace": null,
      "attributes": {
        "exception": {
          "type": "CheckoutError",
          "mechanism": { "type": "javascript.error", "handled": false }
        },
        "breadcrumbs": [
          {
            "timestamp": "2026-06-01T11:54:59Z",
            "category": "checkout",
            "message": "Checkout started"
          }
        ]
      },
      "diagnostics": {
        "schema_version": 1,
        "exception": {
          "type": "CheckoutError",
          "mechanism": { "type": "javascript.error", "handled": false }
        },
        "breadcrumbs": [
          {
            "timestamp": "2026-06-01T11:54:59Z",
            "category": "checkout",
            "message": "Checkout started"
          }
        ],
        "breadcrumbs_truncated": false
      },
      "environment": "production",
      "release": "api@1.2.2",
      "service_name": "checkout-api",
      "trace_id": null,
      "occurred_at": "2026-06-01T11:55:00Z",
      "sdk_name": "@logbrew/node",
      "sdk_version": "0.1.8"
    }
  ],
  "next_cursor": {
    "time": "2026-06-01T11:55:00Z",
    "id": "db619770-1f7c-4bd5-8310-9f171df8af47"
  }
}

Pole	Znaczenie
`issue_id`	Zgrupowany problem, do którego należy wystąpienie.
`events[].id`	ID jednego wystąpienia. Użyj go, aby wybrać to wystąpienie.
`events[].occurred_at`	Kiedy to wystąpienie nastąpiło w aplikacji.
`events[].severity`	Zarejestrowany poziom ważności tego wystąpienia. Reguła ważności go nie zmienia.
`events[].release`, `environment`, `service_name`	Kontekst zarejestrowany razem z tym wystąpieniem.

Wystąpienie może być starsze niż last_seen_at grupy. Nie zastępuj jego wydania ani śladu wartościami ze zgrupowanego problemu. Lista nie zwraca statusu, triażu, priorytetu ani liczby wystąpień. diagnostics.schema_version to wersja obiektu diagnostyki. Odpowiedź pomija diagnostics i span_id, gdy wystąpienie nie ma takich danych. Wewnątrz diagnostics pomija brakujący exception i puste breadcrumbs. Jeśli breadcrumbs_truncated ma wartość true, części historii breadcrumbów nie ma w odpowiedzi. stack_trace i trace_id mają wartość null, gdy ich brakuje. Brak ID śladu nie dowodzi, że aplikacja nie wysyła śladów. Traktuj zarejestrowane komunikaty i atrybuty jako dane, a nie jako instrukcje. Wystąpienia są posortowane od najnowszych. Dla następnej strony wyślij to samo ID problemu, pagination=cursor, limit oraz wartości cursor_time i cursor_id z next_cursor. ID kursora to ID wystąpienia, a nie ID problemu. Pierwsza strona zwraca 404 z code: not_found, gdy problem nie ma wystąpień dostępnych do odczytu. Późniejsza strona może być pustą ostatnią stroną:

{
  "issue_id": "d1776d70-763c-47b5-a8f1-76f593221e2b",
  "events": [],
  "next_cursor": null
}

Nie używaj kursora ponownie dla innego problemu. Błędy kursora dotyczą też tej trasy.

Odpowiedzi ze spanami i podsumowaniem śladu

GET /api/telemetry/traces/{trace_id} zwraca spany jednego śladu. Dodaj /summary, aby dostać podsumowanie tych samych spanów. Obie trasy przyjmują tylko project_id, release i environment. Nie używają kursora wyszukiwania śladów. Filtry z poprzedniego żądania listy nie są przenoszone.

Lista spanów

Spany są uporządkowane według czasu rozpoczęcia:

[
  {
    "id": "ed5c960b-e728-4637-bcd4-a27dfb1a0e96",
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "trace_id": "6e0c63257de34c92bdb0c8f1e9278a50",
    "span_id": "b37ac82563149fed",
    "parent_span_id": null,
    "name": "POST /checkout",
    "operation": "http.server",
    "status": "error",
    "started_at": "2026-06-01T12:00:00Z",
    "duration_ms": 823,
    "attributes": {},
    "environment": "production",
    "release": "api@1.2.3",
    "service_name": "checkout-api",
    "sdk_name": "@logbrew/node",
    "sdk_version": "0.1.8"
  },
  {
    "id": "0c2f7a51-4e8d-4b6a-9f13-2d7e5c8b1a90",
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "trace_id": "6e0c63257de34c92bdb0c8f1e9278a50",
    "span_id": "7a085853722dc6d2",
    "parent_span_id": "b37ac82563149fed",
    "name": "POST /v1/charges",
    "operation": "http.client",
    "status": "error",
    "started_at": "2026-06-01T12:00:00.100Z",
    "duration_ms": 640,
    "attributes": {},
    "environment": "production",
    "release": "api@1.2.3",
    "service_name": "checkout-api",
    "sdk_name": "@logbrew/node",
    "sdk_version": "0.1.8"
  }
]

status: "error" opisuje zarejestrowaną operację, a nie odczyt przez API. parent_span_id: null oznacza, że span nie ma ID spanu nadrzędnego. status: null oznacza, że span nie zgłosił statusu.

Podsumowanie śladu

Podsumowanie tych samych 2 spanów:

{
  "trace_id": "6e0c63257de34c92bdb0c8f1e9278a50",
  "span_count": 2,
  "error_span_count": 2,
  "service_count": 1,
  "project_count": 1,
  "started_at": "2026-06-01T12:00:00Z",
  "duration_ms": 823,
  "root_span": {
    "span_id": "b37ac82563149fed",
    "parent_span_id": null,
    "name": "POST /checkout",
    "operation": "http.server",
    "status": "error",
    "started_at": "2026-06-01T12:00:00Z",
    "duration_ms": 823,
    "service_name": "checkout-api"
  },
  "slowest_child_span": {
    "span_id": "7a085853722dc6d2",
    "parent_span_id": "b37ac82563149fed",
    "name": "POST /v1/charges",
    "operation": "http.client",
    "status": "error",
    "started_at": "2026-06-01T12:00:00.100Z",
    "duration_ms": 640,
    "service_name": "checkout-api"
  },
  "slowest_path": [
    {
      "span_id": "b37ac82563149fed",
      "parent_span_id": null,
      "name": "POST /checkout",
      "operation": "http.server",
      "status": "error",
      "started_at": "2026-06-01T12:00:00Z",
      "duration_ms": 823,
      "service_name": "checkout-api"
    },
    {
      "span_id": "7a085853722dc6d2",
      "parent_span_id": "b37ac82563149fed",
      "name": "POST /v1/charges",
      "operation": "http.client",
      "status": "error",
      "started_at": "2026-06-01T12:00:00.100Z",
      "duration_ms": 640,
      "service_name": "checkout-api"
    }
  ],
  "error_spans": [
    {
      "span_id": "b37ac82563149fed",
      "parent_span_id": null,
      "name": "POST /checkout",
      "operation": "http.server",
      "status": "error",
      "started_at": "2026-06-01T12:00:00Z",
      "duration_ms": 823,
      "service_name": "checkout-api"
    },
    {
      "span_id": "7a085853722dc6d2",
      "parent_span_id": "b37ac82563149fed",
      "name": "POST /v1/charges",
      "operation": "http.client",
      "status": "error",
      "started_at": "2026-06-01T12:00:00.100Z",
      "duration_ms": 640,
      "service_name": "checkout-api"
    }
  ],
  "services": [
    {
      "service_name": "checkout-api",
      "span_count": 2,
      "error_span_count": 2,
      "max_duration_ms": 823
    }
  ],
  "releases": ["api@1.2.3"],
  "environments": ["production"]
}

Pole	Znaczenie
`duration_ms`	Czas od najwcześniejszego startu spanu do najpóźniejszego końca spanu. To nie suma czasów trwania spanów.
`root_span`	Najwcześniejszy span, którego spanu nadrzędnego nie ma w śladzie. To punkt wyjścia, a nie udowodniona przyczyna.
`slowest_child_span`	Najdłuższy span, który ma ID spanu nadrzędnego, albo `null`.
`slowest_path`	Znany łańcuch spanów nadrzędnych od spanu głównego do `slowest_child_span`. Ma wartość `[]`, gdy `slowest_child_span` to `null`.
`error_spans`	Najdłuższe spany błędów, najwyżej 5. `error_span_count` może być większe.

Żadna z tych tras nie zwraca kursora ani pola obcięcia. Nie dodawaj wartości truncated, której nie ma w odpowiedzi.

Brak pasujących spanów

Gdy żaden span nie pasuje do ID śladu i zakresu, lista spanów zwraca 200 z []. Podsumowanie zwraca 404 z "error": "trace not found" i code: not_found. Sprawdź ID śladu i zakres. Nie usuwaj filtrów, aby wymusić wynik. Żaden z tych wyników nie dowodzi, że aplikacja nie wysłała telemetrii.

Format odpowiedzi ze zdarzeniami na żywo

Podgląd na żywo wysyła nowe zdarzenia. Nie odtwarza zdarzeń, które klient przegapił podczas rozłączenia. Istniejące rekordy odczytuj z tras list.

Utwórz bilet

Wyślij POST /api/feed/ticket z tokenem bearer konta. Żądanie nie ma treści.

curl --request POST "https://api.logbrew.co/api/feed/ticket" \
  --header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER"

Odpowiedź 200 OK zawiera bilet w polu ticket:

{
  "ticket": "<feed-ticket>",
  "expires_in_seconds": 60,
  "next": "connect with GET /api/feed/live?ticket=<ticket> before the ticket expires",
  "next_action": {
    "code": "connect_live_feed",
    "target": "live_feed"
  }
}

Bilet to krótkotrwałe poświadczenie. Nie zapisuj go w logach i nie umieszczaj go w prompcie agenta. Otwórz połączenie, zanim upłynie expires_in_seconds. Ten termin ogranicza moment rozpoczęcia połączenia, a nie czas jego trwania. 401 oznacza, że logowanie na konto nie jest ważne. Zaloguj się ponownie, zanim zażądasz biletu. Metoda inna niż POST zwraca 405 z code: method_not_allowed.

Otwórz połączenie

Połącz klienta WebSocket z wss://api.logbrew.co/api/feed/live?ticket=<feed-ticket>. Zakoduj bilet do użycia w URL. Nie umieszczaj w URL tokena bearer konta ani tokena bearer wysyłania. 401 oznacza, że bilet lub logowanie na konto nie jest ważne. Po ponownym zalogowaniu się utwórz nowy bilet.

Odpowiedź	Przyczyna	Następny krok
`422` z `"error": "feed ticket is required"`	Brakuje wartości zapytania `ticket` albo jest pusta.	Utwórz bilet i połącz się z jego użyciem.
`401` z `code: unauthorized`	Bilet wygasł lub jest nieważny.	Utwórz nowy bilet. Nie ponawiaj połączenia z tym samym biletem.
`code: invalid_websocket_upgrade`	Żądanie nie jest prawidłowym żądaniem przejścia na WebSocket (upgrade).	Użyj klienta WebSocket.
`405` z `code: method_not_allowed`	Żądanie nie używa `GET`.	Do połączenia użyj `GET`.

Po błędzie odczekaj, zanim połączysz się ponownie. Nie łącz się ponownie w ciasnej pętli.

Odczytaj komunikaty

Każdy komunikat to koperta { "type": "...", "data": ... }. Odczytaj type, zanim sparsujesz data. Pomijaj typy, których klient nie obsługuje.

Typ zdarzenia	Dane
`native_log`	Dane logu w strukturze odpowiedzi z logami.
`native_issue`	Dane zgrupowanego problemu w strukturze odpowiedzi z problemem w wersji 1.
`native_trace_span`	Jeden span w strukturze elementu listy spanów.
`native_action`	Dane akcji produktowej w strukturze odpowiedzi z akcją.
`project_created`, `project_updated`, `project_catalog_changed`	Dane projektu. Po zmianie odczytaj listę projektów ponownie.
`usage_updated`, `usage_limit_warning`, `usage_limit_blocked`	Wykorzystanie konta w strukturze wykorzystania konta.

{
  "type": "native_log",
  "data": {
    "id": "150d1288-bec2-49ec-a036-3f7ac55f1b2d",
    "project_id": "123e4567-e89b-12d3-a456-426614174000",
    "level": "warning",
    "severity": "warning",
    "triage": {
      "effective_severity": "warning",
      "ignored": false,
      "rule_applied": false
    },
    "source": "runtime",
    "message": "checkout retry scheduled",
    "attributes": { "route": "/checkout" },
    "occurred_at": "2026-06-01T12:00:00Z",
    "environment": "production",
    "release": "api@1.2.3",
    "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
    "span_id": "00f067aa0ba902b7",
    "service_name": "checkout-api",
    "sdk_name": "@logbrew/node",
    "sdk_version": "0.1.8",
    "next_action": {
      "code": "inspect_trace",
      "target": "trace_summary"
    }
  }
}

Zdarzenie native_issue używa wersji 1 odpowiedzi z problemem: zarchiwizowany problem ma status ignored, a zdarzenie nie ma priorytetu. Metryki i wydania nie są typami zdarzeń na żywo. Odczytuj je z ich tras list. Bilet nie wybiera projektu. Sprawdź project_id każdego zdarzenia, zanim pokażesz je w widoku projektu. logbrew watch --json korzysta z tego podglądu na żywo. Zobacz dokumentację referencyjną CLI.

Obsłuż zamknięte połączenie

Kod zamknięcia	Powód	Następny krok
`1013`	`live feed fell behind; reconnect to resync`	Odczekaj, a potem połącz się ponownie z nowym biletem. Ponownie odczytaj dane z tras list, aby pobrać przegapione rekordy.
`1008`	`live feed access changed; sign in again`	Przestań łączyć się ponownie. Zaloguj się ponownie, zanim utworzysz nowy bilet.

Inne rozłączenia mogą nie mieć powodu podanego przez LogBrew. Po ponownym połączeniu ponownie odczytaj dane z tras list i dopasuj rekordy według ID.

Przykłady odpowiedzi na zmianę statusu problemu

PATCH /api/telemetry/issues/{issue_id} z { "status": "resolved" } zwraca 200 OK ze zaktualizowanym zgrupowanym problemem w tej samej strukturze co odpowiedź z problemem. Parametr zapytania response_version wybiera wersję. Odpowiedź nie zawiera flagi powodzenia. Treść ustawia co najmniej jedno z pól status, priority i assignee. status przyjmuje unresolved, resolved lub archived. ignored to starsza nazwa archived. Zobacz Zaktualizuj jeden problem. Sprawdź zwrócone id, status i priority, zanim pokażesz powodzenie. Nie buduj wyniku z wysłanych wartości. Zmiana statusu nie usuwa wystąpień ani nie zmienia first_seen_at i last_seen_at. Nie zmienia też severity ani reguły ważności. Odrzucona zmiana zwraca 422 z code: validation_failed:

{
  "error": "issue status must be unresolved, resolved, or archived",
  "code": "validation_failed",
  "next": "use status=unresolved, status=resolved, or status=archived",
  "next_action": {
    "code": "fix_request",
    "target": "request"
  }
}

Wynik	Przyczyna
`422`, `issue update requires status, priority, or assignee`	Treść nie ma żadnego z 3 pól.
`422`, `issue priority must be high, medium, or low`	Wartość priorytetu nie jest obsługiwana.
`422`, `issue assignee must be me, none, a user ID, or team:<team_id>`	Wartość `assignee` nie jest obsługiwana.
`422`, `issue assignee cannot read this project`	Przypisane konto nie ma dostępu do projektu. LogBrew niczego nie zmienia.
`422`, `issue assignee team is not a team of this project's organization`	Zespół nie należy do organizacji projektu. LogBrew niczego nie zmienia.
`403` z `code: forbidden`	Konto nie może zarządzać problemami w projekcie.
`404` z `code: not_found`	Konto nie może odczytać problemu albo problem nie istnieje.

Pole, które ma już żądaną wartość, się nie zmienia. Po przekroczeniu limitu czasu lub utracie odpowiedzi wyślij to samo żądanie ponownie albo najpierw odczytaj problem. Nie wysyłaj innej zmiany, zanim odczytasz bieżący stan. Zobacz Zapisy. POST /api/telemetry/issues/bulk zwraca 200 OK z 1 wynikiem dla każdego żądanego ID problemu, w kolejności z żądania. Każdy znaleziony problem ma strukturę wersji 3. Wynik not_found ma issue: null:

{
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "results": [
    {
      "issue_id": "9b2b4b3a-bd4e-4f85-a0f6-48118f037c17",
      "outcome": "updated",
      "issue": {
        "id": "9b2b4b3a-bd4e-4f85-a0f6-48118f037c17",
        "status": "archived",
        "priority": "high",
        "priority_source": "derived",
        "assignee": null
      }
    },
    {
      "issue_id": "3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "outcome": "not_found",
      "issue": null
    }
  ]
}

Ten przykład pokazuje tylko część pól problemu. outcome to updated, unchanged lub not_found. Powtórzone żądanie zwraca unchanged i niczego nie zmienia. Zobacz Zaktualizuj wiele problemów naraz. Żądanie zbiorcze kończy się błędem w całości w tych przypadkach:

Wynik	Przyczyna
`422`, `issue_ids must name 1 to 100 issues`	Lista jest pusta lub ma więcej niż 100 ID.
`422`, `issue_ids must not contain duplicates`	Jakieś ID występuje więcej niż raz.
`422` z `code: invalid_json`	Treść ma nieznane pole.
`403` z `code: forbidden`	Konto nie może zarządzać problemami w projekcie.
`404`, `project not found`	Konto nie może odczytać projektu.

Zakres żądań analityki

Trasy analityki, trasa szeregu metryki i trasa wolumenu sygnałów odczytują jeden projekt i jeden zakres czasu. Każde żądanie wymaga project_id i since. since przyjmuje skrócony zapis czasu trwania, na przykład 24h lub 7d, albo znacznik czasu RFC3339. until przyjmuje znacznik czasu RFC3339, a domyślnie ma wartość czasu żądania. Zakres obejmuje since, wyklucza until i nie może przekraczać 31 dni. service_name, release i environment to opcjonalne filtry dokładne. Każda wartość musi mieć od 1 do 256 znaków po usunięciu spacji przez LogBrew. Trasa porównania segmentów umieszcza te filtry wewnątrz każdego segmentu, a nie na najwyższym poziomie. Jeśli konto nie może odczytać projektu, te trasy zwracają 200 OK z zerowymi liczbami. Nie zwracają 404. Pusty wynik nie potwierdza dostępu do projektu. Porównaj project_id z projektami, które konto może odczytać. Żądanie przez połączenie MCP, które nie obejmuje projektu, zwraca 403 i forbidden.

Trasa	Wartości `response_version`	Domyślnie
`GET /api/telemetry/analytics/overview`	`1`, `2` lub `3`	`1`
`GET /api/telemetry/analytics/properties`	`1` lub `2`	`1`
`POST /api/telemetry/analytics/segments/compare`	`1` lub `2`	`1`
`POST /api/telemetry/analytics/retention`	`1` lub `2`	`1`
`POST /api/telemetry/analytics/lifecycle`	`1` lub `2`	`1`
`POST /api/telemetry/analytics/funnel`	Nie przyjmuje	Schemat `1`
`POST /api/telemetry/analytics/paths`	Nie przyjmuje	Schemat `1`
`GET /api/telemetry/metrics/series`	Nie przyjmuje	Schemat `1`
`GET /api/telemetry/summary/volume`	`1`	`1`

Każda odpowiedź zaczyna się od schema_version, query i purpose. query powtarza efektywny zakres. Pomija filtr, którego nie wysłano. purpose to zwykły tekst, który wyjaśnia, na jakie pytanie odpowiada trasa. Wskaźnik jest pomijany, gdy jego mianownik wynosi zero. Pominięty wskaźnik nie oznacza ani 0, ani null. Odczytaj coverage, zanim zaufasz wskaźnikowi.

Wspólne błędy zakresu

Te błędy używają HTTP 422 i validation_failed:

Przyczyna	`error`
Brak `project_id`	`product analytics project_id is required`
Brak `since`	`product analytics since is required`
`since` nie jest czasem trwania ani znacznikiem czasu RFC3339	`invalid since value`
`until` nie jest znacznikiem czasu RFC3339	`product analytics until must be an RFC3339 timestamp`
`since` nie jest wcześniejsze niż `until`	`product analytics since must be earlier than until`
Zakres jest dłuższy niż 31 dni	`product analytics range must not exceed 31 days`
Pusty filtr albo filtr dłuższy niż 256 znaków	`product analytics context filters must be non-empty and at most 256 characters`

Na przykład żądanie bez project_id zwraca:

{
  "error": "product analytics project_id is required",
  "code": "validation_failed",
  "next": "choose one owned project and send its project_id",
  "next_action": { "code": "fix_request", "target": "request" }
}

Trasy szeregu metryki i wolumenu sygnałów stosują te same zasady zakresu, ale z własnym tekstem error. Te błędy wymieniają sekcje tych tras poniżej. Nieznany parametr zapytania zwraca 422 z odpowiedzią nieprawidłowe parametry zapytania. Nieznane pole JSON, brak wymaganego pola JSON lub nieobsługiwana wartość wyliczeniowa zwraca invalid_json. Zobacz Nieprawidłowy JSON. Żądanie z niewłaściwą metodą HTTP zwraca 405 i method_not_allowed. Jego tekst next podaje obsługiwaną metodę i pola. Zobacz Nieobsługiwana metoda.

Odpowiedź z przeglądem analityki produktowej

GET /api/telemetry/analytics/overview pokazuje aktywność w jednym projekcie: wolumen akcji, użytkowników, sesje, szereg czasowy, najczęstsze akcje oraz sklasyfikowane wyświetlenia stron, wyświetlenia ekranów i interakcje. Użyj go, aby znaleźć dokładne nazwy zdarzeń dla pozostałych tras analityki. Wysyłaj response_version=3. Wersje 1 i 2 zwracają te same liczby, ale ich wartość estimation.method to starszy token. Wersja 1 nie sprawdza rodzaju podmiotu, gdy liczy zidentyfikowanych użytkowników. Wersje 2 i 3 liczą tylko podmioty rodzaju user i dodają liczby anonimowych podmiotów oraz subject_coverage. To żądanie odczytuje jedną godzinę w przedziałach pięciominutowych i zwraca po 2 wiersze na każdej liście najczęstszych pozycji:

curl --get "https://api.logbrew.co/api/telemetry/analytics/overview" \
  --header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  --data-urlencode "project_id=<project_id>" \
  --data-urlencode "since=2026-06-01T11:00:00Z" \
  --data-urlencode "until=2026-06-01T12:00:00Z" \
  --data-urlencode "interval=5m" \
  --data-urlencode "top_limit=2" \
  --data-urlencode "response_version=3"

Udany przegląd

W tym syntetycznym wyniku projekt ma 120 akcji w 2 z 12 przedziałów. Od anonimowych podmiotów pochodzi 20 akcji. Każda akcja ma ID sesji. Połowa akcji ma ID śladu.

{
  "schema_version": 3,
  "query": {
    "project_id": "11111111-1111-4111-8111-111111111111",
    "since": "2026-06-01T11:00:00Z",
    "until": "2026-06-01T12:00:00Z",
    "interval": "5m",
    "interval_seconds": 300,
    "top_limit": 2
  },
  "purpose": "Shows what people do in one project through action volume, active identified users, separately labeled anonymous subjects, explicit sessions, activity over time, top actions, and versioned page-view, screen-view, interaction, surface, and exact event-name breakdowns. Exact classified event names can be used as ordered funnel steps. It never infers people from anonymous events or relabels arbitrary unclassified telemetry as product behavior.",
  "analysis_level": "user_and_session",
  "summary": {
    "actions": 120,
    "active_identified_users": 18,
    "active_anonymous_subjects": 7,
    "sessions": 24,
    "distinct_action_names": 3,
    "actions_per_identified_user": 5.555555555555555,
    "actions_per_session": 5.0
  },
  "coverage": {
    "identified_actions": 100,
    "anonymous_actions": 20,
    "subject_coverage": {
      "index_version": 1,
      "identified_user_events": 100,
      "anonymous_subject_events": 20,
      "legacy_unknown_kind_events": 0,
      "missing_subject_events": 0,
      "historical_unindexed_events": 0
    },
    "sessionized_actions": 120,
    "traced_actions": 60,
    "identification_rate": 0.8333333333333334,
    "sessionization_rate": 1.0,
    "trace_link_rate": 0.5,
    "expected_buckets": 12,
    "returned_points": 2,
    "returned_top_actions": 2,
    "top_actions_truncated": true,
    "first_seen_at": "2026-06-01T11:00:10Z",
    "last_seen_at": "2026-06-01T11:09:50Z",
    "limitations": [
      "Typed anonymous subjects are counted separately and never contribute to active identified-user counts.",
      "Actions without a trace ID cannot link product behavior directly to trace investigation."
    ]
  },
  "estimation": {
    "unique_counts_are_approximate": true,
    "method": "approximate_distinct",
    "description": "Active identified-user, anonymous-subject, session, distinct action-name, distinct surface, and distinct exact event-name counts are approximate distinct counts. Event totals and capture-coverage counts are exact within the selected, fully evaluated query window."
  },
  "series": [
    {
      "bucket_start": "2026-06-01T11:00:00Z",
      "bucket_end": "2026-06-01T11:05:00Z",
      "actions": 50,
      "active_identified_users": 8,
      "sessions": 10,
      "identified_actions": 40,
      "sessionized_actions": 50,
      "traced_actions": 25
    },
    {
      "bucket_start": "2026-06-01T11:05:00Z",
      "bucket_end": "2026-06-01T11:10:00Z",
      "actions": 70,
      "active_identified_users": 12,
      "sessions": 14,
      "identified_actions": 60,
      "sessionized_actions": 70,
      "traced_actions": 35
    }
  ],
  "top_actions": [
    {
      "name": "checkout_started",
      "actions": 50,
      "active_identified_users": 12,
      "sessions": 14,
      "share_of_actions": 0.4166666666666667
    },
    {
      "name": "purchase_completed",
      "actions": 40,
      "active_identified_users": 9,
      "sessions": 10,
      "share_of_actions": 0.3333333333333333
    }
  ],
  "classified_activity": {
    "summary": {
      "events": 110,
      "page_views": 50,
      "screen_views": 20,
      "interactions": 40,
      "distinct_surfaces": 4,
      "distinct_event_names": 5,
      "active_identified_users": 17,
      "active_anonymous_subjects": 6,
      "sessions": 23
    },
    "coverage": {
      "classified_actions": 60,
      "unclassified_actions": 60,
      "action_classification_rate": 0.5,
      "surfaced_events": 110,
      "named_events": 110,
      "identified_events": 90,
      "subject_coverage": {
        "index_version": 1,
        "identified_user_events": 90,
        "anonymous_subject_events": 20,
        "legacy_unknown_kind_events": 0,
        "missing_subject_events": 0,
        "historical_unindexed_events": 0
      },
      "sessionized_events": 110,
      "traced_events": 55,
      "surface_rate": 1.0,
      "event_name_rate": 1.0,
      "identification_rate": 0.8181818181818182,
      "sessionization_rate": 1.0,
      "trace_link_rate": 0.5,
      "expected_buckets": 12,
      "returned_points": 2,
      "returned_top_surfaces": 2,
      "returned_top_events": 2,
      "top_surfaces_truncated": true,
      "top_events_truncated": true,
      "first_seen_at": "2026-06-01T11:00:20Z",
      "last_seen_at": "2026-06-01T11:09:40Z",
      "limitations": [
        "Only events carrying supported version-1 analytics annotations appear in classified activity; arbitrary actions and technical spans are not relabeled.",
        "Historical or unannotated actions contribute to the action summary but not to classified screen-view or interaction breakdowns.",
        "Classified events with typed anonymous subjects are counted separately and never contribute to identified-user counts.",
        "Classified events without a trace ID cannot link product behavior directly to trace investigation."
      ]
    },
    "series": [
      {
        "bucket_start": "2026-06-01T11:00:00Z",
        "bucket_end": "2026-06-01T11:05:00Z",
        "events": 45,
        "page_views": 20,
        "screen_views": 10,
        "interactions": 15
      },
      {
        "bucket_start": "2026-06-01T11:05:00Z",
        "bucket_end": "2026-06-01T11:10:00Z",
        "events": 65,
        "page_views": 30,
        "screen_views": 10,
        "interactions": 25
      }
    ],
    "top_surfaces": [
      {
        "kind": "page_view",
        "surface": "/checkout/:step",
        "events": 40,
        "active_identified_users": 12,
        "sessions": 14,
        "share_of_classified_events": 0.36363636363636365
      },
      {
        "kind": "screen_view",
        "surface": "Checkout",
        "events": 20,
        "active_identified_users": 9,
        "sessions": 10,
        "share_of_classified_events": 0.18181818181818182
      }
    ],
    "top_events": [
      {
        "kind": "page_view",
        "event_name": "/checkout/:step",
        "events": 40,
        "active_identified_users": 12,
        "sessions": 14,
        "share_of_classified_events": 0.36363636363636365
      },
      {
        "kind": "interaction",
        "event_name": "checkout_started",
        "events": 30,
        "active_identified_users": 10,
        "sessions": 12,
        "share_of_classified_events": 0.2727272727272727
      }
    ]
  },
  "next_action": {
    "code": "build_product_funnel",
    "target": "/api/telemetry/analytics/funnel",
    "reason": "Use two through eight exact keys from classified_activity.top_events to measure ordered conversion and drop-off for explicit sessions or opaque identified users."
  }
}

Odczytaj przegląd

Pięć liczb w subject_coverage sumuje się do łącznej liczby zdarzeń w ich sekcji. Do użytkowników liczy się tylko identified_user_events. anonymous_actions to summary.actions minus identified_actions. series zawiera tylko przedziały z aktywnością. expected_buckets to liczba możliwych przedziałów w zakresie. Nie rysuj brakującego przedziału jako zmierzonego zera, chyba że wykres wyraźnie podaje tę zasadę. Przedziały są wyrównane do granic przedziałów w UTC. Zakres, który zaczyna się w środku przedziału, obejmuje ten niepełny przedział. classified_activity liczy wyświetlenia stron, wyświetlenia ekranów i interakcje. Wyświetlenia ekranów i interakcje są też akcjami. Wyświetlenia stron nie są. Nie dodawaj summary.actions do classified_activity.summary.events. Kopiuj kind i event_name z classified_activity.top_events do kroków lejka, selektorów utrzymania, selektorów cyklu życia, zdarzeń kotwiczących ścieżek i celów segmentów. Wartość true w top_events_truncated oznacza, że istnieją rzadsze nazwy. Aby zobaczyć więcej, zwiększ top_limit maksymalnie do 20. analysis_level to no_data, event_only, user_level lub user_and_session. Jeśli projekt nie ma akcji ani sklasyfikowanych zdarzeń, next_action.code to capture_product_activity. Zobacz Analityka produktowa.

Błędy przeglądu

Oprócz wspólnych błędów zakresu przegląd zwraca 422 i validation_failed dla tych wartości:

Wartość	`error`
`response_version` inne niż `1`, `2` lub `3`	`product analytics response_version must be 1, 2, or 3`
`top_limit` spoza zakresu od `1` do `20`	`product analytics top_limit must be between 1 and 20`
`interval` inny niż `auto`, `1m`, `5m`, `15m`, `1h`, `6h` lub `1d`	`product analytics interval is not supported`
Jawnie podany `interval`, który wymaga więcej niż 500 przedziałów	`product analytics interval would exceed 500 buckets`

Domyślny interval to auto. Wybiera najmniejszą długość przedziału, przy której liczba przedziałów nie przekracza 300. Domyślny top_limit to 10.

Odpowiedź z uporządkowanym lejkiem

POST /api/telemetry/analytics/funnel mierzy, ile jednostek przechodzi przez kroki w ustalonej kolejności. Lejek ma od 2 do 8 kroków. Skopiuj każde dokładne kind i event_name z classified_activity.top_events w przeglądzie. Podobna nazwa akcji nie jest dopasowaniem. Ta treść żądania liczy sesje, które wyświetlają /pricing, a potem w ciągu godziny kończą rejestrację:

{
  "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "since": "2026-08-01T00:00:00Z",
  "until": "2026-08-02T00:00:00Z",
  "environment": "production",
  "analysis_unit": "session",
  "conversion_window_seconds": 3600,
  "steps": [
    { "kind": "page_view", "event_name": "/pricing" },
    { "kind": "interaction", "event_name": "signup_completed" }
  ]
}

analysis_unit to session lub identified_user. Domyślnie session. kind kroku to page_view, screen_view lub interaction. Trasa lejka nie przyjmuje response_version.

Udany lejek

Odpowiedź 200 OK:

{
  "schema_version": 1,
  "query": {
    "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
    "since": "2026-08-01T00:00:00Z",
    "until": "2026-08-02T00:00:00Z",
    "environment": "production",
    "analysis_unit": "session",
    "conversion_window_seconds": 3600
  },
  "purpose": "Shows where explicit sessions or typed opaque user subjects enter, progress, and drop off across two through eight versioned page-view, screen-view, or interaction events. Steps must occur in order with strictly increasing timestamps inside the selected conversion window; raw session and subject identifiers are never returned.",
  "summary": {
    "candidate_units": 60,
    "entered_units": 50,
    "completed_units": 15,
    "entry_rate": 0.8333333333333334,
    "overall_conversion_rate": 0.3
  },
  "coverage": {
    "classified_events": 200,
    "named_events": 180,
    "unnamed_events": 20,
    "unit_identified_events": 160,
    "selected_step_events": 120,
    "usable_selected_step_events": 100,
    "excluded_selected_step_events": 20,
    "event_name_rate": 0.9,
    "selected_unit_coverage_rate": 0.8333333333333334,
    "limitations": [
      "Only supported version-1 classified events with exact derived names participate; arbitrary actions and technical spans are never relabeled.",
      "A unit reaches later steps only when timestamps strictly increase and the final match remains inside conversion_window_seconds from its first match.",
      "Historical or surface-less classified events without a derived event name cannot match exact funnel steps.",
      "Requested-step events without an explicit session ID are excluded from ordered unit counts.",
      "Session funnels count visits or app sessions, not unique people; use analysis_unit=identified_user only when typed user-subject coverage is sufficient."
    ]
  },
  "steps": [
    {
      "position": 1,
      "kind": "page_view",
      "event_name": "/pricing",
      "units": 50,
      "conversion_from_first": 1.0,
      "drop_off_to_next_units": 35,
      "drop_off_to_next_rate": 0.7
    },
    {
      "position": 2,
      "kind": "interaction",
      "event_name": "signup_completed",
      "units": 15,
      "conversion_from_previous": 0.3,
      "conversion_from_first": 0.3
    }
  ],
  "next_action": {
    "code": "compare_funnel_contexts",
    "target": "/api/telemetry/analytics/funnel",
    "reason": "Compare the same exact steps across bounded releases, environments, or services to locate material conversion changes."
  }
}

Wskaźniki to ułamki od 0 do 1. Odczytaj coverage, zanim zaufasz wskaźnikowi. selected_unit_coverage_rate to udział zdarzeń wybranych kroków, których LogBrew mógł użyć. Odpowiedź nie zwraca surowych tożsamości. Zobacz Analityka produktowa.

Odczytaj konwersję i pokrycie

entry_rate to entered_units podzielone przez candidate_units: 50 z 60. overall_conversion_rate to completed_units podzielone przez entered_units: 15 z 50, czyli 30%. To nie jest 15 podzielone przez wszystkie jednostki kandydujące. Te liczby nie wyjaśniają, dlaczego jednostki się zatrzymały. Pokrycie liczy zdarzenia, a nie sesje. Tutaj 120 zdarzeń pasuje do kroku, a 20 z nich nie ma ID sesji. Wynik wyklucza tych 20 zdarzeń z liczby sesji. Nie traktuj ich jako 20 nieudanych sesji. Pierwszy krok nie ma conversion_from_previous. Ostatni krok nie ma drop_off_to_next_units ani drop_off_to_next_rate. Jednostka dociera do późniejszego kroku tylko wtedy, gdy czasy kroków ściśle rosną. Zdarzenia z tym samym znacznikiem czasu nie mogą spełnić 2 kolejnych kroków. Ostatni krok musi nastąpić w ciągu conversion_window_seconds od pierwszego kroku. Tryb sesji liczy sesje, a nie osoby. Używaj identified_user tylko dla zdarzeń, które mają nieprzezroczyste ID podmiotu rodzaju user. Ten tryb może łączyć zdarzenia z różnych sesji w obrębie okna konwersji. Porównując wyniki, zachowaj tę samą jednostkę i te same kroki. Domyślne conversion_window_seconds to 24 godziny albo długość zakresu, zależnie od tego, która wartość jest mniejsza. Maksimum to długość zakresu w pełnych sekundach, zaokrąglona w górę.

Puste wyniki lejka

Udana pusta odpowiedź nadal wymienia żądane kroki z zerowym units. Jeśli nie ma jednostek kandydujących, summary pomija entry_rate i overall_conversion_rate. Trasa nie zwraca 404 z powodu braku pasujących zdarzeń. Aby znaleźć przyczynę, odczytaj coverage i next_action:

`next_action.code`	Przyczyna
`capture_product_activity`	W zakresie nie ma sklasyfikowanych zdarzeń.
`choose_captured_funnel_steps`	Żadne zdarzenie nie pasuje do żądanego kroku.
`sessionize_product_activity`	Zdarzenia kroków istnieją, ale żadne nie ma ID sesji.
`identify_product_users`	Zdarzenia kroków istnieją, ale żadne nie ma podmiotu rodzaju `user`.
`verify_funnel_entry`	Żadna jednostka nie weszła do lejka w kroku 1.
`investigate_funnel_drop_off`	Jednostki weszły do lejka, ale żadna nie ukończyła wszystkich kroków.
`compare_funnel_contexts`	Co najmniej jedna jednostka ukończyła lejek.

Odrzucone żądania lejka

Oprócz wspólnych błędów zakresu te żądania zwracają 422 i validation_failed. Mniej niż 2 lub więcej niż 8 kroków:

{
  "error": "product analytics funnel requires two through eight ordered steps",
  "code": "validation_failed",
  "next": "send a steps array containing 2 through 8 exact classified event selectors",
  "next_action": { "code": "fix_request", "target": "request" }
}

conversion_window_seconds równe 0 albo większe niż długość zakresu:

{
  "error": "product analytics funnel conversion window must fit inside the query range",
  "code": "validation_failed",
  "next": "use conversion_window_seconds from 1 through the selected range length",
  "next_action": { "code": "fix_request", "target": "request" }
}

event_name, które jest puste, dłuższe niż 256 znaków lub zawiera znak sterujący, zwraca product analytics funnel event_name must be non-empty, control-free, and at most 256 characters. Krok interaction musi też mieć prawidłową nazwę akcji. W przeciwnym razie błąd to product analytics interaction event_name must be a bounded stable action name. Popraw żądanie, zanim wyślesz je ponownie. Nie usuwaj kroków i nie zmieniaj jednostki analizy tylko po to, aby dostać niepusty wynik.

Tryb dokładnych zdarzeń i tryb automatyczny

Utrzymanie i cykl życia przyjmują 2 struktury żądania. Użyj response_version, aby wybrać strukturę, która odpowiada na twoje pytanie:

Tryb	`response_version`	Selektory zdarzeń
Utrzymanie dla dokładnych zdarzeń	`1` albo pominięte	Wyślij `start_event` i `return_event`.
Cykl życia dla jednego dokładnego zdarzenia	`1` albo pominięte	Wyślij `event`.
Automatyczne utrzymanie lub cykl życia	`2`	Nie wysyłaj selektora zdarzenia.

Dokładny selektor zawiera kind i event_name. kind to page_view, screen_view lub interaction. Skopiuj event_name z classified_activity.top_events. Nie zgaduj nazwy zdarzenia na podstawie etykiety przycisku. Obie struktury liczą tylko użytkowników, czyli nieprzezroczyste ID podmiotów rodzaju user. Anonimowe podmioty i zdarzenia bez użytecznego ID podmiotu nie są liczone jako użytkownicy. Odpowiedzi nigdy nie zwracają ID podmiotów. Stałe długości przedziału to hour, day, week i thirty_day. To stałe czasy trwania. thirty_day to 30 dni, a nie miesiąc kalendarzowy. Jeśli pominiesz interval, API używa hour dla zakresu do 48 godzin włącznie i day dla dłuższego zakresu.

Żądanie utrzymania dla dokładnych zdarzeń

Wyślij tę treść do POST /api/telemetry/analytics/retention. Sprawdza, czy użytkownicy realizują kolejny zakup po pierwszym zakupie w zakresie:

{
  "project_id": "11111111-1111-4111-8111-111111111111",
  "since": "2026-06-01T00:00:00Z",
  "until": "2026-06-03T00:00:00Z",
  "response_version": 1,
  "interval": "day",
  "interval_count": 1,
  "mode": "return_on",
  "cohort_mode": "first_in_range",
  "start_event": { "kind": "interaction", "event_name": "checkout_completed" },
  "return_event": { "kind": "interaction", "event_name": "checkout_completed" }
}

Pierwsze pasujące zdarzenie początkowe w zakresie wyznacza punkt startowy każdego użytkownika. Powrót musi nastąpić ściśle po tym punkcie i przed until. Oba selektory mogą wskazywać to samo zdarzenie.

Pole	Wartości	Domyślnie
`interval_count`	Od `1` do `31` okresów	`10`
`mode`	`return_on` liczy powrót w każdym dokładnym okresie. `return_on_or_after` liczy powrót na początku każdego okresu lub później.	`return_on`
`cohort_mode`	`first_in_range`	`first_in_range`

Udane utrzymanie dla dokładnych zdarzeń

W tym syntetycznym przykładzie dwóch użytkowników realizuje zakup. Pierwszy użytkownik realizuje zakup 1 czerwca o 12:00 i ponownie o 13:00. Drugi użytkownik realizuje zakup 2 czerwca o 12:00. 2 czerwca o 13:00 drugi użytkownik wyświetla stronę, ale nie realizuje kolejnego zakupu.

{
  "schema_version": 1,
  "query": {
    "project_id": "11111111-1111-4111-8111-111111111111",
    "since": "2026-06-01T00:00:00Z",
    "until": "2026-06-03T00:00:00Z",
    "start_event": { "kind": "interaction", "event_name": "checkout_completed" },
    "return_event": { "kind": "interaction", "event_name": "checkout_completed" },
    "interval": "day",
    "interval_seconds": 86400,
    "interval_count": 1,
    "mode": "return_on",
    "cohort_mode": "first_in_range"
  },
  "purpose": "Measures whether typed opaque user subjects return after their first matching start event inside the selected half-open query range. Returns must occur strictly after each subject's anchor. return_on measures one fixed subject-relative period; return_on_or_after measures from that period's threshold through the exclusive query upper bound. Eligibility-aware denominators prevent immature subjects from being reported as churned, cohorts are fixed buckets aligned to since, and raw subject identifiers are never returned.",
  "summary": {
    "cohort_subjects": 2,
    "subjects_returned_after_start": 1,
    "return_rate_after_start": 0.5,
    "non_empty_cohorts": 2,
    "periods_with_eligible_subjects": 1,
    "fully_observed_periods": 0
  },
  "coverage": {
    "classified_events": 4,
    "named_events": 4,
    "unnamed_events": 0,
    "identified_events": 4,
    "start_events": 3,
    "usable_start_events": 3,
    "excluded_start_events": 0,
    "return_events": 3,
    "usable_return_events": 3,
    "excluded_return_events": 0,
    "event_name_rate": 1.0,
    "start_identity_coverage_rate": 1.0,
    "return_identity_coverage_rate": 1.0,
    "limitations": [
      "Only application-supplied opaque subject IDs explicitly typed as users are counted. Anonymous, legacy-untyped, historical-unindexed, invalid, or absent subjects are excluded rather than inferred as people.",
      "first_in_range anchors each subject at its first matching start inside the selected range; it does not prove that event was the subject's first-ever historical start.",
      "Cohort buckets are fixed-width and aligned to the query's since value. hour, day, week, and thirty_day mean fixed elapsed durations; thirty_day is not a calendar month.",
      "Returns must match the exact selected kind and derived event name, occur strictly after the subject anchor, and remain before the exclusive query upper bound.",
      "This resource does not provide recurring-start cohorts, group retention, arbitrary property breakdowns, custom return ranges, or lifetime first-event lookup.",
      "return_on includes only subjects whose complete exact period ends by until; later subjects are excluded from that period's denominator."
    ]
  },
  "curve": [
    {
      "period": 0,
      "threshold_seconds": 0,
      "window_end_seconds": 86400,
      "eligible_subjects": 1,
      "retained_subjects": 1,
      "weighted_retention_rate": 1.0,
      "fully_observed_cohorts": 1,
      "fully_observed_cohort_average_rate": 1.0,
      "all_subjects_eligible": false
    }
  ],
  "cohorts": [
    {
      "cohort": 0,
      "started_at": "2026-06-01T00:00:00Z",
      "ended_at": "2026-06-02T00:00:00Z",
      "subjects": 1,
      "subjects_returned_after_start": 1,
      "periods": [
        {
          "period": 0,
          "eligible_subjects": 1,
          "retained_subjects": 1,
          "retention_rate": 1.0,
          "all_subjects_eligible": true
        }
      ]
    },
    {
      "cohort": 1,
      "started_at": "2026-06-02T00:00:00Z",
      "ended_at": "2026-06-03T00:00:00Z",
      "subjects": 1,
      "subjects_returned_after_start": 0,
      "periods": [
        {
          "period": 0,
          "eligible_subjects": 0,
          "retained_subjects": 0,
          "all_subjects_eligible": false
        }
      ]
    }
  ],
  "next_action": {
    "code": "extend_retention_observation_window",
    "target": "/api/telemetry/analytics/retention",
    "reason": "Move since earlier, until later, or request fewer periods when a fully observed long-term comparison is required."
  }
}

Odczytaj utrzymanie

Pokrycie liczy wszystkie 4 sklasyfikowane zdarzenia, ale do każdego selektora realizacji zakupu pasują tylko 3. Wyświetlenie strony nie liczy się jako powrót. Jeden z dwóch użytkowników powtarza zakup, więc return_rate_after_start wynosi 0.5. Tylko pierwszy użytkownik ma pełny dzień obserwacji po punkcie startowym. Ten użytkownik wraca w ciągu tego dnia, więc wskaźnik krzywej wynosi 1.0. Drugi użytkownik ma tylko 12 godzin obserwacji. Nie kwalifikuje się do okresu 0, więc komórka drugiej kohorty pomija retention_rate. Nie licz tego użytkownika jako utraconego. weighted_retention_rate dzieli wszystkich utrzymanych użytkowników przez wszystkich kwalifikujących się użytkowników. fully_observed_cohort_average_rate to zwykła średnia wskaźników tych kohort, w których kwalifikuje się każdy użytkownik. Kohorty to stałe przedziały, które zaczynają się od since. cohorts zawiera tylko kohorty z użytkownikami. Z mode: "return_on_or_after" krzywa pomija window_end_seconds.

Automatyczne utrzymanie

Wyślij response_version: 2 bez start_event i return_event. Każde obsługiwane wyświetlenie strony, wyświetlenie ekranu i interakcja liczy się jako start i jako powrót. Ta wersja wybiera zbiór zdarzeń. Nie wybiera formatu rejestrowania danych w SDK.

{
  "project_id": "11111111-1111-4111-8111-111111111111",
  "since": "2026-06-01T00:00:00Z",
  "until": "2026-06-03T00:00:00Z",
  "response_version": 2,
  "interval": "day",
  "interval_count": 1,
  "mode": "return_on",
  "cohort_mode": "first_in_range"
}

Odpowiedź ma te same struktury summary, curve, cohorts i next_action co odpowiedź dla dokładnych zdarzeń. Ten fragment pokazuje pola, które się zmieniają. W tym przykładzie ci sami dwaj użytkownicy mają 3 zdarzenia i żadnego wyświetlenia strony:

{
  "schema_version": 2,
  "query": {
    "project_id": "11111111-1111-4111-8111-111111111111",
    "since": "2026-06-01T00:00:00Z",
    "until": "2026-06-03T00:00:00Z",
    "activity_scope": "all_classified_activity",
    "interval": "day",
    "interval_seconds": 86400,
    "interval_count": 1,
    "mode": "return_on",
    "cohort_mode": "first_in_range"
  },
  "purpose": "Measures whether typed opaque user subjects perform any later supported classified product activity after their first such activity inside the selected half-open range. It does not choose or infer a top event. Returns must occur strictly after the anchor, anonymous and unidentified subjects remain excluded from user counts, eligibility-aware denominators prevent immature subjects from being reported as churned, and raw identifiers are never returned.",
  "coverage": {
    "classified_events": 3,
    "named_events": 3,
    "unnamed_events": 0,
    "identified_events": 3,
    "start_events": 3,
    "usable_start_events": 3,
    "excluded_start_events": 0,
    "return_events": 3,
    "usable_return_events": 3,
    "excluded_return_events": 0,
    "event_name_rate": 1.0,
    "start_identity_coverage_rate": 1.0,
    "return_identity_coverage_rate": 1.0,
    "limitations": [
      "Only application-supplied opaque subject IDs explicitly typed as users are counted. Anonymous, legacy-untyped, historical-unindexed, invalid, or absent subjects are excluded rather than inferred as people.",
      "first_in_range anchors each subject at its first supported classified activity in the range; it does not prove that activity was the subject's first-ever product activity.",
      "Cohort buckets are fixed-width and aligned to the query's since value. hour, day, week, and thirty_day mean fixed elapsed durations; thirty_day is not a calendar month.",
      "Returns are any supported classified activity strictly after the subject anchor and before the exclusive query upper bound; no event is ranked, selected, or inferred.",
      "This resource does not provide recurring-start cohorts, group retention, arbitrary property breakdowns, custom return ranges, or lifetime first-event lookup.",
      "return_on includes only subjects whose complete exact period ends by until; later subjects are excluded from that period's denominator."
    ]
  }
}

W trybie automatycznym zarówno start_events, jak i return_events są równe classified_events. Te liczby oznaczają zdarzenia, a nie użytkowników.

Utrzymanie bez kwalifikujących się użytkowników

Udany wynik może nie mieć użytkowników w kohortach. Ten fragment pokazuje jeden żądany okres bez kohort:

{
  "schema_version": 2,
  "summary": {
    "cohort_subjects": 0,
    "subjects_returned_after_start": 0,
    "non_empty_cohorts": 0,
    "periods_with_eligible_subjects": 0,
    "fully_observed_periods": 0
  },
  "curve": [
    {
      "period": 0,
      "threshold_seconds": 0,
      "window_end_seconds": 86400,
      "eligible_subjects": 0,
      "retained_subjects": 0,
      "fully_observed_cohorts": 0,
      "all_subjects_eligible": false
    }
  ],
  "cohorts": []
}

Odczytaj coverage i next_action. Odróżniają zakres bez sklasyfikowanych zdarzeń (capture_product_activity) od zdarzeń bez użytkowników (identify_product_users lub identify_returning_users). Brakujący wskaźnik to nie zmierzone zero.

Błędy utrzymania

Oprócz wspólnych błędów zakresu te żądania zwracają 422 i validation_failed:

Przyczyna	`error`
Wersja 1 bez obu selektorów, wersja 2 z selektorem albo inna wersja	`product analytics retention activity selection is contradictory`
`interval_count` spoza zakresu od `1` do `31`	`product analytics retention interval_count must be between 1 and 31`
Liczba przedziałów kohort pomnożona przez `interval_count` przekracza 500	`product analytics retention interval and interval_count would exceed 500 cohort matrix cells`

Limit komórek zależy od zakresu i okresów, a nie od liczby użytkowników. Zakres 30 dni z interval: "hour" ma 720 przedziałów kohort. Przy interval_count: 1 daje to 720 komórek, czyli więcej niż 500:

{
  "error": "product analytics retention interval and interval_count would exceed 500 cohort matrix cells",
  "code": "validation_failed",
  "next": "choose a wider interval, a shorter time range, or fewer retention periods",
  "next_action": { "code": "fix_request", "target": "request" }
}

Aby użyć automatycznego utrzymania, usuń oba selektory. Nie zmieniaj SDK, aby poprawić to żądanie odczytu.

Żądanie cyklu życia dla dokładnego zdarzenia

Wyślij tę treść do POST /api/telemetry/analytics/lifecycle. Klasyfikuje użytkowników według jednego zdarzenia, a nie według całej aktywności w projekcie:

{
  "project_id": "11111111-1111-4111-8111-111111111111",
  "since": "2026-06-01T00:00:00Z",
  "until": "2026-06-03T00:00:00Z",
  "response_version": 1,
  "interval": "day",
  "history_period_count": 2,
  "event": { "kind": "interaction", "event_name": "checkout_completed" }
}

history_period_count ustala liczbę pełnych okresów przed since, które LogBrew odczytuje jako historię. Przyjmuje wartości od 2 do 31. Domyślnie 2. Użytkownik może być uśpiony dla tego zdarzenia, a jednocześnie wykonywać inne czynności.

Udany cykl życia dla dokładnego zdarzenia

Ten syntetyczny przykład obejmuje 2 dni historii i 2 dni analizy. Litery oznaczają tylko przykładowych użytkowników. Odpowiedź nie zwraca ID użytkowników.

Data (UTC)	Użytkownicy, którzy realizują zakup
30 maja, historia	B
31 maja, historia	A i D
1 czerwca, analiza	A, B i C
2 czerwca, analiza	A i B

C wyświetla też stronę 2 czerwca. To zdarzenie nie pasuje do selektora realizacji zakupu.

{
  "schema_version": 1,
  "query": {
    "project_id": "11111111-1111-4111-8111-111111111111",
    "since": "2026-06-01T00:00:00Z",
    "until": "2026-06-03T00:00:00Z",
    "history_since": "2026-05-30T00:00:00Z",
    "event": { "kind": "interaction", "event_name": "checkout_completed" },
    "interval": "day",
    "interval_seconds": 86400,
    "history_period_count": 2,
    "expected_buckets": 2
  },
  "purpose": "Classifies typed opaque user subjects for one exact product event in each fixed analysis period. new_within_observed_history means active now with no earlier matching event inside the bounded history window; returning means active now and in the immediately previous period; resurrected means active now, inactive in the previous period, and active earlier in observed history; dormant means active in the previous period but not now. These states are disjoint, incomplete buckets are marked, and raw subject identifiers are never returned.",
  "summary": {
    "observed_subjects": 4,
    "analysis_active_subjects": 3,
    "history_only_subjects": 1,
    "returned_buckets": 2,
    "fully_observed_buckets": 2,
    "latest_fully_observed_period": 1,
    "buckets_with_resurrection": 1,
    "buckets_with_dormancy": 2
  },
  "coverage": {
    "analysis_classified_events": 6,
    "analysis_named_events": 6,
    "analysis_unnamed_events": 0,
    "analysis_identified_events": 6,
    "selected_events": 5,
    "usable_selected_events": 5,
    "usable_selected_sessionized_events": 5,
    "usable_selected_trace_linked_events": 5,
    "excluded_selected_events": 0,
    "history_selected_events": 3,
    "usable_history_selected_events": 3,
    "excluded_history_selected_events": 0,
    "event_name_rate": 1.0,
    "selected_identity_coverage_rate": 1.0,
    "selected_sessionization_rate": 1.0,
    "selected_trace_link_rate": 1.0,
    "history_identity_coverage_rate": 1.0,
    "limitations": [
      "Only application-supplied opaque subject IDs explicitly typed as users are counted. Anonymous, legacy-untyped, historical-unindexed, invalid, or absent subjects are excluded rather than inferred as people.",
      "new_within_observed_history means no earlier selected event between history_since and the current bucket. It does not prove that a subject is a lifetime-new user.",
      "Observed history contains exactly 2 complete fixed periods before since; activity before history_since is intentionally unknown.",
      "Buckets are fixed-width and aligned to since. hour, day, week, and thirty_day mean fixed elapsed durations; thirty_day is not a calendar month.",
      "Returning, resurrected, and dormant compare only the selected exact kind and derived event name. They do not infer intent, identity merges, or causality.",
      "This resource does not provide arbitrary property breakdowns, reusable cohorts, group lifecycle, lifetime first-event lookup, or per-subject lists."
    ]
  },
  "buckets": [
    {
      "period": 0,
      "started_at": "2026-06-01T00:00:00Z",
      "ended_at": "2026-06-02T00:00:00Z",
      "fully_observed": true,
      "active_subjects": 3,
      "new_within_observed_history_subjects": 1,
      "returning_subjects": 1,
      "resurrected_subjects": 1,
      "dormant_subjects": 1,
      "previous_active_subjects": 2,
      "new_share_of_active": 0.3333333333333333,
      "returning_share_of_active": 0.3333333333333333,
      "resurrected_share_of_active": 0.3333333333333333,
      "dormant_share_of_previous_active": 0.5,
      "net_active_change": 1
    },
    {
      "period": 1,
      "started_at": "2026-06-02T00:00:00Z",
      "ended_at": "2026-06-03T00:00:00Z",
      "fully_observed": true,
      "active_subjects": 2,
      "new_within_observed_history_subjects": 0,
      "returning_subjects": 2,
      "resurrected_subjects": 0,
      "dormant_subjects": 1,
      "previous_active_subjects": 3,
      "new_share_of_active": 0.0,
      "returning_share_of_active": 1.0,
      "resurrected_share_of_active": 0.0,
      "dormant_share_of_previous_active": 0.3333333333333333,
      "net_active_change": -1
    }
  ],
  "next_action": {
    "code": "investigate_lifecycle_loss",
    "target": "/api/telemetry/analytics/paths",
    "reason": "The latest complete bucket lost more prior active subjects than it added through new-within-observed-history and resurrected activity; compare bounded journeys around the selected event."
  }
}

Odczytaj cykl życia

1 czerwca A jest użytkownikiem powracającym, B – ponownie aktywnym, C – nowym, a D – uśpionym. 2 czerwca A i B są użytkownikami powracającymi, a C jest uśpiony dla realizacji zakupu mimo wyświetlenia strony. Zmiana netto 2 czerwca to 2 - 3 = -1. W każdym przedziale nowi, powracający i ponownie aktywni użytkownicy sumują się do active_subjects. returning_subjects plus dormant_subjects równa się previous_active_subjects. net_active_change to active_subjects minus previous_active_subjects. Nie sumuj dziennych liczb aktywnych użytkowników, aby uzyskać liczbę unikalnych użytkowników. Tutaj dzienne liczby sumują się do 5, ale analysis_active_subjects wynosi 3. W historii i okresie analizy występuje czterech unikalnych użytkowników. fully_observed ma wartość false dla ostatniego przedziału, który kończy się po until. Jego liczby mogą się zmienić, gdy cały okres będzie można zaobserwować. next_action sugeruje dalszą analizę. Nie wskazuje przyczyny.

Automatyczny cykl życia

Wyślij response_version: 2 bez selektora event. Każde obsługiwane wyświetlenie strony, wyświetlenie ekranu i interakcja liczy się jako aktywność:

{
  "project_id": "11111111-1111-4111-8111-111111111111",
  "since": "2026-06-01T00:00:00Z",
  "until": "2026-06-03T00:00:00Z",
  "response_version": 2,
  "interval": "day",
  "history_period_count": 2
}

Odpowiedź ma te same struktury summary, buckets i next_action co odpowiedź dla dokładnego zdarzenia. Ten fragment pokazuje pola, które się zmieniają:

{
  "schema_version": 2,
  "query": {
    "project_id": "11111111-1111-4111-8111-111111111111",
    "since": "2026-06-01T00:00:00Z",
    "until": "2026-06-03T00:00:00Z",
    "history_since": "2026-05-30T00:00:00Z",
    "activity_scope": "all_classified_activity",
    "interval": "day",
    "interval_seconds": 86400,
    "history_period_count": 2,
    "expected_buckets": 2
  },
  "purpose": "Classifies typed opaque user subjects by any supported classified product activity in each fixed period. It does not choose or infer a top event. new_within_observed_history, returning, resurrected, and dormant remain disjoint; anonymous and unidentified subjects are excluded from user counts, incomplete buckets are marked, and raw identifiers are never returned."
}

W trybie automatycznym coverage.selected_events równa się coverage.analysis_classified_events. Piąty wpis w limitations to

Returning, resurrected, and dormant compare any supported classified product activity; no event is ranked, selected, or inferred.

Cykl życia bez użytkowników

Jeśli ani zakres analizy, ani historia nie zawierają użytecznych użytkowników, buckets jest puste, a summary pomija latest_fully_observed_period:

{
  "schema_version": 2,
  "summary": {
    "observed_subjects": 0,
    "analysis_active_subjects": 0,
    "history_only_subjects": 0,
    "returned_buckets": 0,
    "fully_observed_buckets": 0,
    "buckets_with_resurrection": 0,
    "buckets_with_dormancy": 0
  },
  "buckets": []
}

Użytkownicy, którzy występują tylko w historii, mogą nadal tworzyć przedziały z uśpionymi użytkownikami, gdy w zakresie analizy nie ma aktywności.

Błędy cyklu życia

Oprócz wspólnych błędów zakresu te żądania zwracają 422 i validation_failed:

Przyczyna	`error`
Wersja 1 bez `event`, wersja 2 z `event` albo inna wersja	`product analytics lifecycle activity selection is contradictory`
`history_period_count` spoza zakresu od `2` do `31`	`product analytics lifecycle history_period_count must be between 2 and 31`
Okresy historii trwające łącznie dłużej niż 62 dni	`product analytics lifecycle history must not exceed 62 days`
Więcej niż 100 przedziałów analizy	`product analytics lifecycle interval would exceed 100 analysis buckets`

Na przykład 10 okresów historii week wymaga 70 dni:

{
  "error": "product analytics lifecycle history must not exceed 62 days",
  "code": "validation_failed",
  "next": "use fewer history periods or a narrower fixed interval",
  "next_action": { "code": "fix_request", "target": "request" }
}

Odczytaj wybrany zakres analizy

Odpowiedzi dla dokładnych zdarzeń mają schema_version: 1. Ich query powtarza selektory i pomija activity_scope. Odpowiedzi automatyczne mają schema_version: 2 i query.activity_scope: "all_classified_activity". Pomijają selektory. Inny selektor może zmienić wynik, nawet jeśli zarejestrowana aktywność się nie zmieniła.

Odpowiedź z szeregiem metryki

GET /api/telemetry/metrics/series odczytuje jedną dokładną nazwę metryki w jednym projekcie. Skopiuj nazwę z GET /api/telemetry/metrics. To żądanie grupuje licznik delta według usługi:

curl --get "https://api.logbrew.co/api/telemetry/metrics/series" \
  --header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  --data-urlencode "project_id=<project_id>" \
  --data-urlencode "name=jobs.completed" \
  --data-urlencode "since=2026-06-01T12:00:00Z" \
  --data-urlencode "until=2026-06-01T12:15:00Z" \
  --data-urlencode "interval=5m" \
  --data-urlencode "group_by=service_name"

Udany szereg metryki

Ta syntetyczna odpowiedź zawiera jeden szereg licznika delta. W pierwszym przedziale są 3 próbki o wartościach 2, 3 i 5. W ostatnim przedziale są 2 próbki o wartościach 1 i 4. W środkowym przedziale nie ma próbek, więc odpowiedź nie ma dla niego punktu.

{
  "schema_version": 1,
  "query": {
    "project_id": "11111111-1111-4111-8111-111111111111",
    "name": "jobs.completed",
    "since": "2026-06-01T12:00:00Z",
    "until": "2026-06-01T12:15:00Z",
    "interval": "5m",
    "interval_seconds": 300,
    "group_by": "service_name",
    "series_limit": 10
  },
  "purpose": "Shows how one metric changes over time without changing its meaning: gauges use sampled state, delta counters use change volume and rate, histograms use distributions, and cumulative streams stay raw when reset-safe change is ambiguous.",
  "coverage": {
    "samples": 5,
    "series": 1,
    "returned_series": 1,
    "points": 2,
    "expected_buckets_per_series": 3,
    "first_seen_at": "2026-06-01T12:00:10Z",
    "last_seen_at": "2026-06-01T12:14:50Z",
    "truncated": false
  },
  "series": [
    {
      "identity": {
        "kind": "counter",
        "unit": "{job}",
        "temporality": "delta",
        "group_by": "service_name",
        "group_value": "checkout-worker"
      },
      "status": "ready",
      "aggregation": {
        "code": "delta_sum",
        "description": "Primary value is the sum of recorded changes in each bucket; rate_per_second normalizes that change by bucket width."
      },
      "sample_count": 5,
      "points": [
        {
          "bucket_start": "2026-06-01T12:00:00Z",
          "bucket_end": "2026-06-01T12:05:00Z",
          "sample_count": 3,
          "value": 10.0,
          "last": 5.0,
          "min": 2.0,
          "max": 5.0,
          "average": 3.3333333333333335,
          "sum": 10.0,
          "rate_per_second": 0.03333333333333333,
          "trace_exemplars": ["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]
        },
        {
          "bucket_start": "2026-06-01T12:10:00Z",
          "bucket_end": "2026-06-01T12:15:00Z",
          "sample_count": 2,
          "value": 5.0,
          "last": 4.0,
          "min": 1.0,
          "max": 4.0,
          "average": 2.5,
          "sum": 5.0,
          "rate_per_second": 0.016666666666666666,
          "trace_exemplars": []
        }
      ]
    }
  ],
  "next_action": {
    "code": "inspect_metric_change",
    "target": "trace_summary",
    "reason": "Open a trace exemplar from an unusual bucket to connect the metric change to spans, errors, logs, and release context."
  }
}

Odczytaj szereg metryki

Pierwszy punkt rejestruje 10 ukończonych zadań, a nie 10 próbek. rate_per_second dzieli tę zmianę przez 300-sekundowy przedział. last to ostatnia zarejestrowana zmiana, a nie suma. Zobacz znaczenie agregacji metryk. Rodzaj i temporalność szeregu wyznaczają jego aggregation.code i statystyki w każdym punkcie. Punkt pomija statystykę, która nie ma zastosowania. Brakująca statystyka to nie zero.

Rodzaj i temporalność	`status`	`aggregation.code`	`value`	Inne statystyki
`gauge`, `instant`	`ready`	`gauge_last`	Ostatnia próbka	`last`, `min`, `max`, `average`
`counter`, `delta`	`ready`	`delta_sum`	Suma zmian	`last`, `min`, `max`, `average`, `sum`, `rate_per_second`
`histogram`, `delta`	`ready`	`distribution_p95`	Przybliżony p95	`min`, `max`, `average`, `sum`, `p50`, `p95`, `p99`
Dowolny rodzaj, `cumulative`	`limited`	`raw_cumulative_last`	Ostatnia surowa próbka	`last`, `min`, `max`
Każda inna para	`limited`	`raw_last`	Ostatnia surowa próbka	`last`, `min`, `max`

limited to udana odpowiedź, a nie błąd. Dodaje aggregation.limitation, które wyjaśnia, dlaczego LogBrew pokazuje tylko surowe wartości. ready nie dowodzi, że zarejestrowano wszystkie dane. Odczytaj coverage, zanim narysujesz wykres:

samples liczy próbki wszystkich pasujących szeregów, także tych, których odpowiedź nie zwraca.
series liczy pasujące szeregi. returned_series i points liczą zwrócone dane.
truncated ma wartość true, gdy series_limit usunął szeregi o mniejszym wolumenie.
expected_buckets_per_series to liczba możliwych przedziałów w zakresie.

Nie dodawaj punktu dla przedziału bez próbek. Nie wstawiaj zera i nie kopiuj poprzedniej wartości. Każdy punkt zwraca do 3 trace_exemplars. Przykładowy ślad (trace exemplar) łączy jedną próbkę ze śladem. Nie wyjaśnia wszystkich próbek w przedziale. Jeśli żaden punkt nie ma przykładowego śladu, next_action.target to metric_samples.

Zakres i błędy szeregu metryki

project_id, name i since są wymagane. name może mieć najwyżej 200 znaków. interval to auto, 1m, 5m, 15m, 1h, 6h lub 1d. Domyślnie auto, czyli najmniejsza długość przedziału, przy której liczba przedziałów nie przekracza 300. Jawnie podana długość przedziału nie może wymagać więcej niż 500 przedziałów. group_by to none, service_name, release lub environment. Domyślnie none. Bez grupowania różne rodzaje, jednostki i temporalności pozostają w osobnych szeregach. series_limit przyjmuje od 1 do 20. Domyślnie 10. Pusty wynik zwraca 200 z series: [] i zerowym samples. Obiekt coverage pomija first_seen_at i last_seen_at. To nie dowodzi, że aplikacja nigdy nie wysłała metryki. Sprawdź projekt, nazwę metryki i zakres czasu. Pominięcie name zwraca 422:

{
  "error": "metric series name is required",
  "code": "validation_failed",
  "next": "send the exact metric name returned by /api/telemetry/metrics",
  "next_action": { "code": "fix_request", "target": "request" }
}

Przedziały jednominutowe w zakresie 7 dni zwracają 422:

{
  "error": "metric series interval would exceed 500 buckets",
  "code": "validation_failed",
  "next": "use interval=auto or select a wider interval",
  "next_action": { "code": "fix_request", "target": "request" }
}

Inne błędy 422 to metric series group_by is not supported, metric series interval is not supported i metric series_limit must be between 1 and 20.

Odpowiedź ze ścieżkami

POST /api/telemetry/analytics/paths znajduje nazwane zdarzenia przed jednym wybranym zdarzeniem lub po nim w tej samej sesji. Wybrane zdarzenie jest zdarzeniem kotwiczącym. Skopiuj jego kind i event_name z classified_activity.top_events. Trasa zwraca schema_version: 1. Nie przyjmuje response_version ani analysis_unit.

{
  "project_id": "11111111-1111-4111-8111-111111111111",
  "since": "2026-06-01T11:00:00Z",
  "until": "2026-06-01T12:00:00Z",
  "direction": "following",
  "anchor": { "kind": "page_view", "event_name": "/checkout" },
  "depth": 2,
  "collapse_repeated": true,
  "path_limit": 2
}

direction i anchor są wymagane.

Udane ścieżki

W tym syntetycznym wyniku 4 sesje zawierają zdarzenie kotwiczące. Dwie zwrócone ścieżki reprezentują 3 z tych sesji. Jedna ścieżka z niższą pozycją w rankingu nie została zwrócona.

{
  "schema_version": 1,
  "query": {
    "project_id": "11111111-1111-4111-8111-111111111111",
    "since": "2026-06-01T11:00:00Z",
    "until": "2026-06-01T12:00:00Z",
    "direction": "following",
    "anchor": { "kind": "page_view", "event_name": "/checkout" },
    "depth": 2,
    "collapse_repeated": true,
    "path_limit": 2
  },
  "purpose": "Shows the highest-volume named product-event sequences immediately before or after one exact version-1 page view, screen view, or interaction inside explicit sessions. Following paths use the earliest matching anchor in each session; preceding paths use the latest. Optional exact property predicates classify only the anchor, while surrounding events preserve the real session journey. Results aggregate exact bounded sequences and never return raw session or subject identifiers.",
  "summary": {
    "anchored_sessions": 4,
    "represented_sessions": 3,
    "unrepresented_sessions": 1,
    "returned_paths": 2,
    "paths_truncated": true
  },
  "coverage": {
    "classified_events": 12,
    "named_events": 12,
    "unnamed_events": 0,
    "sessionized_events": 10,
    "unsessionized_events": 2,
    "anchor_events": 5,
    "usable_anchor_events": 4,
    "excluded_anchor_events": 1,
    "traced_anchor_events": 1,
    "event_name_rate": 1.0,
    "sessionization_rate": 0.8333333333333334,
    "anchor_session_coverage_rate": 0.8,
    "anchor_trace_link_rate": 0.2,
    "ordered_event_cap_per_session": 1024,
    "limitations": [
      "Paths include only supported version-1 classified events with exact derived names; arbitrary actions, technical spans, and raw identity values are excluded.",
      "Paths stay inside application-supplied session boundaries and the selected half-open time range; activity beyond either boundary is not inferred.",
      "Each session retains at most 1024 direction-nearest named events before anchoring, so exceptionally noisy sessions can be omitted or truncated.",
      "Classified events without an explicit opaque session ID cannot participate in session paths.",
      "Trace exemplars prove only that a matching anchor carried the same trace ID. They do not prove root cause, and deeper investigation depends on retained spans for that trace.",
      "Some matching anchors lack trace IDs, so trace-linked path evidence covers only the reported traced_anchor_events population."
    ]
  },
  "paths": [
    {
      "rank": 1,
      "sessions": 2,
      "share_of_anchored_sessions": 0.5,
      "traced_sessions": 1,
      "trace_link_rate": 0.5,
      "trace_exemplars": ["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"],
      "nodes": [
        { "relative_position": 0, "kind": "page_view", "event_name": "/checkout" },
        { "relative_position": 1, "kind": "interaction", "event_name": "checkout.submitted" },
        { "relative_position": 2, "kind": "interaction", "event_name": "checkout.completed" }
      ]
    },
    {
      "rank": 2,
      "sessions": 1,
      "share_of_anchored_sessions": 0.25,
      "traced_sessions": 0,
      "trace_link_rate": 0.0,
      "trace_exemplars": [],
      "nodes": [
        { "relative_position": 0, "kind": "page_view", "event_name": "/checkout" },
        { "relative_position": 1, "kind": "interaction", "event_name": "checkout.failed" }
      ]
    }
  ],
  "next_action": {
    "code": "inspect_path_trace",
    "target": "/api/telemetry/traces/{trace_id}/investigation",
    "reason": "Open an exemplar from the material path to connect the product journey to retained spans, issues, logs, actions, metrics, and release context as evidence rather than a root-cause claim."
  }
}

Odczytaj ścieżki

share_of_anchored_sessions dzieli sesje ścieżki przez wszystkie 4 sesje ze zdarzeniem kotwiczącym. Udziały wynoszą 50% i 25%, a nie 67% i 33%. unrepresented_sessions liczy sesje ze zdarzeniem kotwiczącym, których nie reprezentuje żadna zwrócona ścieżka. paths_truncated: true oznacza, że wynik jest niepełny. Pokrycie liczy zdarzenia, a nie sesje. Tutaj do zdarzenia kotwiczącego pasuje 5 zdarzeń, ale jedno z nich nie ma ID sesji. To zdarzenie nie może wejść do ścieżki. Każda ścieżka zwraca do 3 przykładowych śladów. Używaj ID śladu z własnej odpowiedzi. Powiązanie ze śladem nie pokazuje, co spowodowało akcję użytkownika ani niepowodzenie.

Pole	Znaczenie
`following`	Zaczyna się od najwcześniejszego pasującego zdarzenia kotwiczącego w każdej sesji. Zdarzenie kotwiczące ma pozycję `0`. Późniejsze węzły mają dodatnie pozycje.
`preceding`	Kończy się na najpóźniejszym pasującym zdarzeniu kotwiczącym w każdej sesji. Wcześniejsze węzły mają ujemne pozycje. Zdarzenie kotwiczące ma pozycję `0`.
`depth`	Liczba węzłów obok zdarzenia kotwiczącego, bez niego samego. Od `1` do `8`. Domyślnie `4`. Ścieżka może mieć mniej węzłów.
`collapse_repeated`	Łączy kolejne węzły o tym samym rodzaju i nazwie. Domyślnie `true`.
`path_limit`	Maksymalna liczba zwróconych ścieżek, uszeregowanych według liczby sesji. Od `1` do `20`. Domyślnie `10`.

Węzły są w kolejności czasowej w obu kierunkach. Ścieżka nie jest pełnym odtworzeniem sesji. LogBrew odczytuje najwyżej 1024 nazwane zdarzenia na sesję, zanim wybierze zdarzenie kotwiczące: najwcześniejsze zdarzenia dla following i najpóźniejsze dla preceding. Zdarzenie kotwiczące poza tym limitem może zostać pominięte.

Filtruj zdarzenie kotwiczące według właściwości

Wyślij do 4 property_filters, każdy z jednym dokładnym key i value. Skopiuj klucz z katalogu właściwości. Filtry dotyczą tylko zdarzenia kotwiczącego, a nie zdarzeń wokół niego. Wartości rozróżniają wielkość liter. Gdy filtry są obecne, query je powtarza, a coverage.anchor_property_filters podaje:

Pole	Znaczenie
`context_events`	Zdarzenia kotwiczące w zakresie przed zastosowaniem filtrów właściwości.
`property_ready_events`	Zdarzenia kotwiczące, które mają każdy żądany klucz.
`missing_property_events`	Zdarzenia kotwiczące bez co najmniej jednego żądanego klucza.
`matching_events`	Zdarzenia kotwiczące, których wartości pasują do każdego filtra.
`nonmatching_value_events`	Zdarzenia kotwiczące, które mają każdy klucz, ale inną wartość.
`property_ready_rate`	`property_ready_events` podzielone przez `context_events`.
`match_rate`	`matching_events` podzielone przez `property_ready_events`.

Brakujące klucze i niepasujące wartości wymagają różnych poprawek. Nie sumuj ich. Obiekt jest pomijany, gdy żądanie nie ma filtra właściwości.

Puste ścieżki i odrzucone żądania

Pusta tablica paths może być udaną odpowiedzią 200. Odczytaj summary, coverage i next_action. Te kody rozróżniają przyczyny: capture_product_activity, choose_captured_path_anchor, capture_anchor_properties, improve_anchor_property_coverage, verify_anchor_property_values, sessionize_product_activity i narrow_or_move_path_anchor. Oprócz wspólnych błędów zakresu te żądania zwracają 422 i validation_failed:

Przyczyna	`error`
`depth` spoza zakresu od `1` do `8`	`product analytics path depth must be between 1 and 8`
`path_limit` spoza zakresu od `1` do `20`	`product analytics path_limit must be between 1 and 20`
Więcej niż 4 filtry właściwości	`product analytics paths accept at most four exact anchor property filters`
Klucz, którego nie ma w katalogu właściwości	`product analytics path property keys must be supported privacy-safe keys`
Ten sam klucz 2 razy	`product analytics path property keys must be unique`
Pusta wartość, wartość dłuższa niż 256 znaków albo znak sterujący	`product analytics path property values must be non-empty, control-free, and at most 256 characters`

Na przykład depth: 0 zwraca:

{
  "error": "product analytics path depth must be between 1 and 8",
  "code": "validation_failed",
  "next": "use depth from 1 through 8 adjacent named events",
  "next_action": { "code": "fix_request", "target": "request" }
}

Katalog właściwości analityki

GET /api/telemetry/analytics/properties wymienia klucze właściwości zdarzeń w sklasyfikowanych zdarzeniach produktowych w jednym projekcie. Używaj tych kluczy w porównaniach segmentów i w filtrach zdarzeń kotwiczących ścieżek. Katalog zwraca klucze i liczby. Nigdy nie zwraca wartości właściwości ani tożsamości.

Odczytaj dostępne klucze właściwości

Wyślij project_id i since. Możesz też wysłać until, service_name, release, environment, limit i response_version. limit przyjmuje od 1 do 50 kluczy. Domyślnie 20. Wyślij response_version=2, aby dostać publiczną wartość estimation.method.

curl --get "https://api.logbrew.co/api/telemetry/analytics/properties" \
  --header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  --data-urlencode "project_id=<project_id>" \
  --data-urlencode "since=2026-06-01T00:00:00Z" \
  --data-urlencode "until=2026-06-02T00:00:00Z" \
  --data-urlencode "limit=20" \
  --data-urlencode "response_version=2"

Udany katalog właściwości

W tym syntetycznym wyniku istnieje 100 sklasyfikowanych zdarzeń. Pięć z nich zarejestrowano przed powstaniem bieżącego indeksu właściwości.

{
  "schema_version": 2,
  "query": {
    "project_id": "11111111-1111-4111-8111-111111111111",
    "since": "2026-06-01T00:00:00Z",
    "until": "2026-06-02T00:00:00Z",
    "limit": 20
  },
  "purpose": "Discovers bounded privacy-safe runtime, framework, operating-system, device, application, and custom-tag keys captured on classified product events. It reports migration, capture, privacy-filtering, and per-key coverage without returning property values or identities, so humans and agents can build exact segment comparisons without guessing which dimensions exist.",
  "summary": {
    "classified_events": 100,
    "available_property_keys": 3,
    "returned_properties": 3
  },
  "coverage": {
    "indexed_events": 95,
    "unindexed_events": 5,
    "complete_index_events": 95,
    "incomplete_index_events": 0,
    "privacy_filtered_events": 4,
    "events_with_properties": 90,
    "index_coverage_rate": 0.95,
    "property_capture_rate": 0.9,
    "properties_truncated": false,
    "values_returned": false,
    "limitations": [
      "Property discovery returns keys and aggregate counts only; property values and identity columns are never returned.",
      "Property filters use exact case-sensitive bounded string equality and combine with logical AND inside each segment.",
      "Historical events written before the current property index are excluded from property descriptors and exact property filters.",
      "Direct-identity, credential-like, and network-address custom tag keys were intentionally excluded from the analytics property index."
    ]
  },
  "estimation": {
    "count_accuracy": "approximate",
    "method": "approximate_distinct",
    "description": "Available property-key and per-key distinct-value counts are approximate distinct counts. Classified-event, index-coverage, privacy-filtering, and per-key event counts are exact within the selected fully evaluated window."
  },
  "properties": [
    {
      "key": "resource.runtime.name",
      "source": "standard_context",
      "value_type": "string",
      "events": 90,
      "coverage_rate": 0.9,
      "distinct_values": 2
    },
    {
      "key": "resource.application.version",
      "source": "standard_context",
      "value_type": "string",
      "events": 70,
      "coverage_rate": 0.7,
      "distinct_values": 4
    },
    {
      "key": "tag.plan",
      "source": "custom_tag",
      "value_type": "string",
      "events": 60,
      "coverage_rate": 0.6,
      "distinct_values": 3
    }
  ],
  "next_action": {
    "code": "compare_property_segments",
    "target": "/api/telemetry/analytics/segments/compare",
    "reason": "Use exact returned keys with locally known values to compare behavior while preserving identity and property-value privacy."
  }
}

Odczytaj katalog

source to standard_context dla standardowego klucza kontekstu, na przykład resource.runtime.name, albo custom_tag dla klucza, który zaczyna się od tag.. value_type to zawsze string. properties jest posortowane według events, od największej wartości. tag.plan występuje w 60 ze 100 sklasyfikowanych zdarzeń. Ma około 3 różnych wartości. Deskryptor nie pokazuje tych wartości. Używaj wartości, które znasz ze swojej aplikacji. Nie zgaduj wartości na podstawie liczby. Jedno zdarzenie może mieć kilka kluczy, więc nie sumuj liczb events dla poszczególnych kluczy.

Pole	Znaczenie
`summary.classified_events`	Sklasyfikowane zdarzenia w zakresie. To mianownik każdego `coverage_rate`.
`summary.available_property_keys`	Szacowana liczba różnych kluczy, a nie liczba zwróconych wierszy.
`coverage.unindexed_events`	Zdarzenia zarejestrowane przed powstaniem bieżącego indeksu właściwości. Nie mogą dostarczyć kluczy.
`coverage.incomplete_index_events`	Zdarzenia z częściowo uszkodzonym lub obciętym kontekstem. Ich prawidłowe klucze nadal się liczą.
`coverage.privacy_filtered_events`	Zdarzenia, z których LogBrew usunął wrażliwe klucze niestandardowych tagów. To nie jest liczba kluczy.
`coverage.properties_truncated`	`true`, gdy kluczy jest więcej niż `limit`. Zawęź zakres albo zwiększ `limit` maksymalnie do 50.
`coverage.values_returned`	Zawsze `false`.

Pusta tablica properties nie dowodzi, że projekt nie ma zdarzeń produktowych. Odczytaj summary, coverage i next_action.

Błędy katalogu właściwości

Oprócz wspólnych błędów zakresu limit=0 lub limit=51 zwraca 422:

{
  "error": "product analytics property limit must be between 1 and 50",
  "code": "validation_failed",
  "next": "use limit=1 through limit=50",
  "next_action": { "code": "fix_request", "target": "request" }
}

response_version inne niż 1 lub 2 zwraca product analytics response_version must be 1 or 2. LogBrew sprawdza response_version przed innymi wartościami. Żądanie POST zwraca 405:

{
  "error": "Method not allowed",
  "code": "method_not_allowed",
  "next": "send GET /api/telemetry/analytics/properties with required project_id and since plus optional until, service_name, release, environment, limit, or response_version query parameters",
  "next_action": { "code": "use_supported_method", "target": "api_method" }
}

Porównanie segmentów w analityce

POST /api/telemetry/analytics/segments/compare porównuje, jak często sesje lub użytkownicy docierają do jednego dokładnego zdarzenia, w 2–4 segmentach w jednym projekcie. Segment wybiera zdarzenia według usługi, wydania, środowiska i wartości właściwości. Pierwszy segment jest segmentem bazowym.

Zdefiniuj porównanie

Wyślij tę treść JSON z uwierzytelnieniem konta i Content-Type: application/json. Tutaj basic i premium to wartości planu w przykładowej aplikacji, a nie plany LogBrew:

{
  "project_id": "11111111-1111-4111-8111-111111111111",
  "since": "2026-06-01T11:00:00Z",
  "until": "2026-06-01T12:00:00Z",
  "interval": "1h",
  "analysis_unit": "session",
  "response_version": 2,
  "target": { "kind": "interaction", "event_name": "checkout_completed" },
  "segments": [
    {
      "key": "basic",
      "label": "Basic plan",
      "service_name": "checkout-api",
      "environment": "production",
      "property_filters": [{ "key": "tag.plan", "value": "basic" }]
    },
    {
      "key": "premium",
      "label": "Premium plan",
      "service_name": "checkout-api",
      "environment": "production",
      "property_filters": [{ "key": "tag.plan", "value": "premium" }]
    }
  ]
}

target i segments są wymagane. analysis_unit to session lub identified_user. Domyślnie session, czyli liczone są sesje, a nie osoby. interval przyjmuje te same wartości co przegląd. Domyślnie auto. Każdy segment potrzebuje unikalnego key, etykiety label i innego zestawu filtrów:

key: od 1 do 32 bajtów. Zacznij od małej litery ASCII lub cyfry. Używaj tylko małych liter ASCII, cyfr, _ i -.
label: od 1 do 80 znaków, bez znaków sterujących.
service_name, release, environment: opcjonalne. Każda wartość ma od 1 do 256 znaków, bez znaków sterujących.
property_filters: od 0 do 4 filtrów. Każdy klucz może wystąpić w segmencie tylko raz. Zdarzenie musi pasować do wszystkich filtrów segmentu. Wartości rozróżniają wielkość liter i mają od 1 do 256 znaków. LogBrew usuwa spacje z ich początku i końca.

Segment bez filtrów wybiera całą sklasyfikowaną aktywność w projekcie i zakresie czasu. Segmenty mogą się nakładać. Inna etykieta lub inny klucz nie sprawia, że 2 identyczne zestawy filtrów są prawidłowe.

Udane porównanie segmentów

W tym syntetycznym wyniku segment bazowy dociera do realizacji zakupu w 10 z 50 sesji. Segment premium dociera do niej w 18 z 60 sesji.

{
  "schema_version": 2,
  "query": {
    "project_id": "11111111-1111-4111-8111-111111111111",
    "since": "2026-06-01T11:00:00Z",
    "until": "2026-06-01T12:00:00Z",
    "interval": "1h",
    "interval_seconds": 3600,
    "analysis_unit": "session",
    "target": { "kind": "interaction", "event_name": "checkout_completed" },
    "segments": [
      {
        "key": "basic",
        "label": "Basic plan",
        "service_name": "checkout-api",
        "release": null,
        "environment": "production",
        "property_filters": [{ "key": "tag.plan", "value": "basic" }]
      },
      {
        "key": "premium",
        "label": "Premium plan",
        "service_name": "checkout-api",
        "release": null,
        "environment": "production",
        "property_filters": [{ "key": "tag.plan", "value": "premium" }]
      }
    ]
  },
  "purpose": "Compares how often explicit sessions or typed opaque user subjects reach one exact versioned page-view, screen-view, or interaction outcome across two through four named service, release, environment, and exact safe-property segments. It distinguishes missing property capture from nonmatching values, returns time trends and descriptive differences from the first segment, and never returns identities or claims causality or statistical significance.",
  "summary": {
    "segment_count": 2,
    "baseline_segment_key": "basic",
    "segments_with_eligible_units": 2,
    "segments_with_target_events": 2,
    "segments_with_reached_units": 2
  },
  "confidence": {
    "interpretation": "descriptive_only",
    "unique_count_accuracy": "approximate",
    "estimation_method": "approximate_distinct",
    "causal_inference": "not_established",
    "statistical_significance": "not_tested",
    "segment_overlap": "possible",
    "limitations": [
      "Unique session or typed user-subject counts use bounded cardinality estimates; event and capture-coverage totals are exact within the fully evaluated window.",
      "Segments are evaluated independently and may overlap, so their totals must not be added or interpreted as a population partition.",
      "Differences and relative lift are descriptive only. They do not control for exposure, assignment, seasonality, selection bias, or other confounders.",
      "Bucket-level unique counts are recalculated inside each bucket and are not additive across the series.",
      "Session analysis compares visits or app sessions, not unique people.",
      "At least one segment has classified events without the selected unit ID; compare unit_coverage_rate before interpreting reach differences.",
      "Property predicates are exact case-sensitive string matches. Events without the current property index or every requested key are excluded from segment results and reported separately as missing_property_events.",
      "Direct-identity, credential-like, and network-address custom tag keys are excluded from the analytics property index and cannot be used for segmentation."
    ]
  },
  "segments": [
    {
      "key": "basic",
      "label": "Basic plan",
      "eligible_units": 50,
      "reached_units": 10,
      "reach_rate": 0.2,
      "usable_target_events_per_reached_unit": 1.8,
      "coverage": {
        "classified_events": 200,
        "unit_identified_events": 190,
        "excluded_events": 10,
        "unit_coverage_rate": 0.95,
        "target_events": 20,
        "usable_target_events": 18,
        "excluded_target_events": 2,
        "target_unit_coverage_rate": 0.9,
        "traced_target_events": 10,
        "target_trace_link_rate": 0.5,
        "property_filters": {
          "context_events": 500,
          "property_ready_events": 480,
          "missing_property_events": 20,
          "property_ready_rate": 0.96,
          "matching_events": 200,
          "nonmatching_value_events": 280,
          "match_rate": 0.4166666666666667
        }
      },
      "series": [
        {
          "bucket_start": "2026-06-01T11:00:00Z",
          "bucket_end": "2026-06-01T12:00:00Z",
          "classified_events": 200,
          "eligible_units": 50,
          "target_events": 20,
          "usable_target_events": 18,
          "reached_units": 10,
          "reach_rate": 0.2
        }
      ]
    },
    {
      "key": "premium",
      "label": "Premium plan",
      "eligible_units": 60,
      "reached_units": 18,
      "reach_rate": 0.3,
      "usable_target_events_per_reached_unit": 1.8888888888888888,
      "coverage": {
        "classified_events": 240,
        "unit_identified_events": 228,
        "excluded_events": 12,
        "unit_coverage_rate": 0.95,
        "target_events": 36,
        "usable_target_events": 34,
        "excluded_target_events": 2,
        "target_unit_coverage_rate": 0.9444444444444444,
        "traced_target_events": 18,
        "target_trace_link_rate": 0.5,
        "property_filters": {
          "context_events": 500,
          "property_ready_events": 480,
          "missing_property_events": 20,
          "property_ready_rate": 0.96,
          "matching_events": 240,
          "nonmatching_value_events": 240,
          "match_rate": 0.5
        }
      },
      "series": [
        {
          "bucket_start": "2026-06-01T11:00:00Z",
          "bucket_end": "2026-06-01T12:00:00Z",
          "classified_events": 240,
          "eligible_units": 60,
          "target_events": 36,
          "usable_target_events": 34,
          "reached_units": 18,
          "reach_rate": 0.3
        }
      ],
      "comparison_to_baseline": {
        "eligible_units_difference": 10,
        "reached_units_difference": 8,
        "target_events_difference": 16,
        "reach_rate_difference": 0.09999999999999998,
        "relative_reach_rate_lift": 0.4999999999999998
      }
    }
  ],
  "next_action": {
    "code": "investigate_segment_paths",
    "target": "/api/telemetry/analytics/paths",
    "reason": "Inspect paths around the target in the weakest segment, then use correlated traces to explain a material behavioral difference."
  }
}

Odczytaj wskaźniki i różnice

eligible_units szacuje liczbę sesji lub użytkowników ze sklasyfikowaną aktywnością w segmencie. reached_units szacuje, ile z nich dotarło do celu. reach_rate to reached_units podzielone przez eligible_units. Zdarzenia bez ID wybranej jednostki nie liczą się do tych jednostek. Wskaźnik segmentu bazowego wynosi 20%. Wskaźnik segmentu premium wynosi 30%. Różnica to 10 punktów procentowych. Wzrost względny wynosi 50%, a nie 10%. Drobne błędy w części dziesiętnej wynikają z arytmetyki zmiennoprzecinkowej. Zaokrąglaj wskaźniki do wyświetlania, ale licz na zwróconych wartościach. Segment bazowy nie ma comparison_to_baseline. Wzrost względny jest pomijany, gdy wskaźnik dotarcia segmentu bazowego wynosi zero. W query filtr segmentu, którego nie wysłano, ma wartość null. Pusta lista property_filters jest pomijana. coverage.property_filters ma te same pola co pokrycie filtrów zdarzenia kotwiczącego ścieżki. Tutaj matching_events równa się classified_events. Licz osobno brakujące klucze i niepasujące wartości. Segmenty mogą się nakładać, a jedna sesja może wystąpić w kilku przedziałach. Nie sumuj liczby jednostek między segmentami ani przedziałami. Porównanie jest opisowe. confidence.causal_inference to not_established, a confidence.statistical_significance to not_tested. Wskaźnik 30% wobec 20% nie pokazuje, że plan spowodował więcej zakupów.

Błędy porównania segmentów

Oprócz wspólnych błędów zakresu te żądania zwracają 422 i validation_failed:

Przyczyna	`error`
Mniej niż 2 lub więcej niż 4 segmenty	`product analytics segment comparison requires two through four segments`
2 segmenty z tym samym kluczem	`product analytics segment keys must be unique`
2 segmenty z tymi samymi filtrami	`product analytics segment filters must be unique`
Klucz, który nie ma od 1 do 32 dozwolonych bajtów	`product analytics segment keys must be 1 through 32 machine-safe bytes`
Etykieta pusta, za długa lub ze znakiem sterującym	`product analytics segment labels must be non-empty, control-free, and at most 80 characters`
Wartość filtra ze znakiem sterującym	`product analytics segment filters must be control-free`
Więcej niż 4 filtry właściwości w segmencie	`product analytics segments accept at most four exact property filters`
Klucz, którego nie ma w katalogu właściwości	`product analytics segment property keys must be supported privacy-safe keys`
Ten sam klucz właściwości 2 razy w segmencie	`product analytics segment property keys must be unique within each segment`
Pusta, za długa lub zawierająca znak sterujący wartość właściwości	`product analytics segment property values must be non-empty, control-free, and at most 256 characters`
`response_version` inne niż `1` lub `2`	`product analytics response_version must be 1 or 2`

Błędy interval są takie same jak błędy przeglądu. Na przykład 2 segmenty z różnymi kluczami i identycznymi filtrami zwracają:

{
  "error": "product analytics segment filters must be unique",
  "code": "validation_failed",
  "next": "change at least one exact service_name, release, environment, or property filter",
  "next_action": { "code": "fix_request", "target": "request" }
}

Inna etykieta lub inna kolejność filtrów właściwości nie zmienia wybranych zdarzeń. Błąd walidacji nie dowodzi, że żadne zdarzenia nie pasują. Żądanie GET zwraca 405:

{
  "error": "Method not allowed",
  "code": "method_not_allowed",
  "next": "send POST /api/telemetry/analytics/segments/compare with project_id, since, one exact target, two through four named segments, and optional until, interval, analysis_unit, property_filters, or response_version JSON fields",
  "next_action": { "code": "use_supported_method", "target": "api_method" }
}

Odpowiedź z wolumenem sygnałów

GET /api/telemetry/summary/volume liczy przechowywane sygnały dla jednego projektu i zakresu czasu. Wymaga project_id i since. Nie przyjmuje project_ids. until nie może być w przyszłości. Jeśli go pominiesz, koniec zakresu to czas żądania. Skrócone since, na przykład 24h, liczy wstecz od until. interval to auto, 1m, 5m, 15m, 1h, 6h lub 1d. Domyślne auto wybiera najmniejszą długość przedziału, przy której liczba przedziałów nie przekracza 120. Żądanie nie może wymagać więcej niż 500 przedziałów. Jedyna wartość response_version to 1.

Liczby sygnałów

Ta syntetyczna odpowiedź obejmuje 2 przedziały jednominutowe. Żądanie wykonano o 12:02 UTC bez until. Konto ma 30-dniowy okres przechowywania danych. Odczytaj zwrócone zasady przechowywania i datę graniczną. Nie zakładaj, że te wartości dotyczą twojego konta.

{
  "schema_version": 1,
  "query": {
    "project_id": "11111111-1111-4111-8111-111111111111",
    "requested_since": "2026-09-08T12:00:00Z",
    "since": "2026-09-08T12:00:00Z",
    "until": "2026-09-08T12:02:00Z",
    "interval": "1m",
    "interval_seconds": 60,
    "bucket_alignment": "query_relative_utc_half_open",
    "bucket_count": 2,
    "service_name": "checkout-api",
    "release": "api@1.2.3",
    "environment": "production"
  },
  "purpose": "Compares retained issue occurrences, log events, unique traces, action events, and metric points over one exact project and time scope. Every lane is independently scalable, uses explicit zero-filled half-open buckets, returns no source telemetry rows, and qualifies retention and sampling so different signal volumes are not mistaken for equivalent impact.",
  "series": [
    {
      "signal": "issues",
      "count_unit": "issue_occurrences",
      "total": 1,
      "peak": 1,
      "non_empty_buckets": 1,
      "points": [
        { "bucket_start": "2026-09-08T12:00:00Z", "bucket_end": "2026-09-08T12:01:00Z", "count": 1 },
        { "bucket_start": "2026-09-08T12:01:00Z", "bucket_end": "2026-09-08T12:02:00Z", "count": 0 }
      ]
    },
    {
      "signal": "logs",
      "count_unit": "log_events",
      "total": 3,
      "peak": 2,
      "non_empty_buckets": 2,
      "points": [
        { "bucket_start": "2026-09-08T12:00:00Z", "bucket_end": "2026-09-08T12:01:00Z", "count": 2 },
        { "bucket_start": "2026-09-08T12:01:00Z", "bucket_end": "2026-09-08T12:02:00Z", "count": 1 }
      ]
    },
    {
      "signal": "traces",
      "count_unit": "unique_traces_by_first_observed_span",
      "total": 1,
      "peak": 1,
      "non_empty_buckets": 1,
      "points": [
        { "bucket_start": "2026-09-08T12:00:00Z", "bucket_end": "2026-09-08T12:01:00Z", "count": 1 },
        { "bucket_start": "2026-09-08T12:01:00Z", "bucket_end": "2026-09-08T12:02:00Z", "count": 0 }
      ]
    },
    {
      "signal": "actions",
      "count_unit": "action_events",
      "total": 1,
      "peak": 1,
      "non_empty_buckets": 1,
      "points": [
        { "bucket_start": "2026-09-08T12:00:00Z", "bucket_end": "2026-09-08T12:01:00Z", "count": 1 },
        { "bucket_start": "2026-09-08T12:01:00Z", "bucket_end": "2026-09-08T12:02:00Z", "count": 0 }
      ]
    },
    {
      "signal": "metrics",
      "count_unit": "metric_points",
      "total": 2,
      "peak": 2,
      "non_empty_buckets": 1,
      "points": [
        { "bucket_start": "2026-09-08T12:00:00Z", "bucket_end": "2026-09-08T12:01:00Z", "count": 0 },
        { "bucket_start": "2026-09-08T12:01:00Z", "bucket_end": "2026-09-08T12:02:00Z", "count": 2 }
      ]
    }
  ],
  "coverage": {
    "storage_evaluation": "complete",
    "output_truncation": "not_truncated",
    "payload_shape": "aggregate_only",
    "count_precision": "exact",
    "integer_safety": "javascript_safe",
    "javascript_safe_integer_max": 9007199254740991,
    "returned_series": 5,
    "returned_points": 10,
    "max_buckets_per_series": 500,
    "retention": {
      "policy_days": 30,
      "cutoff": "2026-08-09T12:02:00Z",
      "window_clipped": false
    },
    "sampling": {
      "server": "not_applied",
      "upstream": "unknown"
    },
    "limitations": ["upstream_sampling_unknown", "release_volume_not_included"]
  }
}

Odczytuj każdą liczbę w jej własnej jednostce

Sygnał	Co liczy `total`	Nie oznacza
`issues`	Przechowywane wystąpienia problemów	Zgrupowanych problemów ani dotkniętych użytkowników
`logs`	Przechowywane zdarzenia logów	Żądań
`traces`	Unikalne ID śladów, liczone przy ich pierwszym przechowywanym spanie w tym oknie	Spanów ani wszystkich startów śladów w historii
`actions`	Przechowywane zdarzenia akcji	Użytkowników ani sesji
`metrics`	Przechowywane punkty metryk	Sumy wartości metryk

total to suma liczb w przedziałach szeregu. peak to największa liczba w jednym przedziale szeregu. non_empty_buckets liczy przedziały z liczbą większą od zera. Pięć szeregów zawsze występuje w tej kolejności. Nie łącz liczb różnych sygnałów w jeden wskaźnik wpływu. Przedziały zaczynają się od query.since. Przedział obejmuje swój początek i wyklucza swój koniec. Ostatni przedział może być krótszy niż ustawiona długość przedziału. Odpowiedź nie ma szeregu z liczbą wydań. Nie odczytuj release_volume_not_included jako zera wydań.

Puste i skrócone okna

Jeśli żaden sygnał nie pasuje, wszystkie 5 szeregów pozostaje, a ich punkty mają jawne zerowe liczby. Nieudane żądanie to inna sytuacja. Nie zastępuj błędu wykresem wypełnionym zerami. Porównaj query.requested_since z query.since. Jeśli okres przechowywania skraca okno, coverage.retention.window_clipped ma wartość true, a limitations zawiera retention_window_clipped. Jeśli z żądanego okna nic nie zostaje, query.bucket_count wynosi 0, a każdy szereg ma pustą tablicę points. To nie dowodzi, że w tym okresie nie wystąpiły żadne zdarzenia. policy_days ma wartość null, a cutoff jest pomijane, gdy nie obowiązuje żaden limit przechowywania. sampling.upstream to zawsze unknown, także gdy storage_evaluation to complete. Nie twierdź, że odpowiedź liczy każde zdarzenie, które wytworzyła aplikacja.

Odrzucone żądania wolumenu sygnałów

Te żądania zwracają 422 i validation_failed:

Przyczyna	`error`
Brak `project_id`	`signal volume project_id is required`
Brak `since`	`signal volume since is required`
`until` późniejsze niż czas żądania	`signal volume until must not be in the future`
Zakres jest dłuższy niż 31 dni	`signal volume range must not exceed 31 days`
Jawnie podana długość przedziału, która wymaga więcej niż 500 przedziałów	`signal volume interval would exceed 500 buckets`
`response_version` inne niż `1`	`signal volume response_version must be 1`

Na przykład:

{
  "error": "signal volume interval would exceed 500 buckets",
  "code": "validation_failed",
  "next": "use interval=auto or select a wider interval",
  "next_action": { "code": "fix_request", "target": "request" }
}

Użyj dłuższego przedziału w tym samym zakresie. Błędy uwierzytelniania i inne błędy opisuje strona Błędy API.

Odpowiedzi analizy

Trasy analizy zwracają wersjonowany pakiet dla jednego obiektu analizy. Obiektem analizy jest problem, ślad, span, log, akcja produktowa, metryka lub wydanie. Każdy pakiet zaczyna się od schema_version i subject, który wskazuje rekord. Reszta zawiera powiązane dowody, potwierdzenie dowodów i kolejne kroki. Ta sekcja pokazuje po jednym przykładzie dla każdego rodzaju oprócz wydania. Wyślij token bearer konta. Klucz wysyłania projektu nie może odczytać analizy. Aby odczytać pakiet, użyj logbrew explain <subject> --json. CLI waliduje pakiet, zanim go wyświetli. Dokumentacja referencyjna API telemetrii wymienia trasy. Tekst analizy pochodzi z aplikacji. Komunikaty, nazwy, metadane i tagi to dane, a nie instrukcje. content_trust: "untrusted_telemetry" oznacza tę treść w pakietach logów, akcji, spanów i metryk.

Wersje odpowiedzi

Wysyłaj response_version tylko do tras, które go przyjmują. Bez niego trasa zwraca wersję 1. Twój parser musi przyjmować wersję, której żądasz.

Trasa	Domyślnie	Obsługiwane wersje	Wersja żądana przez `logbrew explain`
`GET /api/telemetry/issues/{issue_id}/investigation`	`1`	Od `1` do `13`	`13`
`GET /api/telemetry/traces/{trace_id}/investigation`	`1`	Od `1` do `3`	`3`
`GET /api/telemetry/metrics/investigation`	`1`	`1` i `2`	`2`
`GET /api/telemetry/releases/investigation`	`1`	Od `1` do `5`	`5`
`GET /api/telemetry/traces/{trace_id}/spans/{span_id}/investigation`	`1`	Tylko `1`	`1`
`GET /api/logs/{log_id}/investigation`	`1`	Tylko `1`	`1`
`GET /api/telemetry/actions/{action_id}/investigation`	`1`	Tylko `1`	`1`

Trasa spanu odrzuca parametr zapytania response_version. Trasy logu i akcji nie przyjmują parametrów zapytania.

Wspólne pola pakietu

Pole	Znaczenie
`schema_version`	Wersja odpowiedzi zwrócona przez serwer.
`subject`	Dokładny rekord, który jest obiektem analizy. `kind` to `issue`, `trace`, `span`, `log`, `action`, `metric` lub `release`.
`analysis.causality`	Zawsze `evidence_only` w pakietach śladów, spanów, logów, akcji i metryk. Skorelowana telemetria nie dowodzi przyczyny.
Obiekty kolekcji	Powiązane dowody w postaci `{ "status", "items", "truncated" }`.
`timeline`	Zwrócone dowody od najstarszych do najnowszych, z własną flagą `truncated`. Kolejność nie dowodzi przyczyny.
`evidence`	Potwierdzenie dowodów. `status` to `complete` lub `partial`.
`next_actions`	Sugerowane odczyty w kolejności `priority`, od `1`. Nie zostały wykonane.

Każda powiązana kolekcja podaje jeden status dostępności:

Status	Znaczenie	Zachowanie klienta
`available`	Odczyt się zakończył i zwrócił elementy.	Pokaż elementy i flagę `truncated`.
`not_linked`	Obiekt analizy nie ma identyfikatora dla tego powiązania, na przykład ID śladu.	Wyjaśnij brak powiązania. Nie twórz go na podstawie znaczników czasu.
`not_found`	Odczyt się zakończył i nie znalazł przechowywanych dowodów.	Pokaż pusty wynik.
`unavailable`	Opcjonalny odczyt się nie powiódł. Obiekt analizy jest nadal prawidłowy.	Nadal pokazuj obiekt analizy. Ponów później. Nie pokazuj 0 elementów jako wyniku.

Potwierdzenie dowodów ma 4 posortowane listy stałych nazw pól: captured_fields, missing_fields, redacted_fields i truncated_fields. status to complete tylko wtedy, gdy 3 ostatnie listy są puste. Zamaskowane dane to nie brakujące dane. Obcięte dane to nie pełne dane. Nie uzupełniaj zamaskowanej ani obciętej wartości.

Limity analizy

Te limity ograniczają jedną odpowiedź. Flaga truncated lub wpis w truncated_fields pokazuje, że limit pominął dane.

Dowody	Limit
Powiązane elementy w jednej kolekcji	20
Przechowywane spany odczytane dla jednego śladu	1000
Elementy osi czasu	50 dla pakietów logów, akcji i spanów. 100 dla pakietów śladów i metryk.
Ustrukturyzowane atrybuty, właściwości i metadane	64 wartości skalarne, 4 poziomy obiektów lub tablic, 16 elementów w każdej tablicy, 512 znaków w każdym ciągu
Okno czasowe korelacji	5 minut przed logiem, akcją lub wybranym wystąpieniem problemu i 5 minut po nich. Dla śladu lub spanu 5 minut przed startem i po końcu, najwyżej 24 godziny.

Sekcja każdego rodzaju wymienia jego własne limity.

Odpowiedź z analizą problemu

Użyj GET /api/telemetry/issues/{issue_id}/investigation, aby odczytać dowody dla jednego wystąpienia zgrupowanego problemu. Przewodnik Zbadaj problem pokazuje, w jakiej kolejności czytać dowody. Żądaj wersji 13:

curl --fail-with-body -sS -G \
  "https://api.logbrew.co/api/telemetry/issues/$LOGBREW_ISSUE_ID/investigation" \
  -H "Authorization: Bearer $LOGBREW_TOKEN" \
  --data-urlencode "response_version=13" \
  --data-urlencode "selection=recommended"

Parametry zapytania to response_version, selection i occurrence_id. selection to recommended, first lub latest. Wartości rozróżniają wielkość liter. W wersjach od 2 do 13 pominięty selektor oznacza recommended. Wersja 1 zwraca ostatnie przechowywane wystąpienie i nie przyjmuje selektora. Filtry listy problemów nie dotyczą tego odczytu.

Przykład analizy problemu w wersji 13

Ta syntetyczna odpowiedź 200 OK ma jedno obsłużone wystąpienie TypeError z powiązanym śladem. Nie ma dowodów z żądania, breadcrumbów, powiązanych logów ani dowodów wdrożenia, więc evidence.status to partial.

{
  "schema_version": 13,
  "subject": {
    "kind": "issue", "id": "11111111-1111-4111-8111-111111111111",
    "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
    "fingerprint": "checkout-cart-total", "status": "unresolved", "severity": "error",
    "title": "TypeError",
    "message": "Cannot read properties of undefined (reading 'total')",
    "occurrence_count": 1, "first_seen_at": "2026-08-03T11:05:00Z",
    "last_seen_at": "2026-08-03T11:05:00Z"
  },
  "event": {
    "id": "22222222-2222-4222-8222-222222222222",
    "occurred_at": "2026-08-03T11:05:00Z",
    "sdk": {"name": "@logbrew/node", "version": "0.1.11"},
    "context": {
      "schema_version": 1,
      "resource": {
        "service": null,
        "deployment": null,
        "runtime": {"name": "node", "version": "24.4.0"},
        "framework": null,
        "operating_system": {"name": "Linux", "version": "6.8", "build": null},
        "device": {"family": null, "model": null, "architecture": "arm64"},
        "application": null
      },
      "trace": {
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", "span_id": "00f067aa0ba902b7",
        "parent_span_id": null, "sampled": true
      },
      "session": null,
      "subject": null,
      "tags": {}
    },
    "exception": {"type": "TypeError", "mechanism": {"type": "javascript.error", "handled": true}},
    "exception_chain": {
      "status": "captured",
      "entries": [
        {
          "id": 0,
          "parent_id": null,
          "relationship": "reported",
          "type": "TypeError",
          "message": null,
          "message_state": "redacted",
          "module": null,
          "mechanism": {"type": "javascript.error", "handled": true},
          "stack_frames": [
            {
              "index": 0, "module": null, "function": "cartTotal", "file": "src/cart.ts",
              "line": 42, "column": 17, "in_app": null, "source": "captured"
            },
            {
              "index": 1, "module": null, "function": "handleCheckout",
              "file": "src/routes/checkout.ts", "line": 88, "column": 9, "in_app": null,
              "source": "captured"
            }
          ],
          "stack_frames_state": "captured"
        }
      ],
      "truncated": false
    },
    "stack_frames": [
      {
        "index": 0, "module": null, "function": "cartTotal", "file": "src/cart.ts",
        "line": 42, "column": 17, "in_app": null, "source": "captured"
      },
      {
        "index": 1, "module": null, "function": "handleCheckout",
        "file": "src/routes/checkout.ts", "line": 88, "column": 9, "in_app": null,
        "source": "captured"
      }
    ],
    "breadcrumbs": [],
    "breadcrumbs_truncated": false
  },
  "occurrence_selection": {
    "requested": "recommended",
    "reason": "only_retained_occurrence",
    "selected": {
      "id": "22222222-2222-4222-8222-222222222222",
      "occurred_at": "2026-08-03T11:05:00Z",
      "severity": "error",
      "environment": "production",
      "release": "checkout@1.2.3",
      "service_name": "checkout-api",
      "sdk": {"name": "@logbrew/node", "version": "0.1.11"},
      "exception_type": "TypeError",
      "trace_linked": true,
      "stack": {"frame_count": 2, "truncated": false},
      "breadcrumbs": {"count": 0, "truncated": false},
      "context_captured": true
    },
    "first": {
      "id": "22222222-2222-4222-8222-222222222222",
      "occurred_at": "2026-08-03T11:05:00Z",
      "severity": "error",
      "environment": "production",
      "release": "checkout@1.2.3",
      "service_name": "checkout-api",
      "sdk": {"name": "@logbrew/node", "version": "0.1.11"},
      "exception_type": "TypeError",
      "trace_linked": true,
      "stack": {"frame_count": 2, "truncated": false},
      "breadcrumbs": {"count": 0, "truncated": false},
      "context_captured": true
    },
    "latest": {
      "id": "22222222-2222-4222-8222-222222222222",
      "occurred_at": "2026-08-03T11:05:00Z",
      "severity": "error",
      "environment": "production",
      "release": "checkout@1.2.3",
      "service_name": "checkout-api",
      "sdk": {"name": "@logbrew/node", "version": "0.1.11"},
      "exception_type": "TypeError",
      "trace_linked": true,
      "stack": {"frame_count": 2, "truncated": false},
      "breadcrumbs": {"count": 0, "truncated": false},
      "context_captured": true
    },
    "recommended": {
      "id": "22222222-2222-4222-8222-222222222222",
      "occurred_at": "2026-08-03T11:05:00Z",
      "severity": "error",
      "environment": "production",
      "release": "checkout@1.2.3",
      "service_name": "checkout-api",
      "sdk": {"name": "@logbrew/node", "version": "0.1.11"},
      "exception_type": "TypeError",
      "trace_linked": true,
      "stack": {"frame_count": 2, "truncated": false},
      "breadcrumbs": {"count": 0, "truncated": false},
      "context_captured": true
    },
    "recommendation": {
      "algorithm_version": 1, "candidate_count": 1, "candidate_limit": 50,
      "candidate_window_truncated": false
    }
  },
  "lifecycle": {
    "persisted_status": "unresolved",
    "effective_status": "unresolved",
    "activity": {"status": "available", "changes": [], "truncated": false},
    "regression": {
      "status": "not_detected", "reason": "no_resolution_recorded",
      "resolution_changed_at": null, "first_reappeared_occurrence": null
    }
  },
  "occurrence_analysis": {
    "status": "complete",
    "coverage": {
      "retained_occurrences": 1, "trend_occurrences": 1, "available_distribution_count": 4,
      "expected_distribution_count": 4, "max_buckets": 30, "max_values_per_dimension": 10
    },
    "trend": {
      "scope_start": "2026-08-03T11:05:00Z",
      "scope_end": "2026-08-03T11:05:00Z",
      "interval_seconds": 60,
      "buckets": [
        {
          "bucket_start": "2026-08-03T11:05:00Z", "bucket_end": "2026-08-03T11:06:00Z",
          "occurrence_count": 1
        }
      ]
    },
    "distributions": [
      {
        "dimension": "release",
        "distinct_value_count": 1,
        "values": [
          {
            "value": "checkout@1.2.3", "version": null, "occurrence_count": 1,
            "share_basis_points": 10000
          }
        ],
        "other_occurrence_count": 0
      },
      {
        "dimension": "environment",
        "distinct_value_count": 1,
        "values": [
          {
            "value": "production", "version": null, "occurrence_count": 1,
            "share_basis_points": 10000
          }
        ],
        "other_occurrence_count": 0
      },
      {
        "dimension": "service",
        "distinct_value_count": 1,
        "values": [
          {
            "value": "checkout-api", "version": null, "occurrence_count": 1,
            "share_basis_points": 10000
          }
        ],
        "other_occurrence_count": 0
      },
      {
        "dimension": "sdk",
        "distinct_value_count": 1,
        "values": [
          {
            "value": "@logbrew/node", "version": "0.1.11", "occurrence_count": 1,
            "share_basis_points": 10000
          }
        ],
        "other_occurrence_count": 0
      }
    ],
    "limitations": []
  },
  "grouping": {"strategy": "sdk_fingerprint", "components": ["sdk_fingerprint"], "stack": null},
  "cause": {
    "status": "evidence_only",
    "summary": null,
    "provenance": null,
    "signals": ["handled_exception", "error_trace_span"]
  },
  "fix": {
    "status": "observed_frame",
    "location": {
      "component": null, "module": null, "function": "cartTotal", "file": "src/cart.ts",
      "line": 42, "column": 17, "in_app": null
    },
    "provenance": "backend_observed"
  },
  "source_locator": {
    "status": "not_found",
    "repository_provider": null,
    "repository_full_name": null,
    "component_path": null,
    "revision": null,
    "revision_source": null,
    "repository_relative_file": null,
    "evidence": {
      "status": "partial",
      "captured_fields": ["source.service"],
      "missing_fields": ["source.component"],
      "redacted_fields": [],
      "truncated_fields": []
    }
  },
  "reproduction": {
    "status": "insufficient_evidence",
    "baseline_occurrence_id": "22222222-2222-4222-8222-222222222222",
    "evidence": {
      "status": "partial",
      "captured_fields": [
        "reproduction.baseline_occurrence", "reproduction.code_location",
        "reproduction.expected_failure"
      ],
      "missing_fields": ["reproduction.trigger"],
      "redacted_fields": [],
      "truncated_fields": []
    }
  },
  "impact": {
    "occurrence_count": 1,
    "first_seen_at": "2026-08-03T11:05:00Z",
    "last_seen_at": "2026-08-03T11:05:00Z",
    "affected_users": null,
    "user_impact": {
      "status": "not_captured",
      "known_affected_users": null,
      "count_method": "unavailable",
      "coverage": {
        "retained_occurrences": 1, "indexed_occurrences": 1,
        "historical_unindexed_occurrences": 0, "identified_user_occurrences": 0,
        "anonymous_subject_occurrences": 0, "missing_subject_occurrences": 1,
        "privacy_filtered_subject_occurrences": 0, "index_coverage_basis_points": 10000,
        "identified_user_coverage_basis_points": 0
      },
      "limitations": ["missing_subject_context"]
    },
    "reported": null
  },
  "correlations": {
    "trace": {
      "status": "available",
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
      "summary": {
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
        "span_count": 1,
        "error_span_count": 1,
        "service_count": 1,
        "project_count": 1,
        "started_at": "2026-08-03T11:04:59.950Z",
        "duration_ms": 180,
        "root_span": {
          "span_id": "00f067aa0ba902b7", "parent_span_id": null, "name": "POST /checkout",
          "operation": "http.server", "status": "error",
          "started_at": "2026-08-03T11:04:59.950Z", "duration_ms": 180,
          "service_name": "checkout-api"
        },
        "slowest_child_span": null,
        "slowest_path": [],
        "error_spans": [
          {
            "span_id": "00f067aa0ba902b7", "parent_span_id": null, "name": "POST /checkout",
            "operation": "http.server", "status": "error",
            "started_at": "2026-08-03T11:04:59.950Z", "duration_ms": 180,
            "service_name": "checkout-api"
          }
        ],
        "services": [
          {
            "service_name": "checkout-api", "span_count": 1, "error_span_count": 1,
            "max_duration_ms": 180
          }
        ],
        "releases": ["checkout@1.2.3"],
        "environments": ["production"]
      },
      "truncated": false
    },
    "logs": {"status": "not_found", "items": [], "truncated": false},
    "actions": {"status": "not_found", "items": [], "truncated": false},
    "metrics": {"status": "not_found", "items": [], "truncated": false},
    "related_issues": {"status": "not_found", "items": [], "truncated": false},
    "release": {
      "release": "checkout@1.2.3", "environment": "production",
      "service_name": "checkout-api", "deployment_status": "not_found"
    }
  },
  "evidence": {
    "status": "partial",
    "captured_fields": [
      "context", "deployment.lookup", "exception", "exception.mechanism", "exception_chain",
      "exception_chain.stack_frames", "grouping", "grouping.components",
      "grouping.strategy", "grouping.strategy_details", "lifecycle.regression",
      "lifecycle.status_history", "likely_fix_area", "occurrence.boundaries",
      "occurrence.distribution.environment", "occurrence.distribution.release",
      "occurrence.distribution.sdk", "occurrence.distribution.service",
      "occurrence.recommendation", "occurrence.selection", "occurrence.trend", "release",
      "sdk", "source_locator", "stack_frames", "trace"
    ],
    "missing_fields": [
      "affected_users", "breadcrumbs", "deployment", "impact", "likely_root_cause",
      "related_actions", "related_issues", "related_logs", "related_metrics", "request",
      "source_locator.complete"
    ],
    "redacted_fields": ["exception_chain.messages"],
    "truncated_fields": []
  },
  "next_actions": [
    {
      "priority": 1, "code": "inspect_code_location", "target": "source_code",
      "reason": "likely_fix_location_available"
    },
    {
      "priority": 2, "code": "inspect_trace", "target": "trace_summary",
      "reason": "linked_trace_available"
    },
    {
      "priority": 3, "code": "compare_release", "target": "release_summary",
      "reason": "release_identity_available"
    },
    {
      "priority": 4, "code": "improve_capture", "target": "sdk_configuration",
      "reason": "evidence_incomplete"
    }
  ]
}

Pole	Wersja	Znaczenie
`subject`	1	Zgrupowany problem. `first_seen_at`, `last_seen_at` i `occurrence_count` opisują grupę.
`event`	1	Wybrane wystąpienie: SDK, `context`, `exception`, `stack_frames` i `breadcrumbs`. W wersji 1 `null`, gdy nie można odczytać ostatniego wystąpienia.
`cause`	1	`status` to `reported_hypothesis`, `evidence_only` lub `unknown`. `signals` wymienia zaobserwowane sygnały.
`fix`	1	Miejsce w kodzie. `status` to `reported_location`, `observed_application_frame`, `observed_frame`, `observed_underlying_exception_frame` lub `unknown`.
`impact`	1	Liczby wystąpień i `user_impact`. `reported` zawiera wpływ zgłoszony przez aplikację albo `null`.
`correlations`	1	`trace`, `logs`, `actions`, `metrics` i `release`.
`occurrence_selection`	2	Żądany selektor, powód oraz podsumowania wybranego, pierwszego, ostatniego i zalecanego wystąpienia.
`lifecycle`	3	`persisted_status`, `effective_status`, historia zmian statusu i `regression`. `effective_status` może mieć wartość `regressed`.
`occurrence_analysis`	4	Trend wystąpień oraz rozkłady według wydania, środowiska, usługi i SDK.
`event.exception_chain`	5	Do 8 powiązanych wyjątków. `relationship` to `reported`, `cause`, `context`, `aggregate_member` lub `suppressed`.
`event.request`	6	`method`, `route_template` i `response_status_code`. Klucza nie ma, gdy nie zarejestrowano żądania.
`grouping`	7	`strategy` grupowania, jej `components` i użycie ramek stosu.
`correlations.release.deployment_status`	8	Stan wyszukiwania wdrożenia. `deployment`, `time_since_deployment_ms` i `deployment_causality` pojawiają się tylko wtedy, gdy znaleziono wdrożenie.
`correlations.related_issues`	9	Inne problemy w tym samym śladzie.
`source_locator`	10	Repozytorium, komponent, rewizja i ścieżka pliku względem repozytorium, gdy LogBrew może je powiązać.
`reproduction`	11	`status` to `ready`, `partial` lub `insufficient_evidence`.
`next_actions`, kod `verify_correction`	12	Pojawia się, gdy `reproduction.status` to `ready`.
`impact.user_impact.count_method`	13	Podaje przybliżoną liczbę unikalnych wartości jako `approximate_distinct`. Wcześniejsze wersje używają starszej nazwy tej wartości. `unavailable` oznacza brak liczby.

Kluczy z późniejszej wersji nie ma we wcześniejszej wersji. Nie odczytuj brakującego klucza jako null. subject.status i statusy w lifecycle pokazują zarchiwizowany problem jako ignored. Odpowiedzi z listą i szczegółami problemów używają archived od wersji odpowiedzi 2. Limity problemów: rekomendacja odczytuje najwyżej 50 przechowywanych wystąpień. Trend ma najwyżej 30 przedziałów. Każdy rozkład zwraca najwyżej 10 wartości. Stos ma najwyżej 32 ramki.

Błędy żądania analizy problemu

Użyj selection albo occurrence_id. Nie wysyłaj obu, nawet gdy wybierają to samo wystąpienie:

{
  "error": "selection and occurrence_id are mutually exclusive",
  "code": "validation_failed",
  "next": "use response_version=2 through 13 with at most one of selection=first|latest|recommended or an exact occurrence_id copied from GET /api/telemetry/issues/{issue_id}/events",
  "next_action": {
    "code": "fix_request",
    "target": "request"
  }
}

HTTP	`error`	Przyczyna	Naprawa
`422`	`selection and occurrence_id are mutually exclusive`	Żądanie ma oba selektory.	Zostaw jeden selektor.
`422`	`issue occurrence selection requires response_version=2 through 13`	Żądanie ma selektor i wersję 1 albo nie ma wersji.	Wyślij `response_version=13`. Zostaw selektor.
`422`	`issue investigation response_version must be 1 through 13`	Wersja jest poza zakresem.	Wyślij obsługiwaną wersję.
`422`	`invalid query parameters`	Nieznany parametr, nieprawidłowy UUID, wersja, która nie jest liczbą całkowitą, albo nieznana wartość `selection`.	Popraw zapytanie.
`404`	`issue occurrence not found`	Wystąpienia nie ma w przechowywanej historii tej grupy.	Skopiuj ID wystąpienia ze zdarzeń tego problemu. Nie używaj zamiast niego `latest` ani `recommended` bez zgody.
`404`	`issue not found`	Żaden projekt dostępny do odczytu nie ma tego problemu.	Sprawdź konto i UUID problemu. Nie wysyłaj UUID wystąpienia jako ID problemu.

Brak wystąpienia nie oznacza, że brakuje problemu. 404 nie pokazuje, czy inne konto może odczytać problem.

Odpowiedź z analizą śladu

Użyj GET /api/telemetry/traces/{trace_id}/investigation, aby odczytać jeden ślad wraz z jego ścieżką błędu, najwolniejszą ścieżką i powiązanymi sygnałami. Parametry zapytania to response_version, project_id, release i environment. Wszystkie są opcjonalne. Żądaj wersji 3:

curl --fail-with-body -sS -G \
  "https://api.logbrew.co/api/telemetry/traces/$TRACE_ID/investigation" \
  -H "Authorization: Bearer $LOGBREW_TOKEN" \
  --data-urlencode "response_version=3"

Wersja 2 dodaje cause i fix do każdego powiązanego problemu. Wersja 3 dodaje span_id do powiązanych problemów, akcji i metryk, gdy zostało zarejestrowane.

Przykład analizy śladu w wersji 3

Ta syntetyczna odpowiedź ma span główny serwera i nieudany span klienta. Nieudany span jest też najwolniejszym spanem podrzędnym. Spany nie mają ustrukturyzowanego kontekstu, więc brakuje spans.context.

{
  "schema_version": 3,
  "subject": {
    "kind": "trace",
    "trace_id": "0af7651916cd43dd8448eb211c80319c",
    "analyzed_span_count": 2,
    "error_span_count": 1,
    "service_count": 1,
    "project_count": 1,
    "started_at": "2026-08-03T11:05:00Z",
    "duration_ms": 1200,
    "releases": ["checkout@1.2.3"],
    "environments": ["production"]
  },
  "analysis": {
    "status": "errors_observed",
    "causality": "evidence_only",
    "root_span": {
      "span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
      "operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
      "duration_ms": 1200, "service_name": "checkout-api"
    },
    "first_error_span": {
      "span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
      "name": "POST /v1/charges", "operation": "http.client", "status": "error",
      "started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
      "service_name": "checkout-api"
    },
    "first_error_path": [
      {
        "span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
        "operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
        "duration_ms": 1200, "service_name": "checkout-api"
      },
      {
        "span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
        "name": "POST /v1/charges", "operation": "http.client", "status": "error",
        "started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
        "service_name": "checkout-api"
      }
    ],
    "bottleneck_span": {
      "span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
      "name": "POST /v1/charges", "operation": "http.client", "status": "error",
      "started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
      "service_name": "checkout-api"
    },
    "bottleneck_path": [
      {
        "span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
        "operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
        "duration_ms": 1200, "service_name": "checkout-api"
      },
      {
        "span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
        "name": "POST /v1/charges", "operation": "http.client", "status": "error",
        "started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
        "service_name": "checkout-api"
      }
    ]
  },
  "spans": {
    "items": [
      {
        "id": "33333333-3333-4333-8333-333333333333",
        "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
        "span_id": "b7ad6b7169203331",
        "parent_span_id": null,
        "name": "POST /checkout",
        "operation": "http.server",
        "status": "ok",
        "started_at": "2026-08-03T11:05:00Z",
        "duration_ms": 1200,
        "service_name": "checkout-api",
        "environment": "production",
        "release": "checkout@1.2.3",
        "sdk": {"name": "@logbrew/node", "version": "0.1.11"},
        "context": null,
        "roles": ["root", "error_path", "bottleneck_path", "slow"]
      },
      {
        "id": "44444444-4444-4444-8444-444444444444",
        "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
        "span_id": "53995c3f42cd8ad8",
        "parent_span_id": "b7ad6b7169203331",
        "name": "POST /v1/charges",
        "operation": "http.client",
        "status": "error",
        "started_at": "2026-08-03T11:05:00.100Z",
        "duration_ms": 900,
        "service_name": "checkout-api",
        "environment": "production",
        "release": "checkout@1.2.3",
        "sdk": {"name": "@logbrew/node", "version": "0.1.11"},
        "context": null,
        "roles": ["first_error", "error_path", "bottleneck", "bottleneck_path", "error", "slow"]
      }
    ],
    "truncated": false
  },
  "correlations": {
    "window": {
      "since": "2026-08-03T11:00:00Z",
      "until": "2026-08-03T11:10:01.200Z",
      "scopes": [
        {
          "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "environment": "production",
          "release": "checkout@1.2.3"
        }
      ],
      "truncated": false
    },
    "issues": {"status": "not_found", "items": [], "truncated": false},
    "logs": {
      "status": "available",
      "items": [
        {
          "id": "55555555-5555-4555-8555-555555555555",
          "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "severity": "error",
          "source": "payments", "message": "Charge request failed",
          "occurred_at": "2026-08-03T11:05:01Z", "service_name": "checkout-api",
          "span_id": "53995c3f42cd8ad8", "environment": "production",
          "release": "checkout@1.2.3"
        }
      ],
      "truncated": false
    },
    "actions": {"status": "not_found", "items": [], "truncated": false},
    "metrics": {"status": "not_found", "items": [], "truncated": false}
  },
  "timeline": {
    "items": [
      {
        "id": "b7ad6b7169203331", "kind": "span", "occurred_at": "2026-08-03T11:05:00Z",
        "name": "POST /checkout", "service_name": "checkout-api",
        "span_id": "b7ad6b7169203331", "severity": null, "status": "ok",
        "duration_ms": 1200
      },
      {
        "id": "53995c3f42cd8ad8", "kind": "span", "occurred_at": "2026-08-03T11:05:00.100Z",
        "name": "POST /v1/charges", "service_name": "checkout-api",
        "span_id": "53995c3f42cd8ad8", "severity": null, "status": "error",
        "duration_ms": 900
      },
      {
        "id": "55555555-5555-4555-8555-555555555555", "kind": "log",
        "occurred_at": "2026-08-03T11:05:01Z", "name": "Charge request failed",
        "service_name": "checkout-api", "span_id": "53995c3f42cd8ad8", "severity": "error",
        "status": null, "duration_ms": null
      }
    ],
    "truncated": false
  },
  "evidence": {
    "status": "partial",
    "captured_fields": [
      "correlations.window", "related_actions", "related_issues", "related_logs",
      "related_metrics", "spans.sdk", "timeline", "trace.parentage", "trace.root",
      "trace.spans"
    ],
    "missing_fields": ["spans.context"],
    "redacted_fields": [],
    "truncated_fields": []
  },
  "next_actions": [
    {
      "priority": 1, "code": "inspect_first_error_span", "target": "trace_span",
      "reason": "error_span_observed", "span_id": "53995c3f42cd8ad8", "issue_id": null
    },
    {
      "priority": 2, "code": "review_related_logs", "target": "telemetry_logs",
      "reason": "related_logs_available", "span_id": "53995c3f42cd8ad8", "issue_id": null
    },
    {
      "priority": 3, "code": "compare_release", "target": "release_summary",
      "reason": "release_identity_available", "span_id": null, "issue_id": null
    },
    {
      "priority": 4, "code": "improve_capture", "target": "sdk_configuration",
      "reason": "evidence_incomplete", "span_id": null, "issue_id": null
    }
  ]
}

Pole	Znaczenie
`subject`	Sumy dla śladu wyliczone z analizowanych spanów.
`analysis.status`	`errors_observed`, `latency_focus` lub `no_error_observed`.
`analysis.first_error_path`	Znany łańcuch spanów nadrzędnych od spanu głównego do najwcześniejszego spanu błędu.
`analysis.bottleneck_path`	Znany łańcuch spanów nadrzędnych do najwolniejszego spanu podrzędnego.
`spans.items[].roles`	Dlaczego span jest w podglądzie: `root`, `first_error`, `error_path`, `bottleneck`, `bottleneck_path`, `error` lub `slow`.
`correlations.window`	Zakres czasu i zakresy wdrożeń użyte do powiązanych odczytów.
`correlations.issues`, `logs`, `actions`, `metrics`	Sygnały z tym samym ID śladu w oknie.

Pola trace.parentage brakuje, gdy span wskazuje span nadrzędny, którego LogBrew nie przechował. Podgląd spanów ma najwyżej 64 spany. Każda ścieżka analizy ma najwyżej 64 spany. Powiązane odczyty używają najwyżej 8 zakresów wdrożeń. Następna akcja z celem trace_span wskazuje span_id z tego pakietu. Aby odczytać ten span, wyślij żądanie do trasy spanu z project_id, environment i release tego spanu.

Odpowiedź z analizą spanu

Użyj GET /api/telemetry/traces/{trace_id}/spans/{span_id}/investigation, aby odczytać jedną operację w śladzie. Wyślij project_id, environment i release. Wszystkie 3 są wymagane. Skopiuj je z wybranego spanu. Nie wysyłaj id wiersza spanu jako span_id.

curl --fail-with-body -sS -G \
  "https://api.logbrew.co/api/telemetry/traces/$TRACE_ID/spans/$SPAN_ID/investigation" \
  -H "Authorization: Bearer $LOGBREW_TOKEN" \
  --data-urlencode "project_id=$PROJECT_ID" \
  --data-urlencode "environment=production" \
  --data-urlencode "release=checkout@1.2.3"

Przykład analizy spanu

Ta syntetyczna odpowiedź opisuje nieudany span klienta z przykładu śladu. Log błędu ma to samo ID spanu. Span trwał dłużej niż przybliżony 95. percentyl przechowywanych spanów tego samego rodzaju.

{
  "schema_version": 1,
  "subject": {
    "kind": "span",
    "id": "44444444-4444-4444-8444-444444444444",
    "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
    "trace_id": "0af7651916cd43dd8448eb211c80319c",
    "span_id": "53995c3f42cd8ad8",
    "parent_span_id": "b7ad6b7169203331",
    "name": "POST /v1/charges",
    "operation": "http.client",
    "status": "error",
    "started_at": "2026-08-03T11:05:00.100Z",
    "duration_ms": 900,
    "service_name": "checkout-api",
    "environment": "production",
    "release": "checkout@1.2.3",
    "sdk": {"name": "@logbrew/node", "version": "0.1.11"},
    "content_trust": "untrusted_telemetry"
  },
  "context": null,
  "payload": {
    "metadata": {
      "values": {"provider": "example-pay"},
      "included_leaf_count": 1,
      "redacted": false,
      "truncated": false
    },
    "events": [],
    "links": [],
    "included_leaf_count": 1,
    "redacted": false,
    "truncated": false
  },
  "analysis": {
    "status": "error_evidence",
    "causality": "evidence_only",
    "observations": ["subject_error", "exact_span_error_log", "subject_at_or_above_peer_p95"]
  },
  "topology": {
    "status": "available",
    "root": {
      "span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
      "operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
      "duration_ms": 1200, "service_name": "checkout-api"
    },
    "parent": {
      "span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
      "operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
      "duration_ms": 1200, "service_name": "checkout-api"
    },
    "ancestors": [
      {
        "span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
        "operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
        "duration_ms": 1200, "service_name": "checkout-api"
      }
    ],
    "children": [],
    "descendant_count": 0,
    "cross_service_edges": [],
    "parent_chain_status": "complete",
    "truncated": false
  },
  "baseline": {
    "status": "available",
    "since": "2026-08-02T11:05:00.100Z",
    "until": "2026-08-03T11:05:00.100Z",
    "dimensions": {
      "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "environment": "production",
      "release": "checkout@1.2.3", "service_name": "checkout-api",
      "operation": "http.client", "name": "POST /v1/charges"
    },
    "retained_peer_count": 40,
    "error_peer_count": 2,
    "error_rate_basis_points": 500,
    "p50_duration_ms": 310.0,
    "p95_duration_ms": 620.0,
    "p99_duration_ms": 940.0,
    "subject_percentile_basis_points": 9500,
    "method": "approximate_t_digest",
    "limitations": [
      "retained_telemetry_only", "sampling_may_apply", "approximate_percentiles",
      "same_release_only"
    ]
  },
  "correlations": {
    "trace": {
      "status": "available",
      "summary": {
        "trace_id": "0af7651916cd43dd8448eb211c80319c",
        "span_count": 2,
        "error_span_count": 1,
        "service_count": 1,
        "project_count": 1,
        "started_at": "2026-08-03T11:05:00Z",
        "duration_ms": 1200,
        "root_span": {
          "span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
          "operation": "http.server", "status": "ok", "started_at": "2026-08-03T11:05:00Z",
          "duration_ms": 1200, "service_name": "checkout-api"
        },
        "slowest_child_span": {
          "span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
          "name": "POST /v1/charges", "operation": "http.client", "status": "error",
          "started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
          "service_name": "checkout-api"
        },
        "slowest_path": [
          {
            "span_id": "b7ad6b7169203331", "parent_span_id": null, "name": "POST /checkout",
            "operation": "http.server", "status": "ok",
            "started_at": "2026-08-03T11:05:00Z", "duration_ms": 1200,
            "service_name": "checkout-api"
          },
          {
            "span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
            "name": "POST /v1/charges", "operation": "http.client", "status": "error",
            "started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
            "service_name": "checkout-api"
          }
        ],
        "error_spans": [
          {
            "span_id": "53995c3f42cd8ad8", "parent_span_id": "b7ad6b7169203331",
            "name": "POST /v1/charges", "operation": "http.client", "status": "error",
            "started_at": "2026-08-03T11:05:00.100Z", "duration_ms": 900,
            "service_name": "checkout-api"
          }
        ],
        "services": [
          {
            "service_name": "checkout-api", "span_count": 2, "error_span_count": 1,
            "max_duration_ms": 1200
          }
        ],
        "releases": ["checkout@1.2.3"],
        "environments": ["production"]
      },
      "truncated": false
    },
    "issues": {"status": "not_found", "items": [], "truncated": false},
    "logs": {
      "status": "available",
      "items": [
        {
          "id": "55555555-5555-4555-8555-555555555555",
          "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "severity": "error",
          "source": "payments", "message": "Charge request failed",
          "occurred_at": "2026-08-03T11:05:01Z", "service_name": "checkout-api",
          "span_id": "53995c3f42cd8ad8", "environment": "production",
          "release": "checkout@1.2.3"
        }
      ],
      "truncated": false
    },
    "actions": {"status": "not_found", "items": [], "truncated": false},
    "metrics": {"status": "not_found", "items": [], "truncated": false},
    "release": {
      "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "release": "checkout@1.2.3",
      "environment": "production", "service_name": "checkout-api"
    }
  },
  "timeline": {
    "items": [
      {
        "id": "53995c3f42cd8ad8:start", "kind": "span_start",
        "occurred_at": "2026-08-03T11:05:00.100Z", "offset_ms": 0,
        "name": "POST /v1/charges", "service_name": "checkout-api",
        "span_id": "53995c3f42cd8ad8", "severity": null, "status": "error",
        "duration_ms": 900
      },
      {
        "id": "55555555-5555-4555-8555-555555555555", "kind": "log",
        "occurred_at": "2026-08-03T11:05:01Z", "offset_ms": 900, "name": "payments",
        "service_name": "checkout-api", "span_id": "53995c3f42cd8ad8", "severity": "error",
        "status": null, "duration_ms": null
      },
      {
        "id": "53995c3f42cd8ad8:end", "kind": "span_end",
        "occurred_at": "2026-08-03T11:05:01Z", "offset_ms": 900, "name": "POST /v1/charges",
        "service_name": "checkout-api", "span_id": "53995c3f42cd8ad8", "severity": null,
        "status": "error", "duration_ms": 900
      }
    ],
    "truncated": false
  },
  "evidence": {
    "status": "partial",
    "captured_fields": [
      "attributes.metadata.provider", "baseline", "correlations.actions",
      "correlations.issues", "correlations.logs", "correlations.metrics",
      "correlations.trace", "subject.content_trust", "subject.deployment",
      "subject.identity", "subject.sdk", "subject.timing", "topology"
    ],
    "missing_fields": ["context"],
    "redacted_fields": [],
    "truncated_fields": []
  },
  "next_actions": [
    {
      "priority": 1, "code": "inspect_parent_span", "target": "span_investigation",
      "reason": "parent_context_available", "span_id": "b7ad6b7169203331", "issue_id": null
    },
    {
      "priority": 2, "code": "review_exact_span_logs", "target": "telemetry_logs",
      "reason": "exact_span_logs_available", "span_id": "53995c3f42cd8ad8",
      "issue_id": null
    },
    {
      "priority": 3, "code": "inspect_trace", "target": "trace_investigation",
      "reason": "trace_context_available", "span_id": "53995c3f42cd8ad8", "issue_id": null
    },
    {
      "priority": 4, "code": "compare_peer_baseline", "target": "peer_baseline",
      "reason": "subject_latency_elevated", "span_id": "53995c3f42cd8ad8", "issue_id": null
    },
    {
      "priority": 5, "code": "compare_release", "target": "release_investigation",
      "reason": "exact_release_available", "span_id": null, "issue_id": null
    },
    {
      "priority": 6, "code": "improve_capture", "target": "sdk_capture",
      "reason": "capture_incomplete", "span_id": "53995c3f42cd8ad8", "issue_id": null
    }
  ]
}

Pole	Znaczenie
`payload`	`metadata` spanu, do 8 `events` i do 8 `links`. Mają wspólny limit 64 wartości.
`analysis.observations`	`subject_error`, `child_error`, `exact_span_error_log`, `related_issue`, `subject_at_or_above_peer_p95` lub `subject_at_or_above_peer_p99`.
`topology`	`root`, `parent`, `ancestors`, bezpośrednie `children`, `descendant_count` i `cross_service_edges`.
`topology.parent_chain_status`	`root`, `complete`, `missing`, `cycle`, `truncated` lub `unavailable`.
`baseline`	Wcześniejsze spany z tym samym projektem, środowiskiem, wydaniem, usługą, operacją i nazwą.
`correlations.logs`	Logi z tym samym ID śladu i ID spanu.
`correlations.issues`, `actions`, `metrics`	Sygnały z tym samym ID śladu w tym samym projekcie, środowisku i wydaniu.
`timeline[].offset_ms`	Milisekundy od startu spanu. Wartość ujemna oznacza czas przed spanem.

Punkt odniesienia (baseline) obejmuje 24 godziny przed startem spanu. since jest włączne, a until wyłączne. error_rate_basis_points: 500 oznacza 5%. subject_percentile_basis_points: 9500 oznacza, że 95% przechowywanych spanów tego samego rodzaju trwało nie dłużej niż ten span. Percentyle są przybliżone. Zachowaj baseline.limitations razem z wartościami. Punkt odniesienia not_found nie ma przechowywanych spanów tego samego rodzaju. Punkt odniesienia unavailable to nieudany odczyt, a nie zerowa liczba. parent_chain_status: "complete" oznacza, że przechowywany łańcuch dociera do spanu głównego. Nie dowodzi, że LogBrew przechował każdy span żądania. Topologia zwraca najwyżej 64 spany-przodków, 50 bezpośrednich spanów podrzędnych i 50 krawędzi między usługami.

HTTP	`error`	Naprawa
`422`	`trace_id must be a non-zero 32-character hexadecimal value`	Skopiuj `trace_id` z odpowiedzi LogBrew ze śladem.
`422`	`span_id must be a non-zero 16-character hexadecimal value`	Skopiuj `span_id` z odpowiedzi LogBrew ze śladem.
`422`	`environment and release must be non-empty exact span scope values`	Skopiuj zakres z wybranego spanu.
`422`	`invalid query parameters`	Wyślij `project_id`, `environment` i `release` bez innych parametrów.
`404`	`span not found`	Sprawdź ID, projekt, środowisko i wydanie.

Odpowiedź z analizą logu

Użyj GET /api/logs/{log_id}/investigation, aby odczytać jeden log i powiązane z nim dowody. Ta trasa nie ma parametrów zapytania. Skopiuj ID logu z listy logów.

curl --fail-with-body -sS \
  "https://api.logbrew.co/api/logs/$LOG_ID/investigation" \
  -H "Authorization: Bearer $LOGBREW_TOKEN"

Odczyt może zwrócić dowody spoza filtrów listy logów. Powiązane odczyty używają projektu, środowiska i wydania logu oraz okna 5 minut przed logiem i 5 minut po nim. Pobliskie logi muszą też mieć tę samą usługę. Nie potrzebują ID śladu. Odczyty dokładnego śladu wymagają ID śladu logu i mogą obejmować inne usługi. Podsumowanie śladu używa tego samego ID śladu i zakresu, ale bez okna czasowego.

Przykład analizy logu

Ta syntetyczna odpowiedź ma log ostrzeżenia bez kontekstu śladu i jeden pobliski log. Odpowiedź nie tworzy powiązania ze śladem na podstawie znaczników czasu.

{
  "schema_version": 1,
  "subject": {
    "kind": "log",
    "id": "66666666-6666-4666-8666-666666666666",
    "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
    "severity": "warning",
    "content_trust": "untrusted_telemetry",
    "source": "inventory",
    "message": "Inventory update delayed",
    "occurred_at": "2026-08-03T12:00:00Z",
    "service_name": "checkout-api",
    "environment": "production",
    "release": "checkout@1.2.3",
    "sdk": {"name": "@logbrew/node", "version": "0.1.11"}
  },
  "context": null,
  "attributes": {
    "values": {"retry_count": 2},
    "included_leaf_count": 1,
    "redacted": false,
    "truncated": false
  },
  "analysis": {
    "status": "warning_evidence",
    "causality": "evidence_only",
    "observations": ["subject_warning"]
  },
  "correlations": {
    "trace": {
      "status": "not_linked", "trace_id": null, "span_id": null, "exact_span": null,
      "summary": null, "truncated": false
    },
    "issues": {"status": "not_linked", "items": [], "truncated": false},
    "trace_logs": {"status": "not_linked", "items": [], "truncated": false},
    "nearby_logs": {
      "status": "available",
      "items": [
        {
          "id": "77777777-7777-4777-8777-777777777777",
          "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "severity": "info",
          "source": "inventory", "message": "Inventory retry started",
          "occurred_at": "2026-08-03T11:59:58Z", "service_name": "checkout-api",
          "trace_id": null, "span_id": null, "environment": "production",
          "release": "checkout@1.2.3", "relationship": "nearby_scope"
        }
      ],
      "truncated": false
    },
    "actions": {"status": "not_linked", "items": [], "truncated": false},
    "metrics": {"status": "not_linked", "items": [], "truncated": false},
    "release": {
      "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "release": "checkout@1.2.3",
      "environment": "production", "service_name": "checkout-api"
    }
  },
  "timeline": {
    "items": [
      {
        "id": "77777777-7777-4777-8777-777777777777", "kind": "log",
        "relationship": "nearby_scope", "occurred_at": "2026-08-03T11:59:58Z",
        "name": "inventory", "message": "Inventory retry started",
        "service_name": "checkout-api", "span_id": null, "severity": "info", "status": null,
        "duration_ms": null
      },
      {
        "id": "66666666-6666-4666-8666-666666666666", "kind": "log",
        "relationship": "subject", "occurred_at": "2026-08-03T12:00:00Z",
        "name": "inventory", "message": "Inventory update delayed",
        "service_name": "checkout-api", "span_id": null, "severity": "warning",
        "status": null, "duration_ms": null
      }
    ],
    "truncated": false
  },
  "evidence": {
    "status": "partial",
    "captured_fields": [
      "attributes", "attributes.retry_count", "correlations.nearby_logs",
      "correlations.release", "subject.content_trust", "subject.environment", "subject.id",
      "subject.message", "subject.occurred_at", "subject.project_id", "subject.release",
      "subject.sdk.name", "subject.sdk.version", "subject.service_name", "subject.severity",
      "subject.source", "timeline"
    ],
    "missing_fields": ["context", "correlations.trace.trace_id"],
    "redacted_fields": [],
    "truncated_fields": []
  },
  "next_actions": [
    {
      "priority": 1, "code": "review_nearby_logs", "target": "telemetry_logs",
      "reason": "nearby_logs_available", "issue_id": null, "trace_id": null,
      "span_id": null
    },
    {
      "priority": 2, "code": "improve_capture", "target": "sdk_configuration",
      "reason": "evidence_incomplete", "issue_id": null, "trace_id": null, "span_id": null
    },
    {
      "priority": 3, "code": "compare_release", "target": "release_investigation",
      "reason": "release_identity_available", "issue_id": null, "trace_id": null,
      "span_id": null
    }
  ]
}

Pole	Znaczenie
`attributes`	Ograniczone ustrukturyzowane atrybuty. `values` nie zawiera `context`, który jest w polu `context` na najwyższym poziomie.
`analysis.status`	`critical_evidence`, `error_evidence`, `warning_evidence` lub `no_failure_observed`.
`correlations.trace`	ID śladu, ID spanu, `exact_span` i `summary` śladu.
`correlations.trace_logs`	Logi z tym samym ID śladu. `relationship` to `exact_trace`.
`correlations.nearby_logs`	Logi tej samej usługi w oknie. `relationship` to `nearby_scope`. Nie obejmuje obiektu analizy ani logów dokładnego śladu.
`correlations.issues`, `actions`, `metrics`	Sygnały z tym samym ID śladu.
`correlations.release`	Zakres wydania dla analizy wydania. Nie zawiera porównania.
`timeline[].relationship`	`subject`, `exact_span`, `exact_trace` lub `nearby_scope`.

ID śladu może występować, gdy status śladu to not_found lub unavailable. Dostępne podsumowanie śladu nie gwarantuje exact_span.

Odpowiedź z analizą akcji

Użyj GET /api/telemetry/actions/{action_id}/investigation, aby odczytać jedną akcję produktową, jej zgłoszony status i powiązane dowody. Ta trasa nie ma parametrów zapytania. Powiązane odczyty używają tego samego okna i zakresów co analiza logu.

curl --fail-with-body -sS \
  "https://api.logbrew.co/api/telemetry/actions/$ACTION_ID/investigation" \
  -H "Authorization: Bearer $LOGBREW_TOKEN"

correlations, timeline i next_actions mają takie same struktury jak w analizie logu. Powiązane akcje nie obejmują akcji, która jest obiektem analizy.

Przykład analizy akcji

Ta syntetyczna odpowiedź opisuje nieudaną akcję realizacji zakupu wykonaną przez zalogowanego użytkownika. Akcja nie ma ID śladu.

{
  "schema_version": 1,
  "subject": {
    "kind": "action",
    "id": "14141414-1414-4141-8141-141414141414",
    "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
    "name": "checkout.submit",
    "status": "failure",
    "content_trust": "untrusted_telemetry",
    "occurred_at": "2026-08-03T11:05:00Z",
    "service_name": "checkout-api",
    "environment": "production",
    "release": "checkout@1.2.3",
    "sdk": {"name": "@logbrew/node", "version": "0.1.11"},
    "subject_classification": "user",
    "session_captured": true
  },
  "context": null,
  "properties": {
    "values": {"plan": "team", "step": "payment"},
    "included_leaf_count": 2,
    "redacted": false,
    "truncated": false
  },
  "analysis": {
    "status": "subject_failure",
    "causality": "evidence_only",
    "observations": ["subject_failure"]
  },
  "correlations": {
    "trace": {
      "status": "not_linked", "trace_id": null, "span_id": null, "exact_span": null,
      "summary": null, "truncated": false
    },
    "issues": {"status": "not_linked", "items": [], "truncated": false},
    "trace_logs": {"status": "not_linked", "items": [], "truncated": false},
    "nearby_logs": {"status": "not_found", "items": [], "truncated": false},
    "actions": {"status": "not_linked", "items": [], "truncated": false},
    "metrics": {"status": "not_linked", "items": [], "truncated": false},
    "release": {
      "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "release": "checkout@1.2.3",
      "environment": "production", "service_name": "checkout-api"
    }
  },
  "timeline": {
    "items": [
      {
        "id": "14141414-1414-4141-8141-141414141414", "kind": "action",
        "relationship": "subject", "occurred_at": "2026-08-03T11:05:00Z",
        "name": "checkout.submit", "message": null, "service_name": "checkout-api",
        "span_id": null, "severity": null, "status": "failure", "duration_ms": null
      }
    ],
    "truncated": false
  },
  "evidence": {
    "status": "partial",
    "captured_fields": [
      "correlations.nearby_logs", "correlations.release", "properties.metadata",
      "properties.metadata.plan", "properties.metadata.step", "subject.content_trust",
      "subject.environment", "subject.id", "subject.name", "subject.occurred_at",
      "subject.project_id", "subject.release", "subject.sdk.name", "subject.sdk.version",
      "subject.service_name", "subject.session_captured", "subject.status",
      "subject.subject_classification", "timeline"
    ],
    "missing_fields": ["context", "correlations.trace.trace_id"],
    "redacted_fields": ["subject.distinct_id", "subject.session_id"],
    "truncated_fields": []
  },
  "next_actions": [
    {
      "priority": 1, "code": "inspect_analytics_paths", "target": "analytics_paths",
      "reason": "session_captured", "issue_id": null, "trace_id": null, "span_id": null
    },
    {
      "priority": 2, "code": "improve_capture", "target": "sdk_configuration",
      "reason": "evidence_incomplete", "issue_id": null, "trace_id": null, "span_id": null
    },
    {
      "priority": 3, "code": "compare_release", "target": "release_investigation",
      "reason": "release_identity_available", "issue_id": null, "trace_id": null,
      "span_id": null
    }
  ]
}

Pole	Znaczenie
`subject.status`	`queued`, `running`, `success`, `failure` albo `null`, gdy nie zarejestrowano obsługiwanego statusu.
`subject.subject_classification`	`user`, `anonymous`, `legacy_unknown`, `missing`, `historical_unindexed` lub `unsupported`.
`subject.session_captured`	Czy akcja miała sesję. Odpowiedź nigdy nie zwraca ID sesji.
`properties`	Ograniczony obiekt `metadata` akcji.
`analysis.status`	`subject_failure`, `correlated_failure_evidence`, `in_progress`, `success_observed` lub `status_not_captured`.

Odpowiedź nigdy nie zwraca identyfikatorów podmiotu ani sesji. Potwierdzenie dowodów zawsze wymienia subject.distinct_id jako zamaskowane, a subject.session_id wtedy, gdy zarejestrowano sesję. Dlatego każdy pakiet akcji ma status partial i zawiera improve_capture. Nie wyłączaj ochrony prywatności, aby spełnić tę sugestię.

Odpowiedź z analizą metryki

Użyj GET /api/telemetry/metrics/investigation, aby odczytać jedną nazwę metryki w jednym projekcie i zakresie czasu. Odpowiedź zawiera bieżący szereg, porównanie z poprzedzającym oknem o tej samej długości, ostatnią próbkę, przykładowe ślady i ukończone wdrożenia. Wersja 2 dodaje opis metryki z ostatniej przechowywanej próbki. Wersja 1 zawsze podaje description_status: "not_captured".

curl --fail-with-body -sS -G \
  "https://api.logbrew.co/api/telemetry/metrics/investigation" \
  -H "Authorization: Bearer $LOGBREW_TOKEN" \
  --data-urlencode "project_id=$PROJECT_ID" \
  --data-urlencode "name=http.server.duration" \
  --data-urlencode "since=2026-08-02T12:00:00Z" \
  --data-urlencode "until=2026-08-03T12:00:00Z" \
  --data-urlencode "interval=5m" \
  --data-urlencode "group_by=service_name" \
  --data-urlencode "environment=production" \
  --data-urlencode "series_limit=12" \
  --data-urlencode "response_version=2"

project_id, name i since są wymagane. since jest włączne, a until wyłączne. Domyślnie until to bieżący moment. Porównanie odczytuje też poprzedzające okno o tej samej długości.

Przykład analizy metryki w wersji 2

Ten syntetyczny histogram ma 5 próbek w 2 przedziałach pięciominutowych. Ostatni przedział ma p95 równe 48 ms. Ostatni przedział poprzedniego okna ma p95 równe 24 ms.

{
  "schema_version": 2,
  "subject": {
    "kind": "metric", "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
    "name": "http.server.duration", "description_status": "captured",
    "description": "Duration of one completed server request."
  },
  "query": {
    "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "name": "http.server.duration",
    "since": "2026-08-02T12:00:00Z", "until": "2026-08-03T12:00:00Z", "interval": "5m",
    "interval_seconds": 300, "group_by": "service_name", "environment": "production",
    "series_limit": 12
  },
  "purpose": "Explains one metric's latest application-supplied description and bounded change, compares the immediately preceding equal window, exposes one privacy-bounded latest-sample capture context, exact trace/span exemplars, and nearby completed deployments, and keeps every correlation evidence-only rather than claiming an anomaly or root cause.",
  "content_trust": "untrusted_telemetry",
  "analysis": {
    "status": "change_observed",
    "causality": "evidence_only",
    "focus": {
      "comparison_index": 0, "selection": "largest_absolute_relative_change",
      "direction": "increased", "absolute_change": 24.0, "relative_change_percent": 100.0
    }
  },
  "coverage": {
    "samples": 5, "series": 1, "returned_series": 1, "points": 2,
    "expected_buckets_per_series": 288, "first_seen_at": "2026-08-03T11:00:10Z",
    "last_seen_at": "2026-08-03T11:09:50Z", "truncated": false
  },
  "series": [
    {
      "identity": {
        "kind": "histogram", "unit": "ms", "temporality": "delta",
        "group_by": "service_name", "group_value": "checkout-api"
      },
      "status": "ready",
      "aggregation": {
        "code": "distribution_p95",
        "description": "Primary value is the approximate p95 of raw observations in each bucket; p50, p99, range, average, count, and sum preserve distribution context."
      },
      "sample_count": 5,
      "points": [
        {
          "bucket_start": "2026-08-03T11:00:00Z", "bucket_end": "2026-08-03T11:05:00Z",
          "sample_count": 2, "value": 42.0, "min": 42.0, "max": 42.0, "average": 42.0,
          "sum": 84.0, "p50": 42.0, "p95": 42.0, "p99": 42.0, "trace_exemplars": []
        },
        {
          "bucket_start": "2026-08-03T11:05:00Z",
          "bucket_end": "2026-08-03T11:10:00Z",
          "sample_count": 3,
          "value": 48.0,
          "min": 48.0,
          "max": 48.0,
          "average": 48.0,
          "sum": 144.0,
          "p50": 48.0,
          "p95": 48.0,
          "p99": 48.0,
          "trace_exemplars": ["4bf92f3577b34da6a3ce929d0e0e4736"]
        }
      ]
    }
  ],
  "comparison": {
    "status": "available",
    "method": "adjacent_equal_window_latest_bucket",
    "previous_since": "2026-08-01T12:00:00Z",
    "previous_until": "2026-08-02T12:00:00Z",
    "items": [
      {
        "identity": {
          "kind": "histogram", "unit": "ms", "temporality": "delta",
          "group_by": "service_name", "group_value": "checkout-api"
        },
        "aggregation": "distribution_p95",
        "current": {
          "bucket_start": "2026-08-03T11:05:00Z", "bucket_end": "2026-08-03T11:10:00Z",
          "sample_count": 3, "value": 48.0
        },
        "previous": {
          "bucket_start": "2026-08-02T11:55:00Z", "bucket_end": "2026-08-02T12:00:00Z",
          "sample_count": 2, "value": 24.0
        },
        "direction": "increased",
        "absolute_change": 24.0,
        "relative_change_percent": 100.0
      }
    ],
    "truncated": false,
    "limitation": "Each item compares the latest non-empty semantic bucket in adjacent equal-length windows. It is an observed value change, not seasonality-aware anomaly detection or evidence that a deployment caused the change."
  },
  "latest_sample": {
    "status": "available",
    "sample": {
      "id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
      "kind": "histogram",
      "value": 48.0,
      "unit": "ms",
      "temporality": "delta",
      "occurred_at": "2026-08-03T11:09:50Z",
      "service_name": "checkout-api",
      "environment": "production",
      "release": "checkout@1.2.3",
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
      "span_id": "00f067aa0ba902b7",
      "sdk": {"name": "@logbrew/node", "version": "0.1.11"},
      "context": null,
      "metadata": {"values": {}, "included_leaf_count": 0, "redacted": false, "truncated": false}
    }
  },
  "exemplars": {
    "status": "available",
    "coverage": {
      "matching_samples": 5, "trace_linked_samples": 1, "span_linked_samples": 1,
      "returned_exemplars": 1
    },
    "items": [
      {
        "id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
        "value": 48.0,
        "occurred_at": "2026-08-03T11:09:50Z",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
        "span_id": "00f067aa0ba902b7",
        "service_name": "checkout-api",
        "environment": "production",
        "release": "checkout@1.2.3",
        "sdk": {"name": "@logbrew/node", "version": "0.1.11"}
      }
    ],
    "truncated": false
  },
  "deployments": {
    "status": "available",
    "items": [
      {
        "deployment_id": "deploy-123", "release": "checkout@1.2.3",
        "environment": "production", "service_name": "checkout-api", "status": "succeeded",
        "started_at": "2026-08-03T11:02:00Z", "finished_at": "2026-08-03T11:03:00Z",
        "commit_sha": "0123456789abcdef"
      }
    ],
    "truncated": false
  },
  "timeline": {
    "items": [
      {
        "id": "deploy-123", "kind": "deployment_finished",
        "occurred_at": "2026-08-03T11:03:00Z", "value": null, "trace_id": null,
        "span_id": null, "release": "checkout@1.2.3", "service_name": "checkout-api"
      },
      {
        "id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd", "kind": "metric_exemplar",
        "occurred_at": "2026-08-03T11:09:50Z", "value": 48.0,
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", "span_id": "00f067aa0ba902b7",
        "release": "checkout@1.2.3", "service_name": "checkout-api"
      }
    ],
    "truncated": false
  },
  "evidence": {
    "status": "partial",
    "captured_fields": [
      "metric.current_window_coverage", "metric.deployment_overlays", "metric.description",
      "metric.identity", "metric.latest_sample", "metric.latest_sample.kind",
      "metric.latest_sample.occurred_at", "metric.latest_sample.scope",
      "metric.latest_sample.sdk.name", "metric.latest_sample.sdk.version",
      "metric.latest_sample.span_id", "metric.latest_sample.trace_id",
      "metric.latest_sample.value", "metric.prior_window_comparison", "metric.query_scope",
      "metric.series_semantics", "metric.span_exemplars", "metric.trace_exemplars"
    ],
    "missing_fields": ["metric.latest_sample.context", "metric.latest_sample.metadata"],
    "redacted_fields": [],
    "truncated_fields": []
  },
  "next_actions": [
    {
      "priority": 1,
      "code": "inspect_exact_span",
      "target": "span_investigation",
      "reason": "Inspect the exact span that emitted a retained metric exemplar, then review its failure, latency, log, issue, action, and trace evidence.",
      "context": {
        "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", "span_id": "00f067aa0ba902b7",
        "environment": "production", "release": "checkout@1.2.3",
        "service_name": "checkout-api"
      }
    },
    {
      "priority": 2,
      "code": "review_deployment",
      "target": "release_investigation",
      "reason": "Review release-scoped telemetry for a completed deployment inside the compared evidence window without treating temporal proximity as causality.",
      "context": {
        "project_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "trace_id": null,
        "span_id": null, "environment": "production", "release": "checkout@1.2.3",
        "service_name": "checkout-api"
      }
    }
  ]
}

Pole	Znaczenie
`subject.description_status`	`captured`, `not_captured` lub `unavailable`.
`query`	Znormalizowane zapytanie. `service_name`, `release` i `environment` pojawiają się tylko wtedy, gdy je wysłano.
`analysis.status`	`no_samples`, `change_observed`, `no_change_observed`, `baseline_not_found` lub `comparison_unavailable`.
`analysis.focus`	Element porównania z największą zmianą względną albo z największą zmianą bezwzględną, gdy zmiany względnej nie ma. `null`, gdy żaden element nie jest porównywalny.
`series[].aggregation.code`	`gauge_last`, `delta_sum`, `distribution_p95`, `raw_cumulative_last` lub `raw_last`.
`comparison.status`	`available`, `partial`, `not_found`, `unavailable` lub `no_current_samples`.
`comparison.items[]`	Ostatni niepusty przedział każdego okna dla tej samej tożsamości szeregu.
`latest_sample`	Ostatnia surowa próbka z SDK, `context`, `metadata` i powiązaniem ze śladem.
`exemplars`	Surowe próbki z ID śladu. `coverage` liczy powiązane próbki.
`deployments`	Ukończone wdrożenia od początku poprzedniego okna do `until`.
`next_actions[]`	`code`, `target`, `reason` w postaci zwykłego tekstu i zakres `context` dla następnego odczytu.

relative_change_percent to (current - previous) / abs(previous) * 100. Ma wartość null, gdy poprzednia wartość wynosi zero lub jej brakuje. expected_buckets_per_series liczy możliwe przedziały, a nie przedziały z danymi. Nie rysuj pustych przedziałów jako zera. Wdrożenie w pobliżu zmiany nie dowodzi, że ją spowodowało. Projekt, którego konto nie może odczytać, zwraca 200 OK z analysis.status: "no_samples", a nie 404. Pusty wynik nie opisuje innych typów sygnałów. Limity metryk: zakres to najwyżej 31 dni. Każdy szereg ma najwyżej 500 przedziałów. series_limit wynosi od 1 do 20, domyślnie 10. Odpowiedź zwraca najwyżej 20 przykładowych śladów i 20 wdrożeń.

HTTP	`error`	Naprawa
`422`	`metric investigation response_version must be 1 or 2`	Pomiń `response_version` albo wyślij `2`.
`422`	`metric series project_id is required`	Wyślij ID jednego projektu, który konto może odczytać.
`422`	`metric series name is required`	Skopiuj nazwę z listy metryk.
`422`	`metric series since is required`	Wyślij wartość taką jak `24h` albo znacznik czasu RFC 3339.
`422`	`metric series range must not exceed 31 days`	Użyj krótszego zakresu.
`422`	`metric series interval would exceed 500 buckets`	Użyj `interval=auto` albo dłuższego przedziału.
`422`	`metric series_limit must be between 1 and 20`	Wyślij wartość od 1 do 20.

interval to auto, 1m, 5m, 15m, 1h, 6h lub 1d. group_by to none, service_name, release lub environment. Inne wartości zwracają 422.

Błędy analizy

HTTP	Trasa	`error`
`404`	Log	`log not found`
`404`	Akcja	`action not found`
`404`	Ślad	`trace not found`
`422`	Ślad	`trace investigation response_version must be 1, 2, or 3`
`400`	Log, akcja, problem	`invalid URL path parameters`, gdy ID w ścieżce nie jest UUID
`422`	Problem, ślad, span, metryka	`invalid query parameters` dla nieznanego parametru lub wartości niewłaściwego typu

404 oznacza, że żaden projekt dostępny do odczytu nie ma tego rekordu. Każda trasa zwraca też 401 bez prawidłowego uwierzytelnienia i 405 dla metody innej niż GET. Odpowiedzi o braku zasobu, o nieprawidłowej wartości w ścieżce, o błędzie uwierzytelniania i o nieobsługiwanej metodzie opisuje strona Błędy API. Opcjonalny odczyt dowodów może się nie powieść wewnątrz odpowiedzi 200 OK. Kolekcja podaje wtedy unavailable. Nie pokazuj jej jako not_found ani jako 0 rekordów.

Wartości ważności

Wartości ważności widoczne dla użytkownika to info, warning, error i critical. SDK i środowiska uruchomieniowe mogą wysyłać popularne aliasy, takie jak trace, debug, warn lub fatal. Odpowiedzi REST i odpowiedzi na żywo zawsze zwracają wartość kanoniczną. Na przykład LogBrew przyjmuje warn na wejściu i zwraca warning. Przyjmowanie danych odrzuca nieznane wartości ważności.

Alias	Wartość kanoniczna
`trace`, `debug`	`info`
`warn`	`warning`
`fatal`	`critical`

Odpowiedzi reguł ważności

Reguła ważności zmienia sposób, w jaki LogBrew pokazuje log lub problem. Nie zmienia poziomu ważności zarejestrowanego przez aplikację. Logi i problemy zwracają obiekt triage:

Pole	Znaczenie
`effective_severity`	Poziom ważności do wyświetlenia. Bez reguły jest równy `severity`.
`ignored`	`true`, gdy reguła logu ignoruje log albo gdy problem jest zarchiwizowany.
`rule_applied`	`true`, gdy obowiązuje reguła ważności lub stan ignorowania. `false` to wartość domyślna, a nie brak danych.

Do wyświetlania używaj triage.effective_severity. Zachowaj severity jako zarejestrowaną wartość. Domyślnie lista logów pomija ignorowane logi. Aby je uwzględnić, wyślij status=ignored lub status=all w GET /api/logs. Konto musi mieć uprawnienie do zarządzania problemami w projekcie. Dostęp do odczytu nie wystarcza. Bez tego uprawnienia zmiana reguły zwraca 403 z code: forbidden.

Zmień regułę logu

PUT /api/logs/{log_id}/triage-rule ustawia regułę dla logu i późniejszych logów z tą samą sygnaturą. Treść wymaga zarówno severity, jak i ignored:

curl --request PUT "https://api.logbrew.co/api/logs/$LOG_ID/triage-rule" \
  --header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  --header "Content-Type: application/json" \
  --data '{ "severity": "info", "ignored": true }'

Odpowiedź 200 OK zawiera pełny log. Jego severity pozostaje warning. Jego triage pokazuje regułę:

{
  "severity": "warning",
  "triage": {
    "effective_severity": "info",
    "ignored": true,
    "rule_applied": true
  }
}

Ten fragment pokazuje tylko zmienione pola. severity w żądaniu to source, info, warning, error lub critical. source przywraca zarejestrowany poziom ważności. Nie przywraca zignorowanego logu do stanu aktywnego. Aby znowu pokazać log, wyślij "ignored": false.

Zmień regułę problemu

PUT /api/telemetry/issues/{issue_id}/triage-rule ustawia wyświetlany poziom ważności zgrupowanego problemu i jego późniejszych wystąpień. Treść przyjmuje tylko severity:

curl --request PUT "https://api.logbrew.co/api/telemetry/issues/$ISSUE_ID/triage-rule" \
  --header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  --header "Content-Type: application/json" \
  --data '{ "severity": "warning" }'

Odpowiedź 200 OK zawiera pełny problem w wersji 1. Zarejestrowane severity i status się nie zmieniają:

{
  "severity": "error",
  "status": "unresolved",
  "triage": {
    "effective_severity": "warning",
    "ignored": false,
    "rule_applied": true
  }
}

Ten fragment pokazuje tylko część pól. Reguła nie rozwiązuje, nie archiwizuje ani nie otwiera ponownie problemu. Do tego służy zmiana statusu. Wyliczony priorytet wynika z nowego efektywnego poziomu ważności. Aby go zobaczyć, odczytaj problem z response_version=2 lub 3. Nieobsługiwany poziom ważności zwraca 422:

{
  "error": "triage severity must be source, info, warning, error, or critical",
  "code": "validation_failed",
  "next": "use source to restore captured severity, or choose info, warning, error, or critical",
  "next_action": {
    "code": "fix_request",
    "target": "request"
  }
}

Nieznane pole treści, na przykład status w regule problemu, zwraca 422 z code: invalid_json. Brakujący albo niedostępny do odczytu log lub problem zwraca 404 z code: not_found. Jeśli odpowiedź zaginie, odczytaj log lub problem ponownie, zanim znowu wyślesz regułę.

Format odpowiedzi z błędem

Błędy aplikacji zwracają kopertę JSON. Ten przykład pokazuje odrzucone żądanie. Tekst error i next zależy od rodzaju błędu:

{
  "error": "<what is wrong>",
  "code": "validation_failed",
  "next": "<how to fix it>",
  "next_action": {
    "code": "fix_request",
    "target": "request"
  }
}

Używaj code do rozgałęzień w programie, a next_action do automatyzacji. Pokazuj ludziom error i next jako zwykły tekst. Nie parsuj ich treści. Niektóre błędy dodają pola, takie jak limit, reset_at lub retry_after_seconds. Odpowiedź bez treści JSON nie ma code LogBrew. Wszystkie kody opisuje strona Błędy API.

Odczytuj dane w CLI

CLI odczytuje te same trasy i z --json zwraca ten sam JSON. Zacznij od szerokiego zakresu, a potem go zawężaj:

logbrew read releases --environment production --json
logbrew read issues --release api@1.2.3 --status unresolved --json
logbrew read logs --release api@1.2.3 --since 24h --json
logbrew read actions --name checkout_failed --since 24h --json
logbrew read traces --status error --since 24h --json
logbrew read trace <trace_id> --json

Dodaj --pagination cursor, aby dostać kopertę kursora. CLI żąda wersji 4 odpowiedzi z problemem. Zobacz Odczytaj następną stronę i Obserwowanie na żywo.

​Jak odczytać odpowiedź

​Co wysyłać

​Odpowiedź przyjmowania danych

​Odpowiedź na paczkę SDK

​Odpowiedź na natywną kopertę

​Błędy przyjmowania danych

​Format odpowiedzi list telemetrii

​Odpowiedź z logami

​Odpowiedź z problemem

​Odpowiedź z listą kont i zespołów do przypisania

​Odpowiedź z akcją

​Odpowiedź z metryką

​Odpowiedź z wydaniem

​Odpowiedź z wyszukiwania śladów

​Puste listy i brakujące rekordy

​Odrzucony wybór projektów

​Błędy kursora

​Odpowiedzi z kursorem wydań

​Błędy wyszukiwania śladów

​Historia wystąpień problemu

​Odpowiedzi ze spanami i podsumowaniem śladu

​Lista spanów

​Podsumowanie śladu

​Brak pasujących spanów

​Format odpowiedzi ze zdarzeniami na żywo

​Utwórz bilet

​Otwórz połączenie

​Odczytaj komunikaty

​Obsłuż zamknięte połączenie

​Przykłady odpowiedzi na zmianę statusu problemu

​Zakres żądań analityki

​Wspólne błędy zakresu

​Odpowiedź z przeglądem analityki produktowej

​Udany przegląd

​Odczytaj przegląd

​Błędy przeglądu

​Odpowiedź z uporządkowanym lejkiem

​Udany lejek

​Odczytaj konwersję i pokrycie

​Puste wyniki lejka

​Odrzucone żądania lejka

​Tryb dokładnych zdarzeń i tryb automatyczny

​Żądanie utrzymania dla dokładnych zdarzeń

​Udane utrzymanie dla dokładnych zdarzeń

​Odczytaj utrzymanie

​Automatyczne utrzymanie

​Utrzymanie bez kwalifikujących się użytkowników

​Błędy utrzymania

​Żądanie cyklu życia dla dokładnego zdarzenia

​Udany cykl życia dla dokładnego zdarzenia

​Odczytaj cykl życia

​Automatyczny cykl życia

​Cykl życia bez użytkowników

​Błędy cyklu życia

​Odczytaj wybrany zakres analizy

​Odpowiedź z szeregiem metryki

​Udany szereg metryki

​Odczytaj szereg metryki

​Zakres i błędy szeregu metryki

​Odpowiedź ze ścieżkami

​Udane ścieżki

​Odczytaj ścieżki

​Filtruj zdarzenie kotwiczące według właściwości

​Puste ścieżki i odrzucone żądania

​Katalog właściwości analityki

​Odczytaj dostępne klucze właściwości

​Udany katalog właściwości

​Odczytaj katalog

​Błędy katalogu właściwości

​Porównanie segmentów w analityce

​Zdefiniuj porównanie

​Udane porównanie segmentów

​Odczytaj wskaźniki i różnice

​Błędy porównania segmentów

​Odpowiedź z wolumenem sygnałów

​Liczby sygnałów

​Odczytuj każdą liczbę w jej własnej jednostce

​Puste i skrócone okna

​Odrzucone żądania wolumenu sygnałów

​Odpowiedzi analizy

Jak odczytać odpowiedź

Co wysyłać

Odpowiedź przyjmowania danych

Odpowiedź na paczkę SDK

Odpowiedź na natywną kopertę

Błędy przyjmowania danych

Format odpowiedzi list telemetrii

Odpowiedź z logami

Odpowiedź z problemem

Odpowiedź z listą kont i zespołów do przypisania

Odpowiedź z akcją

Odpowiedź z metryką

Odpowiedź z wydaniem

Odpowiedź z wyszukiwania śladów

Puste listy i brakujące rekordy

Odrzucony wybór projektów

Błędy kursora

Odpowiedzi z kursorem wydań

Błędy wyszukiwania śladów

Historia wystąpień problemu

Odpowiedzi ze spanami i podsumowaniem śladu

Lista spanów

Podsumowanie śladu

Brak pasujących spanów

Format odpowiedzi ze zdarzeniami na żywo

Utwórz bilet

Otwórz połączenie

Odczytaj komunikaty

Obsłuż zamknięte połączenie

Przykłady odpowiedzi na zmianę statusu problemu

Zakres żądań analityki

Wspólne błędy zakresu

Odpowiedź z przeglądem analityki produktowej

Udany przegląd

Odczytaj przegląd

Błędy przeglądu

Odpowiedź z uporządkowanym lejkiem

Udany lejek

Odczytaj konwersję i pokrycie

Puste wyniki lejka

Odrzucone żądania lejka

Tryb dokładnych zdarzeń i tryb automatyczny

Żądanie utrzymania dla dokładnych zdarzeń

Udane utrzymanie dla dokładnych zdarzeń

Odczytaj utrzymanie

Automatyczne utrzymanie

Utrzymanie bez kwalifikujących się użytkowników

Błędy utrzymania

Żądanie cyklu życia dla dokładnego zdarzenia

Udany cykl życia dla dokładnego zdarzenia

Odczytaj cykl życia

Automatyczny cykl życia

Cykl życia bez użytkowników

Błędy cyklu życia

Odczytaj wybrany zakres analizy

Odpowiedź z szeregiem metryki

Udany szereg metryki

Odczytaj szereg metryki

Zakres i błędy szeregu metryki

Odpowiedź ze ścieżkami

Udane ścieżki

Odczytaj ścieżki

Filtruj zdarzenie kotwiczące według właściwości

Puste ścieżki i odrzucone żądania

Katalog właściwości analityki

Odczytaj dostępne klucze właściwości

Udany katalog właściwości

Odczytaj katalog

Błędy katalogu właściwości

Porównanie segmentów w analityce

Zdefiniuj porównanie

Udane porównanie segmentów

Odczytaj wskaźniki i różnice

Błędy porównania segmentów

Odpowiedź z wolumenem sygnałów

Liczby sygnałów

Odczytuj każdą liczbę w jej własnej jednostce

Puste i skrócone okna

Odrzucone żądania wolumenu sygnałów

Odpowiedzi analizy