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