Using the Sampler

The Sampler interrupts a process at regular, timed intervals and samples the segment and instruction pointer of the process on each timer interrupt. It then writes the gathered samples to a file that can later be read and interpreted by the Profiler.

The Sampler samples the process at a rate based on the tick size. To change the sampling rate (you must have superuser privileges to do this), change the tick size with the ticksize utility. A smaller tick size produces a higher sampling rate.

If multiple copies of the Sampler are running, each will record only those samples that apply to the process it's sampling.

Command syntax and examples

sample [options] [command_name [argument...] ]

-b numbufs

Use this number of buffers (default is 2). A buffer holds up to 2000 samples.

-d

Discard all samples that sample collects while it's writing a buffer.

-f file

Save data to this file (default is command_name.smp in the current directory).

-k

Keep samples from all processes in the system. By default, sample keeps samples only from the specified process or command.

-L file

Use the shared executables specified in this file.

-l pid

Use this shared library, where pid is the process ID of the library.

-p pid

Sample this process (default is the specified command).

-q

Be quiet; don't print information messages.

-s seconds

Save this many seconds worth of samples.

-w

Wait for all buffers to fill before writing to file.

Examples

Sample process pid 234 until it terminates or Ctrl-C is pressed:

sample -p 234

Run and sample busy until it terminates, Ctrl-C is pressed, or 10 seconds of samples have been gathered:

sample -s 10 busy

Sample process pid 3 until it terminates, Ctrl-C is pressed, or 60 seconds of samples have been gathered; discard samples that occur while writing data to disk:

sample -p 3 -s 60 -d

Using Sampler options

-b numbufs

If sample can save the buffers to a file faster than it fills them with samples, then only two buffers are necessary. But if sample fills them at a rate close to the rate at which it saves them, then you should use -b to increase the number of buffers. This will allow for temporary slowdowns in the data rate to the file without sample loss. Slowdowns may occur if the filesystem is busy with other users or is running across a busy network. Running out of buffers and discarding samples shouldn't affect the reliability of the results.

-d

After sample writes a buffer to a file, it continues by filling the next available buffer, which you might not want to happen. If you're sampling a process that's in the data path to the sample file itself (e.g. Fsys), writing the buffers can modify the execution path of the process as the data flows through it. To avoid this problem, specify -d and sample will discard all samples it collects while it's writing a buffer.

-f file

The sample utility accumulates data in a linked list of memory buffers and writes the buffers to a file as each buffer fills. By default, sample places the file in the current directory with a name formed from the command name appended with .smp. To specify a directory path and filename, use the -f option.

-L file

The -L option lets you sample shared executables. The specified file consists of one or more lines, each one mapping a shared executable to a code segment. (To determine the code segment, execute the command sin memory.)

A line such as:

/bin/Fsys.floppy A5

tells Fsys that when it encounters code segment A5 it should interpret the debug information encoded in the /bin/Fsys.floppy file.

-l pid

The -l option lets you specify a shared library process. This lets sample get debugging information for the routines in that shared library. When you subsequently use the Profiler, you'll see information for those routines.

-p pid

You can sample a process that's already running by using -p, or you can have sample start and monitor a new process by providing a command name. If you specify a running process, you can stop sample either by specifying -s on the command line or by pressing Ctrl-C during sampling.

-s seconds

The -s option lets you collect samples for a specified number of execution seconds. For example, if a process runs only 10% of the time (perhaps it blocks or is preempted by another process), specifying -s 10 should accumulate 10 seconds of samples after about 100 seconds of elapsed time.

-w

By default, sample writes each buffer once it fills. When you specify -w, sample delays writing individual buffers until all are full. It then writes all buffers at once, and continues collecting samples.

wprof [sample_file]