Narzędzie wiersza poleceń Logcat

Logcat to narzędzie wiersza poleceń, które zapisuje dziennik komunikatów systemowych, w tym wiadomości napisanych z aplikacji przy użyciu klasy Log.

Ta strona dotyczy narzędzia logcat w wierszu poleceń, ale komunikaty logu możesz też wyświetlić w oknie Logcat w Android Studio. Informacje o wyświetlaniu i filtrowaniu logów z Android Studio znajdziesz w artykule Wyświetlanie i zapisywanie logów w usłudze Logcat.

Omówienie systemu logowania

System logowania w Androidzie to zestaw uporządkowanych buforów kołowych utrzymywanych przez proces systemowy logd. Zbiór dostępnych buforów jest stały i zdefiniowany przez system. Najbardziej odpowiednie bufory to:

  • main: przechowuje większość logów aplikacji.
  • system: zapisuje wiadomości pochodzące z systemu operacyjnego Android.
  • crash: przechowuje dzienniki awarii. Każdy wpis logu ma priorytet, tag określający pochodzenie logu oraz rzeczywisty komunikat logu.

Podstawowym interfejsem C/C++ systemu logowania jest biblioteka współdzielona liblog i jej nagłówek <android/log.h>. Wszystkie obiekty logowania w danym języku (w tym android.util.Log) ostatecznie wywołują funkcję __android_log_write. Domyślnie wywołuje funkcję __android_log_logd_logger, która wysyła wpis logu do logd za pomocą gniazda. Od poziomu interfejsu API 30 funkcję logowania można zmienić, wywołując __android_set_log_writer. Więcej informacji znajdziesz w dokumentacji NDK.

Logi wyświetlane przez adb logcat są poddawane 4 poziomom filtrowania:

Filtrowanie w czasie kompilacji
W zależności od ustawień kompilacji niektóre logi mogą zostać całkowicie usunięte z pliku binarnego. ProGuard można na przykład skonfigurować tak, aby usuwał wywołania Log.d z kodu Java.
Filtrowanie właściwości systemu
liblog wysyła zapytanie do zestawu właściwości systemu, aby określić minimalny poziom ważności, który ma zostać wysłany do instancji logd. Jeśli Twoje logi zawierają tag MyApp, sprawdzane są poniższe właściwości i powinny zawierać pierwszą literę o minimalnej wadze (V, D, I, W, E lub S, aby wyłączyć wszystkie logi):
  • log.tag.MyApp
  • persist.log.tag.MyApp
  • log.tag
  • persist.log.tag
Filtrowanie aplikacji
Jeśli nie ustawisz żadnej właściwości, liblog używa minimalnego priorytetu skonfigurowanego przez __android_log_set_minimum_priority. Ustawienie domyślne to INFO.
Filtrowanie reklam displayowych
adb logcat obsługuje dodatkowe filtry, które mogą zmniejszyć liczbę wyświetlanych logów logd. Więcej informacji znajdziesz w sekcji o filtrowaniu danych wyjściowych logu.

Składnia wiersza poleceń

Ogólnie użycie polecenia logcat za pomocą powłoki adb to: 

[adb] shell logcat [<option>] ... [<filter-spec>] ...

Dostępny jest też skrót typu adb logcat, który rozwija się do adb shell logcat.

Opcje

logcat ma wiele opcji. Dostępne opcje zależą od wersji systemu operacyjnego urządzenia. Aby wyświetlić pomoc dotyczącą logcat dla konkretnego urządzenia, którego używasz, wykonaj: 

    adb logcat --help

Pamiętaj, że logcat to narzędzie przeznaczone zarówno dla deweloperów systemów operacyjnych, jak i deweloperów aplikacji (deweloperzy aplikacji zamiast nich powinni używać Android Studio), dlatego wiele z tych opcji można używać tylko jako root.

Filtruj dane wyjściowe logu

Tag komunikatu logu to krótki ciąg znaków wskazujący komponent systemu, z którego pochodzi komunikat. Na przykład „Widok” w przypadku systemu widoków.

Priorytet może mieć jedną z tych wartości znaków uszeregowanych od najniższego do najwyższego priorytetu:

    • V: szczegółowy (najniższy priorytet)
    • D: debugowanie
    • I: informacje
    • W: ostrzeżenie
    • E: błąd
    • F: krytyczny
    • S: cichy (najwyższy priorytet, w którym nic nie jest drukowane)

    • Aby uzyskać listę tagów używanych w systemie z priorytetami, uruchom polecenie logcat i zwróć uwagę na 2 pierwsze kolumny każdej wiadomości, podane jako <priority>/<tag>.

    Poniżej znajdziesz przykład krótkich danych wyjściowych logcat uzyskanych za pomocą polecenia logcat -v brief output. Dane wyjściowe wskazują, że komunikat odnosi się do poziomu priorytetu „I” i tagu „ActivityManager”: 

    I/ActivityManager(  585): Starting activity: Intent { action=android.intent.action...}

    Aby zmniejszyć ilość danych wyjściowych logu do zarządzania, ogranicz dane wyjściowe za pomocą wyrażeń filtra. Wyrażenia filtra umożliwiają wskazywanie systemowi kombinacji priorytetu tagu, które Cię interesują. System pomija inne wiadomości w określonych tagach.

    Wyrażenie filtra jest zgodne z formatem tag:priority ..., gdzie tag oznacza tag, który interesuje użytkownika, a priority wskazuje minimalny poziom priorytetu tego tagu w raportach. W logu zapisywane są komunikaty dla tego tagu o priorytecie wyższym lub wyższym. Podaj dowolną liczbę specyfikacji tag:priority w jednym wyrażeniu filtra. Seria specyfikacji jest rozdzielana odstępami.

    Poniżej znajdziesz przykład wyrażenia filtra, które pomija wszystkie komunikaty logu oprócz tych z tagiem „ActivityManager” o priorytecie „Info” lub wyższym i tych z tagiem „MojaAplikacja” o priorytecie „Debug” lub wyższym:

    adb logcat ActivityManager:I MyApp:D *:S

    Ostatni element poprzedniego wyrażenia (*:S) ustawia poziom priorytetu wszystkich tagów na „silent”, dzięki czemu wyświetlane są tylko komunikaty z wartościami „ActivityManager” i „MojaAplikacja”. Użycie właściwości *:S gwarantuje, że dane wyjściowe logów będą ograniczone do określonych przez Ciebie filtrów. *:S umożliwia filtrom używanie ich jako listy dozwolonych dla danych wyjściowych logów.

    Uwaga: w niektórych powłokach znak „*” jest zarezerwowany przez powłokę. Jeśli używasz takiej powłoki, ujmij wyrażenie filtra w cudzysłów: adb logcat "ActivityManager:I MyApp:D *:S"

    To wyrażenie filtra wyświetla wszystkie komunikaty logu z priorytetem „warning” (ostrzeżenie) i wyższym we wszystkich tagach:

    adb logcat *:W

    Jeśli używasz logcat na komputerze programistycznym, a nie w zdalnej adb powłoce, możesz też ustawić domyślne wyrażenie filtra, eksportując wartość zmiennej środowiskowej ANDROID_LOG_TAGS:

    export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S"

    Filtr ANDROID_LOG_TAGS nie jest eksportowany do emulatora/instancji urządzenia, jeśli używasz narzędzia logcat ze zdalnej powłoki lub z użyciem adb shell logcat.

    Format wyjściowy logu kontrolnego

    Komunikaty logu oprócz tagu i priorytetu zawierają różne pola metadanych. Możesz zmienić format wyjściowy wiadomości, aby wyświetlały określone pole metadanych. Aby to zrobić, użyj opcji -v i określ jeden z tych obsługiwanych formatów wyjściowych:

    • brief: wyświetla priorytet, tag i identyfikator PID procesu wysyłania wiadomości.
    • long: wyświetla wszystkie pola metadanych i rozdziela wiadomości pustymi wierszami.
    • process: wyświetla tylko PID.
    • raw: wyświetla nieprzetworzony komunikat logu bez innych pól metadanych.
    • tag: wyświetla tylko priorytet i tag.
    • thread: Starszy format, który pokazuje priorytet, PID i TID wątku, z którego pochodzi wiadomość.
    • threadtime (domyślnie): wyświetla datę, czas wywołania, priorytet, tag, identyfikator PID i TID wątku wysyłającego wiadomość.
    • time: wyświetla datę, czas wywołania, priorytet, tag i identyfikator PID procesu wysyłania wiadomości.

    Uruchamiając logcat, określ format wyjściowy za pomocą opcji -v:

    [adb] logcat [-v <format>]

    Oto przykład, który pokazuje, jak generować wiadomości w formacie wyjściowym thread:

    adb logcat -v thread

    Za pomocą opcji -v możesz określić tylko 1 format wyjściowy. Możesz jednak określić dowolną liczbę modyfikatorów, o ile mają sens. logcat ignoruje modyfikatory, które nie mają sensu.

    Modyfikatory formatu

    Modyfikatory formatu zmieniają dane wyjściowe funkcji logcat. Aby określić modyfikator formatu, użyj opcji -v w ten sposób: 

    adb logcat -b all -v color -d

    Z każdą wiadomością z dziennika Androida powiązany jest tag i priorytet. Możesz połączyć dowolny modyfikator formatu z jedną z tych opcji formatowania:

    • brief
    • long
    • process
    • raw
    • tag
    • thread
    • threadtime
    • time

    Aby sformatować następujące szczegóły modyfikatora, wpisz logcat -v --help w wierszu poleceń:

    • color: każdy poziom priorytetu ma inny kolor.
    • descriptive: pokazuje opisy zdarzeń bufora dziennika. Ten modyfikator wpływa tylko na komunikaty bufora dziennika zdarzeń i nie ma wpływu na inne niebinarne bufory. Opisy zdarzeń pochodzą z bazy danych tagów logów zdarzeń.
    • epoch: wyświetla czas w sekundach od 1 stycznia 1970 r.
    • monotonic: wyświetla czas w sekundach procesora od ostatniego uruchomienia.
    • printable: dba o zmianę znaczenia wszystkich treści w logach binarnych.
    • uid: jeśli kontrola dostępu zezwala na to, wyświetla identyfikator UID lub identyfikator Androida zalogowanego procesu.
    • usec: wyświetla godzinę z dokładnością w mikrosekundach.
    • UTC: wyświetla godzinę w formacie UTC.
    • year: dodaje rok do wyświetlanego czasu.
    • zone: dodaje lokalną strefę czasową do wyświetlanego czasu.

    Wyświetl alternatywne bufory logów

    System logowania w Androidzie przechowuje wiele okrągłych buforów komunikatów logu i nie wszystkie komunikaty są wysyłane do domyślnego okrągłego bufora. Aby wyświetlić dodatkowe komunikaty logu, uruchom polecenie logcat z opcją -b, aby zażądać wyświetlenia alternatywnego bufora kołowego. Możesz wyświetlić te alternatywne bufory:

    • radio: wyświetla bufor zawierający wiadomości związane z łącznością radiową lub telefoniczną.
    • events: wyświetla zinterpretowane komunikaty bufora zdarzeń systemu binarnego.
    • main: wyświetla główny bufor dziennika (domyślnie), który nie zawiera komunikatów systemowych i dzienników awarii.
    • system: wyświetla bufor dziennika systemowego (domyślnie).
    • crash: wyświetla bufor dziennika awarii (domyślnie).
    • all: wyświetla wszystkie bufory.
    • default: raportuje main, system i crash buforów.

    Użycie opcji -b:

    [adb] logcat [-b <buffer>]

    Oto przykład, jak wyświetlić bufor dziennika zawierający wiadomości z radiem i telefonami: 

    adb logcat -b radio

    Aby określić wiele flag -b dla wszystkich buforów, które chcesz wydrukować, wpisz: 

    logcat -b main -b radio -b events

    Określ pojedynczą flagę -b z listą buforów rozdzielonych przecinkami, na przykład: 

    logcat -b main,radio,events

    Zapisz z kodu

    Klasa Log umożliwia tworzenie w kodzie wpisów logu, które są wyświetlane w narzędziu logcat. Typowe metody logowania to:

    Na przykład użycie tego wywołania:

    Kotlin

    Log.i("MyActivity", "MyClass.getView() — get item number $position")

    Java

    Log.i("MyActivity", "MyClass.getView() — get item number " + position);

    logcat zwraca wynik podobny do tego:

    I/MyActivity( 1557): MyClass.getView() — get item number 1