Reporting System Usage

USER.LOG

Each time a user logs on to the database, an item is created in the USER.LOG file with port-number as item-id. One attribute of the item contains the user-id. If the user executes the CHARGE-TO command, the software appends to the user-id an asterisk followed by the project name. The software also records the current account logged-on to in this item.

Account Statistics

When the user exits from an account or changes the project charged-to, the system checks if statistics are to be kept for the account (indicated by a U in attribute 9 of the account definition item). If so, statistics are recorded in the ACC file. ACC holds information such as date and time of logon, length of session, CPU usage in milliseconds and account logged-on to. Statistics are kept in multivalued attributes.

If statistics are to be kept on the current account, the software updates the ACC file when the project name changes (CHARGE-TO command), the current account changes (LOGTO command), or the user logs off (OFF command). When one of these occurs the system checks ACC for an item-id that matches the user-id and port number or the user-id, project name and port number.  If it does not find such an item, it creates one.

Reporting Statistics

There are several ways to process statistics from ACC. These include by user, project, account or some combination of these.

To trace usage of the database by project, use the CHARGE-TO command at the beginning of each session. The CHARGE-TO command can be executed from a logon control program. Then use LIST ACC or CHARGES to obtain a report of the usage.

You can use TCL, English, Proc and DataBasic to extract information from the ACC file.

ACC Item-ids

Each item-id in the ACC file has one of the following formats:

user-id#port-number
or
user-id*project-name#port-number

A project name is specified using the CHARGE-TO command.

Listing Usage Statistics

To obtain a report from the ACC file, use the LIST command:

LIST ACC {item-list} {selection-criteria}{(P}

Example

To list all the items recorded for a given user you can use the SELECT command before using the LIST command.  For example, if your user-id is JOE, you can use the following commands to list all items for user JOE:

:SELECT ACC = 'JOE#]' OR 'JOE*]'
3 ITEMS SELECTED.
>LIST ACC (P

Command Logging

If required, you can configure Reality to log each TCL command used. Two types of log are available:

• Audit logs, created for each logon session. By default these contain only commands that were entered at the TCL prompt. They are normally retained until manually deleted (but see note below).
• Support logs. By default these contain not only commands that were entered at the TCL prompt, but also those that were run from within those commands. Only two support logs are retained for each port: the current log and that for the previous session. Each time a user logs on, the previous log is deleted, the current log from the previous session is renamed to become the previous log and a new current log is created.

All these logs are held in the TCL.LOG file, with a separate item for each logon session.

Configuring Logging

You configure logging by using SSM to set an option in the user's security profile. You can enable or inhibit logging, and also separately set audit and support logging to start automatically when the user logs on. If logging is enabled, but not set to start automatically, you can start and stop logging with the START-AUDIT-LOG, STOP-AUDIT-LOG, START-SUPPORT-LOG and STOP-SUPPORT-LOG commands.

Logging Reports

To view a summary of the command log entries, list the contents of TCL.LOG. For example:

LIST TCL.LOG

User Id. Account. Port. Log. Age.. Entries Date..... Time.... PLID..........
                        Type
daveh    SYSMAN   00401 A    1     3       13 Dec 06 10:56:23 UNIX-900383-pts/1
                        ***        3
daveh    SYSMAN   00401 S    1     3       13 Dec 06 12:31:47 UNIX-900383-pts/1
daveh    SYSMAN   00401 S    1     2       13 Dec 06 12:05:21 UNIX-900383-pts/1
                        ***        5
daveh    SYSMAN   00402 A    7     1       07 Dec 06 12:32:27 UNIX-900383-pts/2
                        ***        1
daveh    SYSMAN   00402 S    7     5       07 Dec 06 12:32:03 UNIX-900383-pts/2
                        ***        5
***                                14
                                   14

To list only audit or support entries, specify the AUDIT or SUPPORT macro as appropriate. The following is a typical support listing:

LIST TCL.LOG SUPPORT

User Id. Account. Port. Age.. Entries Date..... Time.... PLID..........
daveh    SYSMAN   00401 1     3       13 Dec 06 12:31:47 UNIX-900383-pts/1
daveh    SYSMAN   00401 1     2       13 Dec 06 12:05:21 UNIX-900383-pts/1
daveh    SYSMAN   00402 7     5       07 Dec 06 12:32:03 UNIX-900383-pts/2
***                           10
                              10

To list the contents of a particular log item, you need to know the item-id.

• For support items, this will be the port number (including the leading zeros) for the current log or portNumber*PREVIOUS for the previous entry.

• For audit items, the item-id is made up of the port number and the date and time (both in internal format) in the format portNumber*date*time{.milliseconds}. Use English to select the required item. For example:

  :SELECT TCL.LOG WITH TYPE = "A" AND WITH PORT = "00401" AND WITH DATE = "13 Dec 06"
  
  1 Items selected.
  >CT TCL.LOG

Log Administration

Because all audit logs are retained on the system, you should periodically archive (if required) and delete the older entries to stop TCL.LOG becoming too large. An AGE dictionary definition item is provided to simplify this. For example:

:SELECT TCL.LOG WITH AGE > 100
>DELETE TCL.LOG

or

:EDELETE TCL.LOG WITH AGE > 100

will delete all audit and support log that are more than 100 days old.

Only two support logs (current and previous) are retained for each port, so no support log administration is normally required.