Scott Main | 300cd26 | 2011-02-08 15:04:42 -0800 | [diff] [blame] | 1 | page.title=Reading and Writing Logs |
Scott Main | 9cf2fa0 | 2011-02-15 18:26:07 -0800 | [diff] [blame] | 2 | parent.title=Debugging |
| 3 | parent.link=index.html |
Robert Ly | ce4d229 | 2010-12-16 17:26:11 -0800 | [diff] [blame] | 4 | @jd:body |
| 5 | |
| 6 | <div id="qv-wrapper"> |
| 7 | <div id="qv"> |
| 8 | <h2>In this document</h2> |
| 9 | |
| 10 | <ol> |
| 11 | <li><a href="#logClass">The Log class</a></li> |
| 12 | |
| 13 | <li><a href="#startingLogcat">Starting LogCat</a></li> |
| 14 | |
| 15 | <li><a href="#filteringOutput">Filtering Log Output</a></li> |
| 16 | |
| 17 | <li><a href="#outputFormat">Controlling Log Output Format</a></li> |
| 18 | |
| 19 | <li><a href="#alternativeBuffers">Viewing Alternative Log Output Buffers</a></li> |
| 20 | |
| 21 | <li><a href="#viewingStd">Viewing stdout and stderr</a></li> |
| 22 | |
| 23 | <li><a href="#DebuggingWebPages">Debugging Web Pages</a></li> |
| 24 | </ol> |
| 25 | </div> |
| 26 | </div> |
| 27 | |
| 28 | <p>The Android logging system provides a mechanism for collecting and viewing system debug |
| 29 | output. Logcat dumps a log of system messages, which include things such as stack traces when the |
| 30 | emulator throws an error and messages that you have written from your application by using the |
| 31 | {@link android.util.Log} class. You can run LogCat through ADB or from DDMS, which allows you to |
| 32 | read the messages in real time.</p> |
| 33 | |
| 34 | <h2 id="logClass">The <code>Log</code> class</h2> |
| 35 | |
| 36 | <p>{@link android.util.Log} is a logging class that you can utilize in your code to print out |
| 37 | messages to the LogCat. Common logging methods include:</p> |
| 38 | |
| 39 | <ul> |
| 40 | <li>{@link android.util.Log#v(String,String)} (verbose)</li> |
| 41 | |
| 42 | <li>{@link android.util.Log#d(String,String)} (debug)</li> |
| 43 | |
| 44 | <li>{@link android.util.Log#i(String,String)} (information)</li> |
| 45 | |
| 46 | <li>{@link android.util.Log#w(String,String)} (warning)</li> |
| 47 | |
| 48 | <li>{@link android.util.Log#e(String,String)} (error)</li> |
| 49 | </ul>For example: |
| 50 | <pre class="no-pretty-print"> |
| 51 | Log.i("MyActivity", "MyClass.getView() — get item number " + position); |
| 52 | </pre> |
| 53 | |
| 54 | <p>The LogCat will then output something like:</p> |
| 55 | <pre class="no-pretty-print"> |
| 56 | I/MyActivity( 1557): MyClass.getView() — get item number 1 |
| 57 | </pre> |
| 58 | |
| 59 | <h2 id="startingLogcat">Using LogCat</h2> |
| 60 | |
| 61 | <p>You can use LogCat from within DDMS or call it on an ADB shell. For more information on how to |
| 62 | use LogCat within DDMS, see <a href="{@docRoot}guide/developing/debugging/ddms.html#logcat">Using |
| 63 | DDMS</a>. To run LogCat, through the ADB shell, the general usage is:</p> |
| 64 | <pre> |
| 65 | [adb] logcat [<option>] ... [<filter-spec>] ... |
| 66 | </pre> |
| 67 | |
| 68 | <p>You can use the <code>logcat</code> command from your development computer or from a remote |
| 69 | adb shell in an emulator/device instance. To view log output in your development computer, you |
| 70 | use</p> |
| 71 | <pre> |
| 72 | $ adb logcat |
| 73 | </pre> |
| 74 | |
| 75 | <p>and from a remote adb shell you use</p> |
| 76 | <pre> |
| 77 | # logcat |
| 78 | </pre> |
| 79 | |
| 80 | <p>The following table describes the <code>logcat</code> command line options:</p> |
| 81 | |
| 82 | <table> |
| 83 | <tr> |
| 84 | <td><code>-c</code></td> |
| 85 | |
| 86 | <td>Clears (flushes) the entire log and exits.</td> |
| 87 | </tr> |
| 88 | |
| 89 | <tr> |
| 90 | <td><code>-d</code></td> |
| 91 | |
| 92 | <td>Dumps the log to the screen and exits.</td> |
| 93 | </tr> |
| 94 | |
| 95 | <tr> |
| 96 | <td><code>-f <filename></code></td> |
| 97 | |
| 98 | <td>Writes log message output to <code><filename></code>. The default is |
| 99 | <code>stdout</code>.</td> |
| 100 | </tr> |
| 101 | |
| 102 | <tr> |
| 103 | <td><code>-g</code></td> |
| 104 | <td>Prints the size of the specified log buffer and exits.</td> |
| 105 | </tr> |
| 106 | |
| 107 | <tr> |
| 108 | <td><code>-n <count></code></td> |
| 109 | |
| 110 | <td>Sets the maximum number of rotated logs to <code><count></code>. The default value |
| 111 | is 4. Requires the <code>-r</code> option.</td> |
| 112 | </tr> |
| 113 | |
| 114 | <tr> |
| 115 | <td><code>-r <kbytes></code></td> |
| 116 | |
| 117 | <td>Rotates the log file every <code><kbytes></code> of output. The default value is |
| 118 | 16. Requires the <code>-f</code> option.</td> |
| 119 | </tr> |
| 120 | |
| 121 | <tr> |
| 122 | <td><code>-s</code></td> |
| 123 | |
| 124 | <td>Sets the default filter spec to silent.</td> |
| 125 | </tr> |
| 126 | |
| 127 | <tr> |
| 128 | <td><code>-v <format></code></td> |
| 129 | |
| 130 | <td>Sets the output format for log messages. The default is <code>brief</code> format. For a |
| 131 | list of supported formats, see <a href="#outputFormat">Controlling Log Output |
| 132 | Format</a>.</td> |
| 133 | </tr> |
| 134 | </table> |
| 135 | |
| 136 | <h3 id="filteringOutput">Filtering Log Output</h3> |
| 137 | |
| 138 | <p>Every Android log message has a <em>tag</em> and a <em>priority</em> associated with it.</p> |
| 139 | |
| 140 | <ul> |
| 141 | <li>The tag of a log message is a short string indicating the system component from which the |
| 142 | message originates (for example, "View" for the view system).</li> |
| 143 | |
| 144 | <li>The priority is one of the following character values, ordered from lowest to highest |
| 145 | priority:</li> |
| 146 | |
| 147 | <li style="list-style: none; display: inline"> |
| 148 | <ul> |
| 149 | <li><code>V</code> — Verbose (lowest priority)</li> |
| 150 | |
| 151 | <li><code>D</code> — Debug</li> |
| 152 | |
| 153 | <li><code>I</code> — Info</li> |
| 154 | |
| 155 | <li><code>W</code> — Warning</li> |
| 156 | |
| 157 | <li><code>E</code> — Error</li> |
| 158 | |
| 159 | <li><code>F</code> — Fatal</li> |
| 160 | |
| 161 | <li><code>S</code> — Silent (highest priority, on which nothing is ever printed)</li> |
| 162 | </ul> |
| 163 | </li> |
| 164 | </ul> |
| 165 | |
| 166 | <p>You can obtain a list of tags used in the system, together with priorities, by running |
| 167 | LogCat and observing the first two columns of each message, given as |
| 168 | <code><priority>/<tag></code>.</p> |
| 169 | |
| 170 | <p>Here's an example of logcat output that shows that the message relates to priority level "I" |
| 171 | and tag "ActivityManager":</p> |
| 172 | <pre> |
| 173 | I/ActivityManager( 585): Starting activity: Intent { action=android.intent.action...} |
| 174 | </pre> |
| 175 | |
| 176 | <p>To reduce the log output to a manageable level, you can restrict log output using <em>filter |
| 177 | expressions</em>. Filter expressions let you indicate to the system the tags-priority |
| 178 | combinations that you are interested in — the system suppresses other messages for the |
| 179 | specified tags.</p> |
| 180 | |
| 181 | <p>A filter expression follows this format <code>tag:priority ...</code>, where <code>tag</code> |
| 182 | indicates the tag of interest and <code>priority</code> indicates the <em>minimum</em> level of |
| 183 | priority to report for that tag. Messages for that tag at or above the specified priority are |
| 184 | written to the log. You can supply any number of <code>tag:priority</code> specifications in a |
| 185 | single filter expression. The series of specifications is whitespace-delimited.</p> |
| 186 | |
| 187 | <p>Here's an example of a filter expression that suppresses all log messages except those with |
| 188 | the tag "ActivityManager", at priority "Info" or above, and all log messages with tag "MyApp", |
| 189 | with priority "Debug" or above:</p> |
| 190 | <pre> |
| 191 | adb logcat ActivityManager:I MyApp:D *:S |
| 192 | </pre> |
| 193 | |
| 194 | <p>The final element in the above expression, <code>*:S</code>, sets the priority level for all |
| 195 | tags to "silent", thus ensuring only log messages with "View" and "MyApp" are displayed. Using |
| 196 | <code>*:S</code> is an excellent way to ensure that log output is restricted to the filters that |
| 197 | you have explicitly specified — it lets your filters serve as a "whitelist" for log |
| 198 | output.</p> |
| 199 | |
| 200 | <p>The following filter expression displays all log messages with priority level "warning" and higher, on all tags:</p> |
| 201 | <pre> |
| 202 | adb logcat *:W |
| 203 | </pre> |
| 204 | |
| 205 | <p>If you're running LogCat from your development computer (versus running it on a |
| 206 | remote adb shell), you can also set a default filter expression by exporting a value for the |
| 207 | environment variable <code>ANDROID_LOG_TAGS</code>:</p> |
| 208 | <pre> |
| 209 | export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S" |
| 210 | </pre> |
| 211 | |
| 212 | <p>Note that <code>ANDROID_LOG_TAGS</code> filter is not exported to the emulator/device |
| 213 | instance, if you are running LogCat from a remote shell or using <code>adb shell |
| 214 | logcat</code>.</p> |
| 215 | |
| 216 | <h3 id="outputFormat">Controlling Log Output Format</h3> |
| 217 | |
| 218 | <p>Log messages contain a number of metadata fields, in addition to the tag and priority. You can |
| 219 | modify the output format for messages so that they display a specific metadata field. To do so, |
| 220 | you use the <code>-v</code> option and specify one of the supported output formats listed |
| 221 | below.</p> |
| 222 | |
| 223 | <ul> |
Christopher Tate | 1df51c6 | 2012-01-03 14:03:06 -0800 | [diff] [blame] | 224 | <li><code>brief</code> — Display priority/tag and PID of the process issuing the |
| 225 | message (the default format).</li> |
Robert Ly | ce4d229 | 2010-12-16 17:26:11 -0800 | [diff] [blame] | 226 | |
| 227 | <li><code>process</code> — Display PID only.</li> |
| 228 | |
| 229 | <li><code>tag</code> — Display the priority/tag only.</li> |
| 230 | |
Robert Ly | ce4d229 | 2010-12-16 17:26:11 -0800 | [diff] [blame] | 231 | <li><code>raw</code> — Display the raw log message, with no other metadata fields.</li> |
| 232 | |
| 233 | <li><code>time</code> — Display the date, invocation time, priority/tag, and PID of the |
Christopher Tate | 1df51c6 | 2012-01-03 14:03:06 -0800 | [diff] [blame] | 234 | process issuing the message.</li> |
| 235 | |
| 236 | <li><code>threadtime</code> — Display the date, invocation time, priority, tag, and |
| 237 | the PID and TID of the thread issuing the message.</li> |
Robert Ly | ce4d229 | 2010-12-16 17:26:11 -0800 | [diff] [blame] | 238 | |
| 239 | <li><code>long</code> — Display all metadata fields and separate messages with blank |
| 240 | lines.</li> |
| 241 | </ul> |
| 242 | |
| 243 | <p>When starting LogCat, you can specify the output format you want by using the |
| 244 | <code>-v</code> option:</p> |
| 245 | <pre> |
| 246 | [adb] logcat [-v <format>] |
| 247 | </pre> |
| 248 | |
| 249 | <p>Here's an example that shows how to generate messages in <code>thread</code> output |
| 250 | format:</p> |
| 251 | <pre> |
| 252 | adb logcat -v thread |
| 253 | </pre> |
| 254 | |
| 255 | <p>Note that you can only specify one output format with the <code>-v</code> option.</p> |
| 256 | |
| 257 | <h3 id="alternativeBuffers">Viewing Alternative Log Buffers</h3> |
| 258 | |
| 259 | <p>The Android logging system keeps multiple circular buffers for log messages, and not all of |
| 260 | the log messages are sent to the default circular buffer. To see additional log messages, you can |
| 261 | run the <code>logcat</code> command with the <code>-b</code> option, to request viewing of an alternate |
| 262 | circular buffer. You can view any of these alternate buffers:</p> |
| 263 | |
| 264 | <ul> |
| 265 | <li><code>radio</code> — View the buffer that contains radio/telephony related |
| 266 | messages.</li> |
| 267 | |
| 268 | <li><code>events</code> — View the buffer containing events-related messages.</li> |
| 269 | |
| 270 | <li><code>main</code> — View the main log buffer (default)</li> |
| 271 | </ul> |
| 272 | |
| 273 | <p>The usage of the <code>-b</code> option is:</p> |
| 274 | <pre> |
| 275 | [adb] logcat [-b <buffer>] |
| 276 | </pre> |
| 277 | |
| 278 | <p>Here's an example of how to view a log buffer containing radio and telephony messages:</p> |
| 279 | <pre> |
| 280 | adb logcat -b radio |
| 281 | </pre><a name="stdout" |
| 282 | id="stdout"></a> |
| 283 | |
| 284 | <h2 id="viewingStd">Viewing stdout and stderr</h2> |
| 285 | |
| 286 | <p>By default, the Android system sends <code>stdout</code> and <code>stderr</code> |
| 287 | (<code>System.out</code> and <code>System.err</code>) output to <code>/dev/null</code>. In |
| 288 | processes that run the Dalvik VM, you can have the system write a copy of the output to the log |
| 289 | file. In this case, the system writes the messages to the log using the log tags |
| 290 | <code>stdout</code> and <code>stderr</code>, both with priority <code>I</code>.</p> |
| 291 | |
| 292 | <p>To route the output in this way, you stop a running emulator/device instance and then use the |
| 293 | shell command <code>setprop</code> to enable the redirection of output. Here's how you do it:</p> |
| 294 | <pre> |
| 295 | $ adb shell stop |
| 296 | $ adb shell setprop log.redirect-stdio true |
| 297 | $ adb shell start |
| 298 | </pre> |
| 299 | |
| 300 | <p>The system retains this setting until you terminate the emulator/device instance. To use the |
| 301 | setting as a default on the emulator/device instance, you can add an entry to |
| 302 | <code>/data/local.prop</code> on the device.</p> |
| 303 | |
| 304 | <h2 id="DebuggingWebPages">Debugging Web Apps</h2> |
| 305 | <p> |
| 306 | If you're developing a web application for Android, you can debug your JavaScript using the console JavaScript APIs, |
| 307 | which output messages to LogCat. For more information, see |
Christopher Tate | 1df51c6 | 2012-01-03 14:03:06 -0800 | [diff] [blame] | 308 | <a href="{@docRoot}guide/webapps/debugging.html">Debugging Web Apps</a>.</p> |