| Current File : //usr/man/man1/rcapstat.1 |
'\" te
.\" Copyright (c) 2010, 2015, Oracle and/or its affiliates. All rights reserved.
.TH rcapstat 1 "20 Mar 2015" "SunOS 5.11" "User Commands"
.SH NAME
rcapstat \- report resource cap enforcement daemon statistics
.SH SYNOPSIS
.LP
.nf
\fBrcapstat\fR [\fB-p | -z\fR] [\fB-T\fR u | d ] [\fIinterval\fR [\fIcount\fR]]
.fi
.SH DESCRIPTION
.sp
.LP
The \fBrcapstat\fR command reports on the projects or zones capped by \fBrcapd\fR(1M). Each report contains statistics that pertain to the project or zone and paging statistics. Paging refers to the act of relocating portions of memory, called pages, to or from physical memory. \fBrcapd\fR pages out the most infrequently used pages.
.sp
.LP
The paging statistics in the first report issued show the activity since the daemon was started. Subsequent reports reflect the activity since the last report was issued.
.sp
.LP
Reports are issued every \fIinterval\fR seconds up to the quantity specified by \fIcount\fR, or forever if \fIcount\fR is not specified.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.mk
.na
\fB\fB-p\fR\fR
.ad
.RS 12n
.rt
Report statistics for capped projects. This is the default if no option is specified.
.RE
.sp
.ne 2
.mk
.na
\fB\fB-T\fR \fBu\fR | \fBd\fR\fR
.ad
.RS 12n
.rt
Display a time stamp.
.sp
Specify \fBu\fR for a printed representation of the internal representation of time. See \fBtime\fR(2). Specify \fBd\fR for standard date format. See \fBdate\fR(1).
.RE
.sp
.ne 2
.mk
.na
\fB\fB-z\fR\fR
.ad
.RS 12n
.rt
Report statistics for capped zones.
.RE
.SH OUTPUT
.sp
.LP
The following list defines the column headings in the \fBrcapstat\fR report and provides information about how to interpret the report.
.sp
.ne 2
.mk
.na
\fB\fBid\fR\fR
.ad
.RS 11n
.rt
The project ID or zone \fBID\fR of the capped project or zone.
.RE
.sp
.ne 2
.mk
.na
\fB\fBcappd\fR\fR
.ad
.RS 11n
.rt
Is the project or zone cap enforced.
.RE
.sp
.ne 2
.mk
.na
\fB\fBproject\fR\fR
.ad
.RS 11n
.rt
The project name.
.RE
.sp
.ne 2
.mk
.na
\fB\fBzone\fR\fR
.ad
.RS 11n
.rt
The zone name.
.RE
.sp
.ne 2
.mk
.na
\fB\fBnproc\fR\fR
.ad
.RS 11n
.rt
The number of processes in the project or zone since the last report.
.RE
.sp
.ne 2
.mk
.na
\fB\fBvm\fR\fR
.ad
.RS 11n
.rt
The total of all anonymous mappings that reserve disk or memory swap.
.RE
.sp
.ne 2
.mk
.na
\fB\fBrss\fR\fR
.ad
.RS 11n
.rt
The total resident set size (\fBRSS\fR) of the project or zone's processes, in kilobytes (\fBK\fR), megabytes (\fBM\fR), or gigabytes (\fBG\fR). The count does not account for shared pages.
.RE
.sp
.ne 2
.mk
.na
\fB\fBcap\fR\fR
.ad
.RS 11n
.rt
The \fBRSS\fR cap for the project or zone. See \fBrcapd\fR(1M) for information about how to specify memory caps.
.RE
.sp
.ne 2
.mk
.na
\fB\fBat\fR\fR
.ad
.RS 11n
.rt
The total amount of memory that \fBrcapd\fR attempted to page out.
.sp
Paging refers to the act of relocating portions of memory, called pages, to or from physical memory. \fBrcapd\fR pages out the most infrequently used pages.
.RE
.sp
.ne 2
.mk
.na
\fB\fBavgat\fR\fR
.ad
.RS 11n
.rt
The average amount of memory that \fBrcapd\fR attempted to page out during each sample cycle. The rate at which \fBrcapd\fR samples \fBRSS\fR can be set with \fBrcapadm\fR(1M).
.RE
.sp
.ne 2
.mk
.na
\fB\fBpg\fR\fR
.ad
.RS 11n
.rt
An estimate of the total amount of memory that \fBrcapd\fR successfully paged out.
.RE
.sp
.ne 2
.mk
.na
\fB\fBavgpg\fR\fR
.ad
.RS 11n
.rt
An estimate of the average amount of memory that \fBrcapd\fR successfully paged out during each sample cycle. The rate at which \fBrcapd\fR samples process \fBRSS\fR sizes can be set with \fBrcapadm\fR.
.RE
.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.mk
.na
\fB\fIinterval\fR\fR
.ad
.RS 12n
.rt
Specifies the reporting interval in seconds. The default interval is 5 seconds.
.RE
.sp
.ne 2
.mk
.na
\fB\fIcount\fR\fR
.ad
.RS 12n
.rt
Specifies the number of reports to produce. By default, \fBrcapstat\fR reports statistics until a termination signal is received or until the \fBrcapd\fR process exits.
.RE
.SH EXAMPLES
.LP
\fBExample 1 \fRUsing \fBrcapstat\fR to Report Cap and Project Information
.sp
.LP
Caps are defined for two projects associated with two users. \fBuser1\fR has a cap of 50 megabytes and \fBuser2\fR has a cap of 10 megabytes.
.sp
.LP
The following command produces five reports at 5-second sampling intervals.
.sp
.in +2
.nf
example# \fBrcapstat 5 5\fR
id project cappd nproc vm rss cap at avgat pg avgpg
112270 user1 Yes 24 123M 35M 50M 50M 0K 3312K 0K
78194 user2 Yes 1 2368K 1856K 10M 0K 0K 0K 0K
id project cappd nproc vm rss cap at avgat pg avgpg
112270 user1 Yes 24 123M 35M 50M 0K 0K 0K 0K
78194 user2 Yes 1 2368K 1856K 10M 0K 0K 0K 0K
id project cappd nproc vm rss cap at avgat pg avgpg
112270 user1 Yes 24 123M 35M 50M 0K 0K 0K 0K
78194 user2 Yes 1 2368K 1928K 10M 0K 0K 0K 0K
id project cappd nproc vm rss cap at avgat pg avgpg
112270 user1 Yes 24 123M 35M 50M 0K 0K 0K 0K
78194 user2 Yes 1 2368K 1928K 10M 0K 0K 0K 0K
id project cappd nproc vm rss cap at avgat pg avgpg
112270 user1 Yes 24 123M 35M 50M 0K 0K 0K 0K
78194 user2 Yes 1 2368K 1928K 10M 0K 0K 0K 0K
.fi
.in -2
.sp
.sp
.LP
The first three lines of output constitute the first report, which contains the cap and project information for the two projects and paging statistics since \fBrcapd\fR was started. The \fBat\fR and \fBpg\fR columns are a number greater than zero for \fBuser1\fR and zero for \fBuser2\fR, which indicates that at some time in the daemon's history, \fBuser1\fR exceeded its cap but \fBuser2\fR did not.
.sp
.LP
The subsequent reports show no significant activity.
.LP
\fBExample 2 \fRUsing \fBrcapstat\fR to Monitor the RSS of a Project
.sp
.in +2
.nf
example% \fBrcapstat 5 5\fR
id project cappd nproc vm rss cap at avgat pg avgpg
376565 user1 Yes 57 209M 46M 10M 440M 220M 5528K 2764K
376565 user1 Yes 57 209M 44M 10M 394M 131M 4912K 1637K
376565 user1 Yes 56 207M 43M 10M 440M 147M 6048K 2016K
376565 user1 Yes 56 207M 42M 10M 522M 174M 4368K 1456K
376565 user1 Yes 56 207M 44M 10M 482M 161M 3376K 1125K
.fi
.in -2
.sp
.sp
.LP
The project \fBuser1\fR has an \fBRSS\fR in excess of its physical memory cap. The nonzero values in the \fBpg\fR column indicate that \fBrcapd\fR is consistently paging out memory as it attempts to meet the cap by lowering the physical memory utilization of the project's processes. However, \fBrcapd\fR is unsuccessful, as indicated by the varying \fBrss\fR values that do not show a corresponding decrease. This means that the application's resident memory is being actively used, forcing \fBrcapd\fR to affect the working set. Under this condition, the system continues to experience high page fault rates, and associated I/O, until the working set size (\fBWSS\fR) is reduced, the cap is raised, or the application changes its memory access pattern. Notice that a page fault occurs when either a new page must be created, or the system must copy in a page from the swap device.
.LP
\fBExample 3 \fRDetermining the Working Set Size of a Project
.sp
.LP
This example is a continuation of \fBExample 1\fR, and it uses the same project.
.sp
.in +2
.nf
example% \fBrcapstat 5 5\fR
id project cappd nproc vm rss cap at avgat pg avgpg
376565 user1 Yes 56 207M 44M 10M 381M 191M 15M 7924K
376565 user1 Yes 56 207M 46M 10M 479M 160M 2696K 898K
376565 user1 Yes 56 207M 46M 10M 424M 141M 7280K 2426K
376565 user1 Yes 56 207M 43M 10M 401M 201M 4808K 2404K
376565 user1 Yes 56 207M 43M 10M 456M 152M 4800K 1600K
376565 user1 Yes 56 207M 44M 10M 486M 162M 4064K 1354K
376565 user1 Yes 56 207M 52M 100M 191M 95M 1944K 972K
376565 user1 Yes 56 207M 55M 100M 0K 0K 0K 0K
376565 user1 Yes 56 207M 56M 100M 0K 0K 0K 0K
376565 user1 Yes 56 207M 56M 100M 0K 0K 0K 0K
376565 user1 Yes 56 207M 56M 100M 0K 0K 0K 0K
376565 user1 Yes 56 207M 56M 100M 0K 0K 0K 0K
.fi
.in -2
.sp
.sp
.LP
By inhibiting cap enforcement, either by raising the cap of a project or by changing the minimum physical memory utilization for cap enforcement (see \fBrcapadm\fR(1M)), the resident set can become the working set. The \fBrss\fR column might stabilize to show the project \fBWSS\fR, as shown in the previous example. The \fBWSS\fR is the minimum cap value that allows the project's processes to operate without perpetually incurring page faults.
.LP
\fBExample 4 \fRAutomatic Enforcement/non enforcement of rss caps
.sp
.in +2
.nf
example% \fBrcapstat 10\fR
id project cappd nproc vm rss cap at avgat pg avgpg
100 user1 Yes - 101M 103M 100M 0K 0K 0K 0K
100 user1 Yes - 101M 103M 100M 0K 0K 0K 0K
100 user1 Yes - 101M 103M 100M 0K 0K 0K 0K
100 user1 Yes 2 201M 203M 100M 2780K 2780K 2780K 2780K
100 user1 Yes - 201M 203M 100M 0K 0K 0K 0K
100 user1 Yes 2 201M 203M 100M 103M 103M 103M 103M
100 user1 Yes 2 201M 203M 100M 103M 103M 103M 103M
100 user1 Yes - 201M 203M 100M 0K 0K 0K 0K
100 user1 Yes 2 201M 203M 100M 103M 103M 103M 103M
100 user1 Yes 2 201M 203M 100M 103M 103M 103M 103M
100 user1 Yes - 201M 203M 100M 0K 0K 0K 0K
100 user1 Yes 2 201M 203M 100M 103M 103M 103M 103M
100 user1 Yes 2 201M 203M 100M 103M 103M 103M 103M
100 user1 Yes - 201M 203M 100M 0K 0K 0K 0K
100 user1 Yes 2 201M 203M 100M 103M 103M 103M 103M
100 user1 Yes 2 201M 203M 100M 103M 103M 103M 103M
100 user1 Yes - 201M 203M 100M 0K 0K 0K 0K
100 user1 No 2 201M 203M 100M 103M 103M 103M 103M
100 user1 Yes - 101M 103M 100M 0K 0K 0K 0K
100 user1 Yes - 101M 103M 100M 0K 0K 0K 0K
.fi
.in -2
.sp
.sp
.LP
project user1 begins with a resident set size of 200M, more than its maximum physical memory cap of 100M. At first \fBrcapd\fR begins enforcing the caps on the project - shown by "Yes" under \fBcappd\fR column. After a while, \fBrcapd\fR evaluates that the memory cap set for project user1 cannot be achieved. Thus to avoid thrashing frequently used pages, causing slower performance, it stops enforcing the caps on user1. Thus we see a "No" against the cappd heading. When the resident set size of user1 reduces to 100M, we see that rcapd begins to enforce caps back on the project.
.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.mk
.na
\fB\fB0\fR\fR
.ad
.RS 5n
.rt
Successful completion.
.RE
.sp
.ne 2
.mk
.na
\fB\fB1\fR\fR
.ad
.RS 5n
.rt
An error occurred.
.RE
.sp
.ne 2
.mk
.na
\fB\fB2\fR\fR
.ad
.RS 5n
.rt
Invalid command-line options were specified.
.RE
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp
.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i)
lw(2.75i) |lw(2.75i)
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Availabilitysystem/resource-mgmt/resource-caps
.TE
.SH SEE ALSO
.sp
.LP
\fBrcapadm\fR(1M), \fBrcapd\fR(1M), \fBattributes\fR(5)
.sp
.LP
\fIPhysical Memory Control Using the Resource Capping Daemon\fR in \fISystem Administration Guide: Resource Management\fR
.SH NOTES
.sp
.LP
If the interval specified to \fBrcapstat\fR is shorter than the reporting interval specified to \fBrcapd\fR (with \fBrcapadm\fR(1M)), the output for some intervals can be zero. This is because \fBrcapd\fR does not update statistics more frequently than the interval specified with \fBrcapadm\fR, and this interval is independent of (and less precise than) the sampling interval used by \fBrcapstat\fR.