System Administration Commands                       latencytop(1M)

NAME
     latencytop - report statistics related to latencies in the
     system and in applications

SYNOPSIS
     latencytop [-t interval] [-o log-file] [-k log-level] [c config-file]
		[-f (no)feature,...] [-l log-interval] [-h]

DESCRIPTION
     LatencyTOP is an observability tool that reports statistics
     about latencies in the system and in applications. The tool
     reports  statistics about where and what  kind of latencies
     are  happening in the  system and in the  applications that
     are running on the system. The  statistics then can be used
     to  improve  performance  throughput  of  applications  and
     system by removing the latencies.

     The tool analyzes system activity periodically and displays
     the data in the output window. Two  types of  latencies are
     tracked - an  LWP  going in and out  of  sleep and  an  LWP
     spinning order to acquire a synchronization object. The tool
     uses the Solaris DTrace framework to collect the statistics
     corresponding to  these two  scenarios of inactivity of the
     system and application LWPs.

     The output window is divided into two sections - upper part
     displays the system-wide  statistics  while  the lower part
     displays  statistics  about  individual processes. The user
     can navigate  the list of  processes (using the < and the >
     keys) and  select the one they are  interested in,  and the
     tool will  display  statistics about that selected  process
     in the lower part of the window; if the t or T key is 
     pressed, the tool  displays  the LWP-specific view of that
     selected process. Thus, the  t or T key can be used to 
     toggle  between the  process-view and the thread-view.

     During execution, a user can force a refresh of the analysis
     by pressing the r or R key.  The interval  time is restored
     to the default or to a specified value (if -t was used). To
     quit  the  application, the user must press the q or Q key.


OPTIONS
     The following options are supported:

     -o [log-file]

         Specifies the log file where output will be written. The
	 default log file is /var/log/latencytop.log.

     -k [log-level]

         Specifies  the level of  logging  in the log file. Valid
         values are: 0 = none (default), 1 = unknown, and 2 = all;

     -t [interval]

         Specifies the interval, in seconds, at  which  the  tool
         collects statistics from the system. The possible values
         are between 1 and 60; the default is 5 seconds.

     -f, --feature [no]feature1,[no]feature2,...
	
	 Enables/disables features in LatencyTOP. Features can only
	 be one of the following :

    		[no]filter: Filter large interruptible latencies,
			e.g. sleep. Default: off

    		[no]sched: Monitors sched (PID=0). Default: off

    		[no]sobj: Monitors synchronize objects. Default: on

    		[no]low: Lower overhead by sampling small latencies.
			Enabling this feature will lower CPU utilization
			by estimating small latencies statistically.
			Use it for heavy workloads such as a very busy
			web server. Default: off

     -l [log-interval]

         Writes data to the log file every log-interval seconds;
	 log-interval must be > 60.

     -h

         Displays the command's usage.


EXAMPLES
     Example 1 Running the tool

     The following command launches the tool with default values
     for options.

       % latencytop

     Example 2 Setting the Interval

     The following command sets the interval to two seconds.

       % latencytop -t 2

     Example 3 Setting the log file

     The following command sets the log file to /tmp/latencytop.log.

       % latencytop -o /tmp/latencytop.log

     Example 4 Setting the log level

     The following command sets the log level to "all".

       % latencytop -l 2

     Example 4 Enabling tracing of latencies caused by synchronization
	objects.

     The following command enables the tracing of latencies caused by
	synchronization objects.

       % latencytop -f sobj


EXIT STATUS
     0

         Successful operation.

     1

         An error occurred.


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Architecture                | x86, SPARC                  |
    |_____________________________|_____________________________|
    | Availability                | SUNWlatencytop              |
    |_____________________________|_____________________________|
    | Interface Stability         | Volatile                    |
    |_____________________________|_____________________________|

SEE ALSO
     kstat(1M), dtrace(1M)

USAGE
     You must have DTrace privileges to run LatencyTOP.