README.md
1# ProtoLogTool
2
3Code transformation tool and viewer for ProtoLog.
4
5## What does it do?
6
7ProtoLogTool incorporates three different modes of operation:
8
9### Code transformation
10
11Command: `protologtool transform-protolog-calls
12 --protolog-class <protolog class name>
13 --protolog-impl-class <protolog implementation class name>
14 --loggroups-class <protolog groups class name>
15 --loggroups-jar <config jar path>
16 --output-srcjar <output.srcjar>
17 [<input.java>]`
18
19In this mode ProtoLogTool transforms every ProtoLog logging call in form of:
20```java
21ProtoLog.x(ProtoLogGroup.GROUP_NAME, "Format string %d %s", value1, value2);
22```
23into:
24```java
25if (ProtoLogImpl.isEnabled(GROUP_NAME)) {
26 int protoLogParam0 = value1;
27 String protoLogParam1 = String.valueOf(value2);
28 ProtoLogImpl.x(ProtoLogGroup.GROUP_NAME, 123456, 0b0100, "Format string %d %s or null", protoLogParam0, protoLogParam1);
29}
30```
31where `ProtoLog`, `ProtoLogImpl` and `ProtoLogGroup` are the classes provided as arguments
32 (can be imported, static imported or full path, wildcard imports are not allowed) and, `x` is the
33 logging method. The transformation is done on the source level. A hash is generated from the format
34 string, log level and log group name and inserted after the `ProtoLogGroup` argument. After the hash
35 we insert a bitmask specifying the types of logged parameters. The format string is replaced
36 by `null` if `ProtoLogGroup.GROUP_NAME.isLogToLogcat()` returns false. If `ProtoLogGroup.GROUP_NAME.isEnabled()`
37 returns false the log statement is removed entirely from the resultant code. The real generated code is inlined
38 and a number of new line characters is added as to preserve line numbering in file.
39
40Input is provided as a list of java source file names. Transformed source is saved to a single
41source jar file. The ProtoLogGroup class with all dependencies should be provided as a compiled
42jar file (config.jar).
43
44### Viewer config generation
45
46Command: `generate-viewer-config
47 --protolog-class <protolog class name>
48 --loggroups-class <protolog groups class name>
49 --loggroups-jar <config jar path>
50 --viewer-conf <viewer.json>
51 [<input.java>]`
52
53This command is similar in it's syntax to the previous one, only instead of creating a processed source jar
54it writes a viewer configuration file with following schema:
55```json
56{
57 "version": "1.0.0",
58 "messages": {
59 "123456": {
60 "message": "Format string %d %s",
61 "level": "ERROR",
62 "group": "GROUP_NAME",
63 "at": "com\/android\/server\/example\/Class.java"
64 }
65 },
66 "groups": {
67 "GROUP_NAME": {
68 "tag": "TestLog"
69 }
70 }
71}
72
73```
74
75### Binary log viewing
76
77Command: `read-log --viewer-conf <viewer.json> <wm_log.pb>`
78
79Reads the binary ProtoLog log file and outputs a human-readable LogCat-like text log.
80
81## What is ProtoLog?
82
83ProtoLog is a generic logging system created for the WindowManager project. It allows both binary and text logging
84and is tunable in runtime. It consists of 3 different submodules:
85* logging system built-in the Android app,
86* log viewer for reading binary logs,
87* a code processing tool.
88
89ProtoLog is designed to reduce both application size (and by that memory usage) and amount of resources needed
90for logging. This is achieved by replacing log message strings with their hashes and only loading to memory/writing
91full log messages when necessary.
92
93### Text logging
94
95For text-based logs Android LogCat is used as a backend. Message strings are loaded from a viewer config
96located on the device when needed.
97
98### Binary logging
99
100Binary logs are saved as Protocol Buffers file. They can be read using the ProtoLog tool or specialised
101viewer like Winscope.
102
103## How to use ProtoLog?
104
105### Adding a new logging group or log statement
106
107To add a new ProtoLogGroup simple create a new enum ProtoLogGroup member with desired parameters.
108
109To add a new logging statement just add a new call to ProtoLog.x where x is a log level.
110
111After doing any changes to logging groups or statements you should build the project and follow instructions printed by the tool.
112
113## How to change settings on device in runtime?
114Use the `adb shell su root cmd window logging` command. To get help just type
115`adb shell su root cmd window logging help`.
116
117
118
119
120