rcapstat(1)							   User Commands						       rcapstat(1)

NAME

       rcapstat - report resource cap enforcement daemon statistics

SYNOPSIS

       rcapstat [-g] [-p | -z] [interval [count]]

DESCRIPTION

       The  rcapstat  command reports on the projects or zones capped by rcapd(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.  rcapd
       pages out the most infrequently used pages.

       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.

       Reports are issued every interval seconds up to the quantity specified by count, or forever if count is not specified.

OPTIONS

       The following options are supported:

       -g    Global statistics. Reports the minimum memory utilization for memory cap enforcement (see rcapadm(1M))  and  reports  current  memory
	     utilization as a percentage of installed physical memory.

       -p    Report statistics for capped projects.  This is the default if no option is specified.

       -z    Report statistics for capped zones.

OUTPUT

       The following list defines the column headings in the rcapstat report and provides information about how to interpret the report.

       id	  The project ID or zone ID of the capped project or zone.

       project	  The project name.

       zone	  The zone name.

       nproc	  The number of processes in the project or zone since the last report.

       vm	  The  total  virtual  memory  size  of the project or zone's processes, including all mapped files and devices, in kilobytes (K),
		  megabytes (M), or gigabytes (G).

       rss	  The total resident set size (RSS) of the project or zone's processes, in kilobytes (K), megabytes (M),  or  gigabytes  (G).  The
		  count does not account for shared pages.

       cap	  The RSS cap for the project or zone. See rcapd(1M) for information about how to specify memory caps.

       at	  The total amount of memory that rcapd attempted to page out.

		  Paging  refers  to  the act of relocating portions of memory, called pages, to or from physical memory. rcapd pages out the most
		  infrequently used pages.

       avgat	  The average amount of memory that rcapd attempted to page out during	each sample cycle. The rate at which rcapd samples RSS can
		  be set with rcapadm(1M).

       pg	  An estimate of the total amount of memory that rcapd successfully paged out.

       avgpg	  An  estimate of the average amount of memory that rcapd successfully paged out during each sample cycle. The rate at which rcapd
		  samples process RSS sizes can be set with rcapadm.

OPERANDS

       The following operands are supported:

       interval    Specifies the reporting interval in seconds. The default interval is 5 seconds.

       count	   Specifies the number of reports to produce. By default, rcapstat reports statistics until a termination signal is  received	or
		   until the rcapd process exits.

EXAMPLES

       Example 1 Using rcapstat to Report Cap and Project Information

       Caps are defined for two projects associated with two users. user1 has a cap of 50 megabytes and user2 has a cap of 10 megabytes.

       The following command produces five reports at 5-second sampling intervals.

	 example# rcapstat 5 5
	     id project  nproc	   vm	 rss   cap    at avgat	  pg avgpg
	 112270   user1     24	 123M	 35M   50M   50M    0K 3312K	0K
	  78194   user2      1	2368K  1856K   10M    0K    0K	  0K	0K
	     id project  nproc	   vm	 rss   cap    at avgat	  pg avgpg
	 112270   user1     24	 123M	 35M   50M    0K    0K	  0K	0K
	  78194   user2      1	2368K  1856K   10M    0K    0K	  0K	0K
	     id project  nproc	   vm	 rss   cap    at avgat	  pg avgpg
	 112270   user1     24	 123M	 35M   50M    0K    0K	  0K	0K
	  78194   user2      1	2368K  1928K   10M    0K    0K	  0K	0K
	     id project  nproc	   vm	 rss   cap    at avgat	  pg avgpg
	 112270   user1     24	 123M	 35M   50M    0K    0K	  0K	0K
	  78194   user2      1	2368K  1928K   10M    0K    0K	  0K	0K
	     id project  nproc	   vm	 rss   cap    at avgat	  pg avgpg
	 112270   user1     24	 123M	 35M   50M    0K    0K	  0K	0K
	  78194   user2      1	2368K  1928K   10M    0K    0K	  0K	0K

       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 rcapd was started. The at and pg columns are a number greater than zero for user1 and zero for user2, which indicates that
       at some time in the daemon's history, user1 exceeded its cap but user2 did not.

       The subsequent reports show no significant activity.

       Example 2 Using rcapstat to Monitor the RSS of a Project

	 example% rcapstat 5 5
	     id project  nproc	  vm   rss   cap    at avgat	 pg  avgpg
	 376565   user1     57	209M   46M   10M  440M	220M  5528K  2764K
	 376565   user1     57	209M   44M   10M  394M	131M  4912K  1637K
	 376565   user1     56	207M   43M   10M  440M	147M  6048K  2016K
	 376565   user1     56	207M   42M   10M  522M	174M  4368K  1456K
	 376565   user1     56	207M   44M   10M  482M	161M  3376K  1125K

       The  project user1 has an RSS in excess of its physical memory cap. The nonzero values in the pg column indicate that rcapd is consistently
       paging out memory as it attempts to meet the cap by lowering the physical memory utilization of the project's processes. However, rcapd	is
       unsuccessful,  as indicated by the varying rss values that do not show a corresponding decrease. This means that the application's resident
       memory is being actively used, forcing rcapd 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 (WSS) 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.

       Example 3 Determining the Working Set Size of a Project

       This example is a continuation of Example 1, and it uses the same project.

	 example% rcapstat 5 5
	     id project  nproc	  vm   rss   cap    at avgat	 pg  avgpg
	 376565   user1     56	207M   44M   10M  381M	191M	15M  7924K
	 376565   user1     56	207M   46M   10M  479M	160M  2696K   898K
	 376565   user1     56	207M   46M   10M  424M	141M  7280K  2426K
	 376565   user1     56	207M   43M   10M  401M	201M  4808K  2404K
	 376565   user1     56	207M   43M   10M  456M	152M  4800K  1600K
	 376565   user1     56	207M   44M   10M  486M	162M  4064K  1354K
	 376565   user1     56	207M   52M  100M  191M	 95M  1944K   972K
	 376565   user1     56	207M   55M  100M    0K	  0K	 0K	0K
	 376565   user1     56	207M   56M  100M    0K	  0K	 0K	0K
	 376565   user1     56	207M   56M  100M    0K	  0K	 0K	0K
	 376565   user1     56	207M   56M  100M    0K	  0K	 0K	0K
	 376565   user1     56	207M   56M  100M    0K	  0K	 0K	0K

       By  inhibiting  cap  enforcement,  either  by  raising the cap of a project or by changing the minimum physical	memory utilization for cap
       enforcement (see rcapadm(1M)), the resident set can become the working set. The rss column might stabilize to  show  the  project  WSS,	as
       shown  in  the previous example. The WSS is the minimum cap value that allows the project's processes to operate without perpetually incur-
       ring page faults.

EXIT STATUS

       The following exit values are returned:

       0    Successful completion.

       1    An error occurred.

       2    Invalid command-line options were specified.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWrcapu 		   |
       +-----------------------------+-----------------------------+

SEE ALSO

       rcapadm(1M), rcapd(1M), attributes(5)

       Physical Memory Control Using the Resource Capping Daemon in System Administration Guide: Resource Management

NOTES

       If the interval specified to rcapstat is shorter than the reporting interval specified to rcapd (with rcapadm(1M)),  the  output  for  some
       intervals  can be zero. This is because rcapd does not update statistics more frequently than the interval specified with rcapadm, and this
       interval is independent of (and less precise than) the sampling interval used by rcapstat.

SunOS 5.11							    15 Dec 2006 						       rcapstat(1)