We have created wrapper tools which launch instrumented applications, collect sample reports, and upload them to a central collection sever based on some simple configuration files. Documentation for these tools is not yet available, but should be coming along soon. Most readers should wait for that documentation rather than fretting over the environment variables described in the next section.
The launchers currently assume that the program was
compiled using -fsampler-random=online. We
should either remove that restriction or document it clearly
here.
The instrumented executable uses a set of environment variables to control sampling and post-execution reporting. Most applications should not need to deal with these directly, and can instead use a launcher as described in the previous section.
The following environment variables influence the behavior of an instrumented executable:
$SAMPLER_EVENT_COUNTDOWNSUsed when the executable was built with
-fsampler-random=offline. Set this to
the name of a file containing pre-generated random
countdowns. See the section called “precompute” for
information on a tool for building these countdown
files.
If not set, countdowns are always initialized to UINT_MAX, effectively disabling sampling.
$SAMPLER_SPARSITYUsed when the executable was built with
-fsampler-random=online or
-fsampler-random=fixed.
For online random sampling, set
this to a positive integer or floating point number: the
mean number of samples skipped between samples taken.
1000, for example, will sample
approximately one instrumentation point per thousand
opportunities.
For fixed random sampling, set this
to a positive integer: the exact number of samples skipped
between samples taken. 1000, for
example, will sample exactly one instrumentation point per
thousand opportunities.
If not set, countdowns are always initialized to UINT_MAX, effectively disabling sampling.
$SAMPLER_SEEDUsed when the executable was built with
-fsampler-random=online. Seeds the
random number generator. In multithreaded code, each new
thread seeds its own generator using this same
value.
If not set, the seed is selected at runtime using
some system entropy source
(e.g. /dev/urandom). In
multithreaded code, each new thread seeds its own
generator using a new seed drawn from this system entropy
source.
$SAMPLER_REPORT_FD, $SAMPLER_FILEIf $SAMPLER_REPORT_FD is set, then it
gives the number of a file descriptor into which the
sampler report will be written at program exit time. This
file descriptor must already be open, and will be closed
once the report is complete.
$SAMPLER_FILE is set, then names a
file which is to receive the report. The named file will
be created if it does not already exist. If the file does
already exist, any existing contents will be
overwritten.
If neither of these environment variables is set, then no post-execution report will be produced. This does not disable sampling while the program runs, but it does mean that the results of the sampling will not be recorded anywhere once the program exits.
If both of these environment variables are set, then
$SAMPLER_REPORT_FD is used and
$SAMPLER_FILE is disregarded.
$SAMPLER_VERBOSEIf $SAMPLER_VERBOSE is set, then
instrumented applications will print some additional CBI
debugging information to standard error. This is intended
as a tool for debugging the instrumentation
infrastructure. The exact messages printed may vary from
release to release.
/usr/local/lib/sampler/tools/precompute
is a tool for producing pre-generated countdowns. This should
be used in conjunction with the
-fsampler-random=offline flag and the
$SAMPLER_EVENT_COUNTDOWNS environment variable.
Before starting the instrumented program:
Set $SAMPLER_SEED to some random seed
integer.
Run precompute
to generate and store random countdowns in
outfileoutfile
Set $SAMPLER_EVENT_COUNTDOWNS to name
this same file when running the instrumented
program.