Triaż problemów i ich rozwiązywanie w LogBrew

Problem grupuje wystąpienia błędów, które mają wspólny odcisk palca. Zanim zmienisz status, priorytet lub przypisanie, przeczytaj podsumowanie grupy i jedno wystąpienie. Zmiana statusu, priorytetu lub przypisania zapisuje decyzję zespołu. Nie naprawia oprogramowania i nie zmienia zarejestrowanych zdarzeń. Zanim zaczniesz, zainstaluj CLI LogBrew i uruchom logbrew login.

Problemy i wystąpienia

Lista problemów zwraca podsumowanie grupy, a nie pełne zdarzenie. Zanim otworzysz szczegóły, przeczytaj te pola:

Pole	Znaczenie
`title`	Zarejestrowany tytuł błędu.
`severity`	Zarejestrowana ważność.
`triage.effective_severity`	Ważność, której LogBrew używa po zastosowaniu reguł problemów. `severity` zachowuje zarejestrowaną wartość. `triage.rule_applied` ma wartość `true`, gdy zastosowano regułę.
`occurrence_count`	Liczba przechowywanych wystąpień w grupie.
`first_seen_at`	Czas najwcześniejszego przechowywanego wystąpienia.
`last_seen_at`	Czas najnowszego przechowywanego wystąpienia.
`project_id`	Projekt, który zawiera problem.
`service_name`	Usługa najnowszego wystąpienia.
`release`	Wydanie najnowszego wystąpienia.
`environment`	Środowisko najnowszego wystąpienia.
`status`	Stan problemu w procesie obsługi. Zobacz Wartości statusu.
`priority`	Kolejność triażu problemu. Zobacz Priorytet.
`priority_source`	`manual`, gdy priorytet ustawiła osoba. `derived`, gdy priorytet wynika z ważności.
`assignee`	Konto lub zespół odpowiedzialny za następny krok albo `null`. Zobacz Przypisz problemy.

Liczba wystąpień nie jest liczbą użytkowników, których dotyczy problem. Liczby i czasy dotyczą zwróconego zakresu, a nie całej historii błędu. Filtr --since lub --until ogranicza wystąpienia, które LogBrew liczy. Gdy podajesz liczbę, podaj też filtry, które ją dały.

Wartości statusu

Status	Znaczenie
`unresolved`	Problem wymaga decyzji.
`resolved`	Zespół oznaczył problem jako naprawiony. Status nie dowodzi poprawki.
`archived`	Zespół usunął problem z aktywnego triażu.

archived wcześniej nazywał się ignored. Obie nazwy wybierają te same problemy i obie są akceptowane na wejściu. logbrew read, logbrew issues oraz API w wersjach 2 i 3 pokazują archived. API w wersji 1 (domyślnej), strumień obserwowania na żywo i odpowiedź analizy problemu pokazują ignored. Pulpit pokazuje statusy jako „Nierozwiązany”, „Rozwiązany” i „Zarchiwizowany”. Status dotyczy całego problemu, a nie jednego wystąpienia. Ważność pokazuje pilność, a status zapisuje decyzję. Nie mieszaj tych pojęć. Problem critical może mieć status resolved po zweryfikowanej poprawce. Problem archived zachowuje zarejestrowaną ważność. LogBrew nie otwiera ponownie rozwiązanego problemu automatycznie. Gdy po rozwiązaniu pojawi się nowe wystąpienie, analiza zwraca lifecycle.effective_status z wartością regressed. status pozostaje resolved, dopóki ktoś nie otworzy problemu ponownie.

Priorytet

Priorytet ustala kolejność, w jakiej zespół przeprowadza triaż problemów:

Priorytet	Znaczenie
`high`	Zbadaj problem najpierw.
`medium`	Zbadaj problem po problemach `high`.
`low`	Problem może poczekać.

Każdy problem ma priorytet. Jeśli nikt go nie ustawi, wynika on z ważności problemu: error i critical dają high, warning daje medium, a info daje low. Gdy reguła problemów zmienia ważność, priorytet wynika z triage.effective_severity. Wtedy priority_source ma wartość derived. Gdy priorytet ustawi osoba, pozostaje on stały, a priority_source ma wartość manual. Aby wyświetlić problemy do zbadania w pierwszej kolejności:

logbrew read issues --project "<project_id>" --status unresolved \
  --priority high --since 24h --json

Przypisz problemy

Przypisz problem, aby pokazać, kto odpowiada za następny krok. Problem może być przypisany najwyżej do 1 konta albo 1 zespołu.

Sprawdź, kogo można przypisać

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

assignees zawiera każde konto, które może czytać projekt, z polami user_id, name i email. teams zawiera każdy zespół organizacji projektu, z polami team_id, slug i name. Nie można przypisać konta, które nie może czytać projektu, ani zespołu z innej organizacji.

Przypisz problem

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

Aby przypisać problem do siebie, użyj me zamiast ID użytkownika. Aby usunąć przypisanie, użyj logbrew issues unassign "<issue_id>" --json. Dodaj --project, aby zmienić do 100 problemów jednego projektu.

Odczytaj swoje problemy

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

Użyj --assignee my_teams, aby zobaczyć problemy swoich zespołów, --assignee "team:<team_id>" dla jednego zespołu, a --assignee none dla problemów, do których nikt nie jest przypisany.

Aby przypisywać problemy, potrzebujesz uprawnienia do zarządzania problemami w projekcie. To samo uprawnienie pozwala zmieniać status, priorytet, reguły własności oraz reguły problemów i logów. Zespoły tworzą właściciele i administratorzy organizacji. Oni też wybierają członków zespołów. Zespół nie daje swoim członkom dostępu do projektu. Gdy członek traci dostęp do projektu, przypisane do niego problemy nie pokazują przypisania. Gdy ktoś usunie zespół, przypisane do niego problemy też tracą przypisanie. Te problemy pojawiają się w odczytach z --assignee none. Jeśli członek odzyska dostęp, problemy znów go pokazują, chyba że ktoś w międzyczasie zmienił lub usunął przypisanie.

Znajdź właściciela problemu

logbrew issues owners "<issue_id>" --json

Wynik zawiera proponowanych właścicieli, od najlepiej dopasowanego, oraz suggested_assignee. Każdy właściciel ma source:

`source`	Znaczenie
`ownership_rule`	Reguła własności projektu pasuje do problemu. `rule`, `line` i `matched` pokazują regułę i to, do czego pasuje.
`codeowners`	Wiersz pliku CODEOWNERS projektu pasuje do ścieżki ramki stosu.
`recent_activity`	Konto zmieniało problem albo było do niego przypisane.

inputs podaje, ile ścieżek ramek stosu, modułów, szablonów tras, tagów i reguł sprawdził LogBrew. Jeśli lista jest pusta, a inputs nie pokazuje żadnych ścieżek, problem nie ma dowodów do dopasowania. Nie oznacza to, że problem nie ma właściciela. Zapisz reguły własności w pliku tekstowym, po jednej regule w wierszu:

# type:pattern owner...
path:src/payments/** ada@example.com #payments
url:/checkout/* #web
service:billing-api ada@example.com
tags.region:eu-* #europe
module:app.billing.* ada@example.com

Wzorzec path pasuje do końca ścieżki ramki stosu, więc src/payments/** pasuje do ramek w dowolnym katalogu wdrożenia. * pasuje do dowolnego tekstu. Właścicielami są adresy e-mail kont lub #team-slug. Ostatnia pasująca reguła ma pierwszeństwo. Następnie wyślij reguły, plik CODEOWNERS z GitHuba albo jedno i drugie:

logbrew issues ownership set --project "<project_id>" \
  --rules ownership.txt --codeowners .github/CODEOWNERS --json
logbrew issues ownership --project "<project_id>" --json

W CODEOWNERS adres e-mail wskazuje konto, a @org/team-slug wskazuje zespół o tym slugu. Reguły, które wskazują konto bez dostępu do projektu lub nieznany zespół, kończą się błędem 422. Właściciele z CODEOWNERS, którzy nie wskazują nikogo, trafiają do unresolved_owners. Pusty plik czyści zapisany tekst tego rodzaju.

Odczytaj historię problemu

logbrew issues activity "<issue_id>" --json

Historia zawiera każdą zmianę statusu, priorytetu, przypisania i reguły ważności, od najnowszej, razem z kontem, które ją wprowadziło. Ostatni wpis to first_seen. Konto, które straciło dostęp do projektu, zachowuje tylko swoje ID. Aby odczytać więcej, użyj --limit i wartości next_cursor.

Sprawdź skrzynkę odbiorczą

logbrew inbox --json
logbrew inbox read --json

Skrzynka odbiorcza zawiera problemy, które inne osoby przypisały tobie lub twoim zespołom, od najnowszych. unread liczy przypisania od twojego znacznika odczytu. logbrew inbox read przesuwa znacznik odczytu na bieżącą chwilę. LogBrew nie wysyła e-maili o tych przypisaniach. Skrzynka pokazuje tylko projekty, które możesz teraz czytać.

Zalecany proces

Wyświetl nierozwiązane problemy w jednym zakresie

logbrew read issues --project "<project_id>" --environment production \
  --release api@1.2.3 --status unresolved --since 24h --json

Przy kolejnych odczytach list zachowaj te same filtry. Pusty wynik oznacza, że żaden problem nie pasuje do tego zakresu. Nie dowodzi, że projekt nie ma błędów. Skopiuj dokładne ID problemu, a nie tytuł.

Odczytaj szczegóły problemu

logbrew read issue "<issue_id>" --json

Zanim przejdziesz dalej, potwierdź, że zwrócony projekt jest prawidłowy. Odczyty zwracają migawkę. Zanim zmienisz status, odczytaj problem ponownie.

Zbadaj jedno wystąpienie

logbrew investigate issue "<issue_id>" --occurrence recommended --json

Odczyty szczegółów i analizy nie używają filtrów listy. Porównaj subject.project_id, event.occurred_at, wydanie i środowisko ze swoim zakresem. Zalecane wystąpienie może być starsze niż najnowsze. Pełny przegląd dowodów opisuje przewodnik Zbadaj problem.

Korzystaj z dowodów ze śladu tylko wtedy, gdy są dostępne

Odczytaj ślad tylko wtedy, gdy correlations.trace.status ma wartość available. Użyj ID śladu z odpowiedzi. Nigdy go nie wymyślaj.

logbrew read trace "<trace_id>" --project "<project_id>" --json
logbrew read logs --trace "<trace_id>" --project "<project_id>" \
  --since 24h --json

Odczyt śladu nie ma filtra czasu. Jeśli status to not_linked, pracuj dalej na podstawie dowodów z problemu.

Zweryfikuj wdrożenie kandydujące

Jako wystąpienia bazowego użyj zbadanego wystąpienia. ID wdrożenia weź z dowodów wdrożenia lub ze swojego procesu wydawania.

logbrew investigate issue "<issue_id>" verify \
  --baseline-occurrence "<occurrence_id>" \
  --candidate-deployment "<deployment_id>" \
  --json

Brak ponownego wystąpienia w oknie obserwacji nie dowodzi trwałej poprawki. Jeśli status ma wartość insufficient_traffic lub unavailable, pozostaw problem w stanie unresolved. Wykonaj zwrócone następne działanie.

Zmień status, priorytet lub przypisanie

Uruchom jedno polecenie. Te polecenia nie proszą o potwierdzenie, więc najpierw sprawdź ID problemu.

logbrew issues resolve "<issue_id>" --json
logbrew issues archive "<issue_id>" --json
logbrew issues reopen "<issue_id>" --json
logbrew issues priority low "<issue_id>" --json
logbrew issues assign me "<issue_id>" --json

Bez --project każde polecenie przyjmuje 1 ID problemu. Sprawdź kod wyjścia oraz zwrócone status, priority i assignee. Jeśli brakuje wyniku, odczytaj problem ponownie przed następną zmianą.Starsze skrypty mogą używać logbrew set issue "<issue_id>" resolved oraz skrótów resolve, ignore i reopen. ignore ustawia archived.

Zmień wiele problemów naraz

Dodaj --project, aby jednym poleceniem zmienić do 100 problemów jednego projektu:

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

Polecenie stosuje jedną zmianę do każdego problemu. Każde ID problemu może wystąpić tylko raz. CLI odrzuca ponad 100 ID lub powtórzone ID, zanim wyśle żądanie. Wynik ma 1 wpis dla każdego problemu, w kolejności z polecenia:

Wynik	Znaczenie
`updated`	LogBrew zastosował zmianę.
`unchanged`	Problem miał już żądaną wartość.
`not_found`	Projekt nie ma problemu o tym ID. LogBrew nic dla niego nie zmienił.

Każdy wpis ma issue_id, outcome i issue. issue to bieżący stan problemu lub null dla not_found. Po awarii sieci możesz ponownie uruchomić to samo polecenie. Problemy, które już się zmieniły, pokazują unchanged. Aby zmienić ponad 100 problemów, uruchom więcej poleceń. Dla wyniku not_found skopiuj ID ponownie z listy problemów tego projektu. Żądanie API opisuje sekcja Zaktualizuj wiele problemów naraz.

Wybierz następny status

Pozostaw unresolved, gdy błąd nadal występuje lub poprawka nie jest zweryfikowana. Brak śladu nie jest powodem do archiwizacji problemu.
Ustaw resolved, gdy zespół zaakceptuje dowody poprawki. Proponowana poprawka nie jest dowodem.
Ustaw archived dla zaakceptowanego stanu lub sygnału tylko testowego. Decyzja dotyczy każdego wystąpienia problemu. Polecenie nie ma pola na powód, więc zapisz powód w zapisach pracy zespołu.
Otwórz ponownie (unresolved), gdy po rozwiązaniu pojawi się nowe wystąpienie. Wskazuje je lifecycle.regression.first_reappeared_occurrence. Porównaj je z wystąpieniem użytym przy rozwiązaniu. Nie twórz innego problemu.

Przekaż analizę

Przekaż następnej osobie odnośniki, a nie zrzut surowych zdarzeń:

ID problemu, status, priorytet, przypisanie i ważność.
Projekt, usługa, środowisko i wydanie.
Czas pierwszego wystąpienia, czas ostatniego wystąpienia i liczba wystąpień.
ID wybranego wystąpienia i occurrence_selection.reason.
fix.status, cause.status i ich provenance.
Status śladu i ID śladu, jeśli są dostępne.
Status odtworzenia i brakujące dowody.
Wynik weryfikacji wdrożenia kandydującego.
Następne działanie zwrócone w odpowiedzi.

Oznacz proponowane przyczyny i poprawki jako propozycje.

Napraw błędy CLI

Zanim przetworzysz wynik, sprawdź kod wyjścia procesu. Przy powodzeniu JSON trafia na standardowe wyjście. Błąd parsowania kończy się kodem 2. Błąd w trakcie działania kończy się kodem 1. Błędy w formacie JSON trafiają na standardowe wyjście błędów i zawierają ok: false, error, message i next. Pokazuj next jako wskazówkę. Nie uruchamiaj go automatycznie. Na przykład w logbrew issues archive "<issue_id_1>" "<issue_id_2>" --json brakuje --project. Polecenie kończy się kodem 2 przed wysłaniem żądania, z błędem invalid_issue_command. Gdy API odrzuci żądanie, error ma wartość api_error. Status HTTP odczytasz z status, a kod błędu API z api_code.

Wynik	Naprawa
`not_logged_in`	Poproś człowieka o uruchomienie `logbrew login`, a potem ponów odczyt.
`invalid_issue_command`	Popraw polecenie. Użyj `--project` dla więcej niż 1 problemu, podaj najwyżej 100 ID i każde ID tylko raz.
Nieprawidłowe ID problemu	Skopiuj dokładne ID z listy problemów lub z odpowiedzi ze szczegółami.
Nie znaleziono problemu	Sprawdź zalogowane konto i projekt.
Zmiana kończy się błędem z `status` równym `403`	Konto nie może zarządzać problemami w tym projekcie. Poproś o pomoc osobę z dostępem.
`invalid_assignee`	Filtr `--assignee` przyjmuje `me`, `none`, `my_teams`, ID użytkownika lub `team:<team_id>`.
Przypisanie kończy się błędem z `status` równym `422` i `api_code` równym `validation_failed`	Konto nie może czytać projektu albo zespół nie należy do organizacji projektu. Wybierz konto lub zespół z `logbrew issues assignees`.
`invalid_ownership_command`, `invalid_ownership_file`	Popraw polecenie. Plik własności musi być tekstem UTF-8 o rozmiarze najwyżej 128 KiB.
`invalid_inbox_command`	Użyj `logbrew inbox` lub `logbrew inbox read`.
`investigation_response_invalid`	Odpowiedź nie przeszła walidacji CLI. Ponów raz. Jeśli błąd się powtórzy, zaktualizuj CLI lub zgłoś problem. Nie omijaj walidacji.
Status śladu `not_linked`	Pracuj dalej na podstawie dowodów z problemu. Nie odczytuj śladu.
Status śladu `unavailable`	Ponów odczyt analizy później.
Weryfikacja `insufficient_traffic`	Pozostaw problem w stanie `unresolved`. Poczekaj na ruch w wydaniu kandydującym, a potem zweryfikuj ponownie.

Nieudana odpowiedź nie dowodzi, że zmiana statusu, priorytetu lub osoby przypisanej nie przyniosła efektu. Zanim spróbujesz ponownie, odczytaj problem.

Co składa się na przydatny problem

Jasny tytuł i czytelny komunikat.
Stały odcisk palca.
Ramki stosu, jeśli są dostępne.
Kontekst wydania, środowiska i usługi.
Kontekst śladu, jeśli zarejestrowano go razem z wystąpieniem.
Małe, istotne atrybuty, a nie pełne zrzuty danych.

Filtry list i kontrakty odpowiedzi opisuje dokumentacja referencyjna API telemetrii.

Pierwsze kroki

Pojęcia

Instalacja i wysyłanie

Analiza

CLI i agenci

Pomoc

Triaż problemów i ich rozwiązywanie w LogBrew

Problemy i wystąpienia

Wartości statusu

Priorytet

Przypisz problemy

Znajdź właściciela problemu

Odczytaj historię problemu

Sprawdź skrzynkę odbiorczą

Zalecany proces

Zmień wiele problemów naraz

Wybierz następny status

Przekaż analizę

Napraw błędy CLI

Co składa się na przydatny problem

​Problemy i wystąpienia

​Wartości statusu

​Priorytet

​Przypisz problemy

​Znajdź właściciela problemu

​Odczytaj historię problemu

​Sprawdź skrzynkę odbiorczą

​Zalecany proces

​Zmień wiele problemów naraz

​Wybierz następny status

​Przekaż analizę

​Napraw błędy CLI

​Co składa się na przydatny problem

Problemy i wystąpienia

Wartości statusu

Priorytet

Przypisz problemy

Znajdź właściciela problemu

Odczytaj historię problemu

Sprawdź skrzynkę odbiorczą

Zalecany proces

Zmień wiele problemów naraz

Wybierz następny status

Przekaż analizę

Napraw błędy CLI

Co składa się na przydatny problem