Solaris Resource Manager 1.3 Reference Manual

rcapstat(1SRM)

NAME

rcapstat- report resource cap enforcement daemon statistics

SYNOPSIS

rcapstat

-g

interval

count

DESCRIPTION

The rcapstat command reports on the lnodes and projects capped by rcapd(1MSRM). Each report contains current statistics that pertain to the lnode or 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.

OPTIONS

The following command-line option is supported:

-g: Report the global memory utilization cap set by rcapadm(1MSRM), and report current memory utilization as a percentage of all physical memory installed on the system.

OUTPUT

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

id

The ID of the capped lnode or project.

lnode/project

The collection ID type, which is project or lnode.

nproc

The number of processes in the collection.

vm

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

rss

The total resident set size (RSS) of the collection of processes, in kilobytes (K), megabytes (M), or gigabytes (G).

cap

The RSS cap defined for a project or an lnode. See rcapd(1MSRM) for information about how to specify memory caps.

at

The total amount of memory that rcapd attempted to page out since the last rcapstat sample.

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 that occurred since the last rcapstat sample. The rate at which rcapd samples collection RSS can be set with rcapadm(1MSRM).

pg

An estimate of the total amount of memory that rcapd successfully paged out since the last rcapstat sample.

avgpg

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

OPERANDS

interval: Specifies the sampling interval in seconds. The default interval is 5 seconds.
count: Specifies the number of times that the statistics are repeated. 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 Lnode Information

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

The following command produces reports at 5-second sampling intervals. A report will be issued five times, once after each sample.

# rcapstat 5 5
    id lnode   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 lnode   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 lnode   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 lnode   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 lnode   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 lnode information for the two lnodes 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 will continue to experience high page fault rates, and associated I/O, until the working set size is reduced, the cap is raised, or the application changes its memory access pattern. Note 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 cap enforcement memory pressure value (see rcapadm(1MSRM)), the resident set can become the working set. The rss column might stabilize to show the project working set size, as shown in the previous example. This is the minimum cap value that will allow the project's processes to operate without perpetually incurring 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
Architecture	SPARC
Availability	SUNWrcapu

NOTES

If the interval specified to rcapstat is shorter than the reporting interval specified to rcapd(with rcapadm(1MSRM)), 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.

The command described in this man page is only available on SunOS 5.8.

SunOS 5.8 Last Revised 1 Nov 2002