NAME
er_kernel - generate an Analyzer experiment on the Solaris
kernel
SYNOPSIS
er_kernel args [load-command]
AVAILABILITY
Solaris systems with DTrace supported
DESCRIPTION
The er_kernel command can generate an experiment from the
Solaris kernel, using the DTrace functionality provided with
some Solaris releases. The data may be examined with a GUI
program, analyzer, or a command-line version, er_print.
The er_kernel command may be used only by a user with DTrace
privileges.
If an optional command to provide a load is given, er_kernel
forks, and the child sleeps for a quiet period, then exe-
cutes the command to provide a load. When the child exits,
er_kernel continues for another quiet period, and then
exits. The duration of the quiet period may be specified by
a -q argument.
If an optional -t argument is given, er_kernel will collect
data according to the -t argument, and then exit.
If neither is specified, er_kernel will run until ter-
minated. It may always be terminated by ctrl-C (SIGINT), or
by using the kill command and sending SIGINT, SIGQUIT, or
SIGTERM to the er_kernel process.
ARGUMENTS
If invoked with no arguments, print a usage message.
-p option
Collect clock-based profiles. The allowed values of
option are:
Value Meaning
off turn off clock-based profiling
on turn on clock-based profiling with the
default profiling interval of approximately
10 milliseconds
lo[w] turn on clock-based profiling with the low-
resolution profiling interval of approxi-
mately 100 milliseconds
hi[gh] turn on clock-based profiling with the high-
resolution profiling interval of approxi-
mately 1 millisecond
n turn on clock-based profiling with a profil-
ing interval of n.
The value may be an integer or floating-point
number, with a suffix of u specifying
microseconds, or m specifying milliseconds.
If no suffix is used, the value will be
assumed to be in milliseconds.
If the value is smaller than the system clock
profiling minimum it is set to the minimum;
if it is not a multiple of the clock profil-
ing resolution it is rounded down to the
nearest multiple of the clock profiling reso-
lution. If it exceeds the clock profiling
maximum, an error is reported. If it is
negative, an error is reported. If it is
zero, clock profiling is turned off.
If no explicit -p off argument is given, clock-based
profiling is turned on.
-T { pid/tid | 0/did }
Profile for the specified thread (tid) of the given
process (pid), or profile for the specified internal-
kernel-thread-id (did). If -p is not specified, it
will be turned on; if you specify -p off, no data will
be recorded.
-t duration
Collect data for the specified duration. duration may
be a single number, followed by either m, specifying
minutes, or s, specifying seconds (default), or two
such numbers separated by a - sign. If one number is
given, data will be collected from the start of the run
until the given time; if two numbers are given, data
will be collected from the first time to the second.
If the second time is zero, data will be collected
until the end of the run. If two non-zero numbers are
given, the first must be less than the second.
-q duration
Enforce a quiet period of length duration (seconds)
before and after running the specified load. Default
duration is 3 seconds. The quiet period is ignored if
no load is specified.
-S interval
Collect periodic samples at the interval specified (in
seconds). If interval is zero, do not collect periodic
samples. By default, enable periodic sampling at 1-
second intervals. The data recorded in the samples is
data for the er_kernel process, and includes a time-
stamp and execution statistics from the kernel, among
other things. Samples are markers within the data, and
can be used for filtering.
-C comment
Put the comment, either a single token, or a quoted
string, into the experiment. Up to ten comments may be
provided.
-o experiment_name
Use experiment_name as the name of the experiment to be
recorded. The experiment_name string must end in the
string .er; if not, reporr an error, and do not run the
experiment.
If -o is not specified, choose a name of the form
stem.n.er, where stem is a string, and n is a number.
If a -g argument is given, use the string appearing
before the .erg suffix in the group name as the stem
prefix; if no -g argument is given, set the stem prefix
to the string ktest.
If the name is not specified in the form stem.n.er,
and the the given name is in use, print an error mes-
sage and do not run experiment. If the name is of that
form, and the name is in use, record the experiment
under a name corresponding to the first available value
of n that is not in use; issue a warning if the name is
changed.
-l signal
Record a sample point whenever the given signal is
delivered to the er_kernel process.
-y signal[,r]
Control recording of data with signal. Whenever the
given signal is delivered to the er_kernel process,
switch between paused (no data is recorded) and resumed
(data is recorded) states. er_kernel is started in the
resumed state if the optional ,r flag is given, other-
wise it is started in the paused state. This option
shall not affect the recording of sample points.
-d directory_name
Place the experiment in directory directory_name. if
none is given, record into the current working direc-
tory.
-g group_name
Consider the experiment to be part of experiment group
group_name. The group_name string must end in the
string .erg; if not, report an error, and do not the
experiment.
-L size
Limit the amount of profiling and tracing data recorded
to size megabytes. The limit applies to the sum of all
profiling data and tracing data, but not to sample
points. The limit is only approximate, and can be
exceeded. Terminate the experiment when the limit is
reached. The allowed values of size are:
Value Meaning
unlimited or none
Do not impose a size limit on the experiment
n Impose a limit of n MB.; n must be positive
and greater than zero.
There is no default limit on the amount of data
recorded.
-A option
Control whether or not the kernel modules used during
the run are copied into the recorded experiment. The
allowed values of option are:
Value Meaning
on Archive the kernel modules.
off Do not archive the kernel modules into the
experiment.
copy Copy the kernel modules into the experiment
and archive them.
To copy experiments onto a different machine, or read
them from a different machine, the user should specify
-A copy.
The default setting for -A is copy.
-n Dry run: do not collect data, but print all the details
of the experiment that would be run. Turn on -v.
-V Print the current version. No further arguments are
examined, and no further processing is done.
-v Print detailed information about the experiment being
run, including the current version.
DATA RECORDED
Clock Profiling
Clock profiling experiments support one metric, labeled
"KCPU Cycles". Data is recorded on a per-CPU basis,
with the CPU number recorded as the CPU, the PID of the
process on behalf of which the kernel is running
recorded as the LWPID, and the kernel thread ID
recorded as thread in the raw data.
When one or more -T arguments are specified, an addi-
tional metric labeled "Kthr Time" is produced; "Kthr
Time" records the kernel microstate for each thread at
each tick, and non-CPU states will be indicated as time
spent in the pseudo-functions <SLEEPING> or <STALLED>
(if waiting for a CPU).
PROFILING STATISTICS
When kernel profiling terminates, er_kernel will write
several lines of statistics for the driver; the statistics
are not yet implemented.
SYSTEM SETUP FOR DTRACE
Normally, the DTrace driver is restricted to user root. To
use it as a regular user, username, that user must have
privileges assigned, and be in group sys.
To give privileges to the user, add a line:
username::::defaultpriv=basic,dtrace_kernel,dtrace_proc
to the file /etc/user_attr.
To put the user in group sys, add username to the sys line
in file /etc/group.
SEE ALSO
dtrace(1M) (Solaris 10 or later), analyzer(1), collect(1),
er_archive(1), er_cp(1), er_export(1), er_mv(1),
er_print(1), er_rm(1), er_src(1), and the Performance
Analyzer manual.