Raporty o błędach

Na blogu, który czasami czytam, pojawił się krótki artykuł, w którym autor narzekał na „raporty o błędach”, mówiąc o tym, że użytkownicy przekazują zdania typu „zepsuło się”, a to przecież nie wystarczy. Przez lata pisałem artykuły do magazynów i książek o tworzeniu raportów o błędach, ale najwyraźniej co jakiś czas potrzebne jest przypomnienie. Dodatkowo, kontenery, maszyny wirtualne i współczesne procesory jeszcze bardziej wszystko komplikują.

Definiujemy problem

Najpierw spróbujmy określić, czy ten konkretny problem jest rzeczywistym błędem, czy może nie wiemy co zrobić, aby osiągnąć swój cel. W tym drugim przypadku sprawdźmy, czy istnieje dokumentacja. Wiele dużych aplikacji (systemy przetwarzania tekstu, różnego rodzaju projekty) posiada rozległą dokumentację online, dostępną w menu Pomoc.

Po przejrzeniu dokumentacji możemy poszukać w Internecie, czy ktoś inny miał podobny problem. Kilka dobrych zapytań w ulubionej przeglądarce pomoże nam odnaleźć użytkowników z tym samym problemem, a może nawet z jego rozwiązaniem. Jeśli w dalszym ciągu wydaje się, że ludzie nie rozumieją dokumentacji, to samo w sobie jest to problemem i powinno być zgłoszone. W końcu taka sytuacja rodzi frustrację, więc jest to błąd. W każdym razie teraz już trochę lepiej rozumiemy nasz problem.

Na tym etapie zrobiliśmy już wszystko, co możemy, przed przyjęciem założenia, że problem rzeczywiście ukryty jest w kodzie programu lub w systemie. Teraz musimy go opisać komuś, kto go będzie rozwiązywał.

Dostarczamy informacji

Zacznijmy zbierać informacje na temat problemu. Jaka jest wersja i wydanie naszego programu? Zwykle znajdziemy te informacje w menu lub opcji Pomoc (Help). Nie poprzestawajmy jedynie na danych z aplikacji, ale dodajmy też informacje o systemie operacyjnym, na którym ona działa.

Powinniśmy uwzględnić nazwę dystrybucji (Ubuntu, Mint, Red Hat), wersję i wydanie (lub rewizję) systemu operacyjnego. Dodać też musimy numer wersji i wydania jądra, gdyż prawdopodobnie będą się różnić. Informacje o jądrze z łatwością uzyskamy, wydając polecenie uname -a, na przykład:

$ uname -a:

Linux shaman 5.4.0-80-generic #90~18.04.1-Ubuntu SMP Tue

Jul 13 19:40:02 UTC 2021 x86_64 x86_64 x86_64 GNU/Linux

Poszukiwana przez nas informacja na temat jądra znajduje się po nazwie urządzenia, w tym przypadku po „shaman”.

W jakiej architekturze jest nasz system? Czy to Intel, AMD, ARM czy RISC-V? Jak wiele rdzeni posiada procesor lub już bardziej konkretnie, jaki to numer modelu?

Jak dużo pamięci ma nasze urządzenie?

Czy system operacyjny działa na maszynie wirtualnej (VM)? Jaka jest wersja VM i jakie są jej ustawienia?

Czy uruchamiamy aplikację w kontenerze? Musimy podać tak wiele informacji o danym kontenerze, jak to możliwe.

Spróbujmy uprościć nasze środowisko tak bardzo, jak tylko się da. Zobaczmy, czy problem w dalszym ciągu się pojawia, kiedy pracujemy bezpośrednio na dystrybucji, a dystrybucja działa na fizycznym urządzeniu.

Aby wszystko to ułatwić, wiele systemów posiada polecenie, który podaje nam wszystkie potrzebne informacje za jednym kliknięciem. Wszystko, co musimy zrobić, to skopiować te informacje lub przenieść je od razu do pliku.

Jeśli nasza aplikacja korzysta z przeglądarki, podajmy nazwę przeglądarki oraz wersję.

Zgłaszamy fakty

Teraz powinniśmy jasno opisać, co jest nie tak. Musimy być maksymalnie precyzyjni. Nie piszemy „zepsuło się”. Co „zepsuło”? Co program zrobił lub czego nie zrobił? Jeśli to możliwe, zróbmy zrzut ekranu. Dodajmy też przykład danych wejściowych i wyjściowych.

Jeśli system przestał działać, nie piszmy tylko „nie działa”. Może chodzić o przeglądarkę, serwer X lub system operacyjny. Bądźmy konkretni: „Wydaje się, że przestał działać serwer X. Na kilka sekund ekran stał się czarny, ale szybko został przywrócony”. Albo może: „Ekran stał się czarny, a system operacyjny zrestartował się”.

Jeśli system „zawiesił się”, opiszmy, co jeszcze się zdarzyło. Czy tylko jedno okno nie odpowiada, czy może wszystkie? Czy cokolwiek reaguje lub porusza się?

Demostracja problemu

Jeśli jesteśmy programistami, możemy napisać mały program, który uwidoczni problem, a który możemy przekazać deweloperowi systemu lub biblioteki. Jeśli ten mały program nie będzie w stanie odtworzyć problemu z dużego programu, to może coś innego jest przyczyną.

Jeśli jednak doświadczamy tego samego błędu, również dodajmy nazwę i wersję kompilatora, z którego korzystamy, oraz opcje wykorzystywane przy kompilacji.

Dostarczenie tak wielu informacji, jak tylko się da, przy pierwszym naszym raporcie może skłonić programistę do naprawy błędu, z jakim my się borykamy, a nie innego.

Jon „maddog” Hall jest autorem, wykładowcą, informatykiem i jednym z pionierów Wolnego Oprogramowania. Od 1994 roku, kiedy po raz pierwszy spotkał Linusa Torvaldsa i ułatwił przeniesienie jądra na systemy 64-bitowe, pozostaje orędownikiem Linuksa. Obecnie jest prezesem Linux International®.