ADB WinLog User Guide

[Estimated Reading Time: 6 minutes]

ADB WinLog is a very simple front end on to the Android SDK adb logcat command. As such, the Android SDK documentation for the command itself provides a good guide to the basic usage.

First, an overview of the main log output area.

The first thing to notice is that log entries are coloured. The colour of each entry is determined by the Priority level of the log entry itself. As such, this colouring is only supported when the selected Content Format includes the Priority field. Only the raw format does not contain this information.

The second thing to note is that way that time information for each entry is omitted in some cases. This occurs when a message has a time stamp that occurs within the same second as the preceding message. This makes it a little easier to follow the timing of log entries without being swamped by lots of repeating, virtually identical information in cases where log messages are output in rapid succession.

Now for the application controls and settings themselves. The control interface consists primarily of a tool bar, divided into three areas:

• logcat Parameters
• Run Controls
• GUI Options

logcat Parameters

The logcat Parameters area is where you can specify the output of the logcat command itself.

You can select the device log buffer you wish to view, the content format presented for the entries in the selected log, and an activity filter to restrict which log entries are presented.

Buffer and Content Format

The buffer and content formats are selected from two drop-down option lists.

The entries in these option lists correspond directly to the options supported by the logcat command.

The content format determines what information is presented for each entry in the selected log at varying levels of detail from raw which provides a simple list of the log messages to threadtime which presents the most detail with process ID, thread ID, priority, activity tag and more.

You can change the buffer and content format at any time.

If the log is currently running it will be automatically restarted with the selected buffer or format.

Activity Filter

The activity filter field accepts any valid logcat activity filter expression. As you type into this field, the expression is validated. The filter expression will be colored red if invalid.

Any valid filter expression is applied automatically. If the log is currently running it is automatically restarted with the new filter expression applied.

Bringing all this together, the screenshot below is an example of a “white list” filter to include only log entries from the dalvikvm activity of “info” priority and above. For additional information, the logcat command being currently applied is displayed in the WINLOG caption bar.

All of the logcat parameter settings are saved by ADB WINLOG when it is closed and are restored the next time it starts. Settings are saved in:

%APPDATA%\nz.co.deltics\adb.winlog\settings.ini

Related ADB LOGCAT Commands:

Run Controls

The following run controls are available:

• Start / Restart
• Stop
• Pause / Resume
• Auto-Start option

Pressing Start will apply the current logcat parameters and start monitoring the log. If a log session is currently running this same button is instead labelled Restart and pressing it will immediately stop and restart the log with the same settings.

Once a log session has started running the Stop and Pause buttons become enabled.

The Stop button will stop any active log session.

Pressing Pause will suspend the capture of log information. The adb logcat command is still running and still producing output, but ADB WINLOG is not updating itself. When paused, the Pause button is labelled Resume and pressing it will cause ADB WINLOG to bring itself up-to-date with the log output and resume monitoring the log.

Pausing an active log can be useful if you wish to examine the current log contents without being distracted by new log entries but without having to stop and restart the log session in order to capture those new entries.

NOTE: If you Restart while logging is Paused, the new log session will not be paused. ADB WINLOG will refresh and resume monitoring the new log session.

Auto-Start Option

If you enable the Auto-Start option, ADB WINLOG will automatically apply the log parameters from any previous session (saved at the point that ADB WINLOG is closed) and start a log session. This can be a useful time saver if you are working with the logs on a specific project and wish to apply the same buffer, format and filter settings on each occasion.

GUI Options

Two simple options are provided for the GUI:

• Stay-on-top
• Auto-Scroll

In addition to these options, the GUI automatically remembers it’s position and size when closed and will re-open at the same position and size when re-started. Position and size information is stored in the same settings file as the logcat parameter settings.

Stay-On-Top

With Stay-on-top enabled, the ADB WINLOG window will not allow itself to be hidden by other windows on your desktop.

Stay-On-Top combined with automatic window sizing and positioning can be useful to consistently position ADB WINLOG over an area of your preferred IDE for Android development.

Auto-Scroll

With this option enabled (the default setting) ADB WINLOG will automatically scroll to the bottom of the log content to ensure that the most recent log entry is visible.

If you turn this option off, ADB WINLOG will continue to update itself with new log entries but will not automatically scroll to bring them into view.

NOTE: Selecting an item in the log entry list automatically disables Auto-Scroll on the presumption that if you are interested in a specified entry (one you have selected) then you will not wish to have is disappear from view if new log entries are received while you are examining it.

Disabling Auto-Scroll is similar to using the Pause button in that it allows you to focus on a specific entry (or entries) in the log when needed. The difference is that with Auto-Scroll disabled you are still aware when new log entries are received which is not possible when the log is Paused.

Clearing the Log

Two options are provided for clearing log entries, both via a right-click menu on the log entry list itself.

The Clear Log command sends the clear command (-c) to adb logcat, clearing the currently selected log buffer. This command should be used with caution and requires that you confirm that you wish to proceed with clearing the device log. Clearing the log buffer also clears any entries from ADB WINLOG itself.

Alternatively, the Clear Monitor command will clear the current content of ADB WINLOG alone, without clearing the device log. If you stop and restart the log at this point, the ADB WINLOG will again receive all of those log entries that remain in the device log buffer.

Non-Log Entry Output Area

At the bottom of the ADB WINLOG window is the non-log entry area.

This is used to capture any adb logcat output that is not recognised as a valid log entry item. When such output has been captured, the non-log entry area will be highlighted in red.

Clicking on the notification bar will then expand the area so that you may see the captured output. Most often this will consist of lines of text marking the beginning of the main and system buffers when capturing the default buffer or the notification that the adb daemon required to be started.

Once viewed, the notification area highlight is removed and clicking the notification bar dismisses it back to the bottom of the window. If any further non-log entries are captured, the area will be highlighted once again.