# Compaq ACMS for OpenVMS
Managing Applications

Previous | Contents | Index

## 15.4.1 Registering the Facility Definition

DECtrace can collect event data from a number of layered products and applications. These other products are referred to as facilities, and each has a facility definition registered in the DECtrace administration database.

At the installation of ACMS, the location of the ACMS facility definition depends on whether or not DECtrace is already installed on the system:

- If DECtrace installation preceded ACMS installation, the ACMS facility definition is registered in the DECtrace administration database. When ACMS is subsequently installed, the ACMS facility definition is registered and you can create a selection and schedule a collection.
- If DECtrace is not already installed on the system at the time of ACMS installation, the ACMS facility definition is inserted in the library file SYS$LIBRARY:EPC$FACILITY.TLB. If you later install DECtrace, the DECtrace EPC$INSERT post-installation procedure inserts the ACMS facility definitions in the DECtrace administration database.

You can use the SHOW DEFINITION command to list the facilities installed on your system. The following example shows the facility definitions on the node TSTVAX:

    $ COLLECT SHOW DEFINITION /FORMAT=NAMES_ONLY
    25-APR-1991 15:58       Facility Definition Information                Page 1
    Names Only Report                                             DECtrace V1.0-0

     Facility:             Version:    Creation Date:      Class:
     --------------------  ----------  ------------------  ------------------
     ACMS                  V3.2-0       7-APR-91 17:23     ALL
                                                           PERFORMANCE       (D)
     ATM_SAMPLE            V1.0        25-APR-91 14:17     ALL               (D)
     MY_FACILITY           V2.0        12-APR-91 10:27     ALL
                                                           WORKLOAD          (D)
     RDBVMS                V3.2-0      20-APR-91 15:21     ALL
                                                           PERFORMANCE       (D)
                                                           WORKLOAD

## 15.4.2 Creating a Selection

DECtrace can collect data from either all the facilities registered with it, or just the ones you are interested in. To specify a subset of the available facilities, use the CREATE SELECTION command to create a facility selection which consists of:

- Selection name
- List of facilities for which to collect data
- Class of data to collect for each facility

The basic format for the CREATE SELECTION command is:

`CREATE SELECTION selection_name /FACILITY=(facility_name[,...])`

The following example defines the selection MY_SELECTION to collect the default data for ACMS:

    $ COLLECT CREATE SELECTION MY_SELECTION /FACILITY=ACMS

However, to define a more detailed selection, use the /OPTIONS qualifier. This qualifier takes a file name as an argument. The options file lists each facility and the collection class you want to use. Each facility is described on a separate line. If you specify /OPTIONS but do not include a file name, DECtrace prompts you for the options. The format of the facility description in the options file is:

`FACILITY facility-name [/VERSION="version-code"] [/CLASS=class-name]`

> ### facility-name

> The name of the facility for which to collect data.

> ### version-code

> A text string identifying the version of the facility. The string must be enclosed with quotation marks (" ").

> ### class-name

> The class of data that you want collected for the facility.

The following example creates the facility selection SELECT_ALL to collect all of the possible data for ACMS and only the performance-related data from MY_FACILITY:

    $ COLLECT CREATE SELECTION SELECT_ALL /OPTIONS
    Option„ FACILITY ACMS /CLASS=ALL
    Option„ FACILITY MY_FACILITY /CLASS=PERFORMANCE
    Option„ [CTRL/Z]
    $

## 15.4.3 Collecting Cross Facility Items

To collect cross facility items, use the CREATE SELECTION command to:

1. Specify the facilities for which to collect data.
2. Specify the collection class that includes the cross facility items to be collected for each facility involved.

The following classes include the PROCEDURE_CALL event, which collects the CROSS_FAC_2 and CROSS_FAC_7 values:

- PERFORMANCE
- RESPONSE
- ALL

To collect the CROSS_FAC_2 or CROSS_FAC_7 values, specify any one of these classes in the DECtrace CREATE SELECTION command.

If you are using the CROSS_FAC_14 value in your application, this value is logged to DECtrace during any ACMS event and collected by DECtrace if any of the above classes are selected.

To collect ACMS and Rdb data, use commands similar to the following:

    DECtrace> create selection <sel-name>  /options
    Option> facility acms  /class=performance
    Option> facility  rdbvms  /class=performance
    Option> [Ctrl/Z]

    DECtrace> schedule collection <coll-name> <coll-file>  -
    _DECtrace>  /selection=<sel-name>  /begin=<start-time> -
    _DECtrace>  /end=<end-time>

## 15.4.4 Scheduling Data Collection

You must schedule data collection on your system before DECtrace can begin collecting information about ACMS. The scheduling criteria include:

- Output file for the collected data
- Start and end times (or alternately, the duration)
- Facility selection to use
- Scope of the collection (the entire cluster or just the local node)

Note that although you can schedule many data collections on a node, only one collection can be active on a node at any time. DECtrace does not allow you to schedule data collections that overlap or run simultaneously.

The following example schedules the collection MY_COLLECTION to begin at 11:00 and end at 12:00 on the current day. The collection uses the facility selection SELECT_ALL and runs on the local node. DECtrace stores the collected data in the file MY_DATA.DAT in your default device and directory:

    $ COLLECT SCHEDULE COLLECTION MY_COLLECTION MY_DATA.DAT -
    _$ /SELECTION=SELECT_ALL -
    _$ /BEGINNING=11:00 /ENDING=12:00 -
    _$ /NOCLUSTER /PROTECTION=(W:W)
    %EPC-S-SCHED, Data collection MY_COLLECTION is scheduled

Alternatively, you can use the /DURATION qualifier in place of the /ENDING qualifier. You must specify the duration as a relative OpenVMS time. For example:

    $ COLLECT SCHEDULE COLLECTION MY_COLLECTION MY_DATA.DAT -
    _$ /SELECTION=MY_SELECTION -
    _$ /BEGINNING=11:00 /DURATION="1:" -
    _$ /NOCLUSTER /PROTECTION=(W:W)
    %EPC-S-SCHED, Data collection MY_COLLECTION is scheduled

You can schedule data collection either locally or clusterwide by using the /[NO]CLUSTER qualifier. By default, the SCHEDULE COLLECTION command schedules data collection to occur on every node in the cluster. To schedule data collection on a subset of the cluster, you must log in to each node that you want data collection to occur on and schedule local data collection on that node by specifying /NOCLUSTER. Note that on a standalone system the /CLUSTER qualifier is ignored.

## 15.4.5 Using Registration IDs

In addition to scheduling when to collect data, you can specify which OpenVMS processes you wish to collect data from during the collection interval.

You select the processes from which to collect data by specifying one or more registration IDs with the SCHEDULE COLLECTION command. The registration ID is a facility- or process-specific character string that is known to the process only at run time.

On the application node, the registration ID is the name of an ACMS application. It identifies the Application Execution Controller and server processes that make up the application. This allows you to collect data for a specific ACMS application.

DECtrace also registers process-specific information when an image containing DECtrace service routine calls activates. The process-specific registration IDs include the EPID (extended process ID), the image name, the user name, and the process name. This allows you to collect data on a per-process, per-user, or per-image basis.

The following example schedules a collection to gather ACMS event data from user JONES running the PAYROLL application:

    $ COLLECT SCHEDULE COLLECTION MY_COLLECTION MY_DATA.DAT -
    _$ /SELECTION=ACMS_SEL -
    _$ /BEGINNING=11:00 /DURATION="1:" -
    _$ /NOCLUSTER /PROTECTION=(W:W)-
    _$ /REGISTRATION_ID=(JONES,WORK1:[FINANCE]PAYROLL.EXE)
    %EPC-S-SCHED, Data collection MY_COLLECTION is scheduled

On the submitter node, the registration ID is "ACMS_AGENT." The registration ID "ACMS_AGENT" can be used to record TDMS, Request Interface, or DECforms I/O performed by an agent process.

Use the DECtrace SHOW REGISTER command to display the processes and images available for data collection on your system.

# 15.5 Creating a Report Based on Collected Data

You can use DECtrace to produce reports based on the data collected from one or more DECtrace collections. The two steps in producing DECtrace reports are:

1. Format and merge the data files.
2. Generate the report.

## 15.5.1 Formatting and Merging Data Files

Before DECtrace can generate a report on the data collected for your collections, you must use the FORMAT command to format the data in the data files into an Rdb database. (An RMS formatted file is also available for users who plan to create their own reports based on the data. See the DECtrace documentation for information.) The following example formats the data in the file MY_DATA.DAT and stores the formatted data in an Rdb database named FORMATTED_DATA.RDB:

    $ COLLECT FORMAT MY_DATA.DAT FORMATTED_DATA

You can also use the FORMAT command to combine the data files from two or more collections into one formatted database. However, these collections must have been scheduled using the same facility selection.

The two ways you can combine data files are: format several data files at once into the same Rdb database, or add a data file to an existing formatted database. The following example combines the data collected from several collections into a new formatted database named WEEK.RDB:

    $ COLLECT FORMAT MONDAY.DAT,TUESDAY.DAT,WEDNESDAY.DAT  WEEK

The following example adds the contents of the data file THURSDAY.DAT to the existing formatted database WEEK.RDB:

    $ COLLECT FORMAT /MERGE THURSDAY.DAT WEEK

See the description of the FORMAT command in the DECtrace documentation for a list of optimization parameters that you can use to speed up formatting operations.

## 15.5.2 Generating a Report

DECtrace can generate tabular reports based on the data in an Rdb formatted database. Table 15-8 lists the three different types of reports that you can produce.

Table 15-8 DECtrace Reports
Type | Description
--- | ---
DETAIL | Actual values of the items collected for each event
FREQUENCY | Event occurrence summary based on a selected time interval
SUMMARY (default) | Summary statistics about the collected data

In the simplest case, the REPORT command creates a Summary Report on all of the data in the formatted database and displays the report on your current SYS$OUTPUT device (usually, your terminal). For example:

    $ COLLECT REPORT FORMATTED_DATA.RDB

You can further refine the report with the /FACILITY qualifier. The following example generates a Summary Report only on ACMS data and writes the report to the file MY_REPORT.TXT:

    $ COLLECT REPORT FORMATTED_DATA.RDB /FACILITY=ACMS -
    _$ /OUTPUT=MY_REPORT.TXT

Example 15-1 shows a typical report, MY_REPORT.TXT, based on ACMS event data.

Example 15-1 Summary Report for ACMS Event Data

    19-APR-1991 16:57                Summary Report                        Page 1
    Selection: ACMS_ONLY                                          DECtrace V1.0-0

    Event:  EXCHANGE_STEP   In Facility:  ACMS            Version:  V3.2-0

               Elapsed

    Minimum       2.17
    Maximum    1489.29
    Mean         17.90
    Std Dev     109.82
    95 Prct     233.16
    Total      5334.71
    Count          298

    %EPC-I-RPQU_BAD_95, 95 Prct for events with counts under 1000 are less precise

    19-APR-1991 16:57                Summary Report                        Page 2
    Selection: ACMS_ONLY                                          DECtrace V1.0-0

    Event:  PROCEDURE_CALL  In Facility:  ACMS            Version:  V3.2-0

               Elapsed  BUFFERED IO    CPU TIME  CURREN    DIRECT IO   PAGEFAULTS
                                                 T PRIO

    Minimum       0.16            0           5       4            4            0
    Maximum      15.64           27         229       5          238         1124
    Mean          0.32         0.11        7.89    4.79         6.44         4.03
    Std Dev       0.89         1.58       12.95    0.40        13.57        65.31
    95 Prct       2.08         3.21       33.29    5.58        33.04       132.04
    Total        97.06           35        2346    1424         1914         1199
    Count          297

               PAGEFAULT     Proc Idx      VIRTUAL    GLOBAL WS   PRIVATE WS
                     IOs                      SIZE

    Minimum            0            1         8148          773         1271
    Maximum           25            1         8148          797         1347
    Mean            0.08         1.00      8148.00       796.71      1344.20
    Std Dev         1.45         0.00         0.00         1.63        12.61
    95 Prct         2.92         1.00      8148.00       799.92      1368.93
    Total             25          297      2419956       236624       399228
    Count            297

                 WORKING
                 SET SIZ

    Minimum         2824
    Maximum         3124
    Mean         3113.89
    Std Dev        54.20
    95 Prct      3220.14
    Total         924828
    Count            297

    %EPC-I-RPQU_BAD_95, 95 Prct for events with counts under 1000 are less precise

    19-APR-1991 16:57                Summary Report                        Page 3
    Selection: ACMS_ONLY                                          DECtrace V1.0-0

    Event:  PROCESSING      In Facility:  ACMS            Version:  V3.2-0
            _STEP

               Elapsed

    Minimum       0.17
    Maximum      15.74
    Mean          0.33
    Std Dev       0.90
    95 Prct       2.11
    Total       100.64
    Count          297

    %EPC-I-RPQU_BAD_95, 95 Prct for events with counts under 1000 are less precise

    %EPC-I-NOEND, 1 Start Event Records had no matching End

    19-APR-1991 16:57                Summary Report                        Page 4
    Selection: ACMS_ONLY                                          DECtrace V1.0-0

    Event:  TASK            In Facility:  ACMS            Version:  V3.2-0

               Elapsed

    Minimum    5436.31
    Maximum    5436.31
    Mean       5436.31
    Std Dev       0.00
    95 Prct    5436.31
    Total      5436.31
    Count            1

    %EPC-I-RPQU_BAD_95, 95 Prct for events with counts under 1000 are less precise

    19-APR-1990 16:57                    Index                             Page 5
    Selection: ACMS_ONLY                                          DECtrace V1.0-0

    Report Index

    Facility Name                Event Name                        Page

    ACMS                         EXCHANGE_STEP                     1
    ACMS                         PROCEDURE_CALL                    2
    ACMS                         PROCESSING_STEP                   3
    ACMS                         TASK                              4

Use the /STATISTICS qualifier to specify the statistics DECtrace uses in the Summary Report. This feature allows you to create customized reports that present information in the manner most suitable to your needs. The valid statistics are:

- ALL
- COUNT (default)
- MAXIMUM
- MEAN
- MINIMUM
- STANDARD_DEVIATION
- TOTAL
- 95_PERCENTILE

The following example generates a Summary Report based on the data collected for ACMS using the statistics MAXIMUM, MINIMUM, and MEAN:

    $ COLLECT REPORT FORMATTED_DATA.RDB /FACILITY=ACMS -
    _$ /TYPE=SUMMARY /STATISTICS=(MAXIMUM,MINIMUM,MEAN) -
    _$ /OUTPUT=MY_SUMMARY.TXT

By default, DECtrace reports on the data collected for all the events contained in the formatted database. You can use the /EVENTS qualifier to restrict the report to specific events. The following example generates a report based on the data collected for a subset of the events in ACMS:

    $ COLLECT REPORT FORMATTED_DATA /OUTPUT=MY_REPORT.TXT -
    _$ /FACILITY=ACMS -
    _$ /EVENTS=(TASK,TASK_WAIT,FORMS_REQUEST)

## 15.5.3 Generating a Report with Cross Facility Items

To generate a formatted report for cross facility items whose values are equal for related events, follow these steps:

1. Use the DECtrace REPORT command options to select the relevant report data.
2. Use the DECtrace join operation to associate the events with each other.

For example, if you join the CROSS_FAC_2 and CROSS_FAC_7 items of the ACMS PROCEDURE_CALL event with those of an Rdb database TRANSACTION event, DECtrace relates each transaction occurrence with the procedure call in which it occurred.

To display ACMS and Rdb summary information for a specific server and procedure, use a DECtrace command similar to the following:

    DECtrace> REPORT  /OPTIONS  /STATISTICS=ALL  /TYPE=SUMMARY
    Option> event  PROCEDURE_CALL  /facility=acms
    Option> event  TRANSACTION  /facility=rdbvms
    Option> restrict  item  server_name=<server>
    Option> restrict  item  procedure_name=<procedure>
    Option> join PROCEDURE_CALL.cross_fac_2=TRANSACTION.cross_fac_2
    Option> join PROCEDURE_CALL.cross_fac_7=TRANSACTION.cross_fac_7
    Option> [Ctrl/Z]

Example 15-2 contains a summary report, which illustrates the related ACMS PROCEDURE_CALL and Rdb TRANSACTION events.

Example 15-2 DECtrace Summary Report

    > COLLECT REPORT /OPTIONS /STATISTICS=ALL /TYPE=SUMMARY
    Option> join PROCEDURE_CALL.CROSS_FAC_2=TRANSACTION.CROSS_FAC_2
    Option> event PROCEDURE_CALL /FACILITY=ACMS
    Option> event TRANSACTION /FACILITY=RDBVMS

    11-May-1993 10:00           Summary Report              Page 1
    Selection: xxx_xxx                                      DECtrace V1.2-0

    Event:  PROCEDURE_CALL  In Facility:  ACMS          Version: V3.3-0B

    CROSS_FAC_2  : 1
            Elapsed  BUFFERED IO   CPU TIME    CURRENT  DIRECT IO  PAGEFAULTS
                                                  PRIO

    Minimum   0.30         0             6          7         6           1
    Maximum   0.47         0             7          7         8           2
    Mean      0.38      0.00          6.50       7.00      7.00        1.50
    Std Dev   0.12      0.00          0.70       0.00      1.41        0.70
    95 Prct   0.62      0.00          7.88       7.00      9.77        2.88
    Total     0.77         0            13         14        14           3
    Count        2

              PAGEFAULT   Proc Idx   VIRTUAL   GLOBAL WS   PRIVATE WS
              IOs                    SIZE

    Minimum      0             1          9676        755      1407
    Maximum      2             1          9676        776      1407
    Mean      1.00          1.00       9679.00      775.5   1407.00
    Std Dev   1.41          0.00          0.00        0.70     0.00
    95 Prct   3.77          1.00       9679.00      776.88  1407.00
    Total        2             2         19358        1551     2814
    Count2

              WORKING     CROSS_FAC_2
              SET SIZE

    Minimum      4096           1
    Maximum      4096           1
    Mean      4096.00        1.00
    Std Dev      0.00        0.00
    95 Prct   4096.00        1.00
    Total        8192           2
    Count           2

    11-May-1993 10:00           Summary Report            Page 1
    Selection: xxx_xxx                                    DECtrace V1.2-0

    Event:  TRANSACTION    In Facility:  RDBVMS       Version: T3.1-2

              Elapsed    AIJ File      BUFFERED  Buffer    Client PC
                           Writes      IO        Pool Rds

    Minimum   0.10          0              0           0         3EC8
    Maximum   0.16          0              0           2         3EC8
    Mean      0.12       0.00           0.00        1.00      3EC8.00
    Std Dev   0.04       0.00           0.00        1.41         0.00
    95 Prct   0.21       0.00           0.00        3.77      3EC8.00
    Total     0.25          0              0           2         7D90
    Count        2

              WORKING   Trans Seq   CROSS_FAC_2
              SET SIZ   Num

    Minimum      4096       45          1
    Maximum      4096       45          1
    Mean      4096.00    45.00       1.00
    Std Dev      0.00     0.00       0.00
    95 Prct   4096.00    45.00       1.00
    Total     8192       90          2
    Count           2

Previous | Next | Contents | Index