usr/src/man/man1m/latencytop.1m

   1 '\" te
   2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   4 .\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
   5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH LATENCYTOP 1M "Sep 29, 2009"
   7 .SH NAME
   8 latencytop \- report latency-related statistics in system and in applications
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBlatencytop\fR [\fB-t\fR \fIinterval\fR] [\fB-o\fR \fIlog_file\fR] [\fB-k\fR \fIlog_level\fR]
  13      [\fB-f\fR [no]\fIfeature\fR,...] [\fB-l\fR \fIlog_interval\fR] [\fB-h\fR]
  14 .fi
  15
  16 .SH DESCRIPTION
  17 .sp
  18 .LP
  19 LatencyTOP is an observability tool that reports statistics about latencies in
  20 the system and in applications. The tool reports statistics about where and
  21 what kind of latencies are happening in the system and in the applications that
  22 are running on the system. The statistics then can be used to improve
  23 performance throughput of applications and system, as you remove the identified
  24 latencies.
  25 .sp
  26 .LP
  27 The tool analyzes system activity periodically and displays the data in the
  28 output window. Two types of latencies are tracked: an LWP going in and out of
  29 sleep and an LWP spinning order to acquire a synchronization object. The tool
  30 uses the Solaris DTrace framework to collect the statistics corresponding to
  31 these two scenarios of inactivity of the system and application LWPs.
  32 .sp
  33 .LP
  34 The output window is divided into two sections. An upper part displays the
  35 system-wide statistics, while the lower part displays statistics about
  36 individual processes. The user can navigate the list of processes (using the
  37 left- and right-arrow keys) and select the list they are interested in. The
  38 tool will then display statistics about that selected process in the lower part
  39 of the window. If the t or T key is pressed, the tool displays the LWP-specific
  40 view of that selected process. The t or T key can be used to toggle between the
  41 process-view and the thread-view.
  42 .sp
  43 .LP
  44 During execution, a user can force a refresh of the analysis by pressing the r
  45 or R key. The interval time is restored to the default or to a specified value
  46 (if -t was used). To quit the application, the user must press the q or Q key.
  47 .SH OPTIONS
  48 .sp
  49 .LP
  50 The following options are supported:
  51 .sp
  52 .ne 2
  53 .na
  54 \fB\fB-f\fR, \fB--feature\fR [no]\fIfeature1\fR,[no]\fIfeature2\fR,...\fR
  55 .ad
  56 .sp .6
  57 .RS 4n
  58 Enables/disables features in LatencyTOP. Features can be only one of the
  59 following:
  60 .sp
  61 .ne 2
  62 .na
  63 \fB[\fBno\fR]\fBfilter\fR\fR
  64 .ad
  65 .sp .6
  66 .RS 4n
  67 Filter large interruptible latencies, for example, sleep. The default is
  68 \fBoff\fR.
  69 .RE
  70
  71 .sp
  72 .ne 2
  73 .na
  74 \fB[\fBno\fR]\fBsched\fR\fR
  75 .ad
  76 .sp .6
  77 .RS 4n
  78 Monitors \fBsched\fR (PID=0). The default is \fBoff\fR.
  79 .RE
  80
  81 .sp
  82 .ne 2
  83 .na
  84 \fB[\fBno\fR]\fBsobj\fR\fR
  85 .ad
  86 .sp .6
  87 .RS 4n
  88 Monitors synchronize objects. The default is \fBon\fR.
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fB[\fBno\fR]\fBlow\fR\fR
  95 .ad
  96 .sp .6
  97 .RS 4n
  98 Lower overhead by sampling small latencies. Enabling this feature will lower
  99 CPU utilization by estimating small latencies statistically. Use it for heavy
 100 workloads such as a very busy web server. The default is \fBoff\fR.
 101 .RE
 102
 103 .RE
 104
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fB-h\fR\fR
 109 .ad
 110 .sp .6
 111 .RS 4n
 112 Displays the command's usage.
 113 .RE
 114
 115 .sp
 116 .ne 2
 117 .na
 118 \fB\fB-k\fR \fIlog_level\fR\fR
 119 .ad
 120 .sp .6
 121 .RS 4n
 122 Specifies the level of logging in the log file. Valid values are:
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fB0\fR\fR
 127 .ad
 128 .RS 5n
 129 \fBnone\fR (default)
 130 .RE
 131
 132 .sp
 133 .ne 2
 134 .na
 135 \fB\fB1\fR\fR
 136 .ad
 137 .RS 5n
 138 \fBunknown\fR
 139 .RE
 140
 141 .sp
 142 .ne 2
 143 .na
 144 \fB\fB2\fR\fR
 145 .ad
 146 .RS 5n
 147 \fBall\fR
 148 .RE
 149
 150 .RE
 151
 152 .sp
 153 .ne 2
 154 .na
 155 \fB\fB-l\fR [\fIlog_interval\fR]\fR
 156 .ad
 157 .sp .6
 158 .RS 4n
 159 Writes data to the log file every \fIlog_interval\fR seconds;
 160 \fIlog_interval\fR must be greater than 60.
 161 .RE
 162
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fB-o\fR \fIlog_file\fR\fR
 167 .ad
 168 .sp .6
 169 .RS 4n
 170 Specifies the log file where output will be written. The default log file is
 171 \fB/var/log/latencytop.log\fR.
 172 .RE
 173
 174 .sp
 175 .ne 2
 176 .na
 177 \fB\fB-t\fR \fIinterval\fR\fR
 178 .ad
 179 .sp .6
 180 .RS 4n
 181 Specifies the interval, in seconds, at which the tool collects statistics from
 182 the system. The possible values are between 1 and 60; the default is 5 seconds.
 183 .RE
 184
 185 .SH EXAMPLES
 186 .LP
 187 \fBExample 1 \fRRunning the Tool
 188 .sp
 189 .LP
 190 The following command launches the tool with default values for options.
 191
 192 .sp
 193 .in +2
 194 .nf
 195 % \fBlatencytop\fR
 196 .fi
 197 .in -2
 198 .sp
 199
 200 .LP
 201 \fBExample 2 \fRSetting the Interval
 202 .sp
 203 .LP
 204 The following command sets the sampling interval to two seconds.
 205
 206 .sp
 207 .in +2
 208 .nf
 209 % \fBlatencytop -t 2\fR
 210 .fi
 211 .in -2
 212 .sp
 213
 214 .LP
 215 \fBExample 3 \fRSpecifying the Log File
 216 .sp
 217 .LP
 218 The following command sets the log file to \fB/tmp/latencytop.log\fR.
 219
 220 .sp
 221 .in +2
 222 .nf
 223 % \fBlatencytop -o /tmp/latencytop.log\fR
 224 .fi
 225 .in -2
 226 .sp
 227
 228 .LP
 229 \fBExample 4 \fRSpecifying the Log Level
 230 .sp
 231 .LP
 232 The following command sets the log level to \fBall\fR.
 233
 234 .sp
 235 .in +2
 236 .nf
 237 % \fBlatencytop -l 2\fR
 238 .fi
 239 .in -2
 240 .sp
 241
 242 .LP
 243 \fBExample 5 \fREnabling Tracing of Latencies
 244 .sp
 245 .LP
 246 The following command enables the tracing of latencies caused by
 247 synchronization objects.
 248
 249 .sp
 250 .in +2
 251 .nf
 252 % \fBlatencytop -f sobj\fR
 253 .fi
 254 .in -2
 255 .sp
 256
 257 .SH EXIT STATUS
 258 .sp
 259 .ne 2
 260 .na
 261 \fB\fB0\fR\fR
 262 .ad
 263 .sp .6
 264 .RS 4n
 265 Successful operation.
 266 .RE
 267
 268 .sp
 269 .ne 2
 270 .na
 271 \fB\fB1\fR\fR
 272 .ad
 273 .sp .6
 274 .RS 4n
 275 An error occurred.
 276 .RE
 277
 278 .SH ATTRIBUTES
 279 .sp
 280 .LP
 281 See \fBattributes\fR(5) for descriptions of the following attributes:
 282 .sp
 283
 284 .sp
 285 .TS
 286 box;
 287 c | c
 288 l | l .
 289 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 290 _
 291 Architecture    x86, SPARC
 292 _
 293 Interface Stability     Volatile
 294 .TE
 295
 296 .SH SEE ALSO
 297 .sp
 298 .LP
 299 \fBdtrace\fR(1M), \fBkstat\fR(1M), \fBattributes\fR(5)
 300 .SH USAGE
 301 .sp
 302 .LP
 303 You must have DTrace privileges to run LatencyTOP.