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}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> 224 <li><code>brief</code> — Display priority/tag and PID of originating process (the default 225 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>thread</code> — Display process:thread and priority/tag only.</li> 232 233 <li><code>raw</code> — Display the raw log message, with no other metadata fields.</li> 234 235 <li><code>time</code> — Display the date, invocation time, priority/tag, and PID of the 236 originating process.</li> 237 238 <li><code>long</code> — Display all metadata fields and separate messages with blank 239 lines.</li> 240 </ul> 241 242 <p>When starting LogCat, you can specify the output format you want by using the 243 <code>-v</code> option:</p> 244 <pre> 245 [adb] logcat [-v <format>] 246 </pre> 247 248 <p>Here's an example that shows how to generate messages in <code>thread</code> output 249 format:</p> 250 <pre> 251 adb logcat -v thread 252 </pre> 253 254 <p>Note that you can only specify one output format with the <code>-v</code> option.</p> 255 256 <h3 id="alternativeBuffers">Viewing Alternative Log Buffers</h3> 257 258 <p>The Android logging system keeps multiple circular buffers for log messages, and not all of 259 the log messages are sent to the default circular buffer. To see additional log messages, you can 260 run the <code>logcat</code> command with the <code>-b</code> option, to request viewing of an alternate 261 circular buffer. You can view any of these alternate buffers:</p> 262 263 <ul> 264 <li><code>radio</code> — View the buffer that contains radio/telephony related 265 messages.</li> 266 267 <li><code>events</code> — View the buffer containing events-related messages.</li> 268 269 <li><code>main</code> — View the main log buffer (default)</li> 270 </ul> 271 272 <p>The usage of the <code>-b</code> option is:</p> 273 <pre> 274 [adb] logcat [-b <buffer>] 275 </pre> 276 277 <p>Here's an example of how to view a log buffer containing radio and telephony messages:</p> 278 <pre> 279 adb logcat -b radio 280 </pre><a name="stdout" 281 id="stdout"></a> 282 283 <h2 id="viewingStd">Viewing stdout and stderr</h2> 284 285 <p>By default, the Android system sends <code>stdout</code> and <code>stderr</code> 286 (<code>System.out</code> and <code>System.err</code>) output to <code>/dev/null</code>. In 287 processes that run the Dalvik VM, you can have the system write a copy of the output to the log 288 file. In this case, the system writes the messages to the log using the log tags 289 <code>stdout</code> and <code>stderr</code>, both with priority <code>I</code>.</p> 290 291 <p>To route the output in this way, you stop a running emulator/device instance and then use the 292 shell command <code>setprop</code> to enable the redirection of output. Here's how you do it:</p> 293 <pre> 294 $ adb shell stop 295 $ adb shell setprop log.redirect-stdio true 296 $ adb shell start 297 </pre> 298 299 <p>The system retains this setting until you terminate the emulator/device instance. To use the 300 setting as a default on the emulator/device instance, you can add an entry to 301 <code>/data/local.prop</code> on the device.</p> 302 303 <h2 id="DebuggingWebPages">Debugging Web Apps</h2> 304 <p> 305 If you're developing a web application for Android, you can debug your JavaScript using the console JavaScript APIs, 306 which output messages to LogCat. For more information, see 307 <a href="{@docRoot}guide/webapps/debugging.html">Debugging Web Apps</a>.</p>
