> ## Documentation Index
> Fetch the complete documentation index at: https://docs.logbrew.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Format odpowiedzi API i przykłady odpowiedzi JSON
> Odczytuj odpowiedzi API LogBrew: listy telemetrii, strony kursora, zdarzenia na żywo, zmiany danych, stany powodzenia i błędy.
Ta strona pokazuje po jednym przykładzie każdego rodzaju odpowiedzi
[API telemetrii](/pl/reference/telemetry-api). Wszystkie wartości są syntetyczne.
Kody błędów i sposoby naprawy opisuje strona [Błędy API](/pl/reference/api-errors).
## Jak odczytać odpowiedź
Odczytuj każdą odpowiedź w tej kolejności:
1. Sprawdź status HTTP.
2. Upewnij się, że treść ma strukturę, którą określa dana trasa.
3. Upewnij się, że każdy `project_id` mieści się w żądanym zakresie projektów.
4. Nie zmieniaj kanonicznych wartości wyliczeniowych ani identyfikatorów.
5. Wykonuj `next_action` tylko wtedy, gdy klient obsługuje jego `code` i
`target`.
6. 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](/pl/guides/sdk-ingestion) i
[Kontrola rejestrowanych danych](/pl/guides/safe-capture).
## 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:
```json theme={null}
{
"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:
```json theme={null}
{
"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](/pl/guides/sdk-ingestion#required-envelope-fields).
### 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`:
```json theme={null}
{
"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ą](/pl/reference/telemetry-api-filters#cursor-pagination).
### Odpowiedź z logami
Strona kursora z logami przy `limit=1`:
```json theme={null}
{
"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](#severity-rule-responses).
`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:
```json theme={null}
{
"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](/pl/guides/investigate-an-issue).
`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](#issue-occurrence-history). |
| `symbolication` | Tylko w `GET /api/telemetry/issues/{issue_id}`, gdy problem ma tożsamość artefaktu wydania. Zobacz [Mapy źródeł JavaScript](/pl/guides/source-maps). |
`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. |
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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=` zwraca każde
konto, któremu można przypisywać problemy w projekcie:
```json theme={null}
{
"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ą
```json theme={null}
{
"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](/pl/guides/product-events).
### Odpowiedź z metryką
```json theme={null}
{
"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
```json theme={null}
{
"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](/pl/concepts/releases).
### 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:
```json theme={null}
{
"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](#trace-spans-and-summary-responses).
### 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](#log-response) | `404` z `code: not_found` |
| `GET /api/telemetry/issues/{issue_id}` | `200` z jednym [problemem](#issue-response) | `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`:
```json theme={null}
{
"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`:
```json theme={null}
{
"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:
```json theme={null}
{
"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](/pl/reference/telemetry-api-filters#project-scope).
### 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:
```json theme={null}
{
"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`:
```json theme={null}
{
"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](#cursor-errors).
### 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](/pl/reference/telemetry-api-filters#trace-filters).
### 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.
```bash theme={null}
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:
```json theme={null}
{
"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](/pl/guides/investigate-an-issue#select-a-different-occurrence). |
| `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ą:
```json theme={null}
{
"issue_id": "d1776d70-763c-47b5-a8f1-76f593221e2b",
"events": [],
"next_cursor": null
}
```
Nie używaj kursora ponownie dla innego problemu. [Błędy kursora](#cursor-errors)
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:
```json theme={null}
[
{
"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:
```json theme={null}
{
"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.
```bash theme={null}
curl --request POST "https://api.logbrew.co/api/feed/ticket" \
--header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER"
```
Odpowiedź `200 OK` zawiera bilet w polu `ticket`:
```json theme={null}
{
"ticket": "",
"expires_in_seconds": 60,
"next": "connect with GET /api/feed/live?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=`. 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](#log-response). |
| `native_issue` | Dane zgrupowanego problemu w strukturze [odpowiedzi z problemem](#issue-response) w wersji 1. |
| `native_trace_span` | Jeden span w strukturze elementu [listy spanów](#span-list). |
| `native_action` | Dane akcji produktowej w strukturze [odpowiedzi z akcją](#action-response). |
| `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](/pl/reference/account-api#account-usage). |
```json theme={null}
{
"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](/pl/reference/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](#issue-response). 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](/pl/reference/telemetry-api#update-one-issue).
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`:
```json theme={null}
{
"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:` | 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](/pl/reference/api-errors#writes).
`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`:
```json theme={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](/pl/reference/telemetry-api#update-issues-in-bulk).
Żą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:
```json theme={null}
{
"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](/pl/reference/api-errors#invalid-query-parameters).
Nieznane pole JSON, brak wymaganego pola JSON lub nieobsługiwana wartość wyliczeniowa
zwraca `invalid_json`. Zobacz
[Nieprawidłowy JSON](/pl/reference/api-errors#invalid-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](/pl/reference/api-errors#unsupported-method).
## 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:
```bash theme={null}
curl --get "https://api.logbrew.co/api/telemetry/analytics/overview" \
--header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
--data-urlencode "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.
```json theme={null}
{
"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](/pl/concepts/product-analytics#use-the-analytics-api).
### Błędy przeglądu
Oprócz [wspólnych błędów zakresu](#shared-scope-errors) 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ę:
```json theme={null}
{
"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`:
```json theme={null}
{
"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](/pl/concepts/product-analytics#measure-a-funnel).
### 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](#shared-scope-errors) te żądania zwracają
`422` i `validation_failed`. Mniej niż 2 lub więcej niż 8 kroków:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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](#shared-scope-errors) 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:
```json theme={null}
{
"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:
```json theme={null}
{
"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.
```json theme={null}
{
"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ść:
```json theme={null}
{
"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ą:
```json theme={null}
{
"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`:
```json theme={null}
{
"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](#shared-scope-errors) 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:
```json theme={null}
{
"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:
```bash theme={null}
curl --get "https://api.logbrew.co/api/telemetry/metrics/series" \
--header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
--data-urlencode "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.
```json theme={null}
{
"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](/pl/concepts/telemetry#read-the-metric-value).
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`:
```json theme={null}
{
"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`:
```json theme={null}
{
"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`.
```json theme={null}
{
"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.
```json theme={null}
{
"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](#analytics-property-catalog). 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](#shared-scope-errors) 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:
```json theme={null}
{
"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](#analytics-segment-comparison) 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`.
```bash theme={null}
curl --get "https://api.logbrew.co/api/telemetry/analytics/properties" \
--header "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
--data-urlencode "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.
```json theme={null}
{
"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](#shared-scope-errors) `limit=0` lub
`limit=51` zwraca `422`:
```json theme={null}
{
"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`:
```json theme={null}
{
"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:
```json theme={null}
{
"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.
```json theme={null}
{
"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](#filter-the-anchor-by-property). 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](#shared-scope-errors) 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](#overview-errors).
Na przykład 2 segmenty z różnymi kluczami i identycznymi filtrami zwracają:
```json theme={null}
{
"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`:
```json theme={null}
{
"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.
```json theme={null}
{
"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:
```json theme={null}
{
"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](/pl/reference/api-errors).
## 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 --json`.
CLI waliduje pakiet, zanim go wyświetli.
[Dokumentacja referencyjna API telemetrii](/pl/reference/telemetry-api)
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](/pl/guides/investigate-an-issue) pokazuje,
w jakiej kolejności czytać dowody. Żądaj wersji 13:
```bash theme={null}
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.
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`.
```json theme={null}
{
"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:
```json theme={null}
{
"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](/pl/reference/api-errors#invalid-query-parameters). |
| `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:
```bash theme={null}
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.
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`.
```json theme={null}
{
"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`.
```bash theme={null}
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"
```
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.
```json theme={null}
{
"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.
```bash theme={null}
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.
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.
```json theme={null}
{
"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.
```bash theme={null}
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.
Ta syntetyczna odpowiedź opisuje nieudaną akcję realizacji zakupu wykonaną przez
zalogowanego użytkownika. Akcja nie ma ID śladu.
```json theme={null}
{
"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"`.
```bash theme={null}
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.
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.
```json theme={null}
{
"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](/pl/reference/api-errors#resource-not-found),
[o nieprawidłowej wartości w ścieżce](/pl/reference/api-errors#invalid-path-value),
[o błędzie uwierzytelniania](/pl/reference/api-errors#authentication-failure) i
[o nieobsługiwanej metodzie](/pl/reference/api-errors#unsupported-method)
opisuje strona [Błędy API](/pl/reference/api-errors).
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`:
```bash theme={null}
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](#log-response). Jego `severity`
pozostaje `warning`. Jego `triage` pokazuje regułę:
```json theme={null}
{
"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`:
```bash theme={null}
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](#issue-response) w wersji 1.
Zarejestrowane `severity` i `status` się nie zmieniają:
```json theme={null}
{
"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](#issue-status-response-examples). 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`:
```json theme={null}
{
"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:
```json theme={null}
{
"error": "",
"code": "validation_failed",
"next": "",
"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](/pl/reference/api-errors).
## 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:
```bash theme={null}
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 --json
```
Dodaj `--pagination cursor`, aby dostać kopertę kursora. CLI żąda wersji 4
odpowiedzi z problemem. Zobacz [Odczytaj następną stronę](/pl/reference/cli#read-the-next-page)
i [Obserwowanie na żywo](/pl/reference/cli#live-watch).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.