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](frameworks/base/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 for both WM Core and WM Shell to print to logcat.
37```shell
38adb shell wm logging enable-text NEW_FEATURE
39adb shell wm logging disable-text NEW_FEATURE
40```
41
42## Winscope Tracing
43
44The Winscope tool is extremely useful in determining what is happening on-screen in both
45WindowManager and SurfaceFlinger.  Follow [go/winscope](http://go/winscope-help) to learn how to
46use the tool.
47
48In addition, there is limited preliminary support for Winscope tracing componetns in the Shell,
49which involves adding trace fields to [wm_shell_trace.proto](frameworks/base/libs/WindowManager/Shell/proto/wm_shell_trace.proto)
50file and ensure it is updated as a part of `WMShell#writeToProto`.
51
52Tracing can be started via the shell command (to be added to the Winscope tool as needed):
53```shell
54adb shell cmd statusbar tracing start
55adb shell cmd statusbar tracing stop
56```
57
58## Dumps
59
60Because the Shell library is built as a part of SystemUI, dumping the state is currently done as a
61part of dumping the SystemUI service.  Dumping the Shell specific data can be done by specifying the
62WMShell SysUI service:
63
64```shell
65adb shell dumpsys activity service SystemUIService WMShell
66```
67
68If information should be added to the dump, either:
69- Update `WMShell` if you are dumping SysUI state
70- Inject `ShellCommandHandler` into your Shell class, and add a dump callback
71
72## Debugging in Android Studio
73
74If you are using the [go/sysui-studio](http://go/sysui-studio) project, then you can debug Shell
75code directly from Android Studio like any other app.
76