Как записывать трассировки с помощью команд adb

Вы можете собирать трассировки Winscope с помощью командной строки adb в отладочных сборках (то есть сборках userdebug и eng). Прежде чем собирать трассировки Winscope с помощью adb, запустите adb root.

В Android 15 трассировки Winscope интегрированы в Perfetto и собираются с помощью командной строки Perfetto. Каждая трассировка Winscope – это источник данных Perfetto со своей конфигурацией. Вы можете включить конфигурации по отдельности или в рамках одной сессии трассировки.

В Android 14 и более ранних версий у каждой трассировки Winscope своя команда, и вы можете собирать их по отдельности. Подробнее о том, как записывать трассировки в Android 14 и более ранних версиях…

WindowManager

Для этого типа трассировки используйте источник данных android.windowmanager.

Варианты конфигурации

  • Уровень ведения журнала (log_level). Указывает уровень детализации журнала. Допустимые значения:

    • LOG_LEVEL_VERBOSE – регистрирует все элементы с максимальным объемом информации.
    • LOG_LEVEL_DEBUG – регистрирует все элементы, но не записывает все данные конфигурации.
    • LOG_LEVEL_CRITICAL: регистрирует только видимые элементы с минимальными накладными расходами на производительность.

  • Частота ведения журнала (log_frequency). Определяет частоту, с которой регистрируются элементы:

    • LOG_FREQUENCY_FRAME – отслеживает снимки состояния, когда фиксируется кадр.
    • LOG_FREQUENCY_TRANSACTION: трассировки содержат снимки состояния каждый раз, когда фиксируется транзакция.
    • LOG_FREQUENCY_SINGLE_DUMP: отслеживает одномоментные снимки состояния при запуске источника данных.

Подробнее о значениях конфигурации…

Пример

В примере ниже показан тип трассировки WindowManager для 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

Для этого типа трассировки используйте название источника данных android.protolog.

Варианты конфигурации

Tracing mode (tracing_mode) – определяет, какую конфигурацию журнала использовать:

  • DEFAULT – отслеживаются только группы и уровни журналов, указанные в group_overrides.
  • ENABLE_ALL – отслеживает все группы и уровни журналов, если не указано в group_overrides.

Минимальный уровень журнала (default_log_from_level). Если задано значение, отслеживаются все сообщения с уровнем журнала выше или равным этому уровню, если не указано переопределение группы. Например, это позволяет включить регистрацию всех предупреждений и ошибок, не включая все журналы. Допустимые значения:

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

Переопределения групп (group_overrides). Позволяет вручную настроить уровень ведения журнала для каждой группы ProtoLog. Каждая группа содержит:

  • name – название группы ProtoLog, используемое в исходном коде Android.
  • log_from – то же, что и default_log_from_level, но только для текущей группы.

  • collect_stacktrace: если задано значение true, собирает трассировку стека для каждого сообщения ProtoLog в отслеживаемой группе.

Пример

В примере ниже показан тип трассировки ProtoLog для 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

Ввод

Для этого типа трассировки используйте источник данных android.input.inputevent.

Варианты конфигурации

Режим трассировки (trace_mode). Определяет, следует ли начинать трассировку входных данных с использованием правил обеспечения конфиденциальности или записывать все входные события.

  • TRACE_MODE_TRACE_ALL – регистрирует все события ввода, обработанные системой, независимо от контекста, в котором они были обработаны.
  • TRACE_MODE_USE_RULES: использует правила трассировки, определенные в этой конфигурации, чтобы указать, какие события нужно отслеживать. Подробную информацию о том, как задать правила для трассировки, можно найти в статье android_input_event_config.proto.

Пример

Ниже приведен пример типа трассировки ввода для 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 (слои)

Для этого типа трассировки используйте источник данных android.surfaceflinger.layers.

Варианты конфигурации

Режим трассировки (mode). Определяет частоту регистрации элементов.

  • MODE_ACTIVE: отслеживает снимки слоев. Снимок делается каждый раз, когда изменяются слои.
  • MODE_GENERATED: создает снимки слоев на основе транзакций, хранящихся во внутреннем кольцевом буфере SurfaceFlinger. Снимки слоя создаются, когда источник данных очищается.
  • MODE_DUMP – отслеживает снимок одного слоя.
  • MODE_GENERATED_BUGREPORT_ONLY: то же, что и MODE_GENERATED, но снимки слоев создаются только при создании отчета об ошибке, а не при каждом сбросе трассировки.

Флаги трассировки (trace_flags).

  • TRACE_FLAG_INPUT – если на поверхности есть данные ввода, отслеживает особенности окна ввода.
  • TRACE_FLAG_COMPOSITION – отслеживает тип композиции и видимую область.

  • TRACE_FLAG_EXTRA: отслеживает дополнительные метаданные поверхности, в том числе внеэкранные слои.

  • TRACE_FLAG_HWC: отслеживает дополнительные неструктурированные метаданные аппаратного компоновщика.

  • TRACE_FLAG_BUFFERS – настраивает SurfaceFlinger для отслеживания всех изменений буфера на поверхности. По умолчанию SurfaceFlinger отслеживает новое состояние только при изменении геометрии.

  • TRACE_FLAG_VIRTUAL_DISPLAYS – включает в трассировку слои виртуального экрана.

Пример

В примере ниже показан тип трассировки SurfaceFlinger для 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

Подробнее о значениях конфигурации можно узнать в разделе SurfaceFlinger.

Переходы в оболочке

Для этого типа трассировки используйте источник данных com.android.wm.shell.transition.

Варианты конфигурации

У этого типа трассировки нет параметров конфигурации.

Пример

В примере ниже показан тип трассировки перехода оболочки для 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 (транзакции)

Используйте название источника данных android.surfaceflinger.transactions для этого типа трассировки.

Варианты конфигурации

Режим трассировки (mode). Определяет частоту регистрации элементов:

  • MODE_CONTINUOUS: SurfaceFlinger записывает свой внутренний кольцевой буфер транзакций каждый раз, когда источник данных сбрасывается. Кольцевой буфер содержит начальное состояние SurfaceFlinger и последние транзакции.

  • MODE_ACTIVE: SurfaceFlinger записывает начальное состояние, а затем каждую входящую транзакцию, пока источник данных не будет остановлен.

Пример

В примере ниже показан тип трассировки транзакций SurfaceFlinger для 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

Способы ввода

Для этого типа трассировки используйте название источника данных android.inputmethod.

Варианты конфигурации

У этого типа трассировки нет параметров конфигурации.

Пример

В следующем примере показан тип трассировки IME для 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

Для этого типа трассировки используйте источник данных android.viewcapture.

Варианты конфигурации

У этого типа трассировки нет параметров конфигурации.

Пример

В следующем примере показан тип трассировки ViewCapture для 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

Полный пример

Perfetto позволяет собирать данные из нескольких источников в рамках одной конфигурации. Чтобы собрать все трассировки Winscope, используйте следующую команду:

$ 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

Как записывать трассировки в Android 14 и более ранних версиях

Выполните команду adb root, прежде чем запускать команды adb shell для каждого из следующих трассировок. По завершении трассировки файлы трассировки будут доступны в /data/misc/wmtrace. Чтобы скопировать файл или каталог и его подкаталоги с устройства, ознакомьтесь с разделом Как копировать файлы на устройство и с него.

Трассировки WindowManager

Чтобы записать трассировки WindowManager, выполните следующие действия:

  • Включить трассировку:

    adb shell wm tracing start

  • Отключить трассировку:

    adb shell wm tracing stop

  • Чтобы сохранить данные журнала в файл во время сбора трассировки:

    adb shell wm tracing save-for-bugreport

  • Записывать трассировку один раз на кадр:

    adb shell wm tracing frame

  • Регистрируйте каждую транзакцию.

    adb shell wm tracing transaction

  • Укажите максимальный размер журнала (в КБ):

    adb shell wm tracing size

  • Статус трассировки печати:

    adb shell wm tracing status

  • Установите уровень журнала: critical (только видимые окна с сокращенной информацией), trim (все окна с сокращенной информацией) или all (все окна и информация).

    adb shell wm tracing level

дампы WindowManager;

Чтобы получить дампы WindowManager:

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

ProtoLog

Для системного журнала ProtoLog используются следующие команды:

В процессе system_server:

  • Start ProtoLog:

    adb shell cmd window logging start

  • Stop ProtoLog:

    adb shell cmd window logging stop

  • Включите ProtoLog для определенных групп журналов:

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

  • Отключить ProtoLog для указанных групп журналов:

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

  • Включите ведение журнала Logcat для определенных групп журналов:

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

  • Отключить ведение журналов Logcat для следующих групп журналов:

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

В WMShell:

  • Start ProtoLog:

    adb shell dumpsys activity service SystemUIService WMShell

Трассировки SurfaceFlinger (слои)

Для записи трассировки слоев SurfaceFlinger используется трассировка Perfetto. Информацию о конфигурации можно найти в разделе Настройка трассировки.

Ниже приведен пример конфигурации для отслеживания слоя SurfaceFlinger:

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
        }
    }
}

Следующая команда генерирует трассировку для слоев SurfaceFlinger:

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

дампы SurfaceFlinger (слои);

Чтобы сделать снимок дампа SurfaceFlinger, выполните следующую команду:

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

Переходы Shell

Для отслеживания переходов используются следующие команды:

В процессе system_server используйте следующие команды:

  • Начните трассировку:

    adb shell cmd window shell tracing start

  • Чтобы остановить трассировку:

    adb shell cmd window shell tracing stop

  • Чтобы начать трассировку в WMShell, выполните следующую команду:

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing start

  • Чтобы остановить трассировку в WMShell, выполните следующие действия:

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop

Способы ввода

Для трассировки редактора метода ввода (IME) используются следующие команды:

  1. Начать трассировку IME для клиентов способа ввода, службы способа ввода и службы управления способом ввода: adb shell ime tracing start

  • Чтобы начать отслеживание клиентов IME, IMS и IMMS, выполните следующую команду:

    adb shell ime tracing stop

SurfaceFlinger (транзакции)

Для записи трассировки транзакций SurfaceFlinger используется трассировка Perfetto. Информацию о конфигурации можно найти в разделе Настройка трассировки.

В примере ниже показана конфигурация Perfetto для активной трассировки SurfaceFlinger:

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

В примере ниже показана конфигурация Perfetto для непрерывной трассировки SurfaceFlinger:

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
        }
    }
}

Следующий пример команды генерирует трассировку для транзакций SurfaceFlinger:

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