Dokumentacja referencyjna CLI LogBrew: polecenia i filtry

CLI LogBrew o otwartym kodzie źródłowym odczytuje telemetrię i zarządza danymi konta z terminala. Zacznij od przewodnika po CLI, który opisuje instalację, logowanie i typowe zadania.

Jak działa CLI

W terminalu używaj czytelnego tekstu. W skryptach i agentach kodujących używaj --json. Odczyty danych konta wymagają zalogowania. Zanim zaczniesz logowanie, uruchom logbrew status --json. Autoryzację w przeglądarce musi dokończyć człowiek. Klucze wysyłania projektu wysyłają telemetrię. Nie zastąpią logowania na konto. Tworzenie projektów i kluczy, zmiany statusu, priorytetu i przypisania do problemu, wdrożenia oraz aktualizacje zgłoszeń do pomocy technicznej zmieniają dane konta. Zanim uruchomisz takie polecenie, upewnij się, że operacja i jej cel są właściwe. Uruchom logbrew --help, aby zobaczyć wszystkie polecenia. Dodaj --help do polecenia, na przykład logbrew read logs --help, aby zobaczyć jego flagi. Uruchom logbrew help json, aby poznać reguły JSON.

Grupa poleceń	Przeznaczenie
`login`, `whoami`, `me`, `logout`	Rozpocznij logowanie, odczytaj tożsamość konta lub zamknij lokalną sesję.
`status`, `health`, `doctor`, `version`, `examples`	Odczytaj dostęp, gotowość projektu, wersję CLI lub przykłady na start.
`setup`	Odczytaj lokalne manifesty i wypisz plan konfiguracji SDK. Nie zmienia plików i nie uruchamia polecenia instalacji.
`projects`	Odczytaj katalog aktywnych projektów.
`projects repositories`	Odczytaj połączone repozytoria lub wykryj komponenty w jednym repozytorium.
`projects create`, `projects keys create`	Utwórz projekt albo utwórz klucz wysyłania dla istniejącego projektu.
`projects setup`	Zapisz zaobserwowaną konfigurację istniejącego projektu.
`projects archive`, `projects delete`	Zarchiwizuj projekt albo usuń go trwale po potwierdzeniu.
`usage`, `account usage`	Odczytaj wykorzystanie, limity, stan limitu i daty resetu.
`mcp grants`, `mcp revoke`	Wyświetl według nazwy klientów MCP połączonych z kontem albo unieważnij jedno połączenie.
`read`	Odczytaj logi, problemy, akcje, wydania, metryki, ślady lub jeden element.
`explain`	Odczytaj ograniczony zestaw dowodów dla problemu, logu, akcji, śladu, spanu, metryki lub wydania.
`investigate issue`	Odczytaj dowody z analizy problemu albo zweryfikuj wdrożenie kandydujące.
`issues archive`, `issues resolve`, `issues reopen`	Ustaw status 1 problemu lub do 100 problemów w jednym projekcie.
`issues priority`	Ustaw priorytet 1 problemu lub do 100 problemów w jednym projekcie.
`issues assign`, `issues unassign`	Ustaw lub usuń przypisanie 1 problemu lub do 100 problemów w jednym projekcie. Problem można przypisać do konta albo zespołu.
`issues assignees`	Wyświetl konta i zespoły, którym można przypisywać problemy w jednym projekcie.
`issues owners`	Wyświetl proponowanych właścicieli 1 problemu.
`issues ownership`	Odczytaj lub ustaw reguły własności i plik CODEOWNERS jednego projektu.
`issues activity`	Odczytaj historię zmian 1 problemu.
`issues rule`, `logs rule`	Ustaw regułę ważności 1 problemu lub 1 sygnatury logu.
`inbox`	Odczytaj problemy, które inni przypisali tobie lub twoim zespołom, albo oznacz je jako przeczytane.
`set issue`, `resolve`, `close`, `ignore`, `reopen`	Ustaw status 1 problemu. `close` oznacza `resolved`. `ignore` i `ignored` oznaczają `archived`.
`deploy`	Zapisz jedno zakończone wdrożenie.
`debug-artifacts`	Prześlij natywne pliki debugowania Apple lub Android albo wyszukaj tożsamość jednego obrazu.
`analytics`	Odczytaj przegląd, właściwości, porównania, ścieżki, lejki, utrzymanie lub cykl życia.
`support`	Twórz, odczytuj, zamykaj i ponownie otwieraj zgłoszenia do pomocy technicznej oraz na nie odpowiadaj.
`watch`	Odbieraj na żywo logi, problemy lub akcje.

Odczytaj raport diagnostyki projektu

Użyj ID projektu z logbrew projects --json:

logbrew doctor --project "<project_id>" --json

Polecenie odczytuje stan projektu i jeden niedawny log. Nie tworzy projektu, nie zmienia klucza i nie zapisuje konfiguracji. Raport ma status, checks i next. Każde sprawdzenie ma check, status i next. Sprawdzenia to api, auth, project, ingest_key, setup, telemetry i logs. Kod wyjścia 0 oznacza, że CLI zapisał raport. Nie oznacza, że projekt jest gotowy. Odczytaj status raportu i każde sprawdzenie. Sprawdzenie not_checked nie zostało zaliczone.

`status` raportu	Znaczenie i następny krok
`auth_invalid`	Brak dostępu do konta albo jest on nieprawidłowy. Człowiek uruchamia `logbrew login`.
`project_missing`	To konto nie ma dostępu do projektu. Użyj ID z `logbrew projects --json`.
`api_unreachable`	Żądanie API się nie zakończyło. Sprawdź połączenie sieciowe, a potem uruchom polecenie ponownie.
`check_failed`	Żądanie się nie powiodło albo jego odpowiedź była nieprawidłowa. Uruchom polecenie ponownie bez zmian. Jeśli znowu się nie powiedzie, zgłoś problem.
`needs_ingest_key`	Projekt nie ma aktywnego klucza wysyłania. Utwórz klucz tylko wtedy, gdy masz uprawnienie do zmiany projektu.
`needs_setup`	Potrzebna jest konfiguracja SDK. Postępuj według szybkiego startu.
`needs_telemetry`	Konfiguracja się zaczęła, ale LogBrew nie ma telemetrii dla projektu. Wyślij zdarzenie testowe.
`ready`	Projekt ma aktywny klucz i telemetrię. Odczytaj sygnał potrzebny do zadania.

Gdy odczyt projektu się powiedzie, sprawdzenie logs ma wartość visible, empty, unavailable, error lub invalid_response. To sprawdzenie nie zmienia status raportu. Pusty wynik logów nic nie mówi o innych sygnałach. Nieudany odczyt to nie to samo co pusty wynik. Traktuj next jako wskazówkę naprawy. Nie daje uprawnienia do zmiany stanu konta ani projektu.

Przykład: brak dostępu do konta

Bez poświadczeń konta polecenie nie wysyła żądania API. Zapisuje ten raport na standardowe wyjście i kończy działanie z kodem 0:

{
  "checks": [
    { "check": "api", "next": "run the API reachability check first", "status": "not_checked" },
    { "check": "auth", "next": "run logbrew login", "status": "missing" },
    { "check": "project", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "ingest_key", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "setup", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "telemetry", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "logs", "next": "resolve the prior check first", "status": "not_checked" }
  ],
  "next": "run logbrew login",
  "status": "auth_invalid"
}

Ten raport różni się od diagnozy projektu w API. Nie zawiera pól API state, setup_status ani next_action.

Filtry

Filtr	Polecenia
`--project <project_id>`	logs, issues, actions, releases, metrics, traces, trace
`--release <release>`	logs, issues, actions, releases, metrics, traces, trace
`--environment <environment>`	logs, issues, actions, releases, metrics, traces, trace
`--service <service_name>`	logs, issues, actions, releases, metrics, traces
`--since 24h`	logs, issues, actions, releases, metrics, traces, analytics
`--until <RFC3339>`	logs, issues, actions, releases, metrics, traces, analytics
`--limit 100`	logs, issues, actions, releases, metrics, traces
`--severity error`	logs, watch
`--search checkout`	logs
`--trace <trace_id>`	logs
`--status unresolved`	issues (`unresolved`, `resolved`, `archived`)
`--priority high`	issues (`high`, `medium`, `low`)
`--assignee me`	issues (`me`, `none`, `my_teams`, ID użytkownika lub `team:<team_id>`)
`--status error`	traces (`error`, `ok`)
`--min-duration-ms <milliseconds>`	traces
`--name <name>`	actions, metrics
`--user <distinct_id>`	actions

--since przyjmuje czas trwania, taki jak 24h lub 7d, albo znacznik czasu RFC 3339. --until przyjmuje znacznik czasu RFC 3339. To czas końca, który nie należy do zakresu, i musi być późniejszy niż --since. Odczyt jednego problemu po ID nie przyjmuje --until. Ważność logu to info, warning, error lub critical. Status problemu to stan problemu w procesie pracy, a nie jego ważność. --status ignored to starsza nazwa --status archived. --status open oznacza unresolved, a --status closed oznacza resolved. --assignee none wybiera problemy bez przypisania, a --assignee my_teams wybiera problemy twoich zespołów. Każda inna wartość --assignee kończy się błędem invalid_assignee. CLI przyjmuje też te aliasy: --project-id, --env, --service-name, --trace-id, --distinct-id oraz --level zamiast --severity. W nowych skryptach używaj nazw z tabeli. To polecenie odczytuje błędy z 1 dnia:

logbrew read logs --severity error \
  --since 2026-10-01T00:00:00Z --until 2026-10-02T00:00:00Z --json

ID projektu wybiera projekt. Nazwa usługi wybiera komponent w tym projekcie. Wartości ze spacjami ujmij w cudzysłów:

logbrew read logs --project "<project_id>" \
  --service checkout-api --since 24h \
  --severity error --search "checkout failed" --json

Jeśli szukany tekst zaczyna się od łącznika, umieść przed nim --:

logbrew logs --json -- --timeout

Wybierz wystąpienie problemu

Problem grupuje pasujące wystąpienia. Odczytaj problem, aby poznać jego status, liczbę wystąpień oraz czas pierwszego i ostatniego wystąpienia:

logbrew read issue "<issue_id>" --json

Dowody z jednego wystąpienia odczytasz przez explain issue lub investigate issue. Bez --occurrence LogBrew wybiera zalecane wystąpienie. Nie zawsze jest to najnowsze zdarzenie. Aby odczytać najnowsze zdarzenie:

logbrew explain issue "<issue_id>" --occurrence latest --json

--occurrence przyjmuje też recommended, first albo ID wystąpienia zwrócone przez LogBrew. Te polecenia odrzucają filtry projektu, wydania, środowiska i czasu. Zanim porównasz dowody, odczytaj znacznik czasu wybranego wystąpienia. Pola dowodów opisuje strona Zbadaj problem.

Zmień status i priorytet problemu

Aby zmienić 1 problem, użyj 1 ID problemu:

logbrew issues archive "<issue_id>" --json
logbrew issues priority high "<issue_id>" --json

archive ustawia archived, resolve ustawia resolved, a reopen ustawia unresolved. Priorytet ma wartość high, medium lub low. Priorytet ustawiony ręcznie się nie zmienia. W przeciwnym razie priorytet wynika z ważności problemu. Aby zmienić więcej niż 1 problem, dodaj --project. Wszystkie problemy muszą należeć do tego projektu. Jedno polecenie zmienia do 100 problemów:

logbrew issues resolve "<issue_id_1>" "<issue_id_2>" \
  --project "<project_id>" --json

Wynik ma 1 wpis dla każdego problemu. Każdy wpis ma wartość updated, unchanged lub not_found. Problem unchanged miał już żądaną wartość. Po błędzie sieci możesz uruchomić to samo polecenie ponownie. Te polecenia nie proszą o potwierdzenie. Najpierw sprawdź ID problemów. Odczyty i zmiany problemów pokazują archived zamiast ignored oraz priority, priority_source i assignee każdego problemu. Zobacz odpowiedź problemu.

Przypisz problemy

Problem może być przypisany najwyżej do 1 konta albo 1 zespołu. Wyświetl konta i zespoły, którym możesz przypisywać problemy w projekcie:

logbrew issues assignees --project "<project_id>" --json

Przypisz 1 problem do konta, do siebie przez me albo do zespołu:

logbrew issues assign "<user_id>" "<issue_id>" --json
logbrew issues assign me "<issue_id>" --json
logbrew issues assign "team:<team_id>" "<issue_id>" --json

Usuń przypisanie:

logbrew issues unassign "<issue_id>" --json

Dodaj --project, aby zmienić do 100 problemów z tego projektu, tak jak przy statusie i priorytecie. Konto musi mieć dostęp do odczytu projektu, a zespół musi należeć do organizacji projektu. Aby znaleźć problemy przypisane do ciebie lub twoich zespołów:

logbrew read issues --project "<project_id>" --assignee my_teams \
  --status unresolved --json

Wyjście tekstowe pokazuje nazwę przypisanego konta albo team #<slug> dla zespołu. Jeśli konto nie ma nazwy, pokazuje adres e-mail, a w dalszej kolejności ID użytkownika. Problem bez przypisania pokazuje unassigned.

Właściciele, historia i skrzynka odbiorcza

logbrew issues owners "<issue_id>" --json
logbrew issues ownership --project "<project_id>" --json
logbrew issues ownership set --project "<project_id>" \
  --rules ownership.txt --codeowners .github/CODEOWNERS --json
logbrew issues activity "<issue_id>" --limit 50 --json
logbrew inbox --json
logbrew inbox read --json

issues owners wyświetla proponowanych właścicieli i dowody, które sprawdził. issues ownership set wysyła lokalne pliki o rozmiarze najwyżej 128 KiB każdy. Pusty plik czyści zapisany tekst tego rodzaju. issues activity i inbox przyjmują --limit od 1 do 200 oraz --cursor-time z --cursor-id z next_cursor. Zobacz Znajdź właściciela problemu.

Ustaw reguły ważności

logbrew issues rule "<issue_id>" warning --json
logbrew logs rule "<log_id>" info --ignore --json

Ważność to info, warning, error, critical lub source. source przywraca zarejestrowaną ważność. --ignore ukrywa pasujące logi na domyślnej liście logów. Bez --ignore reguła je pokazuje.

Odczytaj następną stronę

Logi, problemy, akcje, metryki i ślady obsługują paginację kursorową. Wydania nie. Dla pierwszej strony użyj --pagination cursor:

logbrew read logs --project "<project_id>" --since 24h \
  --pagination cursor --limit 100 --json

Odpowiedź ma logs i next_cursor. Jeśli next_cursor nie jest pusty, zawiera time i id. Wyślij je przez --cursor-time i --cursor-id:

logbrew read logs --project "<project_id>" --since 24h \
  --pagination cursor --limit 100 \
  --cursor-time "<returned_time>" \
  --cursor-id "<returned_id>" --json

Na każdej stronie zachowaj te same filtry i limit. Zakończ, gdy next_cursor ma wartość null. O tym, czy są kolejne strony, decyduj na podstawie kursora, a nie liczby wierszy. Ostatnia strona może być pusta:

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

Problemy, akcje i metryki mają tę samą strukturę odpowiedzi, z issues, actions lub metrics zamiast logs.

Obserwowanie na żywo

logbrew watch --json przesyła strumieniowo na żywo logi, problemy i akcje. Dodaj logs, issues lub actions, aby odbierać tylko jeden rodzaj. tail, follow i stream to aliasy watch. Obserwowanie na żywo nie obsługuje śladów ani spanów. Obserwowanie na żywo wymaga --json. Bez tej flagi polecenie wypisuje watch streams JSON for agents i kończy działanie z kodem 1. W obserwowaniu na żywo zdarzenia problemów pokazują zarchiwizowany problem jako ignored, bez priorytetu. Odczytaj problem, aby poznać jego bieżący status i priorytet. Obserwowanie na żywo przyjmuje tylko --severity, na przykład --severity error,critical. logbrew watch actions nie przyjmuje --severity. CLI stosuje ten filtr po otrzymaniu zdarzeń. Nie zmniejsza tego, co wysyła serwer. Obserwowanie na żywo nie ma filtra projektu, wydania, środowiska ani czasu. Do takich filtrów użyj polecenia read. Po chwilowym rozłączeniu CLI czeka, a potem łączy się ponownie.

Odczytaj wyniki i błędy

Umieść --json przed poleceniem lub po nim. Zanim użyjesz wyjścia, odczytaj kod wyjścia. Nie parsuj wyjścia przeznaczonego dla ludzi. Może się zmieniać między wersjami.

Kod wyjścia	Znaczenie
`0`	Sukces. JSON jest na standardowym wyjściu.
`1`	Polecenie nie powiodło się w trakcie działania, na przykład z powodu błędu API lub sieci.
`2`	CLI odrzucił polecenie przed jego uruchomieniem.

Wyjście przy sukcesie zachowuje strukturę odpowiedzi API. Może to być tablica albo obiekt. Bez paginacji kursorowej odczyt logów zwraca tablicę. Pusta tablica oznacza, że żaden log nie pasuje. To nie jest błąd. Błędy trafiają na standardowe wyjście błędów. Wyjątkiem jest debug-artifacts --json, które zapisuje błędy na standardowe wyjście. Błąd JSON ma ok, error, message i next. Traktuj error jako stały kod niepowodzenia. Zanim uruchomisz polecenie sugerowane w next, sprawdź je. Na przykład logbrew watch traces --json kończy działanie z kodem 2 i wypisuje:

{
  "ok": false,
  "error": "unknown_resource",
  "message": "unknown resource: traces",
  "next": "use logbrew traces for recent traces, or logbrew trace <trace_id> for one trace"
}

logbrew read logs --limit 0 --json kończy działanie z kodem 2 i wypisuje:

{
  "ok": false,
  "error": "invalid_limit",
  "message": "invalid limit: 0",
  "next": "use --limit with a positive whole number"
}

Popraw wartość i uruchom polecenie ponownie. Odrzucone polecenie to nie pusty wynik. Błędy HTTP opisuje strona Błędy API, a bezpośrednie żądania API – dokumentacja referencyjna API telemetrii.

​Jak działa CLI

​Odczytaj raport diagnostyki projektu

​Przykład: brak dostępu do konta

​Filtry

​Wybierz wystąpienie problemu

​Zmień status i priorytet problemu

​Przypisz problemy

​Właściciele, historia i skrzynka odbiorcza

​Ustaw reguły ważności

​Odczytaj następną stronę

​Obserwowanie na żywo

​Odczytaj wyniki i błędy