• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1page.title=Reading and Writing Logs
2parent.title=Debugging
3parent.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">
51Log.i("MyActivity", "MyClass.getView() &mdash; get item number " + position);
52</pre>
53
54  <p>The LogCat will then output something like:</p>
55  <pre class="no-pretty-print">
56I/MyActivity( 1557): MyClass.getView() &mdash; 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 [&lt;option&gt;] ... [&lt;filter-spec&gt;] ...
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&nbsp;&lt;filename&gt;</code></td>
97
98      <td>Writes log message output to <code>&lt;filename&gt;</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&nbsp;&lt;count&gt;</code></td>
109
110      <td>Sets the maximum number of rotated logs to <code>&lt;count&gt;</code>. The default value
111      is 4. Requires the <code>-r</code> option.</td>
112    </tr>
113
114    <tr>
115      <td><code>-r&nbsp;&lt;kbytes&gt;</code></td>
116
117      <td>Rotates the log file every <code>&lt;kbytes&gt;</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&nbsp;&lt;format&gt;</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> &mdash; Verbose (lowest priority)</li>
150
151        <li><code>D</code> &mdash; Debug</li>
152
153        <li><code>I</code> &mdash; Info</li>
154
155        <li><code>W</code> &mdash; Warning</li>
156
157        <li><code>E</code> &mdash; Error</li>
158
159        <li><code>F</code> &mdash; Fatal</li>
160
161        <li><code>S</code> &mdash; 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>&lt;priority&gt;/&lt;tag&gt;</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>
173I/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 &mdash; 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>
191adb 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 &mdash; 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>
202adb 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>
209export 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> &mdash; Display priority/tag and PID of originating process (the default
225    format).</li>
226
227    <li><code>process</code> &mdash; Display PID only.</li>
228
229    <li><code>tag</code> &mdash; Display the priority/tag only.</li>
230
231    <li><code>thread</code> &mdash; Display process:thread and priority/tag only.</li>
232
233    <li><code>raw</code> &mdash; Display the raw log message, with no other metadata fields.</li>
234
235    <li><code>time</code> &mdash; Display the date, invocation time, priority/tag, and PID of the
236    originating process.</li>
237
238    <li><code>long</code> &mdash; 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 &lt;format&gt;]
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>
251adb 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> &mdash; View the buffer that contains radio/telephony related
265    messages.</li>
266
267    <li><code>events</code> &mdash; View the buffer containing events-related messages.</li>
268
269    <li><code>main</code> &mdash; 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 &lt;buffer&gt;]
275</pre>
276
277  <p>Here's an example of how to view a log buffer containing radio and telephony messages:</p>
278  <pre>
279adb 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>