OLD | NEW |
1 # Logging # | 1 # Logging # |
2 | 2 |
3 [TOC] | 3 [TOC] |
4 | 4 |
5 | 5 |
6 ## Overview | 6 ## Overview |
7 | 7 |
8 Logging used to be done using Android's [android.util.Log] | 8 Logging used to be done using Android's [android.util.Log] |
9 (http://developer.android.com/reference/android/util/Log.html). | 9 (http://developer.android.com/reference/android/util/Log.html). |
10 | 10 |
11 A wrapper on that is now available: org.chromium.base.Log. It is designed to | 11 A wrapper on that is now available: org.chromium.base.Log. It is designed to |
12 write logs as belonging to logical groups going beyond single classes, and to | 12 write logs as belonging to logical groups going beyond single classes, and to |
13 make it easy to switch logging on or off for individual groups. | 13 make it easy to switch logging on or off for individual groups. |
14 | 14 |
15 Usage: | 15 Usage: |
16 | 16 |
17 ```java | 17 ```java |
18 private static final String TAG = "cr.YourModuleTag"; | 18 private static final String TAG = "YourModuleTag"; |
19 ... | 19 ... |
20 Log.i(TAG, "Logged INFO message."); | 20 Log.i(TAG, "Logged INFO message."); |
21 Log.d(TAG, "Some DEBUG info: %s", data); | 21 Log.d(TAG, "Some DEBUG info: %s", data); |
22 ``` | 22 ``` |
23 | 23 |
24 Output: | 24 Output: |
25 | 25 |
26 ``` | 26 ``` |
27 I/cr.YourModuleTag: ( 999): Logged INFO message | 27 I/cr_YourModuleTag: ( 999): Logged INFO message |
28 D/cr.YourModuleTag: ( 999): [MyClass.java:42] Some DEBUG info: data.toString | 28 D/cr_YourModuleTag: ( 999): [MyClass.java:42] Some DEBUG info: data.toString |
29 ``` | 29 ``` |
30 | 30 |
31 Here, **TAG** will be a feature or package name, "MediaRemote" or "NFC" for | 31 Here, **TAG** will be a feature or package name, "MediaRemote" or "NFC" for |
32 example. In most cases, the class name is not needed. | 32 example. In most cases, the class name is not needed. It will be prepended by |
| 33 the "cr_" prefix to make obvious which logs are coming from Chrome. |
33 | 34 |
34 ### Verbose and Debug logs have special handling ### | 35 ### Verbose and Debug logs have special handling ### |
35 | 36 |
36 * `Log.v` and `Log.d` Calls made using `org.chromium.base.Log` are stripped | 37 * `Log.v` and `Log.d` Calls made using `org.chromium.base.Log` are stripped |
37 out of production binaries using Proguard. There is no way to get those logs | 38 out of production binaries using Proguard. There is no way to get those logs |
38 in release builds. | 39 in release builds. |
39 | 40 |
40 * The file name and line number will be prepended to the log message. | 41 * The file name and line number will be prepended to the log message. |
41 For higher priority logs, those are not added for performance concerns. | 42 For higher priority logs, those are not added for performance concerns. |
42 | 43 |
43 ### An exception trace is printed when the exception is the last parameter ### | 44 ### An exception trace is printed when the exception is the last parameter ### |
44 | 45 |
45 As with `java.util.Log`, putting a throwable as last parameter will dump the | 46 As with `java.util.Log`, putting a throwable as last parameter will dump the |
46 corresponding stack trace: | 47 corresponding stack trace: |
47 | 48 |
48 ```java | 49 ```java |
49 Log.i(TAG, "An error happened: %s", e) | 50 Log.i(TAG, "An error happened: %s", e) |
50 ``` | 51 ``` |
51 | 52 |
52 ``` | 53 ``` |
53 I/cr.YourModuleTag: ( 999): An error happened: This is the exception's message | 54 I/cr_YourModuleTag: ( 999): An error happened: This is the exception's message |
54 I/cr.YourModuleTag: ( 999): java.lang.Exception: This is the exception's message | 55 I/cr_YourModuleTag: ( 999): java.lang.Exception: This is the exception's message |
55 I/cr.YourModuleTag: ( 999): at foo.bar.MyClass.test(MyClass.java:42) | 56 I/cr_YourModuleTag: ( 999): at foo.bar.MyClass.test(MyClass.java:42) |
56 I/cr.YourModuleTag: ( 999): ... | 57 I/cr_YourModuleTag: ( 999): ... |
57 ``` | 58 ``` |
58 | 59 |
59 Having the exception as last parameter doesn't prevent it from being used for | 60 Having the exception as last parameter doesn't prevent it from being used for |
60 string formatting. | 61 string formatting. |
61 | 62 |
62 ## Logging Best Practices | 63 ## Logging Best Practices |
63 | 64 |
64 ### Rule #1: Never log PII (Personal Identification Information): | 65 ### Rule #1: Never log PII (Personal Identification Information): |
65 | 66 |
66 This is a huge concern, because other applications can access the log and | 67 This is a huge concern, because other applications can access the log and |
(...skipping 113 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
180 ```java | 181 ```java |
181 Log.d(TAG, "fields [%s,%s,%s]", value1, value2, value3); | 182 Log.d(TAG, "fields [%s,%s,%s]", value1, value2, value3); |
182 ``` | 183 ``` |
183 | 184 |
184 ## Filtering logs | 185 ## Filtering logs |
185 | 186 |
186 Logcat allows filtering by specifying tags and the associated level: | 187 Logcat allows filtering by specifying tags and the associated level: |
187 | 188 |
188 ```shell | 189 ```shell |
189 adb logcat [TAG_EXPR:LEVEL]... | 190 adb logcat [TAG_EXPR:LEVEL]... |
190 adb logcat cr.YourModuleTag:D *:S | 191 adb logcat cr_YourModuleTag:D *:S |
191 ``` | 192 ``` |
192 | 193 |
193 This shows only logs having a level higher or equal to DEBUG for | 194 This shows only logs having a level higher or equal to DEBUG for |
194 `cr.YourModuleTag`, and SILENT (nothing is logged at this level or higher, so it | 195 `cr_YourModuleTag`, and SILENT (nothing is logged at this level or higher, so it |
195 silences the tags) for everything else. You can persist a filter by setting an | 196 silences the tags) for everything else. You can persist a filter by setting an |
196 environment variable: | 197 environment variable: |
197 | 198 |
198 ```shell | 199 ```shell |
199 export ANDROID_LOG_TAGS="cr.YourModuleTag:D *:S" | 200 export ANDROID_LOG_TAGS="cr_YourModuleTag:D *:S" |
200 ``` | 201 ``` |
201 | 202 |
202 For more, see the [related page on developer.android.com] | 203 For more, see the [related page on developer.android.com] |
203 (http://developer.android.com/tools/debugging/debugging-log.html#filteringOutput
) | 204 (http://developer.android.com/tools/debugging/debugging-log.html#filteringOutput
) |
OLD | NEW |