Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

rcapstat(1)

Name

rcapstat - report resource cap enforcement daemon statistics

Synopsis

rcapstat [-p | -z] [-T u | d ] [interval [count]]

Description

The rcapstat command reports on the projects or zones capped by rcapd(8). 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:

–p

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

–T u | d

Display a time stamp.

Specify u for a printed representation of the internal representation of time. See time(2). Specify d for standard date format. See date(1).

–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.

cappd

Is the project or zone cap enforced.

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 of all anonymous mappings that reserve disk or memory swap.

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(8) 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(8) .

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    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 

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    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

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    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

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(8)), 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 incurring page faults.

Example 4 Automatic Enforcement/non enforcement of rss caps
example% rcapstat 10
    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

project user1 begins with a resident set size of 200M, more than its maximum physical memory cap of 100M. At first rcapd begins enforcing the caps on the project - shown by "Yes" under cappd column. After a while, rcapd 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.

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(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/resource-mgmt/resource-caps

See Also

attributes(7), rcapadm(8), rcapd(8)

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(8)), 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.