1# Debugging in the Shell 2 3--- 4 5## Logging & ProtoLogs 6 7The interactions in the Shell can be pretty complicated, so having good logging is crucial to 8debugging problems that arise (especially in dogfood). The Shell uses the same efficient Protolog 9mechanism as WM Core, which can be enabled at runtime on debug devices. 10 11**TLDR** Don’t use Logs or Slogs except for error cases, Protologs are much more flexible, 12easy to add and easy to use 13 14### Adding a new ProtoLog 15Update `ShellProtoLogGroup` to include a new log group (ie. NEW_FEATURE) for the content you want to 16log. ProtoLog log calls mirror Log.v/d/e(), and take a format message and arguments: 17```java 18ProtoLog.v(NEW_FEATURE, "Test log w/ params: %d %s", 1, “a”) 19``` 20This code itself will not compile by itself, but the `protologtool` will preprocess the file when 21building to check the log state (is enabled) before printing the print format style log. 22 23**Notes** 24- ProtoLogs currently only work from soong builds (ie. via make/mp). We need to reimplement the 25 tool for use with SysUI-studio 26- Non-text ProtoLogs are not currently supported with the Shell library (you can't view them with 27 traces in Winscope) 28 29### Enabling ProtoLog command line logging 30Run these commands to enable protologs for both WM Core and WM Shell to print to logcat. 31```shell 32adb shell wm logging enable-text NEW_FEATURE 33adb shell wm logging disable-text NEW_FEATURE 34``` 35 36## Winscope Tracing 37 38The Winscope tool is extremely useful in determining what is happening on-screen in both 39WindowManager and SurfaceFlinger. Follow [go/winscope](http://go/winscope-help) to learn how to 40use the tool. 41 42In addition, there is limited preliminary support for Winscope tracing componetns in the Shell, 43which involves adding trace fields to [wm_shell_trace.proto](frameworks/base/libs/WindowManager/Shell/proto/wm_shell_trace.proto) 44file and ensure it is updated as a part of `WMShell#writeToProto`. 45 46Tracing can be started via the shell command (to be added to the Winscope tool as needed): 47```shell 48adb shell cmd statusbar tracing start 49adb shell cmd statusbar tracing stop 50``` 51 52## Dumps 53 54Because the Shell library is built as a part of SystemUI, dumping the state is currently done as a 55part of dumping the SystemUI service. Dumping the Shell specific data can be done by specifying the 56WMShell SysUI service: 57 58```shell 59adb shell dumpsys activity service SystemUIService WMShell 60``` 61 62If information should be added to the dump, either: 63- Update `WMShell` if you are dumping SysUI state 64- Inject `ShellCommandHandler` into your Shell class, and add a dump callback 65 66## Debugging in Android Studio 67 68If you are using the [go/sysui-studio](http://go/sysui-studio) project, then you can debug Shell 69code directly from Android Studio like any other app. 70