.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "TRACEVIEW 1"
.TH TRACEVIEW 1 "2017-01-19" "Debian" "Android SDK Tools"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
traceview \- a graphical viewer for execution logs saved by Android application.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
traceview [\-r] trace
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Traceview is a graphical viewer for execution logs that you create by using the
Debug class to log tracing information in your code. Traceview can help you
debug your application and profile its performance.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-r\fR" 4
.IX Item "-r"
regression only
.SH "TRACEVIEW LAYOUT"
.IX Header "TRACEVIEW LAYOUT"
When you have a trace log file (generated by adding tracing code to your
application or by \s-1DDMS\s0), you can have Traceview load the log files and display
their data in a window visualizes your application in two panels:
.Sp
.RS 4
A timeline panel \- describes when each thread and method started and stopped.
.Sp
A profile panel \- provides a summary of what happened inside a method.
.RE
.PP
The sections below provide addition information about the traceview output
panes.
.SS "Timeline Panel"
.IX Subsection "Timeline Panel"
Each thread's execution is shown in its own row, with time increasing to the
right. Each method is shown in another color (colors are reused in a round-robin
fashion starting with the methods that have the most inclusive time). The thin
lines underneath the first row show the extent (entry to exit) of all the calls
to the selected method. The method in this case is LoadListener.\fInativeFinished()\fR
and it was selected in the profile view.
.SS "Profile Panel"
.IX Subsection "Profile Panel"
This view shows a summary of all the time spent in a method. The table shows
both the inclusive and exclusive times (as well as the percentage of the total
time). Exclusive time is the time spent in the method. Inclusive time is the
time spent in the method plus the time spent in any called functions. We refer
to calling methods as \*(L"parents\*(R" and called methods as \*(L"children.\*(R" When a method
is selected (by clicking on it), it expands to show the parents and children.
Parents are shown with a purple background and children with a yellow
background. The last column in the table shows the number of calls to this
method plus the number of recursive calls. The last column shows the number of
calls out of the total number of calls made to that method. In this view, we
can see that there were 14 calls to LoadListener.\fInativeFinished()\fR; looking at
the timeline panel shows that one of those calls took an unusually long time.
.SH "TRACEVIEW FILE FORMAT"
.IX Header "TRACEVIEW FILE FORMAT"
Tracing creates two distinct pieces of output: a data file, which holds the
trace data, and a key file, which provides a mapping from binary identifiers to
thread and method names. The files are concatenated when tracing completes, into
a single .trace file.
.PP
\&\fBNote:\fR The previous version of Traceview did not concatenate these files for
you. If you have old key and data files that you'd still like to trace, you can
concatenate them yourself with cat mytrace.key mytrace.data > mytrace.trace.
.SS "Data File Format"
.IX Subsection "Data File Format"
The data file is binary, structured as follows (all values are stored in little
endian order):
.PP
.Vb 10
\&  * File format:
\&  * header
\&  * record 0
\&  * record 1
\&  * ...
\&  *
\&  * Header format:
\&  * u4 magic 0x574f4c53 (\*(AqSLOW\*(Aq)
\&  * u2 version
\&  * u2 offset to data
\&  * u8 start date/time in usec
\&  *
\&  * Record format:
\&  * u1 thread ID
\&  * u4 method ID | method action
\&  * u4 time delta since start, in usec
.Ve
.PP
The application is expected to parse all of the header fields, then seek to
\&\*(L"offset to data\*(R" from the start of the file. From there it just reads 9\-byte
records until \s-1EOF\s0 is reached.
.PP
u8 start date/time in usec is the output from \fIgettimeofday()\fR. It's mainly there
so that you can tell if the output was generated yesterday or three months ago.
.PP
method action sits in the two least-significant bits of the method word. The
currently defined meanings are:
.PP
.Vb 4
\&  0 \- method entry
\&  1 \- method exit
\&  2 \- method "exited" when unrolled by exception handling
\&  3 \- (reserved)
.Ve
.PP
An unsigned 32\-bit integer can hold about 70 minutes of time in microseconds.
.SS "Key File Format"
.IX Subsection "Key File Format"
The key file is a plain text file divided into three sections. Each section
starts with a keyword that begins with '*'. If you see a '*' at the start of
a line, you have found the start of a new section.
.PP
An example file might look like this:
.PP
.Vb 10
\&  *version
\&  1
\&  clock=global
\&  *threads
\&  1 main
\&  6 JDWP Handler
\&  5 Async GC
\&  4 Reference Handler
\&  3 Finalizer
\&  2 Signal Handler
\&  *methods
\&  0x080f23f8 java/io/PrintStream write ([BII)V
\&  0x080f25d4 java/io/PrintStream print (Ljava/lang/String;)V
\&  0x080f27f4 java/io/PrintStream println (Ljava/lang/String;)V
\&  0x080da620 java/lang/RuntimeException   <init>    ()V
\&  [...]
\&  0x080f630c android/os/Debug startMethodTracing ()V
\&  0x080f6350 android/os/Debug startMethodTracing (Ljava/lang/String;Ljava/lang/String;I)V
\&  *end
.Ve
.PP
The following list describes the major sections of a key file:
.IP "version section" 4
.IX Item "version section"
The first line is the file version number, currently 1. The second line,
clock=global, indicates that we use a common clock across all threads. A future
version may use per-thread \s-1CPU\s0 time counters that are independent for every
thread.
.IP "threads section" 4
.IX Item "threads section"
One line per thread. Each line consists of two parts: the thread \s-1ID,\s0 followed by
a tab, followed by the thread name. There are few restrictions on what a valid
thread name is, so include everything to the end of the line.
.IP "methods section" 4
.IX Item "methods section"
One line per method entry or exit. A line consists of four pieces, separated by
tab marks: method-ID [\s-1TAB\s0] class-name [\s-1TAB\s0] method-name [\s-1TAB\s0] signature. Only
the methods that were actually entered or exited are included in the list. Note
that all three identifiers are required to uniquely identify a method.
.PP
Neither the threads nor methods sections are sorted.
.SH "CREATING TRACE FILES"
.IX Header "CREATING TRACE FILES"
To use Traceview, you need to generate log files containing the trace
information you want to analyze.
.PP
There are two ways to generate trace logs:
.Sp
.RS 4
Include the Debug class in your code and call its methods to start and stop
logging of trace information to disk. This method is very precise because you
can specify in your code exactly where to start and stop logging trace data.
.Sp
Use the method profiling feature of \s-1DDMS\s0 to generate trace logs. This method is
less precise since you do not modify code, but rather specify when to start and
stop logging with a \s-1DDMS.\s0 Although you have less control on exactly where the
data is logged, this method is useful if you don't have access to the
application's code, or if you do not need the precision of the first method.
.RE
.PP
Before you start generating trace logs, be aware of the following restrictions:
.Sp
.RS 4
If you are using the Debug class, your device or emulator must have an \s-1SD\s0 card
and your application must have permission to write to the \s-1SD\s0 card.
.Sp
If you are using \s-1DDMS,\s0 Android 1.5 devices are not supported.
.Sp
If you are using \s-1DDMS,\s0 Android 2.1 and earlier devices must have an \s-1SD\s0 card
present and your application must have permission to write to the \s-1SD\s0 card.
.Sp
If you are using \s-1DDMS,\s0 Android 2.2 and later devices do not need an \s-1SD\s0 card.
The trace log files are streamed directly to your development machine.
.RE
.PP
To create the trace files, include the Debug class and call one of the
\&\fIstartMethodTracing()\fR methods. In the call, you specify a base name for the
trace files that the system generates. To stop tracing, call
\&\fIstopMethodTracing()\fR. These methods start and stop method tracing across the
entire virtual machine. For example, you could call \fIstartMethodTracing()\fR in your
activity's \fIonCreate()\fR method, and call \fIstopMethodTracing()\fR in that activity's
\&\fIonDestroy()\fR method.
.PP
.Vb 5
\&  // start tracing to "/sdcard/calc.trace"
\&  Debug.startMethodTracing("calc");
\&  // ...
\&  // stop tracing
\&  Debug.stopMethodTracing();
.Ve
.PP
When your application calls \fIstartMethodTracing()\fR, the system creates a file
called <trace\-base\-name>.trace. This contains the binary method trace data and
a mapping table with thread and method names.
.PP
The system then begins buffering the generated trace data, until your
application calls \fIstopMethodTracing()\fR, at which time it writes the buffered data
to the output file. If the system reaches the maximum buffer size before
\&\fIstopMethodTracing()\fR is called, the system stops tracing and sends a notification
to the console.
.PP
Interpreted code will run more slowly when profiling is enabled. Don't try to
generate absolute timings from the profiler results (i.e. \*(L"function X takes 2.5
seconds to run\*(R"). The times are only useful in relation to other profile output,
so you can see if changes have made the code faster or slower.
.PP
When using the Android emulator, you must specify an \s-1SD\s0 card when you create
your \s-1AVD\s0 because the trace files are written to the \s-1SD\s0 card. Your application
must have permission to write to the \s-1SD\s0 card as well.
.SH "COPYING TRACE FILES TO A HOST MACHINE"
.IX Header "COPYING TRACE FILES TO A HOST MACHINE"
After your application has run and the system has created your trace files
<trace\-base\-name>.trace on a device or emulator, you must copy those files to
your development computer. You can use adb pull to copy the files. Here's an
example that shows how to copy an example file, calc.trace, from the default
location on the emulator to the /tmp directory on the emulator host machine:
.PP
.Vb 1
\&  adb pull /sdcard/calc.trace /tmp
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This manual page is licensed under the Apache License, Version 2.0.
.PP
Copyright (C) 2013 Android Open Source Project
.PP
Copyright (C) 2013 Jakub Adam <jakub.adam@ktknet.cz>