Инструмент командной строки logcat

Logcat – это инструмент командной строки, который создает журнал системных сообщений, включая сообщения, написанные вами в приложении с помощью класса Log.

На этой странице рассказывается об инструменте командной строки logcat, но вы также можете просматривать сообщения журнала в окне Logcat в Android Studio. Информацию о том, как просматривать и фильтровать журналы в Android Studio, вы найдете в статье Просмотр и запись журналов с помощью Logcat.

Обзор системы ведения журналов

Система ведения журналов Android представляет собой набор структурированных кольцевых буферов, которые поддерживаются системным процессом logd. Набор доступных буферов фиксирован и определяется системой. Наиболее важные буферы:

• main – хранит большинство журналов приложений.
• system – хранит сообщения, созданные ОС Android.
• crash: хранит журналы сбоев. Каждая запись в журнале имеет приоритет, тег, который идентифицирует источник журнала, и фактическое сообщение журнала.

Основной интерфейс C/C++ для системы ведения журналов – это общая библиотека liblog и ее заголовок <android/log.h>. Все средства ведения журналов, зависящие от языка (включая android.util.Log), в конечном итоге вызывают функцию __android_log_write. По умолчанию вызывается функция __android_log_logd_logger, которая отправляет запись журнала в logd через сокет. Начиная с уровня API 30, функцию ведения журнала можно изменить, вызвав __android_set_log_writer. Дополнительную информацию можно найти в документации по NDK.

Журналы, которые показываются в adb logcat, проходят четыре уровня фильтрации:

Фильтрация во время компиляции

В зависимости от настроек компиляции некоторые журналы могут быть полностью удалены из двоичного файла. Например, ProGuard можно настроить так, чтобы он удалял вызовы Log.d из кода Java.

Фильтрация по свойствам системы

liblog запрашивает набор системных свойств, чтобы определить минимальный уровень серьезности, который нужно отправить в logd. Если в журналах есть тег MyApp, проверяются следующие свойства, которые должны содержать первую букву минимального уровня серьезности (V, D, I, W, E или S, чтобы отключить все журналы):

• log.tag.MyApp
• persist.log.tag.MyApp
• log.tag
• persist.log.tag

Фильтрация приложений

Если ни одно из свойств не задано, liblog использует минимальный приоритет, заданный __android_log_set_minimum_priority. Значение по умолчанию – INFO.

Фильтрация медийных объявлений

adb logcat поддерживает дополнительные фильтры, которые могут уменьшить количество журналов, отображаемых из logd. Подробнее о фильтрации выходных данных журнала…

Синтаксис командной строки

Чтобы запустить logcat через оболочку adb, используйте следующую команду:

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

Также есть сокращенная форма adb logcat, которая расширяется до adb shell logcat.

Параметры

logcat предлагает множество вариантов. Доступные варианты зависят от версии ОС на вашем устройстве. Чтобы посмотреть справку по logcat для вашего устройства, выполните следующую команду:

    adb logcat --help
    

Поскольку logcat – это инструмент как для разработчиков ОС, так и для разработчиков приложений (хотя последним рекомендуется использовать Android Studio), многие параметры доступны только для root.

Фильтрация вывода журнала

Тег сообщения в журнале – это короткая строка, которая указывает на компонент системы, в котором было создано сообщение. Например, View для системы View.

Приоритет может иметь одно из следующих значений (в порядке возрастания):

Чтобы получить список тегов, используемых в системе с приоритетами, выполните команду logcat и посмотрите на первые два столбца каждого сообщения, указанные как <priority>/<tag>.

Ниже приведен пример кратких выходных данных logcat, полученных с помощью команды logcat -v brief output. В выводе показано, что сообщение относится к уровню приоритета I и тегу ActivityManager:

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

Чтобы уменьшить объем выводимых данных до приемлемого уровня, ограничьте его с помощью выражений фильтра. Выражения фильтров позволяют указать системе, какие комбинации тегов и приоритетов вас интересуют. Система блокирует другие сообщения для указанных тегов.

Выражение фильтра имеет формат tag:priority ..., где tag – это тег, а priority – минимальный уровень приоритета, который должен быть у тега, чтобы он попал в отчет. Сообщения для этого тега с указанным приоритетом или выше записываются в журнал. В одном выражении фильтра можно указать любое количество спецификаций tag:priority. Спецификации разделяются пробелами.

Ниже приведен пример выражения фильтра, которое подавляет все сообщения в журнале, кроме сообщений с тегом ActivityManager и приоритетом Info или выше, а также сообщений с тегом MyApp и приоритетом Debug или выше.

adb logcat ActivityManager:I MyApp:D *:S

Последний элемент в предыдущем выражении, *:S, устанавливает уровень приоритета для всех тегов на "silent", что гарантирует отображение только сообщений в журнале с "ActivityManager" и "MyApp". Использование *:S гарантирует, что вывод журнала будет ограничен фильтрами, которые вы явно указали. *:S позволяет использовать фильтры в качестве белого списка для вывода журнала.

Примечание. В некоторых оболочках символ * зарезервирован. Если вы используете такую оболочку, заключите выражение фильтра в кавычки: adb logcat "ActivityManager:I MyApp:D *:S".

Следующее выражение фильтра показывает все сообщения в журнале с уровнем приоритета "предупреждение" и выше для всех тегов:

adb logcat *:W

Если вы запускаете logcat на компьютере разработчика, а не в удаленной оболочке adb, вы также можете задать выражение фильтра по умолчанию, экспортировав значение для переменной среды ANDROID_LOG_TAGS:

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

Фильтр ANDROID_LOG_TAGS не экспортируется в эмулятор или экземпляр устройства, если вы запускаете logcat из удаленной оболочки или используете adb shell logcat.

Управление форматом вывода журнала

Помимо тега и приоритета, сообщения в журнале содержат ряд полей метаданных. Вы можете изменить формат вывода сообщений, чтобы в них отображалось определенное поле метаданных. Для этого используйте параметр -v и укажите один из следующих поддерживаемых форматов вывода:

• brief – приоритет, тег и идентификатор процесса, который выдает сообщение.
• long – показывает все поля метаданных и разделяет сообщения пустыми строками.
• process – показывается только идентификатор PID.
• raw – необработанное сообщение в журнале без других полей метаданных.
• tag: отображаются только приоритет и тег.
• thread: Устаревший формат, в котором показывается приоритет, PID и TID потока, отправляющего сообщение.
• threadtime (по умолчанию) – дата, время вызова, приоритет, тег, PID и TID потока, отправляющего сообщение.
• time – дата, время вызова, приоритет, тег и идентификатор процесса, который выдает сообщение.

При запуске logcat укажите нужный формат вывода с помощью параметра -v:

[adb] logcat [-v <format>]

Ниже приведен пример создания сообщений в формате thread.

adb logcat -v thread

С помощью параметра -v можно указать только один формат вывода. Однако вы можете указать столько модификаторов, сколько вам нужно, если это имеет смысл. logcat игнорирует модификаторы, которые не имеют смысла.

Модификаторы формата

Модификаторы формата изменяют выходные данные logcat. Чтобы указать модификатор формата, используйте параметр -v, как показано ниже.

adb logcat -b all -v color -d

У каждого сообщения в журнале Android есть тег и приоритет. Вы можете комбинировать любой модификатор формата с любым из следующих вариантов формата:

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

Чтобы отформатировать следующие сведения о модификаторе, введите в командной строке logcat -v --help:

• color – каждый уровень приоритета выделяется своим цветом.
• descriptive – показывает описания событий буфера журнала. Этот модификатор влияет только на сообщения буфера журнала событий и не влияет на другие недвоичные буферы. Описания событий берутся из базы данных event-log-tags.
• epoch – время в секундах, начиная с 1 января 1970 г.
• monotonic – время в секундах ЦП, прошедшее с момента последней загрузки.
• printable – экранирует содержимое двоичного журнала.
• uid. Если разрешено настройками контроля доступа, показывает UID или Android ID зарегистрированного процесса.
• usec – время с точностью до микросекунд.
• UTC – время по UTC.
• year – добавляет год к отображаемому времени.
• zone – добавляет местный часовой пояс к отображаемому времени.

Посмотреть альтернативные буферы журнала

В системе ведения журналов Android есть несколько кольцевых буферов для сообщений в журнале, и не все сообщения в журнале отправляются в буфер по умолчанию. Чтобы посмотреть дополнительные сообщения в журнале, выполните команду logcat с параметром -b. Вы можете посмотреть любой из этих альтернативных буферов:

• radio – просмотр буфера, содержащего сообщения, связанные с радио и телефонией.
• events – просмотр интерпретированных сообщений буфера событий двоичной системы.
• main – просмотр основного буфера журнала (по умолчанию), который не содержит сообщений в журнале системы и сбоев.
• system – просмотр буфера системного журнала (по умолчанию).
• crash – просмотр буфера журнала сбоев (по умолчанию).
• all: просмотр всех буферов.
• default: сообщает о буферах main, system и crash.

Параметр -b используется следующим образом:

[adb] logcat [-b <buffer>]

Вот пример того, как посмотреть буфер журнала, содержащий сообщения радио и телефонии:

adb logcat -b radio

Чтобы указать несколько параметров -b для всех буферов, которые нужно распечатать, введите следующую команду:

logcat -b main -b radio -b events

Укажите один флаг -b со списком буферов, разделенных запятыми, например:

logcat -b main,radio,events

Запись из кода

Класс Log позволяет создавать в коде записи журнала, которые отображаются в инструменте logcat. Распространенные методы регистрации включают:

• Log.v(String, String) (подробно)
• Log.d(String, String) (отладка)
• Log.i(String, String) (информация)
• Log.w(String, String) (предупреждение)
• Log.e(String, String) (ошибка)

Например, при использовании следующего вызова:

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

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

logcat выводит примерно следующее:

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