collector man page on OpenIndiana

Man page or keyword search:  
man Server   20441 pages
apropos Keyword Search (all sections)
Output format
OpenIndiana logo
[printable version]

collector(1)							  collector(1)

NAME
       collector - subcommands of dbx used for performance data collection

SYNOPSIS
       dbx

DESCRIPTION
       The  term collector is used to describe the data collection features in
       dbx and the runtime support for those features in libcollector.so.

       The dbx collector  does	not  work  for	applications  written  in  the
       Java(TM) programming language; it can collect data for the Java virtual
       machine, but the Java-specific functionality does not  work  from  dbx.
       (The  terms "Java virtual machine" and "JVM" mean a virtual machine for
       the Java(TM) platform.)

       The data collected is described in the collect(1) man page.   The  col‐
       lect command can collect data without using dbx.

DBX COMMANDS
       The commands accepted by dbx to support performance data collection are
       as follows.

       collector { enable | disable }
	      Enable or disable data collection.

	      If no process is active, control whether or not an experiment is
	      collected when a process starts.	If the mode is disable, do not
	      collect performance data.	 If the mode is enable,	 collect  data
	      for all subsequent runs.

	      If  a  process is running, but no experiment is being collected,
	      and an enable command is received, start an  experiment  on  the
	      running  process.	  If  a disable is given, but no experiment is
	      being collected, ignore the command with a warning.

	      If a process is running, an experiment is being collected, and a
	      disable command is received, terminate the experiment. If enable
	      is given, ignore the command with a warning.

	      If an experiment is terminated, but the process is left  running
	      and an enable command is received, start a new experiment.

       collector pause
	      Temporarily  stop	 recording  data during an experiment.	Ignore
	      the command with no warning if  recording	 of  data  is  already
	      paused.	Ignore	the command with a warning if no experiment is
	      running.

       collector resume
	      Resume recording data during an experiment.  Ignore the  command
	      with  no warning if recording of data is not paused.  Ignore the
	      command with a warning if no experiment is running.

       collector profile { on | off }
	      Enable or disable collection of clock-based profiling data.   If
	      an  experiment  is  active,  ignore  the command with a warning.
	      Default is enabled.

       collector profile timer value
	      Set the profiling timer interval to value.  The value can be  an
	      integer  or a floating-point number, with a suffix of u for val‐
	      ues in microseconds, or m for values  in	milliseconds.	If  no
	      suffix is used, assume the value to be in milliseconds.  Set the
	      default interval to 10 milliseconds.

	      The interval value can also be given as one of the strings  "hi"
	      or  "high"  for  profiling  at a 1 millisecond interval, "lo" or
	      "low" for profiling at a 100 millisecond interval, or  "on"  for
	      profiling	 at  a	10 millisecond interval. These interval values
	      are approximate.

	      If the value is smaller than the system clock profiling  minimum
	      set it to the minimum; if it is not a multiple of the clock pro‐
	      filing resolution round down to  the  nearest  multiple  of  the
	      clock  resolution.  If  it  exceeds the clock profiling maximum,
	      report an error.	If it is negative or zero, report an error.

	      If an experiment is active, ignore the command with a warning.

       collector hwprofile { on | off }
	      Enable or disable hardware-counter overflow profiling.  On  sys‐
	      tems  whose  hardware or operating system does not support hard‐
	      ware-counter overflow profiling, return an error on detecting an
	      attempt  to  enable  it.	If an experiment is active, ignore the
	      command with a warning.  Default is disabled.

       collector hwprofile list
	      Print a usage summary, including the  default  configuration  of
	      the experiment.  If the processor supports hardware counter pro‐
	      filing, print two lists containing  information  about  hardware
	      counters.	  The  first  list  will contain "well known" hardware
	      counters; the second list will contain raw hardware counters.

	      For example, the collector hwprofile list command invoked	 on  a
	      Sun OS SPARC-based system would produce an output similar to the
	      following:

		Well known HW counters available for profiling:
		    cycles[/{0|1}],9999991 (`CPU Cycles', alias for Cycle_cnt; CPU-cycles)
		    insts[/{0|1}],9999991 (`Instructions Executed', alias for Instr_cnt; events)
		    icm[/1],100003 (`I$ Misses', alias for IC_miss; events)
		    ...
		Raw HW counters available for profiling:
		    Cycle_cnt[/{0|1}],1000003 (CPU-cycles)
		    Instr_cnt[/{0|1}],1000003 (events)
		    Dispatch0_IC_miss[/0],1000003 (CPU-cycles)
		    ...

       collector hwprofile counter ctr_def...[,ctr_n_def]
	      Collect  hardware	 counter  overflow  profiles.  The  number  of
	      counter  definitions,  (ctr_def through ctr_n_def) is processor-
	      dependent. For example, on an UltraSPARC III system, up  to  two
	      counters	may  be	 programmed; on an Intel Pentium 4 with Hyper‐
	      threading, up to 18 counters are available. The user can	ascer‐
	      tain  the	 maximum  number  of hardware counters definitions for
	      profiling on a target system, and the  full  list	 of  available
	      hardware	counters,  by  running the collect command without any
	      arguments.  This option is not available on Linux systems.

	      Each counter  definition	takes  one  of	the  following	forms,
	      depending	 on  whether attributes for hardware counters are sup‐
	      ported on the processor:

	      1. [+]ctr[/reg#],interval

		 [+]ctr[/reg#] interval

		 Examples:
		      collector hwprofile counter cycles,on,insts
		      collector hwprofile counter cycles on insts

		 Note: For historical reasons, a space can still  be  used  as
		 the delimiter between hardware counters.

	      2. [+]ctr[~attr=val]...[~attrN=valN][/reg#],interval

		 Example:

		   collector hwprofile counter FP_dispatched_fpu_ops~umask=0x3/2,10007

	      enables  the  Floating  Point  Add and Multiply operations to be
	      tracked.	(For more details on valid attribute values, refer  to
	      the processor documentation).  The "/2" value specifies instruc‐
	      tions to be executed using the second register of the  hardware.
	      The  CPU	cycle  profiling  is done at an interval rate of 10007
	      events.

	      The meanings of the counter definition options are as follows:

	      Value	Meaning

	      +		Optional parameter that	 can  be  applied  to  memory-
			related	 counters.  Causes  collect to backtrack in an
			attempt to find the  instruction  that	triggered  the
			overflow,   and	 to  find  the	virtual	 and  physical
			addresses of the memory reference.  Backtracking  will
			only  work with counters of type load, store, or load-
			store, as displayed in the counter  list  obtained  by
			running	 the  collect command without any command-line
			arguments.

	      ctr	Processor-specific counter name. The user  can	ascer‐
			tain  the list of counter names by running the collect
			command without any command-line arguments.

	      attr=val	On some processors, attribute options can  be  associ‐
			ated  with  a hardware counter.	 If the processor sup‐
			ports attribute options, then running collect  without
			any  command-line  arguments  will specify the counter
			definition, ctr_def, in the second form listed	above,
			and provide a list of attribute names to use for attr.
			Value val can be in  decimal  or  hexadecimal  format.
			Hexadecimal  format  numbers  are  in C program format
			where the number is prepended by a zero and lower-case
			x (0xhex_number).

	      reg#	Hardware register to use for the counter. If not spec‐
			ified, collect will attempt to place the counter  into
			the  first  available register and as a result, may be
			unable to place subsequent counters  due  to  register
			conflicts.   If	 the  user  specifies  more  than  one
			counter, the counters must  use	 different  registers.
			The  list  of allowable register numbers can be ascer‐
			tained by running the collect command without any com‐
			mand-line arguments.

	      interval
			Sampling  frequency, set by defining the counter over‐
			flow value.  Valid values are as follows:

			Value	  Meaning

			on	  Select the default rate, which can be deter‐
				  mined by running the collect command without
				  any command-line arguments.  Note  that  the
				  default  value  for  all raw counters is the
				  same, and may not be the most suitable value
				  for a specific counter.

			hi	  Set	interval  to  approximately  10	 times
				  shorter than on.

			lo	  Set  interval	 to  approximately  10	 times
				  longer than on.

			value	  Set  interval to a specific value, specified
				  in decimal or hexadecimal format.

	  An experiment can specify both hardware counter profiling and clock-
	  based	 profiling.  If	 hardware  counter profiling is specified, but
	  clock-based profiling is not explicitly specified, turn  off	clock-
	  based profiling.

       collector synctrace { on | off }
		 Enable or disable collecting of synchronization tracing data.
		 Default is off.  If an experiment is active, ignore the  com‐
		 mand with a warning.

       collector synctrace threshold value
		 Set the threshold for synchronization delay tracing according
		 to the given value, which can be one of the following:

		 Value	   Meaning

		 calibrate or on
			   Use a calibrated threshold, determined at runtime.

		 off	   Turn off synchronization delay tracing.

		 n	   Use an threshold value of n	microseconds.  A  zero
			   value enables tracing of all events.

		 The  default  setting	is  calibrate.	 If  an	 experiment is
		 active, ignore the command with a warning.

       collector mpitrace { on | off }
		 Enable or disable collecting of MPI tracing data. Default  is
		 off.	If  an experiment is active, ignore the command with a
		 warning.

       collector heaptrace { on | off }
		 Enable or disable collecting of heap tracing data. Default is
		 off.	If  an experiment is active, ignore the command with a
		 warning.

       collector tha { on | all | <option> | off }
		 Control collecting of Thread Analyzer data. Default  is  off.
		 If  an	 experiment is active, ignore the command with a warn‐
		 ing.  The target executable must be instrumented for datarace
		 detection; see the tha(1) man page for more detail.

		 <option>  is  a comma-separated list the Thread Analyzer data
		 options.  See the collect() man page for a list of the Thread
		 Analyzer options.

       collector archive { on | off | copy }
		 Set the mode for archiving the experiment. The default is on,
		 corresponding to normal archiving. If the mode is set to off,
		 do  no	 archiving.  If the mode is set to copy, copy all load
		 objects used into the	experiment.  A	user  that  moves  the
		 experiment  to	 a different machine, or reads it from another
		 machine, should enable the copying of all load objects. If an
		 experiment is active, ignore the command with a warning.

       collector limit value
		 Limit	 the  amount  of  profiling  data  recorded  to	 value
		 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.  When	the  limit  is
		 reached,  record  no more profiling or tracing data, but keep
		 the experiment open  and  record  samples  until  the	target
		 process  terminates.	If an experiment is active, ignore the
		 command with a warning.

		 The default limit on the amount  of  data  recorded  is  2000
		 Mbytes.   To  remove the limit, the user sets value to "none"
		 or "unlimited".

       collector status
		 Report on the status of any open experiment.

       collector show
		 Show the current settings of all collector control variables.

       collector sample { periodic | manual }
		 Set the sampling mode to either periodic or manual. If	 peri‐
		 odic  is  specified,  record  samples at the current sampling
		 frequency.  If manual is specified, record periodic  samples.
		 Samples  can  be  recorded  manually  using  collector sample
		 record regardless of which mode is specified.	If an  experi‐
		 ment is active, ignore the command with a warning.

       collector sample record [name]
		 Record a sample, with the optional label name.	 If an experi‐
		 ment is not active, ignore the command with a warning.

       collector sample period value
		 Set the sampling frequency to value, given in seconds.	 If an
		 experiment is active, ignore the command with a warning.

       collector dbxsample { on | off }
		 Control  the  collection of samples when dbx stops the target
		 process.  For the on option, collect a sample each  time  dbx
		 stops	the  target  process;  if  off	,  collect no samples.
		 Default is on.

       collector store directory name
		 Set the collector directory to name.	If  an	experiment  is
		 active, ignore the command with a warning.

       collector store experiment name
		 Set  the output experiment name to name.  If an experiment is
		 active, ignore the command with a warning.  If a name is  not
		 specified,  use  the  default	name.	The  default  name  is
		 described in the collect(1) man page.

       collector store group name
		 Set the experiment group name to name.	 If an	experiment  is
		 active, ignore the command with a warning.

       collector version
		 Report	 the  version of libcollector.so that would be used to
		 collect data.

       help collector
		 Prompt the user about the various collector  commands	avail‐
		 able.

OBSOLETE DBX COMMANDS
       A few commands previously accepted by dbx are now obsolete; they are:

       collector enable_once
	      Ignored  with a warning. The command used to allow enabling data
	      collection for just one run.

       collector close
	      Treated as  collector  disable  if  an  experiment  is  running.
	      Ignored with a warning if no experiment is running.

       collector quit
	      Treated  as  collector  disable  if  an  experiment  is running.
	      Ignored with a warning if no experiment is running.

       collector address_space { on | off }
	      Address space data  is  no  longer  supported.  The  command  is
	      ignored with a warning.

       collector store filename name
	      Accepted as collector store experiment, for compatibility.  Sets
	      the output experiment name to name.

FOLLOWING DESCENDANT PROCESSES
       When a process that is collecting performance data creates a descendant
       process, the collector continues to collect data on the parent process,
       with the following exception: If a process calls any variant  of	 exec,
       the  experiment terminates abnormally if the exec succeeds, and contin‐
       ues if the exec fails. In either case, the experiment can  be  read  by
       the performance analysis tools.

       If  you want to record data for a descendant process, you should attach
       dbx to the newly created process and then start an  experiment  on  the
       descendant  process  using  collector enable.  If you want to automati‐
       cally collect data on all descendant processes, use the collect(1) com‐
       mand.

ATTACHING TO A PROCESS
       You can attach dbx to a process, and use the collector commands to col‐
       lect performance data from it.

       Collecting data by attaching to applications that install  signal  han‐
       dlers  or use libcpc.so may not work properly, since that functionality
       relies on having the user code call the collector's wrapper around  the
       real routines is referenced, rather than the routines themselves.  Sim‐
       ilarly, collecting trace data (Synchronization tracing,	Heap  tracing,
       or  MPI	tracing), or following descendant processes may not work.  One
       clock- and hwc-profile experiments will work on a process  attached  to
       by  dbx.	  A  workaround for all of these difficulties is to use the -y
       sig flag to collect to start the process, then enable  data  collection
       by sending the specified signal, sig, to the target.

       After  the  executable  has been started, determine its PID, and attach
       dbx to it. At that point, you can enable data collection.

       If you started the executable from dbx without  enabling	 data  collec‐
       tion,  you can pause it from dbx at any time, and then enable data col‐
       lection, but subject to the same restrictions as attaching.

SEE ALSO
       analyzer(1), collect(1), dbx(1), er_archive(1), er_cp(1), er_export(1),
       er_mv(1),  er_print(1), er_rm(1), tha(1), libcollector(3), and the Per‐
       formance Analyzer manual.

				 January 2007			  collector(1)
[top]

List of man pages available for OpenIndiana

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net