User-defined transactions

Collection Services and Performance Explorer collect performance data that you define in your applications.

With the provided APIs, you can integrate transaction data into the regularly scheduled sample data collections using Collection Services, and get trace-level data about your transaction by running Performance Explorer.

For detailed descriptions and usage notes, refer to the following API descriptions:

Start Transaction (QYPESTRT, qypeStartTransaction) API
End transaction (QYPEENDT, qypeEndTransaction) API
Log transaction (QYPELOGT, qypeLogTransaction) API (Used only by Performance Explorer)
Add trace point (QYPEADDT, qypeAddTracePoint) API (Used only by Performance Explorer)

Note: You only need to instrument your application once. Collection Services and Performance Explorer use the same API calls to gather different types of performance data.

Integrating user-defined transaction data into Collection Services

You can select user-defined transactions as a category for collection in the Collection Services configuration. Collection Services then collects the transaction data at every collection interval and stores that data in the collection object. The Create Performance Data (CRTPFRDTA) command exports this data to the user-defined transaction performance database file, QAPMUSRTNS. Collection Services organizes the data by transaction type. You can specify as many transaction types as you require; however, Collection Services will only report the first 15 transaction types. Data for additional transaction types is combined and stored as the *OTHER transaction type. At every collection interval, Collection Services creates one record for each type of transaction for each unique job. For a detailed description, refer to the usage notes in the Start Transaction API.

Collection Services gathers general transaction data, such as the transaction response time. You can also include up to 16 optional application-defined counters that can track application-specific data like the number of SQL statements used for the transaction, or other incremental measurements. Your application should use the Start Transaction API to indicate the beginning of a new transaction, and should include a corresponding End Transaction API to deliver the transaction data to Collection Services.

Collecting trace information for user-defined transactions with Performance Explorer

You can use the Start, End, and Log Transaction APIs during a Performance Explorer session to create a trace record. Performance Explorer stores system resource utilization, such as CPU utilization, I/O, and seize/lock activity, for the current thread in these trace records. Additionally, you may choose to include application-specific performance data, and then send it to Performance Explorer in each of these APIs. You can also use the Add Trace Point API to identify application-specific events for which Performance Explorer should collect trace data.

To start a Performance Explorer session for your transactions, specify *USRTRNS on the (OSEVT) parameter of your Performance Explorer definition. After entering the ENDPEX command, Performance Explorer writes the data supplied by the application to the QMUDTA field in the QAYPEMIUSR Performance Explorer database file. System-supplied performance data for the start, end, and any log records is stored in the QAYPEMIUSR and QAYPETIDX database files.