Merge "Doc change: Debugging section of dev guide restructuring"

1 files changed, 305 insertions, 0 deletions

diff --git a/docs/html/guide/developing/debugging/debugging-log.jd b/docs/html/guide/developing/debugging/debugging-log.jd
new file mode 100644
index 0000000..6ee69c7
--- /dev/null
+++ b/docs/html/guide/developing/debugging/debugging-log.jd
@@ -0,0 +1,305 @@
+page.title=Reading and Writing Log Messages
+@jd:body
+
+<div id="qv-wrapper">
+    <div id="qv">
+      <h2>In this document</h2>
+
+      <ol>
+        <li><a href="#logClass">The Log class</a></li>
+
+        <li><a href="#startingLogcat">Starting LogCat</a></li>
+
+        <li><a href="#filteringOutput">Filtering Log Output</a></li>
+
+        <li><a href="#outputFormat">Controlling Log Output Format</a></li>
+
+        <li><a href="#alternativeBuffers">Viewing Alternative Log Output Buffers</a></li>
+
+        <li><a href="#viewingStd">Viewing stdout and stderr</a></li>
+
+        <li><a href="#DebuggingWebPages">Debugging Web Pages</a></li>
+      </ol>
+    </div>
+  </div>
+
+  <p>The Android logging system provides a mechanism for collecting and viewing system debug
+  output. Logcat dumps a log of system messages, which include things such as stack traces when the
+  emulator throws an error and messages that you have written from your application by using the
+  {@link android.util.Log} class. You can run LogCat through ADB or from DDMS, which allows you to
+  read the messages in real time.</p>
+
+  <h2 id="logClass">The <code>Log</code> class</h2>
+
+  <p>{@link android.util.Log} is a logging class that you can utilize in your code to print out
+  messages to the LogCat. Common logging methods include:</p>
+
+  <ul>
+    <li>{@link android.util.Log#v(String,String)} (verbose)</li>
+
+    <li>{@link android.util.Log#d(String,String)} (debug)</li>
+
+    <li>{@link android.util.Log#i(String,String)} (information)</li>
+
+    <li>{@link android.util.Log#w(String,String)} (warning)</li>
+
+    <li>{@link android.util.Log#e(String,String)} (error)</li>
+  </ul>For example:
+  <pre class="no-pretty-print">
+Log.i("MyActivity", "MyClass.getView() &mdash; get item number " + position);
+</pre>
+
+  <p>The LogCat will then output something like:</p>
+  <pre class="no-pretty-print">
+I/MyActivity( 1557): MyClass.getView() &mdash; get item number 1
+</pre>
+
+  <h2 id="startingLogcat">Using LogCat</h2>
+
+  <p>You can use LogCat from within DDMS or call it on an ADB shell. For more information on how to
+  use LogCat within DDMS, see <a href="{@docRoot}guide/developing/debugging/ddms.html#logcat">Using
+  DDMS</a>. To run LogCat, through the ADB shell, the general usage is:</p>
+  <pre>
+[adb] logcat [&lt;option&gt;] ... [&lt;filter-spec&gt;] ...
+</pre>
+
+  <p>You can use the <code>logcat</code> command from your development computer or from a remote
+  adb shell in an emulator/device instance. To view log output in your development computer, you
+  use</p>
+  <pre>
+$ adb logcat
+</pre>
+
+  <p>and from a remote adb shell you use</p>
+  <pre>
+# logcat
+</pre>
+
+  <p>The following table describes the <code>logcat</code> command line options:</p>
+
+  <table>
+    <tr>
+      <td><code>-c</code></td>
+
+      <td>Clears (flushes) the entire log and exits.</td>
+    </tr>
+
+    <tr>
+      <td><code>-d</code></td>
+
+      <td>Dumps the log to the screen and exits.</td>
+    </tr>
+
+    <tr>
+      <td><code>-f&nbsp;&lt;filename&gt;</code></td>
+
+      <td>Writes log message output to <code>&lt;filename&gt;</code>. The default is
+      <code>stdout</code>.</td>
+    </tr>
+
+    <tr>
+      <td><code>-g</code></td>
+      <td>Prints the size of the specified log buffer and exits.</td>
+    </tr>
+
+    <tr>
+      <td><code>-n&nbsp;&lt;count&gt;</code></td>
+
+      <td>Sets the maximum number of rotated logs to <code>&lt;count&gt;</code>. The default value
+      is 4. Requires the <code>-r</code> option.</td>
+    </tr>
+
+    <tr>
+      <td><code>-r&nbsp;&lt;kbytes&gt;</code></td>
+
+      <td>Rotates the log file every <code>&lt;kbytes&gt;</code> of output. The default value is
+      16. Requires the <code>-f</code> option.</td>
+    </tr>
+
+    <tr>
+      <td><code>-s</code></td>
+
+      <td>Sets the default filter spec to silent.</td>
+    </tr>
+
+    <tr>
+      <td><code>-v&nbsp;&lt;format&gt;</code></td>
+
+      <td>Sets the output format for log messages. The default is <code>brief</code> format. For a
+      list of supported formats, see <a href="#outputFormat">Controlling Log Output
+      Format</a>.</td>
+    </tr>
+  </table>
+
+  <h3 id="filteringOutput">Filtering Log Output</h3>
+
+  <p>Every Android log message has a <em>tag</em> and a <em>priority</em> associated with it.</p>
+
+  <ul>
+    <li>The tag of a log message is a short string indicating the system component from which the
+    message originates (for example, "View" for the view system).</li>
+
+    <li>The priority is one of the following character values, ordered from lowest to highest
+    priority:</li>
+
+    <li style="list-style: none; display: inline">
+      <ul>
+        <li><code>V</code> &mdash; Verbose (lowest priority)</li>
+
+        <li><code>D</code> &mdash; Debug</li>
+
+        <li><code>I</code> &mdash; Info</li>
+
+        <li><code>W</code> &mdash; Warning</li>
+
+        <li><code>E</code> &mdash; Error</li>
+
+        <li><code>F</code> &mdash; Fatal</li>
+
+        <li><code>S</code> &mdash; Silent (highest priority, on which nothing is ever printed)</li>
+      </ul>
+    </li>
+  </ul>
+
+  <p>You can obtain a list of tags used in the system, together with priorities, by running
+  LogCat and observing the first two columns of each message, given as
+  <code>&lt;priority&gt;/&lt;tag&gt;</code>.</p>
+
+  <p>Here's an example of logcat output that shows that the message relates to priority level "I"
+  and tag "ActivityManager":</p>
+  <pre>
+I/ActivityManager(  585): Starting activity: Intent { action=android.intent.action...}
+</pre>
+
+  <p>To reduce the log output to a manageable level, you can restrict log output using <em>filter
+  expressions</em>. Filter expressions let you indicate to the system the tags-priority
+  combinations that you are interested in &mdash; the system suppresses other messages for the
+  specified tags.</p>
+
+  <p>A filter expression follows this format <code>tag:priority ...</code>, where <code>tag</code>
+  indicates the tag of interest and <code>priority</code> indicates the <em>minimum</em> level of
+  priority to report for that tag. Messages for that tag at or above the specified priority are
+  written to the log. You can supply any number of <code>tag:priority</code> specifications in a
+  single filter expression. The series of specifications is whitespace-delimited.</p>
+
+  <p>Here's an example of a filter expression that suppresses all log messages except those with
+  the tag "ActivityManager", at priority "Info" or above, and all log messages with tag "MyApp",
+  with priority "Debug" or above:</p>
+  <pre>
+adb logcat ActivityManager:I MyApp:D *:S
+</pre>
+
+  <p>The final element in the above expression, <code>*:S</code>, sets the priority level for all
+  tags to "silent", thus ensuring only log messages with "View" and "MyApp" are displayed. Using
+  <code>*:S</code> is an excellent way to ensure that log output is restricted to the filters that
+  you have explicitly specified &mdash; it lets your filters serve as a "whitelist" for log
+  output.</p>
+
+  <p>The following filter expression displays all log messages with priority level "warning" and higher, on all tags:</p>
+  <pre>
+adb logcat *:W
+</pre>
+
+  <p>If you're running LogCat from your development computer (versus running it on a
+  remote adb shell), you can also set a default filter expression by exporting a value for the
+  environment variable <code>ANDROID_LOG_TAGS</code>:</p>
+  <pre>
+export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S"
+</pre>
+
+  <p>Note that <code>ANDROID_LOG_TAGS</code> filter is not exported to the emulator/device
+  instance, if you are running LogCat from a remote shell or using <code>adb shell
+  logcat</code>.</p>
+
+  <h3 id="outputFormat">Controlling Log Output Format</h3>
+
+  <p>Log messages contain a number of metadata fields, in addition to the tag and priority. You can
+  modify the output format for messages so that they display a specific metadata field. To do so,
+  you use the <code>-v</code> option and specify one of the supported output formats listed
+  below.</p>
+
+  <ul>
+    <li><code>brief</code> &mdash; Display priority/tag and PID of originating process (the default
+    format).</li>
+
+    <li><code>process</code> &mdash; Display PID only.</li>
+
+    <li><code>tag</code> &mdash; Display the priority/tag only.</li>
+
+    <li><code>thread</code> &mdash; Display process:thread and priority/tag only.</li>
+
+    <li><code>raw</code> &mdash; Display the raw log message, with no other metadata fields.</li>
+
+    <li><code>time</code> &mdash; Display the date, invocation time, priority/tag, and PID of the
+    originating process.</li>
+
+    <li><code>long</code> &mdash; Display all metadata fields and separate messages with blank
+    lines.</li>
+  </ul>
+
+  <p>When starting LogCat, you can specify the output format you want by using the
+  <code>-v</code> option:</p>
+  <pre>
+[adb] logcat [-v &lt;format&gt;]
+</pre>
+
+  <p>Here's an example that shows how to generate messages in <code>thread</code> output
+  format:</p>
+  <pre>
+adb logcat -v thread
+</pre>
+
+  <p>Note that you can only specify one output format with the <code>-v</code> option.</p>
+
+  <h3 id="alternativeBuffers">Viewing Alternative Log Buffers</h3>
+
+  <p>The Android logging system keeps multiple circular buffers for log messages, and not all of
+  the log messages are sent to the default circular buffer. To see additional log messages, you can
+  run the <code>logcat</code> command with the <code>-b</code> option, to request viewing of an alternate
+  circular buffer. You can view any of these alternate buffers:</p>
+
+  <ul>
+    <li><code>radio</code> &mdash; View the buffer that contains radio/telephony related
+    messages.</li>
+
+    <li><code>events</code> &mdash; View the buffer containing events-related messages.</li>
+
+    <li><code>main</code> &mdash; View the main log buffer (default)</li>
+  </ul>
+
+  <p>The usage of the <code>-b</code> option is:</p>
+  <pre>
+[adb] logcat [-b &lt;buffer&gt;]
+</pre>
+
+  <p>Here's an example of how to view a log buffer containing radio and telephony messages:</p>
+  <pre>
+adb logcat -b radio
+</pre><a name="stdout"
+        id="stdout"></a>
+
+  <h2 id="viewingStd">Viewing stdout and stderr</h2>
+
+  <p>By default, the Android system sends <code>stdout</code> and <code>stderr</code>
+  (<code>System.out</code> and <code>System.err</code>) output to <code>/dev/null</code>. In
+  processes that run the Dalvik VM, you can have the system write a copy of the output to the log
+  file. In this case, the system writes the messages to the log using the log tags
+  <code>stdout</code> and <code>stderr</code>, both with priority <code>I</code>.</p>
+
+  <p>To route the output in this way, you stop a running emulator/device instance and then use the
+  shell command <code>setprop</code> to enable the redirection of output. Here's how you do it:</p>
+  <pre>
+$ adb shell stop
+$ adb shell setprop log.redirect-stdio true
+$ adb shell start
+</pre>
+
+  <p>The system retains this setting until you terminate the emulator/device instance. To use the
+  setting as a default on the emulator/device instance, you can add an entry to
+  <code>/data/local.prop</code> on the device.</p>
+
+  <h2 id="DebuggingWebPages">Debugging Web Apps</h2>
+  <p>
+  If you're developing a web application for Android, you can debug your JavaScript using the console JavaScript APIs,
+  which output messages to LogCat. For more information, see
+  <a href="{@docRoot}guide/webapps/debugging.html">Debugging Web Apps</a>.</p>
\ No newline at end of file