VOS Accouting Facility (r281m-00)

Stratus TechnologiesR281M-00

VOS System Administration: The Accounting Facility

Notice

The information contained in this document is subject to change without notice.

UNLESS EXPRESSLY SET FORTH IN A WRITTEN AGREEMENT SIGNED BY AN AUTHORIZED REPRESENTATIVE OF STRATUS TECHNOLOGIES, STRATUS MAKES NO WARRANTY OR REPRESENTATION OF ANY KIND WITH RESPECT TO THE INFORMATION CONTAINED HEREIN, INCLUDING WARRANTY OF MERCHANTABILITY AND FITNESS FOR A PURPOSE. Stratus Technologies assumes no responsibility or obligation of any kind for any errors contained herein or in connection with the furnishing, performance, or use of this document.

Software described in Stratus documents (a) is the property of Stratus Technologies International, S.à r.l. or the third party, (b) is furnished only under license, and (c) may be copied or used only as expressly permitted under the terms of the license.

Stratus documentation describes all supported features of the user interfaces and the application programming interfaces (API) developed by Stratus. Any undocumented features of these interfaces are intended solely for use by Stratus personnel and are subject to change without warning.

This document is protected by copyright. All rights are reserved. No part of this document may be copied, reproduced, or translated, either mechanically or electronically, without the prior written consent of Stratus Technologies.

Stratus, the Stratus logo, Continuum, Continuous Processing, StrataLINK, and StrataNET are registered trademarks of Stratus Technologies International, S.à r.l.

ftServer, ftServer with design, Stratus 24 x 7 with design, The World’s Most Reliable Server, Selectable Availability, XA/R, SQL/2000, and The Availability Company are trademarks of Stratus Technologies International, S.à r.l.

RSN is a trademark of Lucent Technologies, Inc.All other trademarks are the property of their respective owners.

Manual Name: VOS System Administration: The Accounting Facility

Part Number: R281M Revision Number: 00

Stratus Technologies, Inc.111 Powdermill RoadMaynard, Massachusetts 01754-3409

© 2001 Stratus Technologies International, S.à r.l. All rights reserved.

Contents

1. VOS System Administration: The Accounting Facility 1-1THE ACCOUNTING FACILITY 1-1PROCESSING THE ACCOUNTING LOGS 1-2THE EXTERNAL VARIABLE s$acct_record 1-2ACCOUNTING FACILITY SUBROUTINES 1-5

s$acct_processing_init 1-5s$acct_init_summary 1-7s$acct_init_summary_key 1-7s$acct_next_record 1-8s$acct_get_longest_key 1-8s$acct_init_summary_output 1-9s$acct_next_summary_output 1-9

Contents iii

Contents

iv VOS System Administration: The Accounting Facility (R281M-00)

Chapter 1VOS System Administration:

The Accounting Facility1-

This file contains information to supplement the documentation provided inthe chapter entitled “The Accounting Facility” in the SystemAdministrator’s Guide.

THE ACCOUNTING FACILITYThe operating system performs accounting functions by writing recordsto a log file at various times during the execution of a process. Ata minimum, records are written at process creation and termination;you can also choose to write records when files are closed and whencommands are initiated and terminated. In addition, you can enableport accounting through the accounting_admin command to collectdetailed information about I/O activity on ports.

Process statistics records and process defined records are writtenwhen one of the following system subroutines is called:

s$log_resource_usage( client_user_id, code ); declare client_user_id char(65) varying, code fixed bin(15);

s$log_process_record( string_length, string, code ); declare string_len fixed bin(15), string char(N), code fixed bin(15);

The first subroutine, s$log_resource_usage, gathers all currentstatistics, writes them to the log file, and then resets all counters.It is used by server processes such as message servers to distributecharges to users sending requests to them. The second subroutine,s$log_process_record, writes a user defined record into the log. Ifthe accounting facility has not been enabled, these subroutines returnthe error code e$acct_records_not_logging.

If the information being logged is kept by the operating system inbinary form, the records written about it contain binary information.

The following table lists which operating system subroutine calls arecounted as reads and which as writes by port accounting.

WRITES READS ------------------------------------------ s$add_item s$get_item

VOS System Administration: The Accounting Facility 1-1

PROCESSING THE ACCOUNTING LOGS

s$add_key s$keyed_position_read s$keyed_position_rewrite s$keyed_read s$keyed_rewrite s$read_raw s$keyed_write s$rel_position_read s$rel_position_rewrite s$rel_read s$rel_rewrite s$seq_position_read s$rel_write s$seq_read s$seq_position_rewrite s$seq_rewrite s$seq_write s$seq_write_partial s$write_raw

PROCESSING THE ACCOUNTING LOGSThe runtime library contains a subroutine package you can use to readaccounting logs and produce reports. Some subroutines in the packageread selected records from the selected logs and present them to thecaller in time sequential order (even if more than one module isselected). While reading the records, they prepare a database fromwhich one or more summaries can be obtained. Other subroutines in thepackage retrieve the summary information.

The operating system also provides the include files necessary tosupport the package, and sample programs in BASIC, PL/I, and Pascalthat use the subroutines package.

The following subroutines are used for reading log files:

s$acct_processing_init s$acct_init_summary s$acct_init_summary_key s$acct_next_record

The following subroutines return summary information:

s$acct_get_longest_key s$acct_init_summary_output s$acct_next_summary_output

Descriptions of these subroutines appear later in this document.

Note that the external variable s$acct_record.version must be set to 1prior to calling any of the subroutines in this package.

THE EXTERNAL VARIABLE s$acct_recordMany of these subroutines reference fields in an operating systemexternal variable called s$acct_record. These fields are noted here;brief descriptions are given for those fields that are notself-explanatory. All times in s$acct_record are in seconds.

s$acct_record

record_type

1-2 VOS System Administration: The Accounting Facility (R281M-00)

THE EXTERNAL VARIABLE s$acct_record

A tag indicating the type of record. The possible values are:

1 proc start 2 proc term 3 proc cleanup 4 proc stats 6 file close 7 command start 8 command term 9 file log 11 proc log 12 transaction

date_time

The standard date/time this record was logged.

module_name

The name of the module on which the record was logged.

user_name

group_name

terminal_port_path

process_name

process_priority

client_name

The client name given for process statistics records.

client_group

For process statistics records, the group portion of the client name, if the split_client_name parameter in the s$acct_processing_init is specified as true.

file_type

For file close records and file log records, the file type, as returned by s$get_port_attachment.

file_path

For file close records and file log records, the file path.

command_level

For command start and stop records, the command level. This indicates how many commands are nested. For example, if a macro calls a command, the level of the


THE EXTERNAL VARIABLE s$acct_record

macro is 1 and the level of the command is 2.

command

For command start records, the name of the command.

elapsed_time

The amount of real time, in seconds, that has elapsed since the last record was written for this process (0 for process start records).

cpu_time

The amount of cpu time, in seconds, since the last record was written.

pf_time

The amount of page fault time, in seconds, since the last record was written.

disk_reads

disk_writes

page_faults

max_working_set

working_set_usage

max_pages_used

calls_to_other_modules

calls_to_other_systems

transaction_type

task_id

transaction_id

The following fields are filled only if port accounting was enabled when the logs were created.

read_byte_count write_byte_count read_record_count write_record_count

These fields are arrays indexed by device type, as returned by s$get_port_attachment.

number_of_device_types

The number of entries in these arrays that are actually


ACCOUNTING FACILITY SUBROUTINES

relevant.

ACCOUNTING FACILITY SUBROUTINESThe rest of this document contains brief descriptions of the PL/Iversions of these subroutines. Each description illustrates anddiscusses both the procedure declaration for the subroutine and thesubroutine call itself.

s$acct_processing_init declare s$acct_processing_init entry( char(256) varying, fixed bin(31), fixed bin(31), char(66) varying, fixed bin(15), fixed bin(15), fixed bin(15), char(32) varying, char(32) varying, char(32) varying, char(256) varying, char(256) varying, char(256) varying, char(65) varying, char(32) varying, fixed bin(15), char(256) varying, char(32) varying );

The s$acct_processing_init subroutine initializes the accounting package to read records from the accounting log(s) of one or more modules. You should call this subroutine first. All parameters are input.

s$acct_processing_init( accounting_dir, start_time, end_time, modules, port_accounting_required, port_accounting_relevant, split_client_name, match_process, match_user, match_group, match_terminal, match_file, match_command, match_client, match_client_group, num_summaries, user_record_path, command_name )

accounting_dir

Either the null string (‘’) or a directory name. If you specify a directory name, the operating system looks for the accounting files in the specified directory rather than in the standard accounting directories for the desired modules. If you specify a directory name for this parameter, you must specify the null string for the modules parameter.

start_time end_time

The time interval over which the log(s) are to be scanned.

modules

A module star name that defines the module(s) whose log(s) are to be scanned. If you specify a directory name for the accounting_dir parameter, you must specify the null string (‘’) for the modules parameter.

port_accounting_required



port_accounting_relevant

These flags indicate whether the log that is processing should consider port accounting required and/or relevant. Specify a nonzero value to denote that it should be considered required and/or relevant. These flags relate to the port accounting option. If you did not specify the port_accounting option with the accounting_admin command, then the read_byte_count, write_byte_count, read_record_count, and write_record_count values of the s$acct_record external variable will not be valid. If port accounting is required, then the log that is processing will issue warnings if that option was not in effect at any time during the selected time interval. If port accounting is relevant, then the log processing will give a warning if the port_accounting option was changed during the selected time interval.

split_client_name

If this flag is zero, the client names specified in proc_stats records will be treated as a single string; otherwise, they will be parsed as “USER[.GROUP],” and the group name will be split from the user name.

match_process match_user match_group match_terminal match_command match_client match_client_group

These parameters allow you to select a subset of the records in the log files: they specify star names that are checked against the corresponding fields in s$acct_record. If all of the star names match, then the particular record is selected for processing.

These values default to ‘*’. Path names can be full or relative, and can contain a star name in any component. A relative path name that is specified as a pattern matches any string containing that pattern; for example, ‘*>stuff’ matches ‘%a#b>stuff’, ‘%b#d>stuff’, ‘%a#b>c>stuff’. The parameter match_client_group is meaningful only if split_client_name is specified as true (nonzero).

num_summaries

The number of summaries to be produced from the record selected from the logs. In ensuing calls, summaries are identified by a number between 1 and num_summaries.

user_record_path

The path name of a file into which user defined records



are to be placed. If you specify the null string (‘’), no file is created, and user defined records in the logs are ignored.

command_name

This parameter is used when calling s$error.

s$acct_init_summary declare s$acct_init_summary entry( fixed bin(15), fixed bin(15) );

The s$acct_init_summary subroutine is used to initialize one summary. You must call it num_summaries times after the call to s$acct_processing_init, and before any calls to s$acct_next_record. (The value num_summaries is specified as a parameter in the call to s$acct_processing_init.) It must be immediately followed by num_components calls to s$acct_init_summary_key. All parameters are input.

s$acct_init_summary( which_summary, num_keys )

which_summary

A number that identifies the summary to initialize.

num_keys

The number of keys used to identify a unique entry in this summary. In ensuing calls, the keys are identified by a number between 1 and num_keys.

s$acct_init_summary_key declare s$acct_init_summary_key entry( fixed bin(15), fixed bin(15), char(*) varying );

The s$acct_init_summary_key subroutine adds one key to the summary indicated in the preceding s$acct_init_summary call. You must call it before any calls to s$acct_next_record, and must call it once for each of the keys in the summary. These calls must occur in key number order. All parameters are input; however, you must pass the “key” parameter by reference.

s$acct_init_summary_key( which_key, max_size, key )

which_key

The key number for this key.

max_size

The maximum number of characters in the key.

key



One of the following entries in the external variable s$acct_record:

module_name user_name group_name terminal_port_path process_name client_name client_group file_path command

Note that only character varying fields in that specific external variable are allowed.

s$acct_next_record declare s$acct_next_record entry( fixed bin(15) );

The s$acct_next_record subroutine is used to read in all records in the accounting log. You must call this subroutine after the initialization calls (s$acct_processing_init, s$acct_init_summary, and s$acct_init_summary_key).

s$acct_next_record( code )

code

The value returned will be either zero or an operating system error code. The error code e$end_of_file indicates that all selected records have been read. Any other error code is unexpected and indicates that results may be incomplete or invalid.

If code is zero, then the external variable s$acct_record contains the value for the next selected record from the log files. The fields for s$acct_record are defined in the include files acct_record.incl.LANG.

s$acct_get_longest_key declare s$acct_get_longest_key entry( fixed bin(15), fixed bin(15), fixed bin(15) );

The s$acct_get_longest_key subroutine returns the longest value that has been seen for a given key in a given summary. You can call it any time after the last call to s$acct_next_record. The parameters which_summary and which_key are input, and the parameter longest_key is output. This subroutine is useful for deciding on the format for columnar output without actually making a pass



through any summaries.

s$acct_get_longest_key( which_summary, which_key, longest_key )

s$acct_init_summary_output declare s$acct_init_summary_output entry( fixed bin(15), fixed bin(15), fixed bin(15) );

The s$acct_init_summary_output subroutine sorts a given summary and initializes it for output. A call to this subroutine should be followed by calls to s$acct_next_summary_output. The parameters which_summary and delete_after are input.

s$acct_init_summary_output( which_summary, delete_after, code )

which_summary

The summary to be prepared.

delete_after

If this parameter value is nonzero, all data structures for the summary will be freed at some convenient time after the last call to s$acct_next_summary_output. If you want to use a summary more than once, specify zero as the value of this parameter all but the last time.

code

The value returned will be either zero or the operating system error code e$too_many_entries. If there are more than 32767 entries in the summary, code will be nonzero and the extra entries will be arbitrarily discarded. A message will already have been printed.

s$acct_next_summary_output declare s$acct_next_summary_output entry( fixed bin(15), fixed bin(15), fixed bin(15), (*) char(300) varying, fixed bin(15) );

The subroutine s$acct_next_summary_output is used to retrieve the next entry from a summary. After calling s$acct_init_summary_output, call s$acct_next_summary_output repeatedly until receiving the operating system error code e$end_of_file. All parameters except max_num_keys are output parameters. Each entry in the summary is put into the external variable s$acct_record.

Each entry in the summary is a combination of all records selected by the combination of keys for that entry that also match the records selected by the call to s$acct_processing_init. Records are combined into one entry according to the following rules:



1. Fields that are counts contain the sum for all the records.

2. Fields that are maxima contain the maximum for all the records.

3. Other fields are taken from the first record encountered, and probably are not useful.

s$acct_next_summary_output( first_key_change, max_num_keys, num_keys, keys, code )

first_key_change

The number of the first key in the keys array that has a different value than in the previous summary entry. You can use this parameter to produce headings, by using the first few keys as headings for a group of related summary entries. This works because key 1 is the primary key for the sort, key 2 is the secondary key, and so forth.

max_num_keys

The number of entries allocated in the keys array.

num_keys

The number of keys this call actually puts into the keys array.

keys

The keys, indexed by key number, for this summary entry.

code

The value returned is either:

o zero, if another entry is available

o the operating system error code e$end_of_file, if another entry is not available

o the operating system error code e$too_many_entries, if max_num_keys is too small. However, this should not happen, because the caller should know how many keys there are.


VOS Accouting Facility (r281m-00)

Documents

Transcript of VOS Accouting Facility (r281m-00)