Man Page er_kernel.1




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
     superuser 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.



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.
          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 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.