Trace Predefined Probe

The -p option which follows trace.ual indicates that the next argument is a string of options to be passed to the UAL. In this case, those options are -g, which indicates that the Java Graphical User Interface (GUI) is to be started; and -v, which causes "verbose" informative output to be generated by the probe. Every predefined probe accepts the option -h, which describes the full set of command-line options available to that probe. So, to display the full set of options for trace.ual, execute:

aprobe -u trace.ual -p -h main

Predefined probes are generally initiated by invoking [aprobe-9.html#MARKER-9-1075 aprobe] explicitly. However, they may also be invoked implicitly by linking your application with libdal.so or using the run_with_aprobe_apo script and specifying the command-line options in a .apo file as described in [aprobe-7.html#MARKER-9-868 Chapter 4, "Loading Probes Without aprobe"].

Configuration File

The configuration file is used to designate which functions in the target application are to be analyzed, and to specify other options. The easiest way to get an initial configuration file is simply to invoke the predefined probe with no options. You'll get a warning about not finding a configuration file, but one will be created.

You can use the [#MARKER-9-1961 Configuration GUI] to create or change the configuration file by specifying the -g option. This provides a point-and-click interface in which to choose your functions and other options and save them in a configuration file. (Note that this GUI can be quite slow for very large applications, so editing the file directly may be more practical in such cases.)

The default name for the probe configuration file is your_program.probe_name.cfg, where your_program stands for the name of your executable application program, and probe_name is the basename of the predefined probe, e.g., trace. For example, if your program is called wilbur.exe and you're using trace.ual, then the default configuration file name would be wilbur.exe.trace.cfg.

The format of the a probe configuration file is:

PROBE CONFIGURATION FILE FOR probe_name VERSION 2.0.0
keyword data
...
keyword data
// This is a comment line

A warning will be given if the very first line of this file isn't valid, but an attempt will be made to use the information provided. The only allowed variations on this header line are the number of blank spaces between the words, and the case of each character.

All keywords in the configuration file are case-insensitive. However, all function or module names are always case-sensitive.

Each line begins with a keyword, or is a continuation line. A line is a continuation line if the previous line ends in a backslash ("\"). The continuation character is treated as a word separator, like a blank.

Comment lines can be interspersed with any other lines. Comment lines are those lines whose first 2 non-blank characters are "//". Comment lines are ignored by probe and are intended only for the benefit of the human reader.

Any invalid line is ignored. An invalid line is one which contains an invalid keyword or value, or has a missing or extraneous word.

Configuration of Selected Functions

The coverage, profile, and trace predefined probes operate by probing functions in the user's application, so the names of those functions must be specified in the configuration file. While each predefined probe uses different keywords to designate which functions to probe, the syntax of the function name itself is the same in all cases. It is exactly the same as the syntax used for a probe itself, as described in [aprobe-6.html#MARKER-9-497 "Specifying Function Names"] and repeated here:

[ [file_name | extern] : ] function_name [ in module_name ]

file_name, function_name, and module_name are all strings that are bounded by quotation marks (that is, ""), which allows each name to contain embedded blank space characters. The file_name and the module_name are optional. If module_name is omitted, the application module is assumed, and the special character "*" can be used to designated every module. The file_name is required only for static (file-local) functions. A colon must exist between the file_name and the function_name. The colon may be surrounded by optional whitespace, and the keyword IN must always be surrounded by whitespace. Examples are:

"my_file":"my_function"
extern:"malloc()" in "libc.so"

In the configuration file for trace.ual, the keyword indicating that a function is to be traced is "Trace", where the cases of the letters is not significant. In the main.trace.cfg file, then should appear one or more lines that look like

Trace "my_file":"my_function"

Predefined probes may have other keywords, such as Trigger, Remove and Snapshot, which are followed by function names. These are described in their corresponding section below. And, note that memwatch.ual does not require specifying application functions this way -- see [#MARKER-9-2173 "Memory Watch Probe: memwatch.ual"].

Configuration GUI

Some, but not all, predefined probes offer a Configuration GUI (Graphical User Interface). The coverage, profile, and trace predefined probes do offer it, but not events, memwatch, nor info

If the -g option is specified to the UAL, the probe starts a Java process to run the Configuration GUI. This provides a point-and-click interface for selecting functions and setting other options which are recorded in the [#MARKER-9-1955 Configuration File]. This interface differs for each probe, but generally consists of several panes in which functions and option settings are selected. At the bottom are Save & Run , Run, Save As, Abort, and Help buttons. Run proceeds with the execution of the program under aprobe with the current configuration; Save updates the configuration file on disk with the current settings; Abort quits the GUI and aborts the aprobe and target application processes; and Help brings up a dialog describing each pane and the other buttons.

Function Selection Interface

The Configuration GUI can be useful for selecting the functions that are to be operated upon by the probe. The "4.predefined" example illustrates this for the trace probe, and this process generally applies to the other probes as well:

Click on the "Pick..." button under the top pane (for Trace, the top pane is labeled as "Traced Functions"). You'll be presented with a list of modules (the executable plus any shared libraries it loads). When you double-click on one of those, it will be replaced with a dialog that lists all the functions in that module. Those on the left have been selected, those on the right have not. Double-clicking on a function name moves it to the other column. When the functions you want to probe from the selected module are listed on the left, click Ok, and list in the configuration gui itself will be updated.

Note: this process can be very slow for large applications with many thousands of symbols (see [#MARKER-9-1931 "Performance Issues"]). In such cases it may be easier to use [aprobe-9.html#MARKER-9-1016 apcgen] or [aprobe-9.html#MARKER-9-1052 apinfo] to generate symbol lists, and edit those lists by preceding them with the keyword. For example:

apsymbols main | sed "s/^/Trace / " >> main.trace.cfg

Note that for memwatch.ual, selecting individual functions isn't necessary. Instead the MemWatch probe displays graphs at run time showing memory usage patterns, and allowing interactive snapshots.

Callable API

You can invoke functions defined by a predefined probe from within your own probes. The interface is defined by the header file in the [../include/ $APROBE/include] directory whose name corresponds to the predefined probe; for example, trace.h is the interface for trace.ual.

The most useful functions are generally at the end of the file: those which enable and disable the probes, and those which log a "snapshot" of the data currently selected. See the comments in each file for details.

Note that there is no info.h file -- its operation is entirely determined by its command-line parameters; and the quick_gui.h file is the only interface to quick_gui.ual, since it defines no probes.

Snapshots

Trace, profile, coverage, statprof and memwatch all provide the ability to take a "snapshot" of the data at a point during a program's execution. A snapshot is simply a dump of the data collected in memory since the start of execution or the previous snapshot. The coverage, memwatch, and trace probes support the keyword SNAPSHOT in the configuration file, with which a function name is specified. For example, in your main.trace.cfg file you would do:

Snapshot extern:"LOCAL_PROC()" On Exit

This is translated into a probe which calls a function to take the snapshot. You can include this in your own probe--call it mytrace.apc--as follows:

 #include "trace.h"
 probe thread {
   probe extern:"LOCAL_PROC()" {
     on_exit
       ap_Trace_DoSnapshot("after LOCAL_PROC");
   }
 }
 Then, compile this probe, using trace.ual as a library:

apc mytrace.apc trace.ual -o mytrace.ual

and then use  mytrace.ual instead of trace.ual to gather data:

aprobe -u mytrace.ual main

Navigation menu