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 are only fully supported from soong builds (ie. via make/mp). In SysUI-studio it falls 25 back to log via Logcat 26- Non-text ProtoLogs are not currently supported with the Shell library (you can't view them with 27 traces in Winscope) 28 29### Kotlin 30 31Protolog tool does not yet have support for Kotlin code (see [b/168581922](https://b.corp.google.com/issues/168581922)). 32For logging in Kotlin, use the [KtProtoLog](/libs/WindowManager/Shell/src/com/android/wm/shell/util/KtProtoLog.kt) 33class which has a similar API to the Java ProtoLog class. 34 35### Enabling ProtoLog command line logging 36Run these commands to enable protologs (in logcat) for WM Core ([list of all core tags](/core/java/com/android/internal/protolog/ProtoLogGroup.java)): 37```shell 38adb shell wm logging enable-text TAG 39adb shell wm logging disable-text TAG 40``` 41 42And these commands to enable protologs (in logcat) for WM Shell ([list of all shell tags](/libs/WindowManager/Shell/src/com/android/wm/shell/protolog/ShellProtoLogGroup.java)): 43```shell 44adb shell dumpsys activity service SystemUIService WMShell protolog enable-text TAG 45adb shell dumpsys activity service SystemUIService WMShell protolog enable-text TAG 46``` 47 48## Winscope Tracing 49 50The Winscope tool is extremely useful in determining what is happening on-screen in both 51WindowManager and SurfaceFlinger. Follow [go/winscope](http://go/winscope-help) to learn how to 52use the tool. This trace will contain all the information about the windows/activities/surfaces on 53screen. 54 55## WindowManager/SurfaceFlinger hierarchy dump 56 57A quick way to view the WindowManager hierarchy without a winscope trace is via the wm dumps: 58```shell 59adb shell dumpsys activity containers 60``` 61 62Likewise, the SurfaceFlinger hierarchy can be dumped for inspection by running: 63```shell 64adb shell dumpsys SurfaceFlinger 65# Search output for "Layer Hierarchy" 66``` 67 68## Tracing global SurfaceControl transaction updates 69 70While Winscope traces are very useful, it sometimes doesn't give you enough information about which 71part of the code is initiating the transaction updates. In such cases, it can be helpful to get 72stack traces when specific surface transaction calls are made, which is possible by enabling the 73following system properties for example: 74```shell 75# Enabling 76adb shell setprop persist.wm.debug.sc.tx.log_match_call setAlpha # matches the name of the SurfaceControlTransaction method 77adb shell setprop persist.wm.debug.sc.tx.log_match_name com.android.systemui # matches the name of the surface 78adb reboot 79adb logcat -s "SurfaceControlRegistry" 80 81# Disabling logging 82adb shell setprop persist.wm.debug.sc.tx.log_match_call \"\" 83adb shell setprop persist.wm.debug.sc.tx.log_match_name \"\" 84adb reboot 85``` 86 87It is not necessary to set both `log_match_call` and `log_match_name`, but note logs can be quite 88noisy if unfiltered. 89 90## Tracing activity starts in the app process 91 92It's sometimes useful to know when to see a stack trace of when an activity starts in the app code 93(ie. if you are repro'ing a bug related to activity starts). You can enable this system property to 94get this trace: 95```shell 96# Enabling 97adb shell setprop persist.wm.debug.start_activity true 98adb reboot 99adb logcat -s "Instrumentation" 100 101# Disabling 102adb shell setprop persist.wm.debug.start_activity \"\" 103adb reboot 104``` 105 106## Dumps 107 108Because the Shell library is built as a part of SystemUI, dumping the state is currently done as a 109part of dumping the SystemUI service. Dumping the Shell specific data can be done by specifying the 110WMShell SysUI service: 111 112```shell 113adb shell dumpsys activity service SystemUIService WMShell 114``` 115 116If information should be added to the dump, either: 117- Update `WMShell` if you are dumping SysUI state 118- Inject `ShellCommandHandler` into your Shell class, and add a dump callback 119 120## Shell commands 121 122It can be useful to add additional shell commands to drive and test specific interactions. 123 124To add a new command for your feature, inject a `ShellCommandHandler` into your class and add a 125shell command handler in your controller. 126 127```shell 128# List all available commands 129adb shell dumpsys activity service SystemUIService WMShell help 130 131# Run a specific command 132adb shell dumpsys activity service SystemUIService WMShell <cmd> <args> ... 133``` 134 135## Debugging in Android Studio 136 137If you are using the [go/sysui-studio](http://go/sysui-studio) project, then you can debug Shell 138code directly from Android Studio like any other app. 139