traceview(1)
NAME
traceview - a graphical viewer for execution logs saved by Android application.
SYNOPSIS
traceview [-r] trace
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.
OPTIONS
-r regression only
TRACEVIEW LAYOUT
When you have a trace log file (generated by adding tracing code to
your application or by DDMS), you can have Traceview load the log files
and display their data in a window visualizes your application in two
panels:
A timeline panel - describes when each thread and method started
and stopped.
A profile panel - provides a summary of what happened inside a
method.
The sections below provide addition information about the traceview
output panes.
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.nativeFinished() and it was
selected in the profile view.
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 "parents" and
called methods as "children." 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.nativeFinished(); looking at the timeline panel shows that
one of those calls took an unusually long time.
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.
Note: 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.
Data File Format
The data file is binary, structured as follows (all values are stored
in little endian order):
* File format:
* header
* record 0
* record 1
* ...
*
* Header format:
* u4 magic 0x574f4c53 ('SLOW')
* 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
The application is expected to parse all of the header fields, then
seek to "offset to data" from the start of the file. From there it just
reads 9-byte records until EOF is reached.
u8 start date/time in usec is the output from gettimeofday(). It's
mainly there so that you can tell if the output was generated yesterday
or three months ago.
method action sits in the two least-significant bits of the method
word. The currently defined meanings are:
0 - method entry
1 - method exit
2 - method "exited" when unrolled by exception handling
3 - (reserved)
An unsigned 32-bit integer can hold about 70 minutes of time in
microseconds.
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.
An example file might look like this:
*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
The following list describes the major sections of a key file:
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 CPU time counters that
are independent for every thread.
threads section
One line per thread. Each line consists of two parts: the thread
ID, 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.
methods section
One line per method entry or exit. A line consists of four pieces,
separated by tab marks: method-ID [TAB] class-name [TAB] method-
name [TAB] 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.
Neither the threads nor methods sections are sorted.
CREATING TRACE FILES
To use Traceview, you need to generate log files containing the trace
information you want to analyze.
There are two ways to generate trace logs:
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.
Use the method profiling feature of DDMS 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 DDMS. 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.
Before you start generating trace logs, be aware of the following
restrictions:
If you are using the Debug class, your device or emulator must have
an SD card and your application must have permission to write to
the SD card.
If you are using DDMS, Android 1.5 devices are not supported.
If you are using DDMS, Android 2.1 and earlier devices must have an
SD card present and your application must have permission to write
to the SD card.
If you are using DDMS, Android 2.2 and later devices do not need an
SD card. The trace log files are streamed directly to your
development machine.
To create the trace files, include the Debug class and call one of the
startMethodTracing() methods. In the call, you specify a base name for
the trace files that the system generates. To stop tracing, call
stopMethodTracing(). These methods start and stop method tracing across
the entire virtual machine. For example, you could call
startMethodTracing() in your activity's onCreate() method, and call
stopMethodTracing() in that activity's onDestroy() method.
// start tracing to "/sdcard/calc.trace"
Debug.startMethodTracing("calc");
// ...
// stop tracing
Debug.stopMethodTracing();
When your application calls startMethodTracing(), 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.
The system then begins buffering the generated trace data, until your
application calls stopMethodTracing(), at which time it writes the
buffered data to the output file. If the system reaches the maximum
buffer size before stopMethodTracing() is called, the system stops
tracing and sends a notification to the console.
Interpreted code will run more slowly when profiling is enabled. Don't
try to generate absolute timings from the profiler results (i.e.
"function X takes 2.5 seconds to run"). The times are only useful in
relation to other profile output, so you can see if changes have made
the code faster or slower.
When using the Android emulator, you must specify an SD card when you
create your AVD because the trace files are written to the SD card.
Your application must have permission to write to the SD card as well.
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:
adb pull /sdcard/calc.trace /tmp
COPYRIGHT
This manual page is licensed under the Apache License, Version 2.0. Copyright (C) 2013 Android Open Source Project Copyright (C) 2013 Jakub Adam <[email protected]>
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
