| 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 |