The /var/adm/acct directory contains the following directories:

The following files are located in the /var/adm/acct/day directory:

The following files are located in the /var/adm/acct/work/MMDD/hhmm directory:

The following data files are located in the /var/adm/acct/sum/csa directory:

The following files are located in the /var/adm/acct/fiscal/csa directory:

The following files are located in the /var/adm/acct/nite/csa directory:

The /usr/lib/acct directory contains the following commands and shell scripts used by CSA:

The /usr/bin directory contains user commands associated with CSA:

The /usr/lib/acct directory may also contain the following scripts if your site uses the accounting user exits:

The /etc directory is the location of the csa.conf file that contains the parameter labels and values used by CSA software.

The /etc/config directory is the location of the csaacct file used by the chkconfig(1M) command. The csaacct.options contains options passed to the csaswitch(1M) command. Use a text editor to add any csaswitch(1M) options to be passed to csaswitch during system startup only.

The csarun command is invoked periodically by cron. It is very important that you ensure that the previous invocation of csarun completed successfully before invoking csarun for a new accounting period. If this is not done, information about unfinished jobs will be inaccurate.

Data for a new accounting period can also be interactively processed by executing the following:

nohup csarun 2> /var/adm/acct/nite/csa/fd2log &

Before executing csarun in this manner, ensure that the previous invocation completed successfully. To do this, look at the files active and statefile in /var/adm/acct/nite/csa. Both files should specify that the last invocation completed successfully. See “Restarting csarun”.

The csarun error and status messages are placed in the /var/adm/acct/nite/csa directory. The progress of a run is tracked by writing descriptive messages to the file active. Diagnostic output during the execution of csarun is written to fd2log. The lock and lock1 files prevent concurrent invocations of csarun; csarun will abort if these two files exist when it is invoked. The clastdate file contains the month, day, and time of the last two executions of csarun.

Errors and warning messages from programs called by csarun are written to files that have names beginning with E and ending with the current date and time. For example, Ebld.11121400 is an error file from csabuild for a csarun invocation on November 12, at 14:00.

If csarun detects an error, it writes a message to the SYSLOG file, removes the locks, saves the diagnostic files, and terminates execution. When csarun detects an error, it will send mail either to MAIL_LIST if it is a fatal error, or to WMAIL_LIST if it is a warning message, as defined in the configuration file /etc/csa.conf.

Processing is broken down into separate reentrant states so that csarun can be restarted. As each state completes, /var/adm/acct/nite/csa/statefile is updated to reflect the next state. When csarun reaches the CLEANUP state, it removes various data files and the locks, and then terminates.

The following describes the events that occur in each state. MMDD refers to the month and day csarun was invoked. hhmm refers to the hour and minute of invocation.

If csarun is executed without arguments, the previous invocation is assumed to have completed successfully.

The following operands are required with csarun if it is being restarted:

csarun [MMDD [hhmm [state]]]

MMDD is month and day, hhmm is hour and minute, and state is the csarun entry state.

To restart csarun, follow these steps:

Before csarun is restarted, the appropriate directories must be restored. If the directories are not restored, further processing is impossible. These directories are as follows:

/var/adm/acct/work/MMDD/hhmm
/var/adm/acct/sum/csa

If you are restarting at state ARCHIVE2, CMS, REPORT, DREP, or FEF, the sorted pacct file must be in /var/adm/acct/work/MMDD/hhmm. If the file does not exist, csarun automatically will restart at the BUILD state. Depending on the tasks performed during the site-specific USEREXIT state, [the sorted pacct file may or may not need to exist.] This may or may not be acceptable.

Interactive jobs, cron jobs, and at jobs terminate when the last process in the job exits. Normally, the last process to terminate is the login shell. The kernel writes an end-of-job (EOJ) record to the pacct file when the job terminates.

When the NQS daemon or workload management daemon delivers an NQS or workload management request's output, the request terminates. The daemon then writes an NQ_DISP record type for NQS or WM_TERM record type for workload management to the pacct accounting file, while the kernel writes an EOJ record to the pacct file.

Unlike interactive jobs, NQS or workload management requests can have multiple EOJ records associated with them. In addition to the request's EOJ record, there can be EOJ records for pipe clients (NQS only), net clients, and checkpointed portions of the request. The pipe client and net client perform NQS or workload management processing on behalf of the request. The Load Sharing Facility (LSF) system currently does not support net clients.

The csabuild command flags jobs in the sorted pacct file as being terminated if they meet one of the following conditions:

Recycling unnecessary data can consume large amounts of disk space and CPU time. The sorted pacct file and recycled data can occupy a vast amount of disk space on the file system containing /var/adm/acct/day. Sites that archive data also require additional offline media. Wasted CPU cycles are used by csarun to reexamine and recycle the data. Therefore, to conserve disk space and CPU cycles, unnecessary recycled data should be purged from the accounting system.

Any of the following situations can cause CSA erroneously to recycle terminated jobs:

Before choosing to delete recycled data, you should understand the repercussions, as described in “Adverse Effects of Removing Recycled Data”. Data removal can affect billing and can alter the contents of the consolidated data file, which is used by csaperiod.

You can remove recycled data from CSA in the following ways:

CSA assumes that all necessary accounting information is available to it, which means that CSA expects kernel and daemon accounting to be enabled and recycled data not to have been mistakenly removed. If some data is unavailable, CSA may provide erroneous billing information. Sites should be aware of the following facts before removing data:

The following table summarizes the effects of using the methods described in “How to Remove Recycled Data”.

By default, the consolidated data file contains data only for terminated jobs. Manual termination of recycled data may cause some of the recycled data to be included in the consolidated file.

For CSA to identify all NQS or workload management requests, data must be properly recycled. When an administrator manually purges recycled data for an NQS or workload management request, errors such as the following can occur:

These errors occur because valuable NQS or workload management accounting information was purged by the administrator. Only a few NQS or workload management accounting records are written by the NQS or workload management daemon, and all of the records are needed for CSA to properly bill NQS or workload management requests.

NQS or workload management accounting records are only written under the following circumstances:

Thus, for long running requests that span days, there can be days when no NQS or workload management data is written. Consequently, it is extremely important that accounting data be recycled. If the site administrator manually terminates recycled jobs, care must be taken to be sure that only nonexistent NQS or workload management requests are terminated.

A system billing unit (SBU) is a unit of measure that reflects use of machine resources. You can alter the weighting factors associated with each field in each accounting record to obtain an SBU value suitable for your site. SBUs are defined in the accounting configuration file, /etc/csa.conf. By default, all SBUs are set to 0.0.

Accounting allows different periods of time to be designated either prime or nonprime time (the time periods are specified in /usr/lib/acct/holidays).

Following is an example of how the prime/nonprime algorithm works:

Assume a user uses 10 seconds of CPU time, and executes for 100 seconds of prime wall-clock time, and pauses for 100 seconds of nonprime wall-clock time. Therefore, elapsed time is 200 seconds (100+100). If

prime = prime time / elapsed time
nonprime = nonprime time / elapsed time
cputime[PRIME] = prime * CPU time
cputime[NONPRIME] = nonprime * CPU time

then

cputime[PRIME] == 5 seconds
cputime[NONPRIME] == 5 seconds

Under CSA, an SBU value is associated with each record in the sorted pacct file when that file is assembled by csabuild. Final summation of the SBU values is done by csacon during the creation of the cacct record file.

The following examples show how a site can bill different NQS or workload management queues at differing rates.

Total SBU = (NQS queue SBU value) * (sum of all process record SBUs
     + sum of all tape record SBUs)

or

Total SBU = (Workload management queue SBU value) * (sum of all process record SBUs
     + sum of all tape record SBUs)

PSBU = (P_TIME * (P_STIME * stime + P_UTIME * utime + P_QTIME * qwtime +
P_BWTIME * bwtime + P_RWTIME * rwtime)) + (P_MEM * (P_XMEM * coremem + P_VMEM
* virtmem)) + (P_IO * (P_BIO * bio + P_CIO * cio + P_LIO * lio));

NSBU = (NP_TIME * (NP_STIME * stime + NP_UTIME * utime + NP_QTIME * qwtime +
NP_BWTIME * bwtime + NP_RWTIME * rwtime)) + (NP_MEM * (NP_XMEM * coremem +
NP_VMEM * virtmem)) + (NP_IO * (NP_BIO * bio + NP_CIO * cio + NP_LIO * lio));

SBU = P_BASIC * PSBU + NP_BASIC * NSBU;

Accounting information is available from the NQS, workload management, and online tape daemons. Data is written to the pacct file in the /var/adm/acct/day directory.

In most cases, daemon accounting must be enabled by both the CSA subsystem and the daemon. “Setting Up CSA”, describes how to enable daemon accounting at system startup time. You can also enable daemon accounting after the system has booted.

You can enable accounting for a specified daemon by using the csaswitch command. For example, to start tape accounting, you should do the following:

/usr/lib/acct/csaswitch -c on -n tape

The NQS or workload management, and online tape daemon, also, must enable accounting. Use the qmgr set accounting on command to turn on NQS accounting. Tape daemon accounting is enabled when tmdaemon(1m) is executed with the -c option.See the appropriate workload management guide for information on how to enable workload management accounting.

---

Note: If you are running the Load Sharing Facility (LSF) system and want to enable workload management accounting, you must set two LSF configuration variables in the lsf.conf file as follows: LSF_ENABLE_CSA=y LSF_ULDB_DOMAIN = <ULDB_domain_name> If LSF_ENABLE_CSA is defined in the lsf.conf file, LSF writes LSF batch job events to the pacct file for processing through CSA. For LSF job accounting, records are written to pacct at the start and end of each LSF job. If a ULDB domain for LSF is defined in the lsf.conf file, LSF creates an IRIX job and applies the configured resource limits to it. LSF resource limits defined in lsb.queues or at job submission override IRIX job limits defined in the ULDB. For more information on the Load Sharing Facility (LSF) system and workload management accounting, see the appropriate LSF documentation.

---

Daemon accounting is disabled at system shutdown (see “Setting Up CSA”). It can also be disabled at any time by the csaswitch command when used with the off operand. For example, to disable NQS accounting, execute the following command:

/usr/lib/acct/csaswitch -c off -n nqs

These dynamic changes using csaswitch are not saved across a system reboot.

CSA accommodates the following user exits, which can be called from certain csarun states:

CSA accommodates the following user exit, which can be called from certain csaperiod states:

These exits allow an administrator to tailor the csarun procedure (or csaperiod procedure) to the individual site's needs by creating scripts to perform additional site-specific processing during daily accounting. (Note that the following comments also apply to csaperiod).

While executing, csarun checks in the ARCHIVE1, ARCHIVE2, FEF and USEREXIT states for a shell script with the appropriate name.

If the script exists, it is executed via the shell . (dot) command. If the script does not exist, the user exit is ignored. The . (dot) command will not execute a compiled program, but the user exit script can. csarun variables are available, without being exported, to the user exit script. csarun checks the return status from the user exit and if it is nonzero, the execution of csarun is terminated.

If CSA is run by a user without superuser permissions, the user exits must be both readable and executable by this user (see “Allowing Non Superusers to Execute CSA”).

This section provides information about writing a user exit. The first example shows a user exit that saves the sorted pacct file after a daily accounting run. The second example shows a user exit that consolidates information for a daily report by project rather than by user.

#! /bin/sh
echo "Copying spacct file to /tmp/spacct"
cp ${SPACCT} /tmp/spacct

CONSOLIDATED INFORMATION REPORT BETWEEN 08/09 04:00   AND   08/09 14:48

PROJECT    USER    LOGIN    CPU-TIM  KCORE *  KVIRT *   IOWAIT [SECS]
 NAME       ID     NAME     [SECS]   CPU-MIN  CPU-MIN   BLOCK     RAW
======== ======== ======== ======== ======== ======== ======== ========
sysadm   0        root           30      536     1177       48        0
root     4        sys             0        5       11        0        0
csa      5        adm             5       24      194        1        0
root     1461     security        1        2       16        0        0
nqe      10320    user12          2        5       68        1        0

/usr/lib/acct/csacon -Ap -s /tmp/spacct > /tmp/cacct_p
/usr/lib/acct/csacrep -hpcw < /tmp/cacct_p > /tmp/csacrep.out.p

PROJECT    USER    LOGIN    CPU-TIM  KCORE *  KVIRT *   IOWAIT [SECS]
 NAME       ID     NAME     [SECS]   CPU-MIN  CPU-MIN   BLOCK     RAW
======== ======== ======== ======== ======== ======== ======== ========
root     Unknown  Unknown         1        8       28        0        0
sysadm   Unknown  Unknown        31      537     1187       49        0
csa      Unknown  Unknown         5       24      194        1        0
nqe      Unknown  Unknown         2        7       83        1        0

#!/sbin/sh
#
csacon ${ALLJOBS} -p -s ${SPACCT} > ${SUM_DIR}/cacct_p.${DTIME} \
        2> ${NITE_DIR}/Econ.${DTIME}
if [ ${?} -ne 0 ]
then
        CSAERRMSG="REPORT - csacon errors \
                \n\tSee ${NITE_DIR}/Econ.${DTIME} and/or ${NITE_DIR}/fd2log"
        ERROR_EXIT
fi
chgrp ${CHGRP} ${SUM_DIR}/cacct_p.${DTIME}
#
csacrep -hpcw < ${SUM_DIR}/cacct_p.${DTIME} \
> ${SUM_DIR}/conrpt_p.${DTIME} 2> ${NITE_DIR}/Ecrpt_p.${DTIME}
if [ ${?} -ne 0 ]
then
        CSAERRMSG="REPORT - csacrep errors \
                \n\tSee ${NITE_DIR}/Ecrep_p.${DTIME} and/or ${NITE_DIR}/fd2log"
        ERROR_EXIT
fi
#
cd ${SUM_DIR}
echo "${RPTHDR}\n" > tmprprt
echo "Put some header message here\n"  >> tmprprt
cat conrpt_p.${DTIME} >> tmprprt
pr -h "${DAYHDR} ${SYSNAME} ${RELMSG}" tmprprt >> rprt.${DTIME}
#

By default, SBUs are calculated for all NQS jobs regardless of the job's NQS termination code. If you do not want to bill portions of an NQS request, set the appropriate NQS_TERM_xxxx variable (termination code) in the /etc/csa.conf file to 0, which sets the SBU for this portion to 0.0. By default, all portions of a request are billed.

The following table describes the termination codes:

By default, SBUs are calculated for all workload management jobs regardless of the workload management termination code of the job. If you do not want to bill portions of a workload management request, set the appropriate WKMG_TERM_xxxx variable (termination code) in the /etc/csa.conf file to 0, which sets the SBU for this portion to 0.0. By default, all portions of a request are billed.

The following table describes the termination codes:

---

Note: The above descriptions of the termination codes are very generic. Different workload managers will tailor the meaning of these codes to suit their products. LSF currently only uses the WKMG_TERM_EXIT termination code.

---

Modify the following variables in /etc/csa.conf if necessary:

You can use the at command instead of cron to execute csarun periodically. If your system is down when csarun is scheduled to run via cron, csarun will not be executed until the next scheduled time. On the other hand, at jobs execute when the machine reboots if their scheduled execution time was during a down period.

You can execute csarun by using at in several ways. For example, a separate script can be written to execute csarun and then resubmit the job at a specified time. Also, an at invocation of csarun could be placed in a user exit script, /usr/lib/acct/csa.user, that is executed from the USEREXIT section of csarun. For more information, see “Setting up User Exits”.

Your site may want to allow users without superuser permissions to run CSA accounting. CSA can be run by users who are in the group adm and have the CAP_ACCT_MGT capability. See the capability(4) and capabilities(4) man pages for more information on the capability mechanism that provides fine grained control over the privileges of a process.

The following steps describe the process of setting up CSA so it is executed automatically on a daily and periodic basis by a user without superuser permissions. In this example, the user without superuser permissions is adm:

---

Note: The cron entries listed above only work when the login shell of user adm is sh or ksh.

---

By default, the /etc/csa.conf configuration file is used when any of the CSA commands are executed. You can specify a different file by setting the shell variable CSACONFIG to another configuration file, and then executing the CSA commands.

For example, you would execute the following commands to use the configuration file /tmp/myconfig while executing csarun:

CSACONFIG=/tmp/myconfig
/usr/lib/acct/csarun 2> /var/adm/acct/nite/fd2log

The Consolidated Information Report is sorted by user ID and then project ID. The following usage values are the total amount of resources used by all processes for the specified user and project during the reporting period.

The Unfinished Job Information Report describes jobs which have not terminated and are recycled into the next accounting period.

The Disk Usage Report describes the amount of disk resource consumption by login name.

There are no column headings for this report. The first column gives the user identifier. The second column gives the login name associated with the user identifier. The third column gives the number of disk blocks used by this user.

The Command Summary Report summarizes command usage during this reporting period. The usage values are the total amount of resources used by all invocations of the specified command. Commands which were run only once are combined together in the "***other" entry. Only the first 44 command entries are displayed in the daily report. The periodic report displays all command entries.

The Last Login Report shows the last login date for each login account listed.

There are no column headings for this report. The first column is the last login date. The second column is the login account name.

Daemon Usage Report shows reports usage of the NQS or workload management, and tape daemons. This report has several individual reports depending upon if there was NQS, workload management, or tape daemon activity within this reporting period.

The Job Type Report gives the NQS and interactive job usage count.

The CPU Usage Report gives the NQS or workload management and interactive job usage related to CPU usage.

The Tape Usage Report gives the NQS or workload management and interactive job usage related to tape activity for these jobs.

The Batch Queue Report gives the following information for each NQS or workload management queue.

The following usage values for the Consolidated accounting report are the total amount of resources used by all processes for the specified user and project during the reporting period.

The following information summarizes command usage during the defined reporting period. The usage values are the total amount of resources used by all invocations of the specified command. Unlike the daily command summary report, the periodic command summary report displays all command entries. Commands executed only once are not combined together into an "***other" entry but are listed individually in the periodic command summary report.