er_kernel(1)er_kernel(1)NAMEer_kernel - generate an Analyzer experiment on the Solaris kernel
SYNOPSISer_kernel args [load-command]
AVAILABILITY
Solaris systems with DTrace supported
DESCRIPTION
The er_kernel command can generate an experiment from the Solaris ker‐
nel, 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 superuser privi‐
leges.
If an optional command to provide a load is given, er_kernel forks, and
the child sleeps for a quiet period, then executes the command to pro‐
vide 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.
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 profil‐
ing interval of approximately 10 milliseconds
lo[w] turn on clock-based profiling with the low-resolution
profiling interval of approximately 100 milliseconds
hi[gh] turn on clock-based profiling with the high-resolution
profiling interval of approximately 1 millisecond
n turn on clock-based profiling with a profiling inter‐
val of n.
The value may be an integer or floating-point number,
with a suffix of u specifying microseconds, or m spec‐
ifying milliseconds. If no suffix is used, the value
will be assumed to be in milliseconds.
If the value is smaller than the system clock profil‐
ing minimum it is set to the minimum; if it is not a
multiple of the clock profiling resolution it is
rounded down to the nearest multiple of the clock pro‐
filing resolution. 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 sin‐
gle 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 sec‐
onds. 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 timestamp and execution statistics from the ker‐
nel, 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 message 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 sig‐
nal 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, otherwise 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 directory.
-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.
The default limit on the amount of data recorded is 2000 Mbytes.
-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 ar‐
chive 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 additional 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 ALSOdtrace(1M) (Solaris 10 or later), analyzer(1), collect(1), er_ar‐
chive(1), er_cp(1), er_export(1), er_mv(1), er_print(1), er_rm(1),
er_src(1), and the Performance Analyzer manual.
February 2006 er_kernel(1)
