• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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