Logcat command-line tool

Stay organized with collections Save and categorize content based on your preferences.

Logcat is a command-line tool that dumps a log of system messages when the device throws an error and sends messages that you have written from your app with the Log class.

This page is about the command-line logcat tool, but you can also view log messages from the Logcat window in Android Studio. For information about viewing and filtering logs from Android Studio, see View and write logs with Logcat.

Logging system overview

The Android logging system is a set of structured circular buffers maintained by the system process logd. The set of available buffers is fixed and defined by the system. The most relevant buffers are:

  • main: Stores most application logs.
  • system: Stores messages originating from the Android OS.
  • crash: Stores crash logs. Each log entry has a priority, a tag that identifies the origin of the log, and the actual log message.

The primary interface to the logging system is the shared library liblog and its header <android/log.h>. All language-specific logging facilities eventually call the function __android_log_write. By default, it calls the function __android_log_logd_logger, which sends the log entry to logd using a socket. Starting with API level 30, the logging function can be changed by calling __android_set_log_writer. More information is available in the NDK documentation.

Logs displayed by adb logcat undergo four levels of filtering:

Compile-time filtering
Depending on compilation settings, some logs may be completely removed from the binary. For example, ProGuard can be configured to remove calls to Log.d from Java code.
System property filtering
liblog queries a set of system properties to determine the minimum severity level to be sent to logd. If your logs have the tag MyApp, the following properties are checked and are expected to contain the first letter of the minimum severity (V, D, I, W, E, or S to disable all logs):
  • log.tag.MyApp
  • persist.log.tag.MyApp
  • log.tag
  • persist.log.tag
Application filtering
If none of the properties are set, liblog uses the minimum priority set by __android_log_set_minimum_priority. The default setting is INFO.
Display filtering
adb logcat supports additional filters that can reduce the amount of logs shown from logd. See the section about filtering log output for more details.

Command-line syntax

To run logcat through the adb shell, the general usage is:

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

You can run logcat as an adb command or directly in a shell prompt on your emulator or connected device. To view log output using adb, navigate to your SDK platform-tools/ directory and execute:

adb logcat

For logcat online help, start a device and then execute:

adb logcat --help

Create a shell connection to a device and execute:

$ adb shell
# logcat

Options

The following table describes the command-line options for logcat:

Option Description
-b <buffer> Loads an alternate log buffer for viewing, such as events or radio. The main, system, and crash buffer set is used by default. See the section about viewing alternative log buffers.
-c, --clear Clears the selected buffers and exits. The default buffer set is main, system, and crash. To clear all buffers, use -b all -c.
-e <expr>, --regex=<expr> Only prints lines where the log message matches <expr>, where <expr> is a regular expression.
-m <count>, --max-count=<count> Quits after printing <count> number of lines. This is meant to be paired with --regex, but will work on its own.
--print Paired with --regex and --max-count, lets content bypass the regex filter, but still stops at the right number of matches.
-d Dumps the log to the screen and exits.
-f <filename> Writes log message output to <filename>. The default is stdout.
-g, --buffer-size Prints the size of the specified log buffer and exits.
-n <count> Sets the maximum number of rotated logs to <count>. The default value is 4. Requires the -r option.
-r <kbytes> Rotates the log file every <kbytes> of output. The default value is 16. Requires the -f option.
-s Equivalent to the filter expression '*:S', which sets priority for all tags to silent and is used to precede a list of filter expressions that add content. To learn more, go to the section about filtering log output.
-v <format> Sets the output format for log messages. The default is the threadtime format. For a list of supported formats, see the section about controlling log output format.
-D, --dividers Prints dividers between each log buffer.
-c Clears the entire log and exits.
-t <count> Prints only the most recent number of lines. This option includes -d functionality.
-t '<time>' Prints the most recent lines since the specified time. This option includes -d functionality. See the -P option for information about quoting parameters with embedded spaces.
adb logcat -t '01-26 20:52:41.820'
-T <count> Prints the most recent number of lines since the specified time. This option doesn't include -d functionality.
-T '<time>' Prints the most recent lines since the specified time. This option doesn't include include -d functionality. See the -P option for information about quoting parameters with embedded spaces.
adb logcat -t '01-26 20:52:41.820'
-L, --last Dumps the logs prior to the last reboot.
-B, --binary Outputs the log in binary.
-S, --statistics Includes statistics in the output to help you identify and target log spammers.
-G <size> Sets the size of the log ring buffer. You can add K or M at the end to indicate kilobytes or megabytes.
-p, --prune Prints the allowlist and denylist and takes no arguments, as follows:
adb logcat -p
-P '<list> ...'
--prune '<list> ...' -P '<allowlist_and_denylist>'
Writes the allowlist and denylist to adjust the logging content for a specific purpose. You provide a mixed content of allowed and denied list entries, where <allowlist> or <denylist> can be a UID, UID/PID, or PID. With guidance from the logcat statistics (logcat -S), one can consider adjustments to the allowlist and denylist for purposes such as:
  • Giving the highest longevity to specific logging content through UID selections.
  • Preventing someone (UID) or something (PID) from consuming these resources to help increase the logspan so you have more visibility into the problems you are diagnosing.

By default, the logging system automatically prevents the worst offender in the log statistics dynamically to make space for new log messages. Once it has exhausted the heuristics, the system prunes the oldest entries to make space for the new messages.

Adding an allowlist protects your Android Identification number (AID), which becomes the processes' AID and GID, from being declared an offender. Adding a denylist helps free up space before the worst offenders are considered. You can choose how active the pruning is, and you can turn pruning off so it only removes content from the oldest entries in each log buffer.

Quotes

adb logcat doesn't preserve the quotes, so the syntax for specifying allowlist and denylist is as follows:

$ adb logcat -P '"<allowlist_and_denylist>"'

or

adb shell
$ logcat -P '<allowlist_and_denylist>'

The following example specifies an allowlist with PID 32676 and UID 675, and a denylist with PID 32677 and UID 897. PID 32677 on the denylist is weighted for faster pruning.

adb logcat -P '"/32676 675 ~/32677 897"'

You can use the following allowlist and denylist command variations:

~! worst uid denylist
~1000/! worst pid in system (1000)
--pid=<pid> ... Only prints logs from the given PID.
--uid=<uids> ... Only displays log messages from UIDs present in the comma-separated list <uids>. No name look-up is performed, so UIDs must be provided as numeric values. This option is only useful for the 'root', 'log', and 'system' users, because only those users can view logs from other users.
--wrap Sleep for 2 hours or when the buffer is about to wrap, whichever comes first. Improves efficiency of polling by providing an about-to-wrap wakeup.

Filter log output

The tag of a log message is a short string that indicates the system component where the message originates. For example, "View" for the view system.

The priority is one of the following character values, ordered from lowest to highest priority:

    • V: Verbose (lowest priority)
    • D: Debug
    • I: Info
    • W: Warning
    • E: Error
    • F: Fatal
    • S: Silent (highest priority, where nothing is ever printed)
  • To obtain a list of tags used in the system with priorities, run logcat and observe the first two columns of each message, given as <priority>/<tag>.

    The following is an example of brief logcat output obtained with the logcat -v brief output command. The output shows that the message relates to priority level "I" and tag "ActivityManager":

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

    To reduce the log output to a manageable level, restrict log output using filter expressions. Filter expressions let you indicate to the system the tag-priority combinations that you are interested in. The system suppresses other messages for the specified tags.

    A filter expression follows this format tag:priority ..., where tag indicates the tag of interest and priority indicates the minimum level of priority to report for that tag. Messages for that tag at or above the specified priority are written to the log. Supply any number of tag:priority specifications in a single filter expression. The series of specifications is whitespace-delimited.

    The following is an example of a filter expression that suppresses all log messages except those with the tag "ActivityManager" at priority "Info" or above and those with the tag "MyApp" with priority "Debug" or above:

    adb logcat ActivityManager:I MyApp:D *:S
    

    The final element in the preceding expression, *:S, sets the priority level for all tags to "silent", which ensures that only log messages with "ActivityManager" and "MyApp" are displayed. Using *:S ensures that log output is restricted to the filters that you have explicitly specified. *:S lets your filters serve as an allowlist for log output.

    Note: In some shells, the "*" character is reserved by the shell. If you are using such a shell, enclose the filter expression in quotes: adb logcat "ActivityManager:I MyApp:D *:S"

    The following filter expression displays all log messages with priority level "warning" and higher on all tags:

    adb logcat *:W
    

    If you're running logcat from your development computer instead of running it on a remote adb shell, you can also set a default filter expression by exporting a value for the environment variable ANDROID_LOG_TAGS:

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

    The ANDROID_LOG_TAGS filter is not exported to the emulator/device instance if you are running logcat from a remote shell or using adb shell logcat.

    Control log output format

    Log messages contain a number of metadata fields in addition to the tag and priority. You can modify the output format for messages so that they display a specific metadata field. To do so, use the -v option and specify one of the following supported output formats:

    • brief: Displays priority, tag, and PID of the process issuing the message.
    • long: Displays all metadata fields and separate messages with blank lines.
    • process: Displays PID only.
    • raw: Displays the raw log message with no other metadata fields.
    • tag: Displays the priority and tag only.
    • thread: A legacy format that shows priority, PID, and TID of the thread issuing the message.
    • threadtime (default): Displays the date, invocation time, priority, tag, PID, and TID of the thread issuing the message.
    • time: Displays the date, invocation time, priority, tag, and PID of the process issuing the message.

    When starting logcat, specify the output format you want by using the -v option:

    [adb] logcat [-v <format>]
    

    Here's an example that shows how to generate messages in thread output format:

    adb logcat -v thread
    

    You can only specify one output format with the -v option. However, you can specify as many modifiers as you need, provided they make sense. logcat ignores modifiers that don't make sense.

    Format modifiers

    Format modifiers change the logcat output. To specify a format modifier, use the -v option, as follows:

    adb logcat -b all -v color -d
    

    Every Android log message has a tag and a priority associated with it. You can combine any format modifier with any one of the following format options:

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

    To format the following modifier details, enter logcat -v --help at the command line:

    • color: Shows each priority level with a different color.
    • descriptive: Shows log buffer event descriptions. This modifier affects event log buffer messages only and has no effect on the other non-binary buffers. The event descriptions come from the event-log-tags database.
    • epoch: Displays time in seconds starting from Jan 1, 1970.
    • monotonic: Displays time in CPU seconds starting from the last boot.
    • printable: Ensures that any binary logging content is escaped.
    • uid: If permitted by access controls, displays the UID or Android ID of the logged process.
    • usec: Displays the time, with precision in microseconds.
    • UTC: Displays the time as UTC.
    • year: Adds the year to the displayed time.
    • zone: Adds the local time zone to the displayed time.

    View alternative log buffers

    The Android logging system keeps multiple circular buffers for log messages, and not all of log messages are sent to the default circular buffer. To see additional log messages, run the logcat command with the -b option to request viewing of an alternate circular buffer. You can view any of these alternate buffers:

    • radio: Views the buffer that contains radio/telephony related messages.
    • events: Views the interpreted binary system event buffer messages.
    • main: Views the main log buffer (default), which doesn't contain system and crash log messages.
    • system: Views the system log buffer (default).
    • crash: Views the crash log buffer (default).
    • all: Views all buffers.
    • default: Reports main, system, and crash buffers.

    The usage of the -b option is:

    [adb] logcat [-b <buffer>]
    

    Here is an example of how to view a log buffer containing radio and telephony messages:

    adb logcat -b radio
    

    To specify multiple -b flags for all the buffers you want to print, enter the following:

    logcat -b main -b radio -b events
    

    Specify a single -b flag with a comma-separated list of buffers, for example:

    logcat -b main,radio,events
    

    Log from code

    The Log class lets you create log entries in your code that display in the logcat tool. Common logging methods include:

    For example, using the following call:

    Kotlin

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

    Java

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

    logcat outputs something similar to the following:

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