1 page.title=Reading and Writing Logs 2 parent.title=Debugging 3 parent.link=index.html 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}tools/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> 224 <li><code>brief</code> — Display priority/tag and PID of the process issuing the 225 message (the default format).</li> 226 227 <li><code>process</code> — Display PID only.</li> 228 229 <li><code>tag</code> — Display the priority/tag only.</li> 230 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 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> 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 308 <a href="{@docRoot}guide/webapps/debugging.html">Debugging Web Apps</a>.</p> 309
