Rejestrowanie dzienników za pomocą poleceń adb

Ślady Winscope możesz zbierać za pomocą wiersza poleceń adb w kompilacjach do debugowania (czyli userdebug i eng). Przed zebraniem śladów Winscope za pomocą adb uruchom adb root.

adb

Począwszy od Androida 15, ślady Winscope są zintegrowane z Perfetto i zbierane za pomocą wiersza poleceń Perfetto. Każdy ślad Winscope jest źródłem danych Perfetto z własną konfiguracją. Konfiguracje możesz włączać pojedynczo lub w ramach jednej sesji śledzenia.

W Androidzie 14 i starszych wersjach każdy ślad Winscope ma inne polecenie i możesz je zbierać niezależnie. Więcej informacji znajdziesz w sekcji Rejestrowanie śladów w Androidzie 14 i starszych wersjach.

WindowManager

W przypadku tego typu śladu użyj nazwy źródła danych android.windowmanager.

Opcje konfiguracji

  • Poziom rejestrowania (log_level): określa szczegółowość logów. Obsługiwane wartości:

    • LOG_LEVEL_VERBOSE: rejestruje wszystkie elementy z maksymalną ilością informacji.
    • LOG_LEVEL_DEBUG: rejestruje wszystkie elementy, ale nie zapisuje wszystkich danych konfiguracyjnych.
    • LOG_LEVEL_CRITICAL: rejestruje tylko widoczne elementy z minimalnym obciążeniem wydajności.

  • Częstotliwość rejestrowania (log_frequency): określa częstotliwość rejestrowania elementów:

    • LOG_FREQUENCY_FRAME: śledzi zrzuty stanu po zatwierdzeniu ramki.
    • LOG_FREQUENCY_TRANSACTION: logi czasu rejestrują zrzuty stanu za każdym razem, gdy transakcja jest zatwierdzana.
    • LOG_FREQUENCY_SINGLE_DUMP: śledzi pojedyncze zrzuty stanu po uruchomieniu źródła danych.

Szczegółowe informacje o wartościach konfiguracji znajdziesz w sekcji WindowManager.

Przykład

Poniższy przykład pokazuje typ śladu usługi WindowManager w adb:

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.windowmanager"
           windowmanager_config: {
              log_level: LOG_LEVEL_VERBOSE
              log_frequency: LOG_FREQUENCY_TRANSACTION
           }
       }
   }
EOF

ProtoLog

W przypadku tego typu śladu użyj nazwy źródła danych android.protolog.

Opcje konfiguracji

Tryb śledzenia (tracing_mode): określa konfigurację logów, która ma być używana:

  • DEFAULT: śledzi tylko grupy i poziomy logów określone w group_overrides.
  • ENABLE_ALL: śledzi wszystkie grupy i poziomy logów, chyba że określono je w group_overrides.

Minimalny poziom logowania (default_log_from_level): jeśli ta opcja jest ustawiona, śledzone są wszystkie wiadomości o poziomie rejestrowania wyższym lub równym temu poziomowi, chyba że określono zastąpienie na poziomie grupy. Na przykład służy to do włączania rejestrowania wszystkich ostrzeżeń i błędów bez konieczności włączania wszystkich logów. Obsługiwane wartości to:

  • PROTOLOG_LEVEL_DEBUG
  • PROTOLOG_LEVEL_VERBOSE
  • PROTOLOG_LEVEL_INFO
  • PROTOLOG_LEVEL_WARN
  • PROTOLOG_LEVEL_ERROR
  • PROTOLOG_LEVEL_WTF

Zastąpienia grup (group_overrides): umożliwia ręczną konfigurację poziomu logowania dla każdej grupy ProtoLog. Każda grupa zawiera:

  • name: nazwa grupy ProtoLog używana w kodzie źródłowym Androida.
  • log_from: taka sama jak default_log_from_level, ale określona tylko dla bieżącej grupy.

  • collect_stacktrace: gdy ta wartość jest ustawiona na true, zbiera zrzut stosu dla każdej wiadomości ProtoLog w śledzonej grupie.

Przykład

Poniższy przykład pokazuje typ śladu ProtoLog w adb:

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.protolog"
           protolog_config: {
              tracing_mode: DEFAULT
              default_log_from_level: PROTOLOG_LEVEL_WARN
              group_overrides: {
                 group_name: "WM_SHELL_STARTING_WINDOW"
                 log_from: PROTOLOG_LEVEL_DEBUG
                 collect_stacktrace: true
              }
           }
       }
   }
EOF

Dane wejściowe

W przypadku tego typu śladu użyj nazwy źródła danych android.input.inputevent.

Opcje konfiguracji

Tryb śledzenia (trace_mode): określa, czy śledzenie danych wejściowych ma być uruchamiane przy użyciu reguł chroniących prywatność, czy też ma rejestrować wszystkie zdarzenia wejściowe:

  • TRACE_MODE_TRACE_ALL: rejestruje wszystkie zdarzenia wejściowe przetwarzane przez system, niezależnie od kontekstu, w którym zostały przetworzone.
  • TRACE_MODE_USE_RULES: używa reguł śledzenia zdefiniowanych w tej konfiguracji, aby określić, które zdarzenia mają być śledzone. Więcej informacji o określaniu reguł śledzenia znajdziesz w android_input_event_config.proto.

Przykład

Poniżej znajdziesz przykład typu śledzenia danych wejściowych w adb:

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.input.inputevent"
           android_input_event_config: {
              mode: TRACE_MODE_TRACE_ALL
           }
       }
   }
EOF

SurfaceFlinger (warstwy)

W przypadku tego typu śladu użyj nazwy źródła danych android.surfaceflinger.layers.

Opcje konfiguracji

Tryb śledzenia (mode): określa częstotliwość rejestrowania elementów:

  • MODE_ACTIVE: śledzi zrzuty warstw. Za każdym razem, gdy następuje zmiana warstw, jest robiona migawka.
  • MODE_GENERATED: generuje zrzuty warstw na podstawie transakcji przechowywanych w wewnętrznym buforze pierścieniowym SurfaceFlingera. Generowanie zrzutów warstw następuje po opróżnieniu tego źródła danych.
  • MODE_DUMP: śledzi pojedynczy zrzut warstw.
  • MODE_GENERATED_BUGREPORT_ONLY: tak samo jak MODE_GENERATED, ale wywołuje generowanie zrzutów warstw tylko wtedy, gdy zostanie zgłoszony błąd, a nie każdorazowo przy opróżnianiu śladu.

Flagi śledzenia (trace_flags):

  • TRACE_FLAG_INPUT: jeśli powierzchnia zawiera dane wejściowe, śledzi szczegóły okna wejściowego.
  • TRACE_FLAG_COMPOSITION: śledzi typ kompozycji i widoczny region.

  • TRACE_FLAG_EXTRA: śledzi dodatkowe metadane powierzchni, w tym warstwy poza ekranem.

  • TRACE_FLAG_HWC: śledzi dodatkowe nieustrukturyzowane metadane kompozytora sprzętu.

  • TRACE_FLAG_BUFFERS: konfiguruje SurfaceFlingera tak, aby śledził wszystkie zmiany bufora na powierzchni. Domyślnie SurfaceFlinger śledzi nowy stan tylko wtedy, gdy nastąpią zmiany w geometrii.

  • TRACE_FLAG_VIRTUAL_DISPLAYS: uwzględnia w śladzie warstwy wyświetlacza wirtualnego.

Przykład

Poniższy przykład pokazuje typ śladu SurfaceFlingera w adb:

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.surfaceflinger.layers"
           surfaceflinger_layers_config: {
              mode: MODE_ACTIVE
              trace_flags: TRACE_FLAG_INPUT
              trace_flags: TRACE_FLAG_COMPOSITION
              trace_flags: TRACE_FLAG_HWC
              trace_flags: TRACE_FLAG_BUFFERS
              trace_flags: TRACE_FLAG_VIRTUAL_DISPLAYS
           }
       }
   }
EOF

Szczegółowe informacje o znaczeniu różnych wartości konfiguracji znajdziesz w sekcji SurfaceFlinger.

Animacje przejściowe powłoki

W przypadku tego typu śladu użyj nazwy źródła danych com.android.wm.shell.transition.

Opcje konfiguracji

Ten typ śladu nie ma opcji konfiguracji.

Przykład

Poniższy przykład pokazuje typ śladu animacji przejściowych powłoki w adb:

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "com.android.wm.shell.transition"
       }
   }
EOF

SurfaceFlinger (transakcje)

W przypadku tego typu śladu użyj nazwy źródła danych android.surfaceflinger.transactions.

Opcje konfiguracji

Tryb śledzenia (mode): określa częstotliwość rejestrowania elementów:

  • MODE_CONTINUOUS: SurfaceFlinger zapisuje swój wewnętrzny bufor pierścieniowy transakcji za każdym razem, gdy źródło danych jest opróżniane. Bufor pierścieniowy zawiera stan początkowy SurfaceFlingera i najnowsze transakcje.

  • MODE_ACTIVE: SurfaceFlinger zapisuje stan początkowy, a następnie każdą przychodzącą transakcję, aż do zatrzymania źródła danych.

Przykład

Poniższy przykład pokazuje typ śladu transakcji SurfaceFlingera w adb.

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.surfaceflinger.transactions"
           surfaceflinger_transactions_config: {
              mode: MODE_ACTIVE
           }
       }
   }
EOF

IME

W przypadku tego typu śladu użyj nazwy źródła danych android.inputmethod.

Opcje konfiguracji

Ten typ śladu nie ma opcji konfiguracji.

Przykład

Poniższy przykład pokazuje typ śladu IME w adb:

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.inputmethod"
       }
   }
EOF

ViewCapture

W przypadku tego typu śladu użyj nazwy źródła danych android.viewcapture.

Opcje konfiguracji

Ten typ śladu nie ma opcji konfiguracji.

Przykład

Poniższy przykład pokazuje typ śladu ViewCapture w adb:

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.viewcapture"
       }
   }
EOF

Kompletny przykład

Perfetto umożliwia zbieranie danych z wielu źródeł w ramach jednej konfiguracji. Wszystkie ślady Winscope możesz zebrać za pomocą jednego polecenia:

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.windowmanager"
           windowmanager_config: {
              log_level: LOG_LEVEL_VERBOSE
              log_frequency: LOG_FREQUENCY_TRANSACTION
           }
       }
   }
   data_sources: {
       config {
           name: "android.protolog"
           protolog_config: {
              tracing_mode: ENABLE_ALL
           }
       }
   }
   data_sources: {
       config {
           name: "android.input.inputevent"
           android_input_event_config: {
              mode: TRACE_MODE_TRACE_ALL
           }
       }
   }
   data_sources: {
       config {
           name: "android.surfaceflinger.layers"
           surfaceflinger_layers_config: {
              mode: MODE_ACTIVE
              trace_flags: TRACE_FLAG_INPUT
              trace_flags: TRACE_FLAG_COMPOSITION
              trace_flags: TRACE_FLAG_HWC
              trace_flags: TRACE_FLAG_BUFFERS
              trace_flags: TRACE_FLAG_VIRTUAL_DISPLAYS
           }
       }
   }
   data_sources: {
       config {
           name: "com.android.wm.shell.transition"
       }
   }
   data_sources: {
       config {
           name: "android.surfaceflinger.transactions"
           surfaceflinger_transactions_config: {
              mode: MODE_ACTIVE
           }
       }
   }
   data_sources: {
       config {
           name: "android.inputmethod"
       }
   }
   data_sources: {
       config {
           name: "android.viewcapture"
       }
   }
EOF

Rejestrowanie śladów w Androidzie 14 i starszych wersjach

Przed uruchomieniem poleceń adb shell dla każdego z tych śladów uruchom adb root. Na końcu śledzenia pliki śledzenia są dostępne w /data/misc/wmtrace. Aby skopiować plik lub katalog i jego podkatalogi z urządzenia, przeczytaj artykuł Kopiowanie plików na urządzenie i z urządzenia.

Ślady usługi WindowManager

Aby zarejestrować ślady usługi WindowManager:

  • Włącz śledzenie:

    adb shell wm tracing start

  • Wyłącz śledzenie:

    adb shell wm tracing stop

  • Zapisz dane logowania w pliku podczas rejestrowania śladu:

    adb shell wm tracing save-for-bugreport

  • Rejestruj ślad raz na ramkę:

    adb shell wm tracing frame

  • Rejestruj każdą transakcję:

    adb shell wm tracing transaction

  • Ustaw maksymalny rozmiar logu (w KB):

    adb shell wm tracing size

  • Wyświetl stan śledzenia:

    adb shell wm tracing status

  • Ustaw poziom logowania na critical (tylko widoczne okna z ograniczoną ilością informacji), trim (wszystkie okna z ograniczoną ilością informacji) lub all (wszystkie okna i informacje):

    adb shell wm tracing level

Zrzuty usługi WindowManager

Aby zarejestrować zrzuty usługi WindowManager:

adb exec-out dumpsys window --proto > window_dump.winscope

ProtoLog

Do systemu ProtoLog używane są te polecenia.

W procesie system_server:

  • Uruchom ProtoLog:

    adb shell cmd window logging start

  • Zatrzymaj ProtoLog:

    adb shell cmd window logging stop

  • Włącz ProtoLog dla wybranych grup logów:

    adb shell cmd window logging enable [group...]

  • Wyłącz ProtoLog dla wybranych grup logów:

    adb shell cmd window logging disable [group...]

  • Włącz Logcat logowanie dla wybranych grup logów:

    adb shell cmd window logging enable-text [group...]

  • Wyłącz logowanie Logcat dla wybranych grup logów:

    adb shell cmd window logging disable-text [group...]

W WMShell:

  • Uruchom ProtoLog:

    adb shell dumpsys activity service SystemUIService WMShell

Ślady SurfaceFlingera (warstwy)

Funkcja śledzenia warstw SurfaceFlingera używa śladu Perfetto do rejestrowania. Informacje o konfiguracji znajdziesz w sekcji Konfiguracja śledzenia.

Poniższy przykład pokazuje konfigurację śledzenia warstw SurfaceFlingera:

unique_session_name: "surfaceflinger_layers_active"
buffers: {
    size_kb: 63488
    fill_policy: RING_BUFFER
}
data_sources: {
    config {
        name: "android.surfaceflinger.layers"
        surfaceflinger_layers_config: {
            mode: MODE_ACTIVE
            trace_flags: TRACE_FLAG_INPUT
            trace_flags: TRACE_FLAG_COMPOSITION
            trace_flags: TRACE_FLAG_HWC
            trace_flags: TRACE_FLAG_BUFFERS
            trace_flags: TRACE_FLAG_VIRTUAL_DISPLAYS
        }
    }
}

Poniższe polecenie generuje śledzenie warstw SurfaceFlingera:

adb shell -t perfetto \
    -c - --txt \
    -o /data/misc/perfetto-traces/trace \

Zrzuty SurfaceFlingera (warstwy)

Aby zarejestrować zrzuty SurfaceFlingera, uruchom to polecenie:

adb exec-out dumpsys SurfaceFlinger --proto > sf_dump.winscope

Animacje przejściowe powłoki

Do śledzenia animacji przejściowych używane są te polecenia.

W procesie system_server użyj tych poleceń:

  • Uruchom śledzenie:

    adb shell cmd window shell tracing start

  • Zatrzymaj śledzenie:

    adb shell cmd window shell tracing stop

  • Uruchom śledzenie w WMShell:

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing start

  • Zatrzymymaj śledzenie w WMShell:

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop

IME

Do śledzenia edytora metody wprowadzania (IME) używane są te polecenia:

  1. Uruchom śledzenie IME dla klientów metody wprowadzania (IM), usługi metody wprowadzania (IMS) i usługi zarządzania metodą wprowadzania (IMMS): adb shell ime tracing start

  • Uruchom śledzenie klientów IME, IMS i IMMS:

    adb shell ime tracing stop

SurfaceFlinger (transakcje)

Funkcja śledzenia transakcji SurfaceFlinger używa śladu Perfetto do rejestrowania. Informacje o konfiguracji znajdziesz w sekcji Konfiguracja śledzenia.

Poniższy przykład pokazuje konfigurację Perfetto dla SurfaceFlinger aktywnego śledzenia:

unique_session_name: "surfaceflinger_transactions_active"
buffers: {
    size_kb: 1024
    fill_policy: RING_BUFFER
}
data_sources: {
    config {
        name: "android.surfaceflinger.transactions"
        surfaceflinger_transactions_config: {
            mode: MODE_ACTIVE
        }
    }
}
write_into_file: true
file_write_period_ms: 100

Poniższy przykład pokazuje konfigurację Perfetto dla SurfaceFlingera ciągłego śledzenia:

unique_session_name: "surfaceflinger_transactions_continuous"
buffers: {
    size_kb: 1024
    fill_policy: RING_BUFFER
}
data_sources: {
    config {
        name: "android.surfaceflinger.transactions"
        surfaceflinger_transactions_config: {
            mode: MODE_CONTINUOUS
        }
    }
}

Poniższe polecenie generuje śledzenie transakcji SurfaceFlingera:

    adb shell perfetto \
    -c - --txt \
    -o /data/misc/perfetto-traces/trace \