The command line tools provide a way to sample applications and generate reports when the graphical user interface can not be used, for example, when you are not working in a graphical environment, or in a scripted environment. Or if you simply prefer to work from the command line.
Applications are sampled using the sample command in the Acumem Freja package, usually installed as /opt/acumem/freja/bin/sample. The only required arguments are the mode of operation and the information needed to start or identify the application:
$ sample -r application and arguments
Run application and
arguments
and sample it, for example,
$ sample -r ./myapp arg1
to sample the command myapp arg1. The
application is sampled from the start until it terminates.
The -r option must be the last option to the sample command on the command line. All options after the -r option are interpreted as options to the application.
Note that the sampler will only sample the process started by the command you specify, it will not sample any processes that the process starts in turn. This means that if you, for example, specify a script that starts an application, only the script will be sampled and not the application.
$ sample -p PID
Sample the already running process with process id
PID
. The process is
sampled until it terminates or until the user stops the sampling.
This mode of operation is useful to sample a process without having to restart it or to sample only a part of its execution, for example, if an application has a long start up time but you are not interested in the start up code.
$ sample -w application name
Sample the already running process
with application name
as part of its name. If there is no matching process the sampler
waits for one to start and then samples it. The process is sampled
until it terminates or until the user stops the sampling.
This is a convenient way to sample an already running process without having to look up its process id, or to sample an application started by a script by first starting the sampler and then running the script.
If there are multiple processes matching the specified name the sample command exits with an error message and no sampling is done.
When the sample command waits for a matching process to start it periodically polls for such a process. This means that part of the application startup may be executed before the sample command notices the process, and that that part of the execution therefore is not sampled.
You can delay the start of the sampling by a specified number of
seconds using
the -d delay
option to
the sample command. The start of the sampling will
then be delayed
by delay
seconds. This
may be useful, for example, if you want to start the application
using sample -r but don't want to sample the
application start up.
You can also start the sampling when a specified function is executed
with the --start-at-function
function
option, or at a specified
address with
the --start-at-address address
option. You can also start the sampling after the function or address
has been executed a number of times using
the --start-at-ignore count
option. See Section 2.5.2, “Sampling Start Conditions” for more
information.
If the part of the application run you intend to sample takes at
least 5 minutes to execute, you can enable burst sampling to reduce
the sampling overhead. This is done with
the -b execution time
option.
The execution time
argument should be the estimated execution time without sampling in
minutes of the part of the application that you intend to sample. For
example, to sample an application that takes 30 minutes to run
without sampling cases:
$ sample -b 30 -r application and arguments
See Section 2.5.1, “Burst Sampling” for more information about burst sampling.
When you start the sampler with the -r option to the sample command the application is started in the same terminal as the sampler, and there is no way to stop sampling without terminating the application.
When you start the sampler with the -p or -w options you get a sampler command prompt. The sampler only supports one command, q, which stops the sampling but leaves the application running.
Sometimes the sampler will not be able to stop the sampling immediately. This happens if a sampled thread is waiting in a system call. If this happens you can try to "activate" the application to get the thread to finish the system call, for example, if the application has a command line interface and is waiting for user input, entering a command may help.
If that does not help, you can force a detach by giving the sampler the q command one more time. Doing this will cause a small memory leak in the sampled process, but that will usually not cause any problems.
In very rare cases it may not be possibly to stop the sampling without corrupting the sampled application. You will get a warning if that is the case.
You can also tell the sampler to automatically stop the sampling
after a preset number of seconds by specifying the -t
duration
option to
the sample command. The sampling will then
automatically be stopped after
duration
seconds. If
the process was started using the -r option, the
process will also be terminated.
In the same way as when starting the sampling at a function or
address, you can stop the sampling at a function or address with
the --stop-at-function
function
,
--stop-at-address address
and
--stop-at-ignore count
options. See Section 2.5.3, “Sampling Stop Conditions” for more
information.
By default the sample command will generate a
sample file named sample.smp
in the current
directory. If you would like a different file name you can specify
the -o filename
option
to the sample
command. The sample command will overwrite any
existing sample file with the same name without asking.
The sampler will by default collect information for analyzing the
application's behavior with 64-byte cache lines, since
this is the most common line size. If the cache you are optimizing
your application for uses a different line size, you can specify the
line size with the -l line
sizes
option to the sample
command.
For example, if you want to produce a sample file that allows analysis for both 64-byte and 128-byte cache lines:
$ sample -l 64,128 -r application
You must specify all line sizes for which you will later generate reports based on this sampling.
If you experience incorrect execution or crashes in the sampled program, try passing the --safe-stack option to the sample command, see Section 2.5.4.2, “Disabling Application Stack Use by the Sampler”.
After sampling your application the sampler will have created a
sample file, by default named sample.smp
in the
current working directory.
To generate a report from this sample file you run it through
the report command found in the Acumem Freja package,
usually installed as
/opt/acumem/freja/bin/report.
The name of the sample file has to be specified with the
-i filename
option:
$ report -i sample.smp
The report command will by default create a report
file named report.tsr
in the current working
directory.
The advice in the report depends on the cache configuration. Some data structures or code sections may, for example, work well with a processor model with a large cache but have problems with another processor model with a smaller cache, or they may work well in the L2 cache but have problems in the smaller L1 cache. To get relevant advice for your application and hardware, you have to specify which processor and cache level you want to optimize for.
The processor model may be specified with the --cpu
model
option. By default the
processor model of computer you run the report
tool on is selected. A list of available processor models can be
printed by specifying help as the model name.
The cache level to analyze is selected using the
$ report --level level
option. Acumem Freja will analyze the highest cache level by
default.
It is possible to override parts of a CPU model using options to explicitly set cache size and line size. Refer to report(1) for a description of all available options.
![]() | Note |
---|---|
Always specify a processor model and cache level that matches the intended target as closely as possible. Not all model parameters can be overridden at the command line and some of these parameters depend on the cache level. |
For example, to analyze the application's behavior with respect to the first level data cache in an Intel Core 2 Quad with 12 MB L2 cache you could use the following command line:
$ report --cpu intel/yorkfield_4_12288 --level 1 -i sample.smp
![]() | Note |
---|---|
You can only use line sizes that the sampler was told to sample when it generated the sample file, by default 64 bytes. |
If you want a different name than
report.tsr
for the report file you can
specify a different name with the -o
name
option to the
report command.
For example, to generate a report file named
after-opt.tsr
:
$ report -i sample.smp -o after-opt.tsr
The report generator will try to look up source code files in the
location specified in the debug information of the
application. However, if the source code has been moved since the
application was compiled, you will have to specify the new location
of the source with the -s source
directory
option to get a source code view in
the report. If multiple parts of the source code have been moved you
can specify the -s option multiple times.
If the application binaries have been moved from where they were
during sampling, the report generator will need to be told the new
location to be able to find source code references as described
above. The -b filename
option can be used to name the moved
binaries. The -b option can be specified multiple
times if multiple files have been moved, for example, if both the
binary and a shared library it uses has been moved.
If you do not specify anything else the generated report will include
all locations in the program that are responsible for at least one
percent of all cache line fetches, write-backs or upgrades. For a
large application this may lead to an excessively large report. To
limit the report to issues that contribute to at least a certain
percentage of the total cache line fetches of the application,
specify
the -p percentage
option to the report command.
For example, if you are only interested in issues contributing to at least 5% of the total cache line fetches of the application you could run:
$ report -p 5 -i sample.smp
Once you have created a report you can use the view command found in the Acumem Freja package to view it. It is usually installed as /opt/acumem/freja/bin/view.
The view command requires the filename of the report
to be specified with the -i option. For example, to
view a report with the name report.tsr
you would
use the following command:
$ view -i report.tsr
The report viewer actually starts a web server serving the report as HTML pages on a port on the local machine, and also starts a web browser displaying the report. The web server detects when the report is closed in the browser and will then automatically quit, by default 10 seconds after the report has been closed.
If you do not want the view command to start a new web browser you can give it the --no-browser option. It will then only start the web server and print a URL that you can use to view the report. Note that the port serving the report is only accessible from the computer on which the view command is run, so you can not view the report from a browser on another computer.
By default the view command will start the web server on an arbitrary free port on the computer it is running on. If you want the web server to use a specific port you can specify it using the --port option.
For example, to start the web server serving the
report report.tsr
on port 2000 without starting a
browser, you would run this command:
$ view -i report.tsr --port 2000 --no-browser
To protect the report from being viewed by other users on the same computer, the URL used to open the report contains a randomly generated password. Once you have opened the report in a browser the password becomes invalid, so you can not open the report again in another browser. If you need to do that simply run the view command again.
The view command will try to start the default
browser on the system. If you wish to view the report in another
browser, or if the command fails to find a browser, you can set
the BROWSER
environment variable to the browser that
should be used.