Measuring application performance from the command line

You can run an application built with profiling instrumentation or run Valgrind Cachegrind on an application from the command line, outside of QNX Momentics IDE. This option gives you more control over how an analysis tool is configured while still allowing you to view the analysis results in the IDE.

Running an instrumented application binary

After building an application binary with either call count or function runtime measurement instrumentation, you can copy the binary to the target. Then, you must set environment variables (as explained below) to direct the data output. At this point, you can run the instrumented binary to generate the profiling data.

Position sampling profiling

With this profiling method, you must set PROFDIR to the directory where the results are to be written. When you do so, the results file is stored at PROFDIR/gmon.out.pid.process_name. If you don't set this environment variable, the file is named simply gmon.out (which makes it hard to distinguish from files produced by other profiling sessions) and is stored in the directory where the program ran.

Note: The program must exit normally for profiling data to be written. If you don't see a results file, you must fix whatever problems are preventing the application from successfully terminating. The other option is to force it to exit normally by attaching a signal handler that calls exit().

When used from the command line, this profiling method has the following restrictions:

Information for individual threads isn't available — In the threads tree shown by the Execution Time view, the profiling results from all threads get combined into one entry.
Results from shared libraries aren't available — The results shown by Execution Time contain runtime estimates for code in shared libraries but simply say @unknown under Location, so you don't know which functions the entries refer to.
No sampling information is collected if you don't run as root — If you don't run the program as root, the process can't attach the necessary interrupt handler to write out position sampling data. This means you'll see only call counts and not function runtime estimates in the results.

Function runtime measurement profiling

With this profiling method, you must set QPROF_FILE to the full path of the file for storing the results. If you define only a filename in this variable, the results file gets written to the directory where the program ran. If you don't define the variable, no results are output. Also, the filename portion must finish with a .ptrace extension so the file can later be imported into the IDE.

Profiling data get written even if the program doesn't exit normally. However, if this happens, some data may be lost because some buffers can't be flushed to the results file. You can force the application to exit normally by attaching a signal handler that calls exit().

The restrictions of individual thread information and results from shared libraries not being available also apply to this profiling method (for details, see the explanation above for position sampling).

Application profiling with kernel event tracing

You can run an application binary built with function instrumentation while performing a kernel event trace, to capture the function entrance and exit events for that application. To do this, you must first set QPROF_KERNEL_TRACE to 1 (to make the kernel start logging events), then run tracelogger in the background (to make this utility start writing the logged events to a trace file). Note that QPROF_FILE must not be defined when the tracing variable is set to 1.

The tracelogger utility must be run for long enough that the application can be started and execute until its normal exit point, or long enough to generate valuable profiling data. Information on the command-line options for setting the output file and tracing time are given in the tracelogger entry in the Utilities Reference.

Viewing results

To view the profiling results, you must either attach the Application Profiler tool to one of the application's processes or wait until the application exits and then copy the results file from the target to the host and import it into the IDE.

Running Valgrind Cachegrind on an application

You can issue a command that tells Valgrind to run Cachegrind on the specified application with certain options and environment variables. For examples of such command lines, see the valgrind entry in the Utilities Reference.

To see backtrace information (i.e., source file names and line numbers) in the analysis results, you must provide Valgrind with an application binary and libraries that contain debug symbols, or with access to the debug symbols in separate .sym files. In the latter case, the symbol files must be kept in the same directory as the libraries (and binary); using LD_LIBRARY_PATH won't work because Valgrind doesn't use the dynamic loader.

The symbol files for SDP components delivered as libraries (e.g., audio drivers, networking protocols, video capture) are available from the QNX Software Center. Some component packages contain the stripped libraries and the debug symbol files. For others, there's a separate package for the symbols. Typically, symbol packages are automatically installed (if you've kept the default QNX Software Center settings), but you should confirm that the symbols that you need have been installed. For more information, see the QNX Software Center User's Guide, available from the QNX download center (http://www.qnx.com/download).

Valgrind produces a log file when it finishes executing the program. To see the analysis results, you must copy the log file from the target to the host, then import it into the IDE. Although the log file is somewhat readable, we recommend viewing the results in the IDE because it presents them in a more readable way and lets you navigate to the related source code.