| blob | 711a40556ee6a4164b3df34d52cae232526e2af1 |
1 '\" te
2 .\" Copyright (c) 2006, 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 RCAPSTAT 1 "Jun 16, 2009"
7 .SH NAME
8 rcapstat \- report resource cap enforcement daemon statistics
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBrcapstat\fR [\fB-g\fR] [\fB-p | -z\fR] [\fB-T\fR u | d ] [\fIinterval\fR [\fIcount\fR]]
13 .fi
15 .SH DESCRIPTION
16 .sp
17 .LP
18 The \fBrcapstat\fR command reports on the projects or zones capped by
19 \fBrcapd\fR(8). Each report contains statistics that pertain to the project or
20 zone and paging statistics. Paging refers to the act of relocating portions of
21 memory, called pages, to or from physical memory. \fBrcapd\fR pages out the
22 most infrequently used pages.
23 .sp
24 .LP
25 The paging statistics in the first report issued show the activity since the
26 daemon was started. Subsequent reports reflect the activity since the last
27 report was issued.
28 .sp
29 .LP
30 Reports are issued every \fIinterval\fR seconds up to the quantity specified by
31 \fIcount\fR, or forever if \fIcount\fR is not specified.
32 .SH OPTIONS
33 .sp
34 .LP
35 The following options are supported:
36 .sp
37 .ne 2
38 .na
39 \fB\fB-g\fR\fR
40 .ad
41 .RS 12n
42 Global statistics. Reports the minimum memory utilization for memory cap
43 enforcement (see \fBrcapadm\fR(8)) and reports current memory utilization as a
44 percentage of installed physical memory.
45 .RE
47 .sp
48 .ne 2
49 .na
50 \fB\fB-p\fR\fR
51 .ad
52 .RS 12n
53 Report statistics for capped projects. This is the default if no option is
54 specified.
55 .RE
57 .sp
58 .ne 2
59 .na
60 \fB\fB-T\fR \fBu\fR | \fBd\fR\fR
61 .ad
62 .RS 12n
63 Display a time stamp.
64 .sp
65 Specify \fBu\fR for a printed representation of the internal representation of
66 time. See \fBtime\fR(2). Specify \fBd\fR for standard date format. See
67 \fBdate\fR(1).
68 .RE
70 .sp
71 .ne 2
72 .na
73 \fB\fB-z\fR\fR
74 .ad
75 .RS 12n
76 Report statistics for capped zones.
77 .RE
79 .SH OUTPUT
80 .sp
81 .LP
82 The following list defines the column headings in the \fBrcapstat\fR report and
83 provides information about how to interpret the report.
84 .sp
85 .ne 2
86 .na
87 \fB\fBid\fR\fR
88 .ad
89 .RS 11n
90 The project ID or zone \fBID\fR of the capped project or zone.
91 .RE
93 .sp
94 .ne 2
95 .na
96 \fB\fBproject\fR\fR
97 .ad
98 .RS 11n
99 The project name.
100 .RE
102 .sp
103 .ne 2
104 .na
105 \fB\fBzone\fR\fR
106 .ad
107 .RS 11n
108 The zone name.
109 .RE
111 .sp
112 .ne 2
113 .na
114 \fB\fBnproc\fR\fR
115 .ad
116 .RS 11n
117 The number of processes in the project or zone since the last report.
118 .RE
120 .sp
121 .ne 2
122 .na
123 \fB\fBvm\fR\fR
124 .ad
125 .RS 11n
126 The total virtual memory size of the project or zone's processes, including all
127 mapped files and devices, in kilobytes (\fBK\fR), megabytes (\fBM\fR), or
128 gigabytes (\fBG\fR).
129 .RE
131 .sp
132 .ne 2
133 .na
134 \fB\fBrss\fR\fR
135 .ad
136 .RS 11n
137 The total resident set size (\fBRSS\fR) of the project or zone's processes, in
138 kilobytes (\fBK\fR), megabytes (\fBM\fR), or gigabytes (\fBG\fR). The count
139 does not account for shared pages.
140 .RE
142 .sp
143 .ne 2
144 .na
145 \fB\fBcap\fR\fR
146 .ad
147 .RS 11n
148 The \fBRSS\fR cap for the project or zone. See \fBrcapd\fR(8) for information
149 about how to specify memory caps.
150 .RE
152 .sp
153 .ne 2
154 .na
155 \fB\fBat\fR\fR
156 .ad
157 .RS 11n
158 The total amount of memory that \fBrcapd\fR attempted to page out.
159 .sp
160 Paging refers to the act of relocating portions of memory, called pages, to or
161 from physical memory. \fBrcapd\fR pages out the most infrequently used pages.
162 .RE
164 .sp
165 .ne 2
166 .na
167 \fB\fBavgat\fR\fR
168 .ad
169 .RS 11n
170 The average amount of memory that \fBrcapd\fR attempted to page out during
171 each sample cycle. The rate at which \fBrcapd\fR samples \fBRSS\fR can be set
172 with \fBrcapadm\fR(8).
173 .RE
175 .sp
176 .ne 2
177 .na
178 \fB\fBpg\fR\fR
179 .ad
180 .RS 11n
181 An estimate of the total amount of memory that \fBrcapd\fR successfully paged
182 out.
183 .RE
185 .sp
186 .ne 2
187 .na
188 \fB\fBavgpg\fR\fR
189 .ad
190 .RS 11n
191 An estimate of the average amount of memory that \fBrcapd\fR successfully paged
192 out during each sample cycle. The rate at which \fBrcapd\fR samples process
193 \fBRSS\fR sizes can be set with \fBrcapadm\fR.
194 .RE
196 .SH OPERANDS
197 .sp
198 .LP
199 The following operands are supported:
200 .sp
201 .ne 2
202 .na
203 \fB\fIinterval\fR\fR
204 .ad
205 .RS 12n
206 Specifies the reporting interval in seconds. The default interval is 5 seconds.
207 .RE
209 .sp
210 .ne 2
211 .na
212 \fB\fIcount\fR\fR
213 .ad
214 .RS 12n
215 Specifies the number of reports to produce. By default, \fBrcapstat\fR reports
216 statistics until a termination signal is received or until the \fBrcapd\fR
217 process exits.
218 .RE
220 .SH EXAMPLES
221 .LP
222 \fBExample 1 \fRUsing \fBrcapstat\fR to Report Cap and Project Information
223 .sp
224 .LP
225 Caps are defined for two projects associated with two users. \fBuser1\fR has a
226 cap of 50 megabytes and \fBuser2\fR has a cap of 10 megabytes.
228 .sp
229 .LP
230 The following command produces five reports at 5-second sampling intervals.
232 .sp
233 .in +2
234 .nf
235 example# \fBrcapstat 5 5\fR
236 id project nproc vm rss cap at avgat pg avgpg
237 112270 user1 24 123M 35M 50M 50M 0K 3312K 0K
238 78194 user2 1 2368K 1856K 10M 0K 0K 0K 0K
239 id project nproc vm rss cap at avgat pg avgpg
240 112270 user1 24 123M 35M 50M 0K 0K 0K 0K
241 78194 user2 1 2368K 1856K 10M 0K 0K 0K 0K
242 id project nproc vm rss cap at avgat pg avgpg
243 112270 user1 24 123M 35M 50M 0K 0K 0K 0K
244 78194 user2 1 2368K 1928K 10M 0K 0K 0K 0K
245 id project nproc vm rss cap at avgat pg avgpg
246 112270 user1 24 123M 35M 50M 0K 0K 0K 0K
247 78194 user2 1 2368K 1928K 10M 0K 0K 0K 0K
248 id project nproc vm rss cap at avgat pg avgpg
249 112270 user1 24 123M 35M 50M 0K 0K 0K 0K
250 78194 user2 1 2368K 1928K 10M 0K 0K 0K 0K
251 .fi
252 .in -2
253 .sp
255 .sp
256 .LP
257 The first three lines of output constitute the first report, which contains the
258 cap and project information for the two projects and paging statistics since
259 \fBrcapd\fR was started. The \fBat\fR and \fBpg\fR columns are a number greater
260 than zero for \fBuser1\fR and zero for \fBuser2\fR, which indicates that at
261 some time in the daemon's history, \fBuser1\fR exceeded its cap but \fBuser2\fR
262 did not.
264 .sp
265 .LP
266 The subsequent reports show no significant activity.
268 .LP
269 \fBExample 2 \fRUsing \fBrcapstat\fR to Monitor the RSS of a Project
270 .sp
271 .in +2
272 .nf
273 example% \fBrcapstat 5 5\fR
274 id project nproc vm rss cap at avgat pg avgpg
275 376565 user1 57 209M 46M 10M 440M 220M 5528K 2764K
276 376565 user1 57 209M 44M 10M 394M 131M 4912K 1637K
277 376565 user1 56 207M 43M 10M 440M 147M 6048K 2016K
278 376565 user1 56 207M 42M 10M 522M 174M 4368K 1456K
279 376565 user1 56 207M 44M 10M 482M 161M 3376K 1125K
280 .fi
281 .in -2
282 .sp
284 .sp
285 .LP
286 The project \fBuser1\fR has an \fBRSS\fR in excess of its physical memory cap.
287 The nonzero values in the \fBpg\fR column indicate that \fBrcapd\fR is
288 consistently paging out memory as it attempts to meet the cap by lowering the
289 physical memory utilization of the project's processes. However, \fBrcapd\fR is
290 unsuccessful, as indicated by the varying \fBrss\fR values that do not show a
291 corresponding decrease. This means that the application's resident memory is
292 being actively used, forcing \fBrcapd\fR to affect the working set. Under this
293 condition, the system continues to experience high page fault rates, and
294 associated I/O, until the working set size (\fBWSS\fR) is reduced, the cap is
295 raised, or the application changes its memory access pattern. Notice that a
296 page fault occurs when either a new page must be created, or the system must
297 copy in a page from the swap device.
299 .LP
300 \fBExample 3 \fRDetermining the Working Set Size of a Project
301 .sp
302 .LP
303 This example is a continuation of \fBExample 1\fR, and it uses the same
304 project.
306 .sp
307 .in +2
308 .nf
309 example% \fBrcapstat 5 5\fR
310 id project nproc vm rss cap at avgat pg avgpg
311 376565 user1 56 207M 44M 10M 381M 191M 15M 7924K
312 376565 user1 56 207M 46M 10M 479M 160M 2696K 898K
313 376565 user1 56 207M 46M 10M 424M 141M 7280K 2426K
314 376565 user1 56 207M 43M 10M 401M 201M 4808K 2404K
315 376565 user1 56 207M 43M 10M 456M 152M 4800K 1600K
316 376565 user1 56 207M 44M 10M 486M 162M 4064K 1354K
317 376565 user1 56 207M 52M 100M 191M 95M 1944K 972K
318 376565 user1 56 207M 55M 100M 0K 0K 0K 0K
319 376565 user1 56 207M 56M 100M 0K 0K 0K 0K
320 376565 user1 56 207M 56M 100M 0K 0K 0K 0K
321 376565 user1 56 207M 56M 100M 0K 0K 0K 0K
322 376565 user1 56 207M 56M 100M 0K 0K 0K 0K
323 .fi
324 .in -2
325 .sp
327 .sp
328 .LP
329 By inhibiting cap enforcement, either by raising the cap of a project or by
330 changing the minimum physical memory utilization for cap enforcement (see
331 \fBrcapadm\fR(8)), the resident set can become the working set. The \fBrss\fR
332 column might stabilize to show the project \fBWSS\fR, as shown in the previous
333 example. The \fBWSS\fR is the minimum cap value that allows the project's
334 processes to operate without perpetually incurring page faults.
336 .SH EXIT STATUS
337 .sp
338 .LP
339 The following exit values are returned:
340 .sp
341 .ne 2
342 .na
343 \fB\fB0\fR\fR
344 .ad
345 .RS 5n
346 Successful completion.
347 .RE
349 .sp
350 .ne 2
351 .na
352 \fB\fB1\fR\fR
353 .ad
354 .RS 5n
355 An error occurred.
356 .RE
358 .sp
359 .ne 2
360 .na
361 \fB\fB2\fR\fR
362 .ad
363 .RS 5n
364 Invalid command-line options were specified.
365 .RE
367 .SH SEE ALSO
368 .sp
369 .LP
370 \fBrcapadm\fR(8), \fBrcapd\fR(8), \fBattributes\fR(5)
371 .sp
372 .LP
373 \fIPhysical Memory Control Using the Resource Capping Daemon\fR in \fISystem
374 Administration Guide: Resource Management\fR
375 .SH NOTES
376 .sp
377 .LP
378 If the interval specified to \fBrcapstat\fR is shorter than the reporting
379 interval specified to \fBrcapd\fR (with \fBrcapadm\fR(8)), the output for some
380 intervals can be zero. This is because \fBrcapd\fR does not update statistics
381 more frequently than the interval specified with \fBrcapadm\fR, and this
382 interval is independent of (and less precise than) the sampling interval used
383 by \fBrcapstat\fR.