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.4.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 option 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.4.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.4.4.2, “Disabling Application Stack Use by the Sampler”.

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. 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.

	Note
	Detecting the current cpu and cache hierarchy does not work reliably in virtualized environments. In this case you need to manuall supply the number of caches that Freja shall assume to be present.

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

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. For example, if you are using the bash shell and want to use the google-chrome browser, you can use this command:

$ export BROWSER=google-chrome

Freja has been verified to work with Internet Explorer, Firefox and Google Chrome. If you are using a different browser and experience problems viewing the report, try using one of the supported browsers instead.

The Firefox browser, and possibly other Gecko-based browsers, have a default behaviour when used on multiple computers in an X environment that is confusing, and that does not work well with the view command.

When you start a Firefox process and specify a URL to open, the process will by default look for other Firefox processes running in the same X server, and if one is found open the URL in that process's window even if that process is running on a different computer.

This does not work with the view command for a couple of reasons. The URL used to connect to the report web server uses the address localhost to refer to the web server, so if the report is opened on a another computer the URL will refer to the wrong computer. Also, since the report web server only accepts connections from the computer it is running on, Firefox would not be able to open the report from another computer even if it managed to resolve the URL to the correct computer.

The easiest way to avoid this problem is to set the MOZ_NO_REMOTE environment variable to 1 before you run the view command. For example, if you are using the bash shell, you can use this command:

$ export MOZ_NO_REMOTE=1

This forces Firefox to start a new process on the computer where the command is run, even if there are already Firefox processes running on other computers. However, it will also prevent you from launching multiple browsers viewing the same report on the same computer, so you will have to close the report you are viewing before you can open another report on the same computer.