rcapstat(1)															       rcapstat(1)

NAME

       rcapstat - report resource cap enforcement daemon statistics

SYNOPSIS

       rcapstat [-g] [interval	[count]]

       The  rcapstat  command  reports on the projects capped by rcapd(1M). Each report contains statistics that pertain to the project 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.

       The following command-line option is 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.

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 of the capped project.

       project	       The project name.

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

       vm	       The  total  virtual  memory  size  of  the  project'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'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. 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.

       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.

       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.

       The following exit values are returned:

       0	Successful completion.

       1	An error occurred.

       2	Invalid command-line options were specified.

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

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

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

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

       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.

								    22 Feb 2005 						       rcapstat(1)