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.

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