diff options
| author | Scott Main <smain@google.com> | 2012-06-21 17:14:39 -0700 |
|---|---|---|
| committer | Scott Main <smain@google.com> | 2012-06-21 21:27:30 -0700 |
| commit | 50e990c64fa23ce94efa76b9e72df7f8ec3cee6a (patch) | |
| tree | 52605cd25e01763596477956963fabcd087054b0 /docs/html/guide/developing/debugging/debugging-log.jd | |
| parent | a2860267cad115659018d636bf9203a644c680a7 (diff) | |
Massive clobber of all HTML files in developer docs for new site design
Change-Id: Idc55a0b368c1d2c1e7d4999601b739dd57f08eb3
Diffstat (limited to 'docs/html/guide/developing/debugging/debugging-log.jd')
| -rw-r--r-- | docs/html/guide/developing/debugging/debugging-log.jd | 308 |
1 files changed, 0 insertions, 308 deletions
diff --git a/docs/html/guide/developing/debugging/debugging-log.jd b/docs/html/guide/developing/debugging/debugging-log.jd deleted file mode 100644 index b5b626e9bf3a..000000000000 --- a/docs/html/guide/developing/debugging/debugging-log.jd +++ /dev/null @@ -1,308 +0,0 @@ -page.title=Reading and Writing Logs -parent.title=Debugging -parent.link=index.html -@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() — get item number " + position); -</pre> - - <p>The LogCat will then output something like:</p> - <pre class="no-pretty-print"> -I/MyActivity( 1557): MyClass.getView() — 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 [<option>] ... [<filter-spec>] ... -</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 <filename></code></td> - - <td>Writes log message output to <code><filename></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 <count></code></td> - - <td>Sets the maximum number of rotated logs to <code><count></code>. The default value - is 4. Requires the <code>-r</code> option.</td> - </tr> - - <tr> - <td><code>-r <kbytes></code></td> - - <td>Rotates the log file every <code><kbytes></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 <format></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> — Verbose (lowest priority)</li> - - <li><code>D</code> — Debug</li> - - <li><code>I</code> — Info</li> - - <li><code>W</code> — Warning</li> - - <li><code>E</code> — Error</li> - - <li><code>F</code> — Fatal</li> - - <li><code>S</code> — 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><priority>/<tag></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 — 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 — 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> — Display priority/tag and PID of the process issuing the - message (the default format).</li> - - <li><code>process</code> — Display PID only.</li> - - <li><code>tag</code> — Display the priority/tag only.</li> - - <li><code>raw</code> — Display the raw log message, with no other metadata fields.</li> - - <li><code>time</code> — Display the date, invocation time, priority/tag, and PID of the - process issuing the message.</li> - - <li><code>threadtime</code> — Display the date, invocation time, priority, tag, and - the PID and TID of the thread issuing the message.</li> - - <li><code>long</code> — 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 <format>] -</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> — View the buffer that contains radio/telephony related - messages.</li> - - <li><code>events</code> — View the buffer containing events-related messages.</li> - - <li><code>main</code> — View the main log buffer (default)</li> - </ul> - - <p>The usage of the <code>-b</code> option is:</p> - <pre> -[adb] logcat [-b <buffer>] -</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> |