The xstat Data Collection Facility

The xstat Data Collection Facility
	Chapter 8. Monitoring and Auditing AFS Performance

The afsmonitor program uses the xstat data collection facility to gather and calculate the data that it (the afsmonitor program) then uses to perform its function. You can also use the xstat facility to create your own data display programs. If you do, keep the following in mind. The File Server considers any program calling its RPC routines to be a Cache Manager; therefore, any program calling the File Server interface directly must export the Cache Manager's callback interface. The calling program must be capable of emulating the necessary callback state, and it must respond to periodic keep-alive messages from the File Server. In addition, a calling program must be able to gather the collected data.

The xstat facility consists of two C language libraries available to user-level applications:

/usr/afsws/lib/afs/libxstat_fs.a exports calls that gather information from one or more running File Server processes.
/usr/afsws/lib/afs/libxstat_cm.a exports calls that collect information from one or more running Cache Managers.

The libraries allow the caller to register

A set of File Servers or Cache Managers to be examined.
The frequency with which the File Servers or Cache Managers are to be probed for data.
A user-specified routine to be called each time data is collected.

The libraries handle all of the lightweight processes, callback interactions, and timing issues associated with the data collection. The user needs only to process the data as it arrives.

The libxstat Libraries

The libxstat_fs.a and libxstat_cm.a libraries handle the callback requirements and other complications associated with the collection of data from File Servers and Cache Managers. The user provides only the means of accumulating the desired data. Each xstat library implements three routines:

Initialization (xstat_fs_Init and xstat_cm_Init) arranges the periodic collection and handling of data.
Immediate probe (xstat_fs_ForceProbeNow and xstat_cm_ForceProbeNow) forces the immediate collection of data, after which collection returns to its normal probe schedule.
Cleanup (xstat_fs_Cleanup and xstat_cm_Cleanup) terminates all connections and removes all traces of the data collection from memory.

The File Server and Cache Manager each define data collections that clients can fetch. A data collection is simply a related set of numbers that can be collected as a unit. For example, the File Server and Cache Manager each define profiling and performance data collections. The profiling collections maintain counts of the number of times internal functions are called within servers, allowing bottleneck analysis to be performed. The performance collections record, among other things, internal disk I/O statistics for a File Server and cache effectiveness figures for a Cache Manager, allowing for performance analysis.

For a copy of the detailed specification which provides much additional usage information about the xstat facility, its libraries, and the routines in the libraries, contact AFS Product Support.

Example xstat Commands

AFS comes with two low-level, example commands: xstat_fs_test and xstat_cm_test. The commands allow you to experiment with the xstat facility. They gather information and display the available data collections for a File Server or Cache Manager. They are intended merely to provide examples of the types of data that can be collected via xstat; they are not intended for use in the actual collection of data.

To use the example xstat_fs_test command

Issue the example xstat_fs_test command to test the routines in the libxstat_fs.a library and display the data collections associated with the File Server process. The command executes in the foreground.
```
   % xstat_fs_test [initcmd]  \
                   -fsname <File Server name(s) to monitor>+  \
                   -collID <Collection(s) to fetch>+  [-onceonly]  \
                   [-frequency <poll frequency, in seconds>]  \
                   [-period <data collection time, in minutes>] [-debug] 
```
where
xstat_fs_test
Must be typed in full.
initcmd
Is an optional string that accommodates the command's use of the AFS command parser. It can be omitted and ignored.
-fsname
Is the Internet host name of each file server machine on which to monitor the File Server process.
-collID
Specifies each data collection to return. The indicated data collection defines the type and amount of data the command is to gather about the File Server. Data is returned in the form of a predefined data structure (refer to the specification documents referenced previously for more information about the data structures).
There are two acceptable values:
1 reports various internal performance statistics related to the File Server (for example, vnode cache entries and Rx protocol activity).
2 reports all of the internal performance statistics provided by the 1 setting, plus some additional, detailed performance figures about the File Server (for example, minimum, maximum, and cumulative statistics regarding File Server RPCs, how long they take to complete, and how many succeed).
-onceonly
Directs the command to gather statistics just one time. Omit this option to have the command continue to probe the File Server for statistics every 30 seconds. If you omit this option, you can use the <Ctrl-c> interrupt signal to halt the command at any time.
-frequency
Sets the frequency in seconds at which the program initiates probes to the File Server. If you omit this argument, the default is 30 seconds.
-period
Sets how long the utility runs before exiting, as a number of minutes. If you omit this argument, the default is 10 minutes.
-debug
Displays additional information as the command runs.

To use the example xstat_cm_test command

Issue the example xstat_cm_test command to test the routines in the libxstat_cm.a library and display the data collections associated with the Cache Manager. The command executes in the foreground.
```
   % xstat_cm_test [initcmd]  \
                   -cmname <Cache Manager name(s) to monitor>+  \
                   -collID <Collection(s) to fetch>+ \
                   [-onceonly] [-frequency <poll frequency, in seconds>]  \
                   [-period <data collection time, in minutes>] [-debug] 
```
where
xstat_cm_test
Must be typed in full.
initcmd
Is an optional string that accommodates the command's use of the AFS command parser. It can be omitted and ignored.
-cmname
Is the host name of each client machine on which to monitor the Cache Manager.
-collID
Specifies each data collection to return. The indicated data collection defines the type and amount of data the command is to gather about the Cache Manager. Data is returned in the form of a predefined data structure (refer to the specification documents referenced previously for more information about the data structures).
There are two acceptable values:
0 provides profiling information about the numbers of times different internal Cache Manager routines were called since the Cache manager was started.
1 reports various internal performance statistics related to the Cache manager (for example, statistics about how effectively the cache is being used and the quantity of intracell and intercell data access).
2 reports all of the internal performance statistics provided by the 1 setting, plus some additional, detailed performance figures about the Cache Manager (for example, statistics about the number of RPCs sent by the Cache Manager and how long they take to complete; and statistics regarding things such as authentication, access, and PAG information associated with data access).
-onceonly
Directs the command to gather statistics just one time. Omit this option to have the command continue to probe the Cache Manager for statistics every 30 seconds. If you omit this option, you can use the <Ctrl-c> interrupt signal to halt the command at any time.
-frequency
Sets the frequency in seconds at which the program initiates probes to the Cache Manager. If you omit this argument, the default is 30 seconds.
-period
Sets how long the utility runs before exiting, as a number of minutes. If you omit this argument, the default is 10 minutes.
-debug
Displays additional information as the command runs.


To stop the afsmonitor program		Auditing AFS Events on AIX File Servers