Using Strobe for WebSphere MQ

This topic explains how to configure and use Strobe to measure a batch or CICS application that is using WebSphere MQ. It also describes how to set reporting parameters to define what information appears in theStrobe for WebSphere MQ Performance Profile reports.

To enable Strobe to correctly attribute WebSphere MQ measurement activity to application modules other than the one that invoked WebSphere MQ, you must provide a special Strobe - Data Collectors panel parameter. It is the name of the common WebSphere MQ user module that invokes WebSphere MQ on behalf of other applications. For more information, see Measuring Applications that Call WebSphere MQ.

About the Application

Strobefor WebSphere MQ enables you to measure batch and CICS applications that use IBM’s WebSphere MQ product. While the application code is making a service call to WebSphere MQ, Strobe collects data on the code activity. Strobe collects the following types of WebSphere MQ information:

• WebSphere MQ function (API) called
• Application module (and its offset) that called the WebSphere MQ function
• WebSphere MQ queue holding data requested by function
• Characteristics (size, priority) of message data being processed.

Common WebSphere MQ User Module

Some users provide a common WebSphere MQ user module that all program modules use to invoke WebSphere MQ API calls. When Strobe detects a call to the WebSphere MQ address space, it attributes the measurement data to the calling module. If the call is made directly from the application being measured to WebSphere MQ, Strobe correctly attributes the measurement data to the calling application module.

If a common user module invokes a WebSphere MQ service call for the application being measured, Strobe is able to correlate the application module requesting WebSphere MQ to the WebSphere MQ activity it detects. Strobe for WebSphere MQ identifies the common user module that directly called WebSphere MQ and then finds the application module that actually requested WebSphere MQ data, attributing the resource consumption to that module.

Common WebSphere MQ User Module shows an example of a z/OS environment where Strobe is measuring an application that uses a common user module to call WebSphere MQ.

To enable Strobe to provide WebSphere MQ information about the application you are measuring instead of the common user module it detects, you have to identify the name of the user module when you add a measurement request. Strobe for WebSphere MQ can correctly attribute measurement data it collected to the calling application module instead of the common user module. The user module name will not typically appear in WebSphere MQ reports.

Common WebSphere MQ User Module

MVS programming standards must be followed for Strobe and Strobe for WebSphere MQ to trace application activity through common WebSphere MQ user modules. The common user module must be one of the following:

• Separate load module from the load module(s) that invoke it.
• Separate CSECT in the program being measured
• CSECT in one of the load modules that is mapped for measurement.

The common user module must comply with standard MVS linkage conventions as follows:

• During its entire operation, register 13 of the common user module must point to its own save area
• Offset 4 (i.e., the second word) of that save area must point to a save area of the caller of the user module.
• Offset 12 (i.e., the fourth word) of the caller’s save area must contain the return address to the calling routine.

If the WebSphere MQ common user module is being called by a CICS transaction, the following rules apply:

• If the common user module is called dynamically, follow the batch application linking conventions.
• The common user module is invoked through the CICS application programming interface using either a LINK or XCTL command. However, for a XCTL command, no offset in the calling program can be provided.

Starting Strobe

You have two options when starting Strobe:

• Strobe/ISPF — a menu-driven interface to the Strobe system
• Strobe command language — a set of procedural operators and parameters that you can invoke through Time Sharing Option (TSO) commands or batch jobs.

If necessary, consult your systems programmer for specific information on how to start Strobe in your environment.

Measuring the Application

With Strobe you can measure applications that run as batch jobs, use TSO, or execute in online regions. This section describes the steps to take in order to measure a particular application with Strobe.

To measure an application that is accessing WebSphere MQ, you have to set parameters on the Strobe - Data Collectors panel. One value can be designated as a default so you only have to set the parameter name once.

1. Select either Option 1 ADD ACTIVE or Option 2 ADD QUEUED REQUEST depending on the type of job you are measuring.
2. Specify the target job name in the JOBNAME field.
3. If this is a queued request, specify the target job step in the PROGRAM or STEP fields.
4. Specify the target system in the SYSTEM field or clear this field to select from a list of systems.
5. Configure the measurement session by specifying the following:
   
   • How long you want to measure the job in the SESSION DURATION field
   • How many performance samples you want Strobe to take in the TARGET SAMPLE SIZE field
   • TSO user ID for Strobe to notify when the request is complete in the TSO USER ID TO NOTIFY field.
6. Specify the sample data set information in the SAMPLE DATA SET INFORMATION fields.

7. Enter Y in the DATA COLLECTORS field and press Enter. The Strobe - Data Collectors panel shown in the following figure is displayed.

   Strobe - Data Collectors Panel

   

8. If you want to suppress WebSphere MQ data collection, enter N in the MQSERIES field.
9. If applications accessing WebSphere MQ call a common user module, perform the following steps:
   

   1. Enter Y in the MQSERIES DATA COLLECTORS field to display the Strobe - MQ Series Data Collector Options panel (See the following figure).

      Strobe - MQ Series Data Collector Options Panel

      
      

   2. Enter the name of the user module that the measured application uses to access WebSphere MQ in the Common MQ User Module field. This name must comply with MVS naming conventions. If using the command language, specify the MQROUTINE=user module name parameter with the ADD command.
   3. If you are using a WebSphere MQ common user module for all Strobe for WebSphere MQ measurements, enter Y in the Always Use as Default field. This will provide attribution back to the calling application during subsequent WebSphere MQ measurements.
10. To generate the WebSphere MQ Service Time by Queue report, enter Y in Collect Region Data field on the Strobe - CICS Data Collector Options panel or specify a transaction name(s) in the Detail Transaction field. See Strobe-for-CICS for more information about CICS data collection and reporting.
11. To view counts of MQI function calls on the MQSeries Total CPU Activity by Queue and MQSeries Total Wait by Queue reports, specify Y in the OTHER PARAMETERS field when adding the measurement. On the Strobe - Other Parameters panel, specify MQSERIES=CAPTURE.
12. Press Enter.

Viewing the Status of Your Measurement Request

Once you have submitted a WebSphere MQ measurement request, you can view the status of the request, regardless of the system on which it is executing.

To view the status of a measurement request, follow these steps:

1. Select Option 3 (STATUS) from the Strobe Options menu. Strobe displays the Strobe - Status panel, which shows the status (active, suspended, queued, or completed) of each measurement request on a given system.
   The Strobe - Status panel displays the status of each measurement request on a given system, as well as specific information about the measurement request.
2. Enter the system name in the SYSTEM field to view the status of measurement requests on a particular system. Alternately, clear this field using the space bar, and press Enter to view a list of all active systems in the sysplex. Strobe displays the Strobe - System Selection List panel, which lists the active systems in the Sysplex. Select one or more of these systems by entering S to the left of the system name.
3. Press the F3 key to exit from the Strobe - Status panel.

Creating the Performance Profile

After the measurement is complete, (the sample data set and, optionally, the map data sets are created) you can create a Performance Profile for your application.

You have three options for creating a Performance Profile with Strobe/ISPF:

• Create a Performance Profile automatically when submitting a measurement request for an active or queued request.
  Enter Y in the AUTO PROFILE CREATION field on the Strobe - Add Active Request panel or the Strobe - Add Queued Request panel.

• Create a Performance Profile from the Strobe Options menu.
  Select Option 4 (PROFILE) from the Strobe Options menu. Strobe displays the Strobe - Produce a Performance Profile panel, where you can specify options for the Performance Profile.

• Create a Performance Profile from the Strobe - Status panel.
  Enter P to the left of a completed measurement request number on the Strobe - Status panel. Strobe displays the Strobe - Produce a Performance Profile panel, where you can specify options for the Performance Profile.

Tailoring WebSphere MQ Reports

When you are creating a Performance Profile, you can limit the amount of reporting of WebSphere MQ measurement data that is contained in the Profile. The Strobe - Tailor Reports panel, (Strobe - Tailor Reports Panel (Scrollable)), provides two fields that pertain to WebSphere MQ reporting.

The MQSERIES CALLS field allows you to specify a percentage value that controls what WebSphere MQ service calls are included in the Performance Profile. These reports are the CPU Usage by Module by MQSeries Call and the Wait by Module by MQSeries Call. The percentage represents the threshold for which you do not require measurement information about a WebSphere MQ statement. For example, you can specify a percentage value of 10 in the MQSERIES CALLS field. A value of 10 causes Strobe not to report on any WebSphere MQ statement that did not execute enough times during a measurement session to represent 10% of the CPU or run time spent in wait that is recorded by Strobe for WebSphere MQ. All WebSphere MQ statements that exceed 10% of the total CPU or run time spent in wait, are shown in the Performance Profile reports.

By default, Strobe will report on WebSphere MQ service calls that show any amount of CPU or run time spent in wait activity.

To set these parameters with Strobe/ISPF or the Strobe command language:

1. Enter Y in the Tailor Reports field of the Strobe - Produce a Performance Profile panel.
2. On the Strobe - Tailor Reports panel, specify a baseline percentage between 0 and 99.9 in the Compress below% portion of the MQSERIES CALLS field (Strobe - Tailor Reports Panel (Scrollable)).

When you submit a batch job using the STROE or STROXE procedure, specify MQCALL=nn.n. where nn.n is the baseline percentage you want to specify.

IMS Transaction Level Reporting

For IMS, Strobe for WebSphere MQ provides you with the option of reporting on either a module or transaction level for the CPU Usage by Module by WebSphere MQ Call and Wait by Module by WebSphere MQ Call reports. To choose transaction level reporting, you specify the MQTRAN parameter as follows and shown in Strobe - Detail for a Performance Profile Panel:

1. On the Strobe - Produce a Performance Profile panel, specify Y in the Detail Reports field.
2. Press Enter to display the Strobe - Detail for a Performance Profile panel.

3. Enter MQTRAN in the OTHER PARAMETERS field as shown in the following figure.
   

   Strobe

    - Detail for a Performance Profile Panel
   
   With the STROE or STROXE procedure, specify the MQTRAN parameter.

Suppressing Attribution Reports

You can suppress all Strobe for WebSphere MQ Attribution reports.

 To set these parameters with Strobe/ISPF:

1. Enter Y in the Tailor Reports field of the Strobe - Produce a Performance Profile panel.
2. On the Strobe - Tailor Reports panel, enter Y in the Suppress reports for MQSERIES field in the ATTRIBUTION REPORTS section.

With the STROE or STROXE procedure, specify the NOATTR=MQSERIES parameter.

Strobe - Tailor Reports Panel (Scrollable)