82
Tivoli ® IBM Tivoli Monitoring for Transaction Performance Application Response Measurement (ARM) Instrumentation Guide Version 5.3 SC32-9412-00

Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

  • Upload
    others

  • View
    6

  • Download
    0

Embed Size (px)

Citation preview

Page 1: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Tivoli® IBM Tivoli Monitoring for Transaction Performance

Application Response Measurement (ARM) Instrumentation Guide

Version 5.3

SC32-9412-00

���

Page 2: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and
Page 3: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Tivoli® IBM Tivoli Monitoring for Transaction Performance

Application Response Measurement (ARM) Instrumentation Guide

Version 5.3

SC32-9412-00

���

Page 4: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Note

Before using this information and the product it supports, read the information Appendix C, “Notices,” on page 61.

First Edition (February 2005)

This edition applies to Version 5.3.0 of IBM® Tivoli® Monitoring for Transaction Performance and to all subsequent

releases and modifications until otherwise indicated in new editions.

© Copyright International Business Machines Corporation 2003. All rights reserved. US Government Users

Restricted Rights — Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Page 5: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Contents

Figures . . . . . . . . . . . . . . . v

About this guide . . . . . . . . . . vii

Who should read this guide . . . . . . . . . vii

Publications . . . . . . . . . . . . . . vii

IBM Tivoli Monitoring for Transaction

Performance library . . . . . . . . . . vii

Related publications . . . . . . . . . . viii

Ordering publications . . . . . . . . . . ix

Accessibility . . . . . . . . . . . . . . ix

Tivoli technical training . . . . . . . . . . ix

Conventions used in this guide . . . . . . . . ix

Typeface conventions . . . . . . . . . . x

Operating system-dependent variables and paths x

Tivoli command syntax . . . . . . . . . . x

Chapter 1. Introduction to Application

Response Measurement (ARM) . . . . . 1

How the ARM API works . . . . . . . . . . 1

How data is collected . . . . . . . . . . . 1

Commercial applications with ARM instrumentation 2

Chapter 2. Overview of ARM

instrumentation for IBM Tivoli

Monitoring for Transaction Performance . 3

Chapter 3. Comparing ARM Versions 1

and 2 . . . . . . . . . . . . . . . . 5

Chapter 4. Using ARM API in a simple

application . . . . . . . . . . . . . 7

ARM API calls . . . . . . . . . . . . . . 7

Example code . . . . . . . . . . . . . 9

Case sensitivity . . . . . . . . . . . . . 10

Returns from ARM API calls . . . . . . . . 10

Handles and return codes . . . . . . . . . 11

Nested and overlapping transactions . . . . . . 11

Using ARM API calls efficiently . . . . . . . 13

Using the completion status on the arm_stop call . . 13

Compiling with ARM . . . . . . . . . . . 14

Chapter 5. ARM Version 2: Tracing a

transaction and writing context data . . 17

Registering your application: ARM Version 2 . . . 17

Registering your transaction: ARM Version 2 . . . 18

Starting and stopping a transaction: ARM Version 2 19

Ending applications and transactions: ARM Version

2 . . . . . . . . . . . . . . . . . . 20

Correlating transactions: ARM Version 2 . . . . . 21

Correlators . . . . . . . . . . . . . 23

Working with correlators . . . . . . . . . 26

Working with Java applications: ARM Version 2 . . 29

Making ARM API Calls From Your Java Classes 30

Java examples for performing ARM Version 2

instrumentation . . . . . . . . . . . . 30

Adding additional metrics for a transaction instance:

ARM Version 2 . . . . . . . . . . . . . 32

Chapter 6. Problem determination and

debugging ARM instrumentation . . . 33

With ARM Version 2 instrumentation in C programs 33

Chapter 7. Performance considerations 35

Instrumentation detail control . . . . . . . . 35

Diagnostic information control . . . . . . . . 35

Chapter 8. Instrumenting generic

windows using Rational Robot . . . . 37

Measuring performance of a transaction . . . . . 37

Simple transaction measurement . . . . . . 37

Compound transaction measurment . . . . . 38

Inserting ARM timers in business processes . . . 39

Inserting IBM Tivoli Monitoring for Transaction

Performance ARM timers in a Generic Windows

GUI script . . . . . . . . . . . . . . 39

Inserting IBM Tivoli Monitoring for Transaction

Performance ARM timers in a Generic Windows

VU script . . . . . . . . . . . . . . 40

Chapter 9. Alternate language bindings 47

Making ARM API calls from PowerBuilder

applications . . . . . . . . . . . . . . 47

Making ARM API calls from Visual Basic

applications . . . . . . . . . . . . . . 48

Using the ARM Version 2 Software Developer’s

Kit . . . . . . . . . . . . . . . . 48

Appendix A. Tracking a transaction into

a J2EE application server . . . . . . 51

Using HTTP . . . . . . . . . . . . . . 51

Using JMS . . . . . . . . . . . . . . . 51

Using SOAP . . . . . . . . . . . . . . 52

Using RMI . . . . . . . . . . . . . . . 53

WebSphere Application Server Version 4: . . . 53

WebSphere Application Server Version 5 and

later: . . . . . . . . . . . . . . . . 54

Weblogic: . . . . . . . . . . . . . . 55

Appendix B. libSWARM function calls 57

Appendix C. Notices . . . . . . . . . 61

Trademarks . . . . . . . . . . . . . . 62

Index . . . . . . . . . . . . . . . 65

iii

Page 6: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

iv IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 7: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Figures

1. Relationship between ARM calls . . . . . . 1

2. Relationship between ARM API calls . . . . 7

3. Overlapping transactions . . . . . . . . 12

4. Making the arm_init and arm_getid calls at

program initialization . . . . . . . . . 13

5. Compile and link process for an

ARM-instrumented application . . . . . . 14

6. ARM API transaction correlation . . . . . 22

7. Tracing a transaction through WebSphere

Application Server . . . . . . . . . . 23

8. ARM Version 2: Correlator buffer . . . . . 24

9. ARM Version 2: Correlator buffer flags 25

10. ARM Version 2: Correlation example files 26

11. ARM Version 2: Generating transaction

correlators . . . . . . . . . . . . . 27

12. ARM Version 2: Passing transaction correlators 28

13. ARM Version 2: Consuming transaction

correlators . . . . . . . . . . . . . 29

14. Resolving the ARM calls as PowerBuilder

external functions . . . . . . . . . . 48

15. Using the ARM SDK to compile and link a

Windows program. . . . . . . . . . . 49

v

Page 8: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

vi IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 9: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

About this guide

IBM Tivoli Monitoring for Transaction Performance enables you to manage the

availability and performance of your Web application environment. It gathers the

detailed information you need to track and improve transaction times, with the

goal of ensuring optimal responsiveness.

The Application Response Measurement (ARM) API is a set of standard API calls

that enable you to measure the performance of your applications. The API is

mainly used to measure response time, but it can also be used to record

application availability and account for application usage.

Who should read this guide

This guide is for developers who want to add ARM instrumentation to their

applications, so that they work with IBM Tivoli Monitoring for Transaction

Performance. The guide assumes that readers are familiar with IBM Tivoli

Monitoring for Transaction Performance. Specifically, readers of this guide should

have some knowledge of the following software:

v Operating systems on which you intend to instrument ARM. Supported

operating systems include Windows® 2000, Windows XP, AIX®, Solaris

Operating Environment (referred to as Solaris in this document), Red Hat Linux,

SuSE Linux, TurboLinux, HPUX, z/OS®, and OS/400®.

v Web servers, such as IBM® HTTP Server, Apache HTTP Server, and Microsoft®

Internet Information Server.

v Web application servers, such as IBM WebSphere® Application Server.

v Internet protocols such as HTTP, HTTPS, TCP/IP, Secure Sockets Layer (SSL),

and Transport Layer Security (TLS).

Publications

This section lists publications in the IBM Tivoli Monitoring for Transaction

Performance library and related documents. It also describes how to access Tivoli®

publications online and how to order Tivoli publications.

IBM Tivoli Monitoring for Transaction Performance library

The following documents provide information about the IBM Tivoli Monitoring for

Transaction Performance product:

v IBM Tivoli Monitoring for Transaction Performance Installation and Configuration

Guide, SC32-9107-00

Provides prerequisite information and instructions for installing the product.

This guide also contains information that you might find useful after installing

the product, such as uninstallation instructions.

v IBM Tivoli Monitoring for Transaction Performance Evaluation Guide, GC32-9190-00

Provides prerequisite information and instructions for performing a very simple

installation of the product and deploying one of the components for evaluation

purposes. This document enables you to go through the installation wizards and

see the product’s user interface performing some basic task and functions.

v IBM Tivoli Monitoring for Transaction Performance Administrator’s Guide,

GC32–9189–00

vii

Page 10: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Provides detailed procedures for deploying and using each of the product

components.

v IBM Tivoli Monitoring for Transaction Performance Checking Performance and

Availability Guide, SC32–9106–00

The guide also describes the browser-based graphical user interface (GUI), the

help system, and how to produce graphical reports from transaction

performance data.

v IBM Tivoli Monitoring for Transaction Performance Problem Determination Guide,

SC32-9108–00

Provides the latest information about known product limitations and

workarounds for the product. To ensure that the information is the latest

available, this document is provided only on the Web, where it is updated as

needed.

v IBM Tivoli Monitoring for Transaction Performance: Web Transaction Performance

Warehouse Enablement Pack Implementation Guide, SC32-9109-00

Describes how to install and configure the warehouse enablement pack for the

product. This document also describes the data flow and data structures used by

the warehouse pack. The warehouse pack enables the product to transfer data to

the Tivoli Enterprise™ Data Warehouse.

v Program Directory for IBM Tivoli Monitoring for Transaction Performance for z/OS,

Version 5.3

Describes installing and maintaining IBM Tivoli Monitoring for Transaction

Performance for z/OS.

Related publications

The Application Response Measurement (ARM) standard describes a common

method for integrating enterprise applications as manageable entities. The ARM

standard allows users to extend their enterprise management tools directly to

applications creating a comprehensive end-to-end management capability that

includes measuring application availability, application performance, application

usage, and end-to-end transaction response time.

v All of the information about ARM is provided on the following Web site:

http://www.opengroup.org/arm/

IBM Tivoli Monitoring for Transaction Performance can optionally be integrated

with a number of enterprise products to provide more advanced capabilities.

Following is a list of these products and some of the publications provided by each

product.

v IBM WebSphere Site Analyzer

All information about IBM WebSphere Site Analyzer is provided on the

following Web site:

http://www-3.ibm.com/software/webservers/siteanalyzer/library.html

The following IBM Redbooks™ provide information about advanced

configuration options for WebSphere Application Server, which hosts the

management server application for IBM Tivoli Monitoring for Transaction

Performance:

– IBM WebSphere Application Server System Management and Configuration:

WebSphere Handbook Series, SG24-6195

– IBM WebSphere Security WebSphere Handbook Series, SG24-6573v IBM WebSphere Application Server, Version 5.1

viii IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 11: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

All information about the IBM WebSphere Application Server Version 5.1 is

provided on the following Web site:

http://www-3.ibm.com/software/webservers/appserv/was/library/

v IBM WebSphere Caching Proxy, Version 5.1

All information about the IBM WebSphere Caching Proxy Version 5.1 is

provided on the following Web site:

http://www-306.ibm.com/software/webservers/appserv/ecinfocenter.html

The Tivoli Glossary includes definitions for many of the technical terms related to

Tivoli software. The Tivoli Glossary is available, in English only, at the following

Web site:

http://publib.boulder.ibm.com/tividd/glossary/termsmst04.htm

Ordering publications

You can order many Tivoli publications online at the following Web site:

http://www.elink.ibmlink.ibm.com/public/applications/

publications/cgibin/pbi.cgi

You can also order by telephone by calling one of these numbers:

v In the United States: 800-879-2755

v In Canada: 800-426-4968

In other countries, see the following Web site for a list of telephone numbers:

http://www.ibm.com/software/tivoli/order-lit/

Accessibility

Accessibility features help users with a physical disability, such as restricted

mobility or limited vision, to use software products successfully. With this product,

you can use assistive technologies to hear and navigate the interface. You can also

use the keyboard instead of the mouse to operate most features of the graphical

user interface.

For additional information, see the Accessibility Appendix in the Administrator’s

guide for this product.

Tivoli technical training

For Tivoli technical training information, refer to the following IBM Tivoli

Education Web site:

http://www.ibm.com/software/tivoli/education/

Conventions used in this guide

This guide uses several conventions for special terms and actions, and operating

system-dependent commands and paths.

About this guide ix

Page 12: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Typeface conventions

This guide uses the following typeface conventions:

Bold

v Lowercase commands and mixed case commands that are otherwise

difficult to distinguish from surrounding text

v Interface controls (check boxes, push buttons, radio buttons, spin

buttons, fields, folders, icons, list boxes, items inside list boxes,

multicolumn lists, containers, menu choices, menu names, tabs, property

sheets), labels (such as Tip:, and Operating system considerations:)

v Keywords and parameters in text

Italic

v Words defined in text

v Emphasis of words (for example, ″Use the word that to introduce a

restrictive clause.″)

v New terms in text (except in a definition list)

v Variables and values you must provide

Monospace

v Code and other examples

v File names, programming keywords, and other elements that are difficult

to distinguish from surrounding text

v Message text and prompts addressed to the user

v Text that the user must type

v Values for arguments or command options

Operating system-dependent variables and paths

The publications in this library use the UNIX® convention for specifying

environment variables and for directory notation.

When using the Windows command line, replace $variable with %variable% for

environment variables and replace each forward slash (/) with a backslash (\) in

directory paths. The names of environment variables are not always the same in

Windows and UNIX. For example, %TEMP% in Windows is equivalent to $tmp in

UNIX.

Note: If you are using the bash shell on a Windows system, you can use the UNIX

conventions.

Tivoli command syntax

The following special characters define Tivoli command syntax:

[ ] Identifies elements that are optional. Required elements do not have

brackets around them.

... Indicates that you can specify multiple values for the previous element.

Separate multiple values by a space, unless otherwise directed by

command information.

If the ellipsis for an element follows a closing bracket, use the syntax

within the brackets to specify multiple values. For example, to specify two

administrators for the option [–a admin]..., use –a admin1 –a admin2.

x IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 13: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

If the ellipsis for an element is within the brackets, use the syntax of the

last element to specify multiple values. For example, to specify two hosts

for the option [–h host...], use –h host1 host2.

| Indicates mutually exclusive information. You can use the element on

either the left or right of the vertical bar.

{ } Delimits a set of mutually exclusive elements when a command requires

one of them. Brackets ([ ]) are around elements that are optional.

In addition to the special characters, Tivoli command syntax uses the typeface

conventions described in “Typeface conventions” on page x. The following

examples illustrate the typeface conventions used in Tivoli command syntax:

v wcrtpr [–a admin]... [–s region] [–m resource]... name

The name argument is the only required element for the wcrtpr command. The

brackets around the options indicate they are optional. The ellipsis after the –a

admin resource option means that you can specify multiple administrators

multiple times. The ellipsis after the –m resource option means that you can

specify multiple resources multiple times.v wchkdb [–o outfile] [–u] [–x] {–f infile | –i | object...}

The –f, –i, and object elements are mutually exclusive. Braces that surround

elements indicate that you are including a required element. If you specify the

object argument, you can specify more than one object.

About this guide xi

Page 14: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

xii IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 15: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Chapter 1. Introduction to Application Response Measurement

(ARM)

The Application Response Measurement (ARM) API is a set of standard API calls

that enable you to measure the performance of your applications. The API is

mainly used to measure response time, but can also be used to record application

availability usage.

For more information on the ARM, see http://www.opengroup.org/arm/.

How the ARM API works

To measure response time for an application, the application must be instrumented.

Instrumenting an application means there must be ARM API calls in the

application source code. To see how the calls are used to measure response time,

we will use the ARM API Version 1 calls as an example. See Figure 1.

The benefit of this approach is that you can place the calls that start and stop the

response time clock in exactly the parts of the application that you want to

measure. This is done by defining individual applications and transactions within a

program, and then placing the ARM API calls at the start of the transaction and at

the end of the transaction.

How data is collected

Response time collection is performed by the IBM Tivoli Monitoring for

Transaction Performance management agent.

For IBM Tivoli Monitoring for Transaction Performance to collect response times

for an application, that application must make calls to the ARM API on the

machine where response time measurements are being made.

Figure 1. Relationship between ARM calls

1

Page 16: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

An IBM Tivoli Monitoring for Transaction Performance management agent on

which an ARM component is deployed could be installed on each of the machines

within the path of the transaction, then, if the matching start and stop calls for

each component of the transaction that runs on that machine are made on that

machine, the transaction can be followed through the infrastructure.

Commercial applications with ARM instrumentation

You can use applications that are already instrumented. The following are

commercial applications that already contain ARM instrumentation.

v WebSphere Version 5.1 and 6

v Apache Web server

v IBM HTTP server

v Microsoft Internet Information Server

v DB2 Version 8v Siebel server Version 7.7

v Baan ERP based on porting set 7.0a or later

v SAS Version 8 and later

2 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 17: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Chapter 2. Overview of ARM instrumentation for IBM Tivoli

Monitoring for Transaction Performance

ARM instrumentation is performed to enable the you to monitor the response time

of requests or the work that an application is performing. In order to monitor an

application, it is important that the IBM Tivoli Monitoring for Transaction

Performance product receive notification of the following types of events:

v The start of a request serviced by the application.

v The beginning and end of the components servicing a request within the

application.

This information provides a basic understanding of the work the application is

performing and monitors the overall response time of the applications requests and

the sub-components that are used for servicing those requests.

From a IBM Tivoli Monitoring for Transaction Performance perspective, an

application is a program that is designed for a specific purpose. Examples of

applications are:

v WebSphere Application Server

v Siebel Application Server

v Apache

v Microsoft word

If you have multiple installations of one application, each installation is considered

an instance of that application. This is true even if the installations are on different

computers.

ARM should be notified about each application to be monitored, and then again

about each specific instance of those applications. This enables the IBM Tivoli

Monitoring for Transaction Performance product to report statistics based upon the

application without regard to where it resides or what instance it is, or to report

information based upon a specific instance of an application.

A transaction is the section of work that should be monitored and timed by the

ARM engine. When a user hits a Web page and receives a reply from the server,

this is single transaction from a user perspective. From the server perspective,

however, this transaction is broken down into several units of work, each of which

is considered an ARM transaction.

In the IBM Tivoli Monitoring for Transaction Performance product, the edge

transaction is the first point in time that work being done to service a user request

is monitored. Other units of work performed to process that edge transaction are

referred to as subtransactions.

Table 1 on page 4 summarizes the basic flow of steps you should take to

instrument ARM for IBM Tivoli Monitoring for Transaction Performance.

3

Page 18: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Table 1. Goals for performing ARM instrumentation for IBM Tivoli Monitoring for Transaction

Performance

Steps Refer to

1. Register your

application

ARM Version 2: “Registering your application: ARM Version 2” on

page 17

2. Register your

transaction

ARM Version 2: “Registering your transaction: ARM Version 2” on

page 18

3. Start and stop your

transaction

ARM Version 2: “Starting and stopping a transaction: ARM Version

2” on page 19

4. End your

application and

transaction

ARM Version 2: “Ending applications and transactions: ARM

Version 2” on page 20

5. (Optional) Correlate

transactions

ARM Version 2: “Correlating transactions: ARM Version 2” on page

21

6. (Optional) Write

context data for

transaction instances

ARM Version 2: “Adding additional metrics for a transaction

instance: ARM Version 2” on page 32

4 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 19: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Chapter 3. Comparing ARM Versions 1 and 2

Table 2 lists the supported versions of ARM and provides a brief summary of the

functions included with each. You can perform ARM instrumentation for IBM

Tivoli Monitoring for Transaction Performance using ARM Version 1 and 2.

Each version of ARM build upon the previous version enabling you to perform

increasingly complex instrumentation.

ARM Version 1

Provides basic ARM API calls.

ARM Version 2

Provides the following in addition to the Version 1 capabilities:

v Transaction correlation which enables you to trace transaction steps on

one computer, or across multiple computers.

v Additional metrics support which enables you to add meaningful

identification information when running transactions.

Table 2. Comparing ARM Version 1 and 2

ARM Version

Languages

supported Function provided Complexity

ARM Version 1 C and C++ Response time

Completion status

Simple

ARM Version 2 C and C++ Response time

Completion status

Tracing across machines

Additional metrics

Simple

(Optionally complex with

customization)

5

Page 20: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

6 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 21: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Chapter 4. Using ARM API in a simple application

Applications must be instrumented for the ARM agents to measure response times.

An ARM agent is any agent that implements ARM and receives the program calls,

such as the IBM Tivoli Monitoring for Transaction Performance management agent.

This section addresses what it means to be instrumented, and shows how to

instrument some sample applications written in C using ARM Version 1 calls.

To instrument an application for ARM, you must place ARM API calls at

appropriate points in the application code.

ARM API calls

In this section, each ARM API Version 1 call is described and a code example is

provided. In these calls you will see that some parameters are set to zero (0). In

ARM API Version 1, these are reserved, but in later versions they can be used.

arm_init

This function is used to define an application. It must be made before any

other ARM API calls related to that application. For example:

appl_handle = arm_init(application,"appl_user_id",0,0,0);

Where:

application

This is the name you specify for the application. This can be any

name you like, up to 128 bytes. Choose a name that will be

meaningful in the reports.

appl_user_id

This can be set to *, in which case the logged in user ID is pulled

from the operating system.

The handle returned by this function is placed in the appl_handle variable,

which is then used by the arm_getid function.

Figure 2. Relationship between ARM API calls

7

Page 22: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

arm_getid

This function is used to define a transaction. The transaction must be a

child of an application. For example:

getid_handle = arm_getid(appl_handle,transaction,"W95/NTwks",0,0,0);

Where:

transaction

This is the name you specify for the transaction. This can be any

name you like, up to 128 bytes. Choose a name that will be

meaningful in the reports.

appl_handle

This is the variable that was returned by the arm_init function.

tran_detail

This parameter is set to W95/NTwks so that reports on this

transaction include information indicating the type of machine on

which it is running. IBM Tivoli Monitoring for Transaction

Performance uses the tran_detail parameter to group transactions

in boxes in the topology view. For example, for all EJB type

transactions J2EE uses the value EJB for the tran_detail parameter,

which is then used by reporting to group the EJB transactions into

a box in the topology view.

The handle returned by this function is placed in the getid_handle variable.

The getid_handle variable is then used by the arm_start function.

arm_start

Call this function when the transaction starts running. It starts the response

time clock. For example:

start_handle = arm_start(getid_handle,0,0,0);

Where:

getid_handle

This is the variable that was returned by the arm_getid function.

The handle returned by this function is placed in the start_handle variable.

The start_handle variable is used by the arm_update and arm_stop

functions.

arm_update

This function can be used as a heartbeat, to check the progress of a

long-running transaction. It can be used as many times as you want,

between the arm_start and arm_stop calls. For example:

updaterc = arm_update(start_handle,0,0,0);

Where:

start_handle

This is the variable that was returned by the arm_start function.

This function returns an error code rather than a handle. The error code is

placed in the updaterc variable.

arm_stop

This call is made when the transaction stops running. It stops the response

time clock. For example:

stoprc = arm_stop(start_handle,ARM_GOOD,0,0,0);

8 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 23: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Where:

start_handle

This is the variable that was returned by the arm_start function.

ARM_GOOD

In the example the transaction status field was set to ARM_GOOD.

The other options are ARM_ABORT and ARM_FAILED. These can

be used to separately record transactions that do not complete as

expected.

This function returns an error code rather than a handle. The error code is

placed in the stoprc variable.

arm_end

Make this call when the application ends. It causes a cleanup of the

memory that the IBM Tivoli Monitoring for Transaction Performance agent

has allocated for this application. For example:

endrc = arm_end(appl_handle,0,0,0);

Where:

appl_handle

This is the variable that was returned by the arm_init function

This function returns an error code rather than a handle. The error code is

placed in the endrc variable.

Example code

The bold text in this example is used to highlight the information that was entered

to perform the ARM instrumentation.

/***************************************************************/

/* This is a simple demonstration program. */

/* It tests the IBM TMTP agent for Windows. */

/***************************************************************/

#define W32

#include <windows.h>

#include "arm.h"

#include <stdio.h>

#include <string.h>

void main()

/*****************************************************************************/

/* Define the variables. */

/*****************************************************************************/

{

char application[128];

char transaction[128];

long appl_handle;

long getid_handle;

long start_handle;

char string[20];

long stoprc;

long endrc;

/***************************************************************************/

/* Ask for application name and make arm_init call. */

/***************************************************************************/

Chapter 4. Using ARM API in a simple application 9

Page 24: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

printf("\nThis program generates transactions for TMTP.\n\n");

printf("Please enter the name of your application:\n");

scanf("%s", &application);

appl_handle = arm_init(application,"*",0,0,0);

/***************************************************************************/

/* Ask for transaction name and make arm_getid call. */

/***************************************************************************/

printf("\nPlease enter the name of your transaction:\n");

scanf("%s",&transaction);

getid_handle = arm_getid(appl_handle,transaction,"ARM",0,0,0);

/************************************************************************/

/* Start transaction and make arm_start call. */

/************************************************************************/

start_handle = arm_start(getid_handle,0,0,0);

printf("\nTransaction started...\n");

printf("Type some characters and press ENTER when\n");

printf("you want to stop the transaction.\n");

scanf("%s",&string);

/************************************************************************/

/* Stop transaction and make arm_stop call. */

/************************************************************************/

printf("\n\nTransaction stopped.\n\n");

stoprc = arm_stop(start_handle,ARM_GOOD,0,0,0);

/***************************************************************************/

/* End application by making an arm_end call. */

/***************************************************************************/

endrc = arm_end(appl_handle,0,0,0);

}

/*****************************************************************************/

/* End of program. */

/*****************************************************************************/

Case sensitivity

The ARM API calls are C functions and are case sensitive. All ARM API functions

use lowercase.

If you use uppercase:

v In C or C++ the compiler will fail to resolve the external functions.

v In a language other than C, the call will return -1.

Returns from ARM API calls

Each ARM function returns a 32-bit signed integer.

The following functions return handles that indicate status or are used on

subsequent calls:

v arm_init

10 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 25: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

v arm_getid

v arm_start

The following functions return integers that indicate status:

v arm_update

v arm_stop

v arm_end

Handles and return codes

Declare integer variables in your program to hold the handles and return codes

from the ARM API calls. The handles cannot be manipulated as integer variables.

The handle has meaning only to the ARM agent and cannot be modified in any

way.

A negative return code always indicates that the function was unsuccessful. For

calls that return handles, a positive integer indicates success. For calls that return

status, zero (0) indicates success.

The following table gives the possible return codes for failure:

Table 3. Handles and return codes

Return code Explanation

-1 An invalid argument was specified. This usually means that a mistake

was made in the syntax of the call. For example, too many or too few

arguments might have been coded on the call.

In C or C++, these errors are caught by the linker when it resolves the

external references in the shared library that is shipped with the agent.

In other languages, there is no link step and the errors occur when the

ARM API call is made.

-2 The ARM agent is not running.

This error usually occurs because the ARM agent has not been started on

the machine where the ARM API call is being made. The agent must be

installed and running.

Nested and overlapping transactions

An IBM Tivoli Monitoring for Transaction Performance management agent, with

ARM implemented, returns a handle in response to each ARM API call. This

enables you to nest or overlap transactions. For an example of overlapping

transactions in application code, see Figure 3 on page 12.

Chapter 4. Using ARM API in a simple application 11

Page 26: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Figure 3. Overlapping transactions

12 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 27: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Using ARM API calls efficiently

There are two API function calls in the ARM Version 2 API that are associated with

registration, the arm_init function call and the arm_getid function call. These API

calls normally have a higher overhead than the corresponding arm_start function

call and the arm_stop function call. These function calls should be performed once

when the application starts, for the arm_init function, and once the first time the

transaction is run, for the arm_getid function.

Using the completion status on the arm_stop call

Provide transaction status to IBM Tivoli Monitoring for Transaction Performance

by passing one of the following parameters to the arm_stop function:

Table 4. Completion status on the arm_stop call

Value Explanation

ARM_GOOD Indicates the transaction completed

successfully.

ARM_FAIL Can be used to create alarms if the

transaction does not complete as expected.

Figure 4. Making the arm_init and arm_getid calls at program initialization

Chapter 4. Using ARM API in a simple application 13

Page 28: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Table 4. Completion status on the arm_stop call (continued)

Value Explanation

ARM_ABORT Can be used to create alarms if the

transaction does not complete as expected.

IBM Tivoli Monitoring for Transaction Performance separately reports transactions

that complete in each of the three statuses.

Compiling with ARM

Once you have placed the ARM API calls in source file, you are ready to compile.

The compile process for an ARM-instrumented application is shown in Figure 5.

You do not need to have an ARM agent installed or active on the machine where

you are compiling.

Before compiling, check the following:

1. That the required header and library files are present on the machine. The

ARM header and library files provide the prototypes for the ARM functions

Figure 5. Compile and link process for an ARM-instrumented application

14 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 29: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

and resolve those functions during the link step. You need the header and

library files appropriate for the operating system platform on which the

application will run.

2. That the directory containing the header and library files has been specified in

the compiler’s include and in the link directory paths.

3. That you have specified the correct library file to the linker. Each operating

system platform requires a different library file.

Chapter 4. Using ARM API in a simple application 15

Page 30: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

16 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 31: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Chapter 5. ARM Version 2: Tracing a transaction and writing

context data

ARM Version 2 provides transaction correlation and additional metrics in addition

to the Version 1 capabilities.

Table 5. Goals for performing ARM Version 2 instrumentation for IBM Tivoli Monitoring for

Transaction Performance

Steps Refer to

1. Register your

application

“Registering your application: ARM Version 2”

2. Register your

transaction

“Registering your transaction: ARM Version 2” on page 18

3. Start and stop your

transaction

“Starting and stopping a transaction: ARM Version 2” on page 19

4. End your

application and

transaction

“Ending applications and transactions: ARM Version 2” on page 20

5. (Optional) Correlate

transactions

“Correlating transactions: ARM Version 2” on page 21

6. (Optional) Write

context data for

transaction instances

“Adding additional metrics for a transaction instance: ARM Version

2” on page 32

Registering your application: ARM Version 2

In ARM Version 2, you must register your application before it can be monitored.

Registration is done using the arm_init function.

When you register an application, you are informing ARM that it should be

monitored. Typically an application registers itself each time it is started and

passes contextual information for identification. When the application ends, it

notifies the ARM agent that it is no longer running and that any resources

allocated on the local machine can be freed up for other uses.

The application name passed to the arm_init function should be the same every

time the application is started and for every instance of this application. This

enables you to identify the application and the user that runs the application. The

return value from this call needs to be saved for later use and is a great candidate

for encapsulation into a singleton object for the application.

Using C or C++:

/**

* Obtain/create a handle for the given Application/User pair.

*

*appl_name ASCIIZ pointer to the application name. Must not be NULL

* or an empty string.

*appl_user_id ASCIIZ pointer to the user name. If NULL, will use an

* empty string as the name. If <B>*</B> will get the currently running

* user from the base operating system.

*flags Reserved parameter.

*data Reserver parameter. Not used.

17

Page 32: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

*data_size Reserver parameter. Not used.

*

* return Value > 0 containing a handle to the application/user

* pair, otherwise an error code (<= 0).

*/

arm_int32_t ARM_API arm_init(char *appl_name,

char *appl_user_id,

arm_int32_t flags,

char *data,

arm_int32_t data_size);

For example:

int applicationID=-1;

applicationID = arm_init("WebSphere","*",0,null,0);

/**

*Registers an application Identified as "Websphere" running as

*the logged in user.

*/

Registering your transaction: ARM Version 2

Register a transaction to inform ARM about a type of transaction that will be run.

When you register a transaction, you are providing contextual information that is

used by the ARM engine to classify that transaction.

Transactions are usually registered once when the application is started, or when a

class is loaded in Java using a static initializer for that class. Information that

changes from instance to instance is described at registration and then is passed at

the time the transaction starts.

Transactions must be organized and formatted so they can be easily understood by

the product collecting the ARM data and the user who is viewing that data. For

these reasons it is important that you plan carefully when creating transaction

names.

For edge transactions, use more descriptive names from a business perspective.

Examples of descriptive names are:

v URLs

v Script name and useful parameters

v The action being performed and the object on which it is being performed. For

example:

MicrosoftWord.SpellCheck("ArmInstrumentationGuide");

Use this type of naming convention on subtransactions if you are using an engine

that decodes information and performs work based upon the values passed to it.

For example, a subtranscation named runScript(String) is not as useful as

runScript(actualscriptname).

Note: In the following examples a transaction is registered for an object called Foo

and method named bar with signature (String) or Foo.bar(String).

Using C or C++:

/**

* Obtain/create a transaction class ID for the input transaction name

* associated with the input Application/User handle.

18 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 33: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

*

* Each transaction name associated with an application/user handle is unique.

* The same transaction name may exist for 2 or more application/user handles

* but they will each have a unique transaction class ID.

*

*appl_id Application/user handle previously returned by a

* successful call to arm_init().

*tran_name ASCIIZ pointer to the transaction name.

*tran_detail ASCIIZ pointer to the transaction detail. Must not be NULL.

*flags Not used.

*data Must point to an arm_user_data101_t element (see arm.h).

* Contains the metrics meta data for all metrics used by this transaction.

* This metric data is passed in arm_start, arm_update, arm_stop, etc.

* The format element must be ARM_Format101.

*data_size Number of bytes pointed to by data.

*

*return Value > 0 containing a handle to the application/user

* pair, otherwise an error code (<= 0).

*/

arm_int32_t ARM_API arm_getid(arm_int32_t appl_id,

char* tran_name,

char* tran_detail,

arm_int32_t flags,

char* data,

arm_int32_t data_size);

For example:

int applicationID;

int transactionID;

applicationID = arm_init("WebSphere/Cell/Node/Server","*",0,null,0);

transactionID = arm_getid(applicationID,"Foo.bar(String);","",0,NULL,0);

Starting and stopping a transaction: ARM Version 2

The following sections describe how to use the handles returned by the ARM

functions to run transactions that are monitored by the application.

Note: Without the use of correlators, products using the ARM are unable to

establish relationships between transactions and their subtransactions. The

examples in this section do not make use of correlators. For more

information on correlators, see “Correlating transactions: ARM Version 2” on

page 21.

Using C or C++:

* Mark the beginning of execution of a transaction. Each time a transaction

* runs, it is called a transaction instance.

* Parameters:

* tran_id: the unique identifier assigned to the transaction

* class

* flags: reserved = 0

* data: a pointer to a buffer with additional data that can

* optionally be passed

* data_size: length in bytes of the buffer pointed to by data

* Return value:

* start_handle: the unique transaction handle assigned to this

* instance of a transaction

**/

arm_int32_t arm_start( arm_int32_t tran_id,

arm_int32_t flags,

char *data,

Chapter 5. ARM Version 2: Tracing a transaction and writing context data 19

Page 34: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

arm_int32_t data_size);

/**

* Mark the completion of a transaction instance that was started with a call to

* arm_start().

*

*start_handle The handle to a successfully started transaction

* i.e. return value from arm_start()).

*tranStatus The status of the transaction. Valid values are the

* values of arm_tran_status_e (see arm.h):

* <ul>

* <li>ARM_GOOD - Transaction was successful.

* <li>ARM_ABORT - Transaction was aborted before it could finish.

* <li>ARM_ABORT - Transaction was aborted before it could finish.

* </ul>

*flags Reserved = 0.

*data Pointer to a arm_user_data1_t structure containing

* metric information for the transaction. Can be NULL

* if no metric information is to be passed.

*data_size Number of bytes pointed to by data. Should be 0 if

* data is NULL.

*

*return 0 if the transaction instance is successfully

* stopped, an

* error code otherwise (< 0).

*/

arm_int32_t ARM_API arm_stop(arm_int32_t start_handle,

arm_int32_t tranStatus,

arm_int32_t flags,

char *data,

arm_int32_t data_size);

For example:

int applicationID;

int transactionID;

int startHandle;

applicationID = arm_init("WebSphere/Cell/Node/Server","*",0,null,0);

transactionID = arm_getid(applicationID,"Foo.bar(String);","",0,NULL,0);

/**

*

*Appication logic

*

*/startHandle = arm_start(transactionID,0,NULL,0);

arm_stop(startHandle,ARM_GOOD,0,NULL,0);

Ending applications and transactions: ARM Version 2

The following section describes how to use the ARM end function call to clean up

of the memory that the IBM Tivoli Monitoring for Transaction Performance agent

has allocated for this application.

Using C or C++:

/** Mark the end of an application

*

*

* appl_id Application/user handle previously returned by a

* successful call to arm_init()

* flags Reserved. Set this to 0.

20 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 35: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

* data Reserved. A NULL pointer. Set this to 0.

* data_size Reserved. Set this to 0.

*

* return 0 if the call is successful

*

*/

arm_int32_t ARM_API arm_end(arm_int32_t appl_id,

arm_int32_t flags,

char* data,

arm_int32_t data_size);

For example:

endrc = arm_end(appl_id,0,0,0);

Correlating transactions: ARM Version 2

Transaction correlation was introduced with Version 2.0 of the ARM API and

enables you to do the following:

1. Break a transaction into its component parts, enabling you to see each

component’s contribution to the total response time of the application.

2. Reconstruct the path of the overall transaction and see the relationship between

the various component transactions. It is usually possible for a transaction to

follow more than one path.

To trace a multi-step transaction or parent transaction, across its subtransactions, or

child transactions, the ARM API defines a transaction correlation capability. This is

used by requesting a correlator from the IBM Tivoli Monitoring for Transaction

Performance agent on the arm_start function call. A correlator is a data structure

that contains a number of fields that make it unique to the transaction instance for

which it was generated, see “Correlators” on page 23. The instrumented code must

then pass the correlator on to the next step in the transaction, which can be on the

same computer, or another computer, and it must then be passed in on the

arm_start function call that is made there.

Chapter 5. ARM Version 2: Tracing a transaction and writing context data 21

Page 36: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Figure 7 on page 23 shows the topology of a WebSphere Application Server

transaction and enables you to see the relationship between the various component

transactions.

Figure 6. ARM API transaction correlation

22 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 37: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Correlators

A correlator is stored as part of the ARM Additional Data buffer. The Additional

Data buffer must be set up by the application before the arm_start function call is

made. This buffer can contain data pertaining to ARM additional metrics and

transaction correlation. We will only look at transaction correlation, in which case

all the metric fields in the buffer can be zero (0).

Figure 7. Tracing a transaction through WebSphere Application Server

Chapter 5. ARM Version 2: Tracing a transaction and writing context data 23

Page 38: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Three parts of the buffer are relevant for transaction correlation:

Flags Used to control correlator handling in the ARM agent.

Correlator Length

Contains the length of the Correlator Data section, is variable, and can be

up to 168 bytes.

Correlator Data

Contains the correlator.

The flags section is used to control the behavior of the ARM agent with respect to

correlator handling; only the first four bits of the first byte are relevant for

transaction correlation.

There are four bit-switches that can be used in correlation. The switches can be set

by the application before making the arm_start function call, and by the ARM

agent in response to the call.

Figure 8. ARM Version 2: Correlator buffer

24 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 39: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

A sample program is available, in source and compiled form, to test correlation

functions. Refer to this sample while reading the sections on performing

correlation. To download this program go to the following Web site:

http://publib.boulder.ibm.com/infocenter/tiv3help/index.jsp?topic=

/com.ibm.itmtp.doc/correlation.zip

The sample program is made up of a number of components, as in Figure 10 on

page 26.

Figure 9. ARM Version 2: Correlator buffer flags

Chapter 5. ARM Version 2: Tracing a transaction and writing context data 25

Page 40: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

The client component makes an arm_start function call requesting a correlator. If a

correlator is returned, it is displayed on the screen. Here is sample output:

Buffer flags section contains: 64

Client start call made: handle = 17

Now the buffer flags section contains: 32

------------------------ correlator ------------------------

correlator = |01|00|00 01|06 3e|00 02|00 00|00 00 00 11|00

00 00 01|00 04|ff 54 12 45|00 00

Length = 26

Format = 1

Flags = 0

Address format = 1

Vendor Id = 1598

Agent version = 2

Agent Instance = 0

Trans Instance = 17

Trans class Id = 1

Address length = 4

------------------------------------------------------------

Then the server component consumes the correlator.

Working with correlators

To use ARM transaction correlation you must do the following:

Figure 10. ARM Version 2: Correlation example files

26 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 41: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

1. Generate a correlator when a parent transaction’s arm_start function call is

made.

2. Pass the returned correlator up to the next step, so that it is available if an

arm_start function call is made for a child transaction.

3. Pass the correlator in from the buffer, to be consumed by a child transaction,

when an arm_start function call is made.

Generating a correlator

A unique correlator should be generated for each transaction. To generate a

correlator, do the following:

Note: For information on the buffer, see “Correlators” on page 23.

1. Create a buffer in the transaction’s memory.

2. Set the request correlator flag in the buffer.

3. Make a arm_start function call that has parameters pointing to the buffer and

setting the maximum correlator length for the requested correlator. The

maximum correlator length is 168 bytes.

The IBM Tivoli Monitoring for Transaction Performance agent will return a

correlator, put it in the buffer, and set the correlator returned flag.

Figure 11. ARM Version 2: Generating transaction correlators

Chapter 5. ARM Version 2: Tracing a transaction and writing context data 27

Page 42: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Passing a correlator

After the correlator is generated, the instrumented code must then pass the

correlator on to the next step in the transaction, which can be on the same

computer, or another computer. This correlator must be stored in a buffer that can

be read when an arm_start function call is made for one of its child transactions

and is requesting a correlator.

It might also be beneficial to pass correlators to external applications (or processes

if your application runs in multiple processes). This enables the ARM engine

servicing the other application to associate work it performs in that application

with the work done by the external application to build an inter-application

transaction tree view.

Consuming a correlator

When the child transaction is run, a flag must be set in the buffer to request that a

parent correlator be passed in. To set the flag, do the following:

1. Set the flag in the buffer to pass in the parent correlator.

2. If this transaction will call another transaction, a grandchild transaction, set the

request correlator flag in the buffer.

Note: A new correlator must be requested at each step.

Figure 12. ARM Version 2: Passing transaction correlators

28 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 43: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

3. Make the arm_start function call with parameters pointing to the buffer and

specifying the length of the correlator that is being passed in.

The IBM Tivoli Monitoring for Transaction Performance agent will consume the

parent correlator that is passed in. If a new correlator was requested, the IBM

Tivoli Monitoring for Transaction Performance agent will also return a new

correlator, put it in the buffer, and set the correlator returned flag.

Working with Java applications: ARM Version 2

IBM Tivoli Monitoring for Transaction Performance provides a Java Native

Interface (JNI) implementation for ARM Version 2, so that ARM Version 2 calls can

be made from Java applications. The JNI will translate them into C calls using the

ARM Version 2 standard. This is less complex, but also less powerful than the Java

bindings that are included in ARM Version 4.

Note: If you use ARM Version 4 Java bindings, IBM Tivoli Monitoring for

Transaction Performance uses a JNI implementation to convert them to C as

well.

Using the JNI to make calls to a native method potentially compromises the Java

environment as follows:

Figure 13. ARM Version 2: Consuming transaction correlators

Chapter 5. ARM Version 2: Tracing a transaction and writing context data 29

Page 44: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

v Java applications could be lost since the native method are operating system

dependent. Tivoli Monitoring for Transaction Performance provides the JNI

implementation for all platforms that are supported as management agents.

v There could be a security risk, since it might permit access to host operating

system services. IBM Tivoli Monitoring for Transaction Performance handles this

by requiring that the management agent be installed on the machine where calls

are being made. See, for the mechanism for making the calls.

To give your Java application access to the JNI, add the appropriate ARM .jar file

to the class path on the Management Agent machine where your

ARM-instrumented application will run. For ARM Version 2 calls, this is:

Windows

%MA\lib\armjni.jar

UNIX

$MA/lib/armjni.jar

Making ARM API Calls From Your Java Classes

You can make ARM Version 2 calls from any of your Java Classes by doing the

following:

1. Code an import statement for the class ARMClass.

2. Make the ARM API calls, using the standard C calling convention, with the

following modifications:

v For each of the ARM API functions, add the ARMClass class to the function

name.

v All of the ARM API calls have an argument called data which must be

written as zero (0). This argument is a char pointer and in Java, a char

pointer must be a string. For example:

int start_handle= ARMClass.arm_start(getid_handle,0,"0",0);

Java examples for performing ARM Version 2 instrumentation

This section contains Java examples corresponding to the steps involved in

preforming ARM Version 2 instrumentation.

Registering your application

Using Java:

package com.tivoli.tapm.armjni;

/** Tells ARM you have an application/user pair that wishes to make ARM calls.

* @param appName Name of the application (128 ASCIIZ)

* @param userId user name (128 ASCIIZ) Specifying "*" for the username tells

* the IBM Tivoli Monitoring for Transaction Performance ARM engine to use

* the user ID that the process is currently running under.

* @return application ID to use for future armGetId calls.

**/

public static native int armInit(String applName, String userId);

int appl_id;

com.tivoli.tapm.armjni.ArmJni.armInit("Websphere","*");

/**

*Registers an application Identified as "Websphere" running as whatever

*user on the local machine started the engine.

*/

30 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 45: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Registering your transaction

Using Java:

package com.tivoli.tapm.armjni;

/** Tells ARM you have a unique class of transaction you wish to monitor

* for your application

* @param appId returned by a previous armInit call

* @param tranName name of the transaction (2k ASCIIZ)

* @param tranDetail Description of the transcation (128 ASCIIZ)

* @param metricInfo array of metric info description objects.

* @return transClassID a unique ID used to identify this transaction.

**/

public static native int armGetId(int applId, String tranName,

String tranDetail,MetricInfo[] metricInfoSet);

int appl_id;

int tran_id;

appl_id = ArmJni.armInit("Websphere/Cell/Node/Server","*");

tran_id = ArmJni.armGetId(appl_id,"Foo.bar(String);","",null);

Starting and stopping a transaction

Using Java:

package com.tivoli.tapm.armjni;

class ArmJni;

/**

* arm_start indicates that an instance of a transaction has begun execution.

* Contrast this with arm_getid, which defines the name of the transaction

* class during initialization, but doesn’t actually indicate that a

* transaction is executing. The identifier returned on the arm_getid call

* is passed as a parameter on arm_start so an agent knows which type of

* transaction is starting. There can be any number of instances of the

* same transaction class executing simultaneously on the same system.

* To identify each one, the return code from arm_start is a unique handle

* generated by the agent. This handle is unique within a system

* across all instances of all transactions of all applications.

* The transaction instance is the fundamental entity that the ARM API

* measures. The parent correlator is passed within the data paramater,

* and the new correlator is returned in place of the parent correlator.

* @param transclassid returned from a previous ARM getid call

* @param MetricData metric data as described in a previous ARM getid call.

* @param correlator input correlator. <B>Must not be null.</B>

**/

public static int armStartWithCorrelator(int tranId,

MetricData[] metricDataSet,

Correlator correlator ) ;

/**

* arm_stop indicates that an instance of a transaction has completed.

* The handle returned on the arm_start call is passed as a parameter

* to indicate which instance of a transaction is ending.

* arm_stop can be issued from adifferent thread or process

* from which the arm_start was issued.

* @param transaction id return from a previous ARM start call.

* @param status The transaction status is also passed, and there

* are three possible values.

* ARM_GOOD - the transaction completed normally and the intended service

* was performed.

* ARM_ERROR - the transaction completed with an error (so the intended

* service was not performed).

* ARM_ABORT - the transaction was unable to complete. An example

* of a reason for an abort would be a

Chapter 5. ARM Version 2: Tracing a transaction and writing context data 31

Page 46: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

* time-out error from a communications stack.

* @return 0 on success.

**/

public static int armStop(int tranId, int status,

MetricData[] metricDataSet)

int appl_id;

int tran_id;

int startHandle;

appl_id = ArmJni.armInit("Websphere/Cell/Node/Server","*");

tran_id = ArmJni.armGetId(appl_id,"Foo.bar(String);","",null);

startHandle = ArmJni.armStartWithCorrelator(tran_id,null,null);

ArmJni.armStop(startHandle,ArmJni.ARM_GOOD,null);

Adding additional metrics for a transaction instance: ARM Version 2

You can further supplement this basic information by adding requirements to the

instrumentation of the application. For example, with the notification about the

start of an overall request serviced by the application, pass in additional metrics

about the type of request and how it is related to the business objects the

application is servicing.

This provides information on the type of requests the application is servicing and

enables the user to:

v Know how long each type of request is taking.

v Manage the types of requests differently based upon configurable Management

policies.

v Place thresholds upon specific requests based upon different Service Level

Agreements.

v Take corrective actions in the event that a request is slowing or not working at

all.

32 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 47: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Chapter 6. Problem determination and debugging ARM

instrumentation

This section provides hints and tips on how to debug problems that might arise

when adding ARM instrumentation calls to an application.

With ARM Version 2 instrumentation in C programs

This section details some problems that might occur when developing a C

application that contains ARM Version 2 instrumentation.

Table 6. ARM Version 2 instrumentation in C problem determination

Problem Solution

Problems with your

ARM

instrumentation, or

the IBM Tivoli

Monitoring for

Transaction

Performance agent

First test the agent against a known and working application that

has been ARM-instrumented. The armtest application is provided

for this purpose. If you find that the armtest application works

with your IBM Tivoli Monitoring for Transaction Performance

implementation and produces valid data, the problem is in your

ARM instrumentation. If the armtest application does not produce

data in the IBM Tivoli Monitoring for Transaction Performance

product, the problem is in IBM Tivoli Monitoring for Transaction

Performance.

The armtest program is available in source and compiled form.http://publib.boulder.ibm.com/infocenter/tiv3help

/index.jsp?topic=/com.ibm.itmtp.doc/armtest.zip

Look at the return codes that are produced when the armtest

application makes ARM calls.

33

Page 48: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

34 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 49: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Chapter 7. Performance considerations

When adding instrumentation to an application, consider the overhead that will be

incurred by having the instrumentation present. This section discusses two

methods that enable the user of your application to control the instrumentation

and diagnostic detail level being used. This enables them to control the

performance overhead incurred by monitoring the application.

Instrumentation detail control

One method of controlling the overhead is to make the number of points

monitored in your application configurable. Using instrumentation detail control

you provide a configuration value that enables the application user to turn the

instrumentation to different levels.

Example Levels:

Off No instrumentation will occur.

Entry/Exit into the application only

This monitors only entry and exit points for the application, not entry and

exit points for a function. That is, monitor only when a thread starts or

when and API call is made to another application.

Medium Trace Level

Only component level entry and exit points are traced.

High Trace Level

All non-trivial function level entry and exit point inside functions are

traced.

Have your application instrument all non-trivial function entry and exit points.

Then, check the configuration value of each function and abort the instrumentation

points of those that do not meet the specified level, before gathering information to

make the transaction start call.

Diagnostic information control

Another method of controlling the overhead is to make the amount of metric

information passed for each ARM call configurable. Gathering diagnostic

information and the passing of all the metric information to the ARM agent can be

an expensive process due to the volume of data and frequency of its passing.

Enabling the user to specify how much diagnostic information is gathered enables

the user to balance the ease of debugging a problem with the base instrumentation

overhead.

Example levels:

Off No diagnostic information is gathered.

Low Diagnostic information

Only a small amount of information is gathered.

Medium Trace Level

Only information that is of reasonable size and reasonably fast to gather is

done.

35

Page 50: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

High Trace Level

All information relevant to this transaction is gathered.

36 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 51: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Chapter 8. Instrumenting generic windows using Rational

Robot

Application performance is measured using the Simplified Wrapper for ARM

(SWARM) library. SWARM makes Application Response Measurement (ARM)

engine function calls. It provides a simplified layer for the Generic Windows GUI

or VU application to interface with the ARM engine by reducing the number of

function calls, parameters, and automatic correlator tracking. The SWARM library

function calls are inserted into the Robot GUI or VU recorded script. When the

script plays, the SWARM function calls measure the time to:

v Run a transaction.

v Run the subtransactions comprising the transaction.

Note: For a complete list of libSWARM function calls, see Appendix B, “libSWARM

function calls,” on page 57.

This section describes a procedure for creating a Generic Windows recording for

collecting availability and performance data. The recording is created using

Rational Robot and then the SWARM library function calls are inserted manually.

Robot supports two types of recording mechanisms:

GUI Captures Microsoft Windows mouse and keyboard events and runs

visually on a screen.

VU Captures network level events created by a browser like Internet Explorer

and runs them with out a visual interface.

Measuring performance of a transaction

A transaction can be made up of multiple subtransactions. Measuring the

performance of a transaction is done by placing timer start and timer stop function

calls around the transaction and its individual subtransactions.

Note: The examples in the section are Rational Robot VU scripts.

Simple transaction measurement

A simple transaction, a transaction that does not contain subtransactions, is

measured by:

v Passing the recording name to the ARM engine using a SWARM library

function.

v Starting the timer using a SWARM library start function call before the

transaction begins.

v Placing an ARM timer stop function call after the transaction completes.

For example:

/* start transaction timer */

arm_start_with_name_rt("BusLoginOp")

...

application transaction

...

/* stop transaction timer */

arm_stop_rt()

37

Page 52: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Compound transaction measurment

To measure the performance of a compound transaction, or a transaction containing

subtransactions, the individual subtransactions must be wrapped by a root timer. A

root timer is the timer that marks the start and stop of a compound transaction.

The overall run time of the compound transaction is larger then the sum of the run

times of the subtransactions, because it uses separate timer marks. The time

difference is dependent on the amount of work done between the root start and

root stop timers and the start timer associated with the first subtransaction and the

stop timer associated with the final subtransaction.

The following example shows a transaction with multiple subtransactions.

/* start root timer measuring entire transaction */

arm_start_with_name_rt("OrderPartsOp")

/* start timer for subtransaction 1 */

arm_start_with_name_rt("OrderPartsOp_1")

...

application subtransaction 1

...

/* stop timer for subtransaction 1 */

arm_stop_rt()

/* start timer for subtransaction 2 */

arm_start_with_name_rt("OrderPartsOp_2")

...

application subtransaction 2

...

/* stop timer for subtransaction 2 */

arm_stop_rt()

/* start timer for subtransaction 3 */

arm_start_with_name_rt("OrderPartsOp_3")

...

application subtransaction 3

...

/* stop timer for subtransaction 3 */

arm_stop_rt()

/* stop transaction’s root timer */

arm_stop_rt()

Each transaction recording must be organized in the root and child hierarchy, or

the transactions are not measured correctly. In the following example, the simple

transactions are not nested under a compound transaction and their run times will

be recorded separately, not as part of a cumulative procedure. Here is an example

of an incorrect hierarchy:

/* start timer for transaction 1 */

arm_start_with_name_rt("OrderPartsOp")

...

application transaction 1

...

/* stop timer for transaction 1 */

arm_stop_rt()

/* start timer for transaction 2 */

arm_start_with_name_rt("CheckInventory")

...

application transaction 2

...

/* stop timer for transaction 2 */

arm_stop_rt()

38 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 53: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Inserting ARM timers in business processes

For Generic Windows GUI and VU recordings, you can replace Rational timer

function calls with IBM Tivoli Monitoring for Transaction Performance ARM

timers. For Generic Windows GUI recordings, replace Rational GUI timers with

IBM Tivoli Monitoring for Transaction Performance ARM timers. For Generic

Windows VU recordings, insert IBM Tivoli Monitoring for Transaction Performance

ARM timers around each transaction Web page and Web page items like loaded

HTML, Javascript, or GIF files. Robot VU scripts also can add the ARM correlator

HTTP header to all HTTP requests.

For a complete list of libSWARM function calls, see Appendix B, “libSWARM

function calls,” on page 57.

Inserting IBM Tivoli Monitoring for Transaction Performance

ARM timers in a Generic Windows GUI script

1. Add Rational GUI timers when recording the script using the timer start and

stop icons on the recording tool bar.

2. Convert the Rational GUI timers to Generic Windows GUI ARM timers by

editing the script and manually replacing the Robot StartTimer and StopTimer

function calls with arm_start_rt and arm_stop_rt function calls.

Example

The following is a Robot script before ARM timers have been inserted. The timer

calls are highlighted in bold.

Sub Main

Dim Result As Integer

’Initially Recorded: 11/29/2004 5:45:07 PM

’Script Name: IBMTest

StartTimer "IBMSite"

StartTimer "HomePage"

StartBrowser "http://www.ibm.com", "WindowTag=WEBBrowser"

StopTimer "HomePage"

StartTimer "ProductsPage"

Window SetContext, "WindowTag=WEBBrowser", ""

Browser NewPage,"HTMLTitle=IBM United States",""

HTMLLink Click, "HTMLText=Products", ""

StopTimer "ProductsPage"

StartTimer "ServicesPage"

Browser NewPage,"HTMLTitle=IBM Products - United States",""

HTMLLink Click, "HTMLText=Services & solutions", ""

StopTimer "ServicesPage"

StartTimer "SupportPage"

Browser NewPage,"HTMLTitle=IBM Services & solutions - United States",""

HTMLTable Click, "Index=6", "Row=1;Col=8"

HTMLLink Click, "HTMLText=Support & downloads", ""

StopTimer "SupportPage"

Window CloseWin, "", ""

StopTimer "IBMSite"

End Sub

The following is a Robot script with the ARM calls inserted. The inserted calls are

highlighted in bold.

Chapter 8. Instrumenting generic windows using Rational Robot 39

Page 54: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

The arm_start_using_name_rt function is used instead of arm_start_rt so that the

transaction and its subtransactions use descriptive names. If arm_start_rt is used

libSWARM automatically generates a name for each transaction. The generated

name is formatted as follows:

TransactionName __LevelX _StepY

Where:

TransactionName

Is the name of the recorded test.

LevelX

Is the ARM nesting level.

StepY Is the subtransaction number within the nesting level.

For example, AccountLoginTest__Level2 _Step4 is the fourth subtransaction on the

second level of the recorded AccountLoginTest test.

’TMTP: Added Header

’$include "SWARM.sbh"

Sub Main

Dim Result As Integer

’Initially Recorded: 11/29/2004 5:45:07 PM

’Script Name: IBMTest

’TMTP: Added ARM base name and overall start

arm_start_with_name_rt("IBMTest")

’TMTP: Added ARM start for HomePage

arm_start_with_name_rt("HomePage")

StartBrowser "http://www.ibm.com", "WindowTag=WEBBrowser"

’TMTP: Added ARM stop

arm_stop_rt

’TMTP: Added ARM start for ProductsPage

arm_start_with_name_rt("ProductsPage")

Window SetContext, "WindowTag=WEBBrowser", ""

Browser NewPage,"HTMLTitle=IBM United States",""

HTMLLink Click, "HTMLText=Products", ""

’TMTP: Added ARM stop

arm_stop_rt

’TMTP: Added ARM start for ServicePage

arm_start_with_name_rt("ServicePage")

Browser NewPage,"HTMLTitle=IBM Products - United States",""

HTMLLink Click, "HTMLText=Services & solutions", ""

’TMTP: Added ARM stop

arm_stop_rt

’TMTP: Added ARM start for SupportPage

arm_start_with_name_rt("SupportPage")

Browser NewPage,"HTMLTitle=IBM Services & solutions - United States",""

HTMLTable Click, "Index=6", "Row=1;Col=8"

HTMLLink Click, "HTMLText=Support & downloads", ""

’TMTP: Added ARM stop

arm_stop_rt

Window CloseWin, "", ""

’TMTP: Added ARM stop for overall transaction

arm_stop_rt

End Sub

Inserting IBM Tivoli Monitoring for Transaction Performance

ARM timers in a Generic Windows VU script

When recording a Robot VU transaction:

40 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 55: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

v Use Robot VU timing marks to distinguish when a Web page starts loading and

when it is complete. The timing marks are added using the Robot VU recording

toolbar.

v Ensure that all HTTP requests between timing marks correspond to items on the

Web page.

v To time only the Web page, replace the VU timing marks with libSWARM start

and stop function calls.

v To time the Web page and individual items on the page, add libSWARM start

and stop function calls around the page and each individual HTTP item request.

v Insert the HTTP ARM header for each HTTP item request so the requests can be

correlated through the entire end to end business transaction on all downstream

servers being monitored by IBM Tivoli Monitoring for Transaction Performance

(using either Tivoli Monitoring for Transaction Performance instrumentation or

custom generic ARM instrumentation in an application).

Note: For a list of the libSWARM function calls, see Appendix B, “libSWARM

function calls,” on page 57.

Example

The follow is a section of a Generic Window VU script before ARM calls have been

inserted. The complete script would open the www.ibm.com Web site.

/*

->-> Session File Information <-<-

Created: Mon Nov 29 17:51:49 2004

Name: C:\Documents and Settings\Administrator\My Documents

\RobotProjs\pirates\TestDatastore\DefaultTestScriptDatastore

\TMS_Sessions\IBMTestV.wch

Type: Rational Robot - API

(with Wininet HTTP)

(with Winsock1 Data)

*/

#include VU.h

{

push Http_control = HTTP_PARTIAL_OK | HTTP_CACHE_OK | HTTP_REDIRECT_OK;

push Timeout_scale = 200; /* Set timeouts to 200% of maximum response time */

push Think_def = "LR";

Min_tmout = 120000; /* Set minimum Timeout_val to 2 minutes */

push Timeout_val = Min_tmout;

DP1 = datapool_open("VuIEIbmCom1Step");

datapool_fetch(DP1);

start_time ["Overall"];

start_time ["IbmComPage"];

push Think_avg = 0;

www_ibm_com = http_request ["VuIEIbm~001"] "www.ibm.com:80",

HTTP_CONN_DIRECT,

"GET / HTTP/1.1\r\n"

"Accept: */*\r\n"

"Accept-Language: en-us\r\n"

"Accept-Encoding: gzip, deflate\r\n"

"User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR"

" 1.1.4322)\r\n"

"Host: www.ibm.com\r\n"

"Connection: Keep-Alive\r\n"

"Cookie: w3ibmProfile=2001111016254301611275733917|gAME|897|BNT|null\r\n"

"\r\n";

set Server_connection = www_ibm_com;

Chapter 8. Instrumenting generic windows using Rational Robot 41

Page 56: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

http_header_recv ["VuIEIbm~002"] 302; /* Moved Temporarily */

http_nrecv ["VuIEIbm~003"] 100 %% ; /* Internally Generated */

set Think_avg = 71;

/* Keep-Alive request over connection www_ibm_com */

http_request ["VuIEIbm~004"]

"GET /us/ HTTP/1.1\r\n"

"Accept: */*\r\n"

"Accept-Language: en-us\r\n"

"Accept-Encoding: gzip, deflate\r\n"

"User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR"

" 1.1.4322)\r\n"

"Host: www.ibm.com\r\n"

"Connection: Keep-Alive\r\n"

"Cookie: w3ibmProfile=2001111016254301611275733917|gAME|897|BNT|null\r\n"

"\r\n";

{ string SgenURI_003; }

SgenURI_003 = _reference_URI; /* Save "Referer:" string */

http_header_recv ["VuIEIbm~005"] 200; /* OK */

http_nrecv ["VuIEIbm~006"] 100 %% ; /* 20137 bytes */

set Think_avg = 371

.

.

.

.

.

.

www_ibm_com_23 = http_request ["VuIEIbm~032"] "www.ibm.com:80",

HTTP_CONN_DIRECT,

"GET /us/images/2005/01/7_012505_CHQ_HelpDesk_Class.gif HTTP/1.1\r\n"

"Accept: */*\r\n"

"Referer: " + SgenURI_003 + "\r\n"

/* "Referer: http://www.ibm.com/us/" */

"Accept-Language: en-us\r\n"

"Accept-Encoding: gzip, deflate\r\n"

"If-Modified-Since: Fri, 28 Jan 2005 20:19:55 GMT\r\n"

"If-None-Match: \"142022-1f75-41fa9e6b\"\r\n"

"User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR"

" 1.1.4322)\r\n"

"Host: www.ibm.com\r\n"

"Connection: Keep-Alive\r\n"

"Cookie: w3ibmProfile=2001111016254301611275733917|gAME|897|BNT|null; ms"

"p=isEnabled\r\n"

"\r\n";

set Server_connection = www_ibm_com_23;

http_header_recv ["VuIEIbm~033"] 304; /* Not Modified */

http_nrecv ["VuIEIbm~034"] 100 %% ; /* 8053 bytes - From Cache */

http_disconnect(www_ibm_com_23);

set Server_connection = www_ibm_com_17;

http_header_recv ["VuIEIbm~035"] 304; /* Not Modified */

http_nrecv ["VuIEIbm~036"] 100 %% ; /* 11066 bytes - From Cache */

http_disconnect(www_ibm_com_17);

42 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 57: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

stop_time ["IbmComPage"];

stop_time ["Overall"];

pop [Think_def, Think_avg, Timeout_val, Timeout_scale];

pop Http_control;

}

The following is the same Generic Windows script after the ARM timers have been

inserted. The complete script would open the www.ibm.com Web site. The ARM

timers are highlighted in bold.

/*

->-> Session File Information <-<-

Created: Mon Nov 29 17:51:49 2004

Name: C:\Documents and Settings\Administrator\My Documents

\RobotProjs\pirates\TestDatastore\DefaultTestScriptDatastore

\TMS_Sessions\IBMTestV.wch

Type: Rational Robot - API

(with Wininet HTTP)

(with Winsock1 Data)

*/

#include VU.h

/*TMTP: Added Header*/

#include "SWARM.h"

{

/*TMTP: Added ARM Variables*/

string arm_corr;

string http_corr;

push Http_control = HTTP_PARTIAL_OK | HTTP_CACHE_OK | HTTP_REDIRECT_OK;

push Timeout_scale = 200; /* Set timeouts to 200% of maximum response time */

push Think_def = "LR";

Min_tmout = 120000; /* Set minimum Timeout_val to 2 minutes */

push Timeout_val = Min_tmout;

DP1 = datapool_open("VuIEIbmCom1Step");

datapool_fetch(DP1);

/*TMTP: Added ARM start for Overall Transaction */

arm_start_using_name_rt("VuIEIbmCom1Step_Overall");

/*TMTP: Added ARM start for www.ibm.com Web page */

arm_start_using_name_rt("IbmComPage");

push Think_avg = 0;

/*TMTP: Added ARM start*/

arm_start_using_name_rt("http://www.ibm.com:80/");

/*TMTP: Copy ARM correlator*/

arm_copy_correlator_hex_rt(&arm_corr);

/*TMTP: Create ARM correlator header*/

sprintf(&http_corr, "ARM_CORRELATOR: %s", arm_corr);

www_ibm_com = http_request ["VuIEIbm~001"] "www.ibm.com:80",

HTTP_CONN_DIRECT,

"GET / HTTP/1.1\r\n"

"Accept: */*\r\n"

"Accept-Language: en-us\r\n"

"Accept-Encoding: gzip, deflate\r\n"

"User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR"

" 1.1.4322)\r\n"

"Host: www.ibm.com\r\n"

"Connection: Keep-Alive\r\n"

"Cookie: w3ibmProfile=2001111016254301611275733917|gAME|897|BNT|null\r\n"

Chapter 8. Instrumenting generic windows using Rational Robot 43

Page 58: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

/*TMTP: Added ARM Correlator to HTTP Header*/

+ http_corr + "\r\n"

"\r\n";

/*TMTP: Check HTTP return code status and fail if unavailable*/

if (www_ibm_com <= 0)

{

/*TMTP: Failing all unterminated transactions*/

arm_stop_failed_rt(); /* for page item ["VuIEIbm~001"] */

arm_stop_failed_rt(); /* for www.ibm.com Web page */

arm_stop_failed_rt(); /* for overall transaction */

/*TMTP: Exit script*/

script_exit("");

}

set Server_connection = www_ibm_com;

http_header_recv ["VuIEIbm~002"] 302; /* Moved Temporarily */

http_nrecv ["VuIEIbm~003"] 100 %% ; /* Internally Generated */

set Think_avg = 71;

/* Keep-Alive request over connection www_ibm_com */

/*TMTP: Added ARM stop for page item ["VuIEIbm~001"] */

arm_stop_rt();

/*TMTP: Added ARM start*/

arm_start_using_name_rt("http://www.ibm.com:80/us/");

/*TMTP: Copy ARM correlator*/

arm_copy_correlator_hex_rt(&arm_corr);

/*TMTP: Create ARM correlator header*/

sprintf(&http_corr, "ARM_CORRELATOR: %s", arm_corr);

http_request ["VuIEIbm~004"]

"GET /us/ HTTP/1.1\r\n"

"Accept: */*\r\n"

"Accept-Language: en-us\r\n"

"Accept-Encoding: gzip, deflate\r\n"

"User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR"

" 1.1.4322)\r\n"

"Host: www.ibm.com\r\n"

"Connection: Keep-Alive\r\n"

"Cookie: w3ibmProfile=2001111016254301611275733917|gAME|897|BNT|null\r\n"

/*TMTP: Added ARM Correlator to HTTP Header*/

+ http_corr + "\r\n"

"\r\n";

{ string SgenURI_003; }

SgenURI_003 = _reference_URI; /* Save "Referer:" string */

http_header_recv ["VuIEIbm~005"] 200; /* OK */

http_nrecv ["VuIEIbm~006"] 100 %% ; /* 20137 bytes */

set Think_avg = 371;

/*TMTP: Added ARM stop for page item ["VuIEIbm~004"] */

arm_stop_rt();

.

.

.

.

.

.

.

/*TMTP: Added ARM start*/

arm_start_using_name_rt("http://www.ibm.com:80/us/

images/2005/01/7_012505_CHQ_HelpDesk_Class.gif");

/*TMTP: Copy ARM correlator*/

arm_copy_correlator_hex_rt(&arm_corr);

44 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 59: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

/*TMTP: Create ARM correlator header*/

sprintf(&http_corr, "ARM_CORRELATOR: %s", arm_corr);

www_ibm_com_23 = http_request ["VuIEIbm~032"] "www.ibm.com:80",

HTTP_CONN_DIRECT,

"GET /us/images/2005/01/7_012505_CHQ_HelpDesk_Class.gif HTTP/1.1\r\n"

"Accept: */*\r\n"

"Referer: " + SgenURI_003 + "\r\n"

/* "Referer: http://www.ibm.com/us/" */

"Accept-Language: en-us\r\n"

"Accept-Encoding: gzip, deflate\r\n"

"If-Modified-Since: Fri, 28 Jan 2005 20:19:55 GMT\r\n"

"If-None-Match: \"142022-1f75-41fa9e6b\"\r\n"

"User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR"

" 1.1.4322)\r\n"

"Host: www.ibm.com\r\n"

"Connection: Keep-Alive\r\n"

"Cookie: w3ibmProfile=2001111016254301611275733917|gAME|897|BNT|null; ms"

"p=isEnabled\r\n"

/*TMTP: Added ARM Correlator to HTTP Header*/

+ http_corr + "\r\n"

"\r\n";

/*TMTP: Check HTTP return code status and fail if unavailable*/

if (www_ibm_com_23 <= 0)

{

/*TMTP: Failing all unterminated transactions*/

arm_stop_failed_rt(); /* for page item ["VuIEIbm~032"] */

arm_stop_failed_rt(); /* for www.ibm.com Web page */

arm_stop_failed_rt(); /* for overall transaction */

/*TMTP: Exit script*/

script_exit("");

}

set Server_connection = www_ibm_com_23;

http_header_recv ["VuIEIbm~033"] 304; /* Not Modified */

http_nrecv ["VuIEIbm~034"] 100 %% ; /* 8053 bytes - From Cache */

http_disconnect(www_ibm_com_23);

set Server_connection = www_ibm_com_17;

http_header_recv ["VuIEIbm~035"] 304; /* Not Modified */

http_nrecv ["VuIEIbm~036"] 100 %% ; /* 11066 bytes - From Cache */

http_disconnect(www_ibm_com_17);

/*TMTP: Added ARM stop for page item ["VuIEIbm~032"] */

arm_stop_rt();

/*TMTP: Added ARM stop for www.ibm.com Web page */

arm_stop_rt();

/*TMTP: Added ARM stop for Overall Transaction */

arm_stop_rt();

pop [Think_def, Think_avg, Timeout_val, Timeout_scale];

pop Http_control;

}

Chapter 8. Instrumenting generic windows using Rational Robot 45

Page 60: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

46 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 61: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Chapter 9. Alternate language bindings

The ARM API includes bindings for the C, C++, and Java languages, but can be

called from any language.

If you are using a language other than C, C++, or Java, you should call the ARM

API as an external C function from your programming language.

Making ARM API calls from PowerBuilder applications

This section uses a PowerBuilder application as an example of how to call the

ARM API using a language other than C or C++.

PowerBuilder provides its own development language called PowerScript. You can

make all of the ARM API calls in PowerScript following its syntax rules. Here is an

example of how the ARM API calls can be made using a PowerBuilder script. After

each call this script pops up a window to display the handle. This can be useful

during initial development and testing.

arm_application = arm_init("new_account", "*",0,0,0)

messagebox("arm_init", string(arm_application))

arm_transaction = arm_getid(arm_application, "open", "", 0,0,0)

messagebox("arm_getid", string(arm_transaction))

arm_start_val = arm_start(arm_transaction, 0,0,0)

t = getapplication()

messagebox("arm_start", string(arm_start_val))

t.af_opencustomer(s)

arm_stop = arm_stop(arm_start_val, 0,0,0,0)

messagebox("arm_stop", string(arm_stop))

arm_end_val = arm_end(arm_transaction,0,0,0)

messagebox("arm_transaction", string(arm_end_val))

For the ARM function calls to be resolved, you must declare the ARM API

functions to PowerBuilder as Global External Functions.

In a PowerBuilder window click Declare on the toolbar and open the Global

External Function editor. Fill in the ARM function prototypes as shown in the

following example.

Note: These declarations are case sensitive. Everything must be in lowercase.

function long arm_init(string name,string user_id,long flag,long data,long size)

library "libarm32.dll"

function long arm_getid(long id,string name,string detail,long flag,long data,

long size) library "libarm32.dll"

function long arm_start(long id,long flag,long data,long size) library

"libarm32.dll"

function long arm_update(long handle,long flag,long data,long size) library

"libarm32.dll"

function long arm_stop(long handle,long status,long flag,long data,long size)

47

Page 62: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

library "libarm32.dll"

function long arm_end(long id,long flag,long data,long size) library "libarm32.dll"

When the Powerbuilder application runs, the ARM calls that it makes are resolved

in the external function definitions and result in ARM API calls being made to the

ARM client agent.

Making ARM API calls from Visual Basic applications

There are two steps involved in using ARM API calls from a Visual Basic

application:

1. Declare the ARM API functions to Visual Basic as DLL procedures by loading

the file form1.frm from the ARM Version 2 Software Developer’s Kit (SDK) into

your Visual Basic development environment.

2. Call the DLL procedures in your Visual Basic program.

Using the ARM Version 2 Software Developer’s Kit

The ARM Software Developer’s Kit (SDK) enables you to build and run application

programs that are instrumented for ARM, even if you do not yet have an ARM

agent.

You can download a free copy of the SDK from http://www.opengroup.org/arm/

The SDK includes the header and library files necessary to compile an

ARM-instrumented application that is written in C or C++, and a no-operation

(NOP) runtime library.

Note: The no-operation (NOP) runtime library is only available in ARM Version 2

SDK.

Figure 14. Resolving the ARM calls as PowerBuilder external functions

48 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 63: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

The NOP library receives the ARM API calls that your application makes and

returns a handle of zero (0). When you install an IBM Tivoli Monitoring for

Transaction Performance agent, replace the NOP with the IBM Tivoli Monitoring

for Transaction Performance run-time library.

If you are developing an ARM-instrumented application with the SDK, test the

application with the IBM Tivoli Monitoring for Transaction Performance ARM

agent before putting the application into production.

The SDK NOP library always returns a zero (0) when your application makes an

ARM API call, even if the call is invalid. In contrast, the IBM Tivoli Monitoring for

Transaction Performance ARM agent returns error codes in the handle.

For example, if you make an arm_stop call in your program for a transaction that

has not started, the SDK agent returns a zero (0), but the IBM Tivoli Monitoring for

Transaction Performance agent recognizes that you made an arm_stop call for

which there was no corresponding arm_start call.

Figure 15. Using the ARM SDK to compile and link a Windows program.

Chapter 9. Alternate language bindings 49

Page 64: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

50 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 65: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Appendix A. Tracking a transaction into a J2EE application

server

There are multiple mechanisms for passing correlators from ARM-instrumented

applications to J2EE-instrumented application servers. For more information on

correlators, see “Correlating transactions: ARM Version 2” on page 21. To use the

IBM Tivoli Monitoring for Transaction Performance infrastructure to monitor

transactions going from your ARM-instrumented applications to J2EE-instrumented

servers, use HTTP, Java Message Service (JMS), Simple Object Access Protocol

(SOAP) or Resource Manager Interface (RMI) to pass correlators to the application

server. This section describes these four methods.

The examples in this section use C++.

Using HTTP

To pass a correlator to a J2EE-instrumented Application server from your

ARM-instrumented application, modify the HTTP request header to add an

element in Key:Value format.

Where:

Key Must be set to ARMCorrelator.

Value Must be set to the hex string representation of the correlator.

The application server that receives the HTTP requests looks for the

ARMCorrelator key in the HTTP header elements and begins monitoring the

transaction in the J2EE server.

Example:

Socket socket = new Socket(host,port_number);

OutputStream os = socket.getOutputStream();

boolean autoflush = true;

PrintWriter out = new PrintWriter(os, autoflush);

out.println("GET " + uri + " HTTP/1.1");

out.println("Host: " + host);

out.println("Connection: Close");

out.println("ARMCorrelator: " + Correlator.toHexString(httpCorrelator.getBytes()));

Note: Use the method call ArmJni.armGetCorrelatorKey() to get the key string.

ArmJni.armGetCorrelatorKey() returns ARM_CORRELATOR for the IBM

Tivoli Monitoring for Transaction Performance Version 5.3 product. In earlier

versions of the product, ArmJni.armGetCorrelatorKey() might return

ARMCorrelator.

Using JMS

To pass a correlator to a J2EE-instrumented Application server from your

ARM-instrumented application, add the ARMCorrelator parameter and the hex

string for the correlator to the message being sent.

Where:

51

Page 66: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Property Name

Must be set to ARMCorrelator.

Value Must be set to the hex string representation of the correlator.

If the application server receives a message with an ARMcorrelator parameter, the

embedded correlator is used to begin monitoring the transaction within the J2EE

server.

Example:

message.setStringProperty("ARMCorrelator",Correlator.toHexString

(jmsCorrelator.getBytes()));

Note: Use the method call ArmJni.armGetCorrelatorKey() to get the key string.

ArmJni.armGetCorrelatorKey() returns ARM_CORRELATOR for the IBM

Tivoli Monitoring for Transaction Performance Version 5.3 product. In earlier

versions of the product, ArmJni.armGetCorrelatorKey() might return

ARMCorrelator.

See the JMSCorrelatorPassing.java file under the JMSExample directory to see

complete source code. These files are located at the following Web site:

http://publib.boulder.ibm.com/infocenter/tiv3help/index.jsp?topic=

/com.ibm.itmtp.doc/correlator_passing.zip

Using SOAP

To pass a correlator from your ARM-instrumented application to a

J2EE-instrumented WebSphere Application server, modify the SOAP header to add

a header element that contains the correlator. To do this, a SOAP Handler needs to

be implemented.

Note: J2EE-instrumented Weblogic Application servers do not support this

functionality.

The application server that receives the SOAP message looks for the required

element in the SOAP header, and if it is found, the embedded correlator is used to

activate monitoring the transaction within the J2EE server.

Example:

protected static final String REQMETRICS_NS_URI = "http://websphere.ibm.com";

protected static final String REQMETRICS_PREFIX = "reqmetrics";

protected static final String REQMETRICS_ELEMENT = "correlator";

protected final static String REQMETRICS_ACTOR_URI = "reqmetricsURI";

/**

* Add correlator to outgoing message.

*/

public boolean handleRequest(MessageContext mc) {

soapTxn.start();

soapCorrelator = soapTxn.getCorrelator();

correlatorHexString = Correlator.toHexString(soapCorrelator.getBytes());

addCorrelator((SOAPMessageContext)mc);

return true;

}

/**

* Add correlator to the SOAP message header

52 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 67: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

*/

public void addCorrelator(SOAPMessageContext mc) {

try {

SOAPMessage msg = mc.getMessage();

SOAPPart part = msg.getSOAPPart();

SOAPEnvelope envelope = part.getEnvelope();

SOAPHeader header = envelope.getHeader();

if (header == null) {

header = envelope.addHeader();

}

// create new header element, add correlator to it

Name temp_name = envelope.createName(REQMETRICS_ELEMENT,

REQMETRICS_PREFIX,

REQMETRICS_NS_URI);

SOAPHeaderElement she = header.addHeaderElement(temp_name);

// set element value is the correlator

she.addTextNode(correlatorHexString);

she.setActor(REQMETRICS_ACTOR_URI);

} catch (Exception e) {

e.printStackTrace();

}

}

See the SOAPClientHandler.java file under the SOAPExample/src directory to see

a complete example of a SOAP handler. These files are located at the following

Web site:

http://publib.boulder.ibm.com/infocenter/tiv3help/index.jsp?topic=

/com.ibm.itmtp.doc/correlator_passing.zip

Using RMI

WebSphere Application Server Version 4:

To pass a correlator to a J2EE-instrumented WebSphere Application Server (WAS)

Version 4 from an ARM-instrumented application, an RMI interceptor needs to be

in place to add the correlator to RMI requests. The WebSphere Application Server

Version 4 RMI interceptor must extend com.ibm.CORBA.iiop.RequestInterceptor.

The WebSphere Application Server Version 4 server that receives the RMI-IIOP

requests looks for the ID (0x49424d1e) in the ServiceContext of the request, and if it

is found, the embedded correlator is used to continue monitoring the transaction.

Example:

public static final int TMTP_ID = 0x49424d1e;

public void client_unmarshalled_request(RequestHolder rh) throws SystemException {

try {

rmiTxn.start();

rmiCorrelator = rmiTxn.getCorrelator();

byte[] corrBytes = rmiCorrelator.getBytes();

byte data[] = null;

CDROutputStream cos = new CDROutputStream(_orb);

cos.putEndian();

int length = corrBytes.length;

cos.write_string("" + length);

cos.write_octet_array(corrBytes, 0, corrBytes.length);

Appendix A. Tracking a transaction into a J2EE application server 53

Page 68: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

data = cos.toByteArray();

// Add the ServiceContext with TMTP_ID and Correlator to the request

// to be picked up by the Server side

setServiceContext(rh, data);

} catch (Exception e) {

e.printStackTrace();

}

}

public static void setServiceContext(RequestHolder rh, byte[] data) {

ServiceContext sc = new ServiceContext(TMTP_ID, data);

ServiceContext[] list = rh.serviceContextList();

if (list == null) {

list = new ServiceContext[1];

list[0] = sc;

rh.serviceContextList(list);

} else {

boolean alreadyExists = false;

for (int i = 0; i < list.length; i++) {

if (list[i].getId() == InterceptorTxnInfo.ID) {

alreadyExists = true;

list[i] = sc;

rh.serviceContextList(list);

break;

}

}

if (!alreadyExists) {

ServiceContext[] newlist = new ServiceContext[list.length + 1];

System.arraycopy(list, 0, newlist, 0, list.length);

newlist[list.length] = sc;

rh.serviceContextList(newlist);

}

}

}

WebSphere Application Server Version 5 and later:

To pass a correlator from an ARM-instrumented application to a J2EE-instrumented

WebSphere Application Server (WAS) Version 5 and later, add it to the RMI request

as ServiceContext data. The ServiceContext key used to send the correlator is an ID

assigned to IBM Tivoli Monitoring for Transaction Performance by WebSphere

(0x49424d1e), and the value is a byte array which represents the correlator. An RMI

Interceptor must be implemented to modify RMI requests to add the correlator.

The interceptor has to implement the

org.omg.PortableInterceptor.ClientRequestInterceptor interface.

The WebSphere Application Server Version 5 server that receives the RMI-IIOP

requests looks for the ID (0x49424d1e) in the ServiceContext of the request, and if it

is found, the embedded correlator is used to continue monitoring the transaction.

Example:

public static final int TMTP_ID = 0x49424d1e;

public void send_request(ClientRequestInfo cri) throws ForwardRequest

{

try {

rmiTxn.start();

rmiCorrelator = rmiTxn.getCorrelator();

byte[] corrBytes = rmiCorrelator.getBytes();

//This is an IBM specific class

ExtendedClientRequestInfo ri = (ExtendedClientRequestInfo) cri;

byte data[] = null;

ORB theORB = (ORB) ((LocalObject) ri)._orb();

54 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 69: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

CDROutputStream cos = ORB.createCDROutputStream(theORB);

cos.putEndian();

int length = corrBytes.length;

cos.write_string("" + length);

cos.write_octet_array(corrBytes, 0, corrBytes.length);

data = cos.toByteArray();

// Add the ServiceContext with TMTP_ID and Correlator to the request

// to be picked up by the Server side

ServiceContext sc = new ServiceContext(WASRMIInterceptor.TMTP_ID, data);

ri.add_request_service_context(sc, true);

} catch (Exception e) {

e.printStackTrace();

}

}

See the WASRMIInterceptor.java file under the RMIExample directory to see a

complete example of a RMI Interceptor for sending correlators to WebSphere

Application Server Version 5 and above. These files are located at the following

Web site:

http://publib.boulder.ibm.com/infocenter/tiv3help/index.jsp?topic=

/com.ibm.itmtp.doc/correlator_passing.zip

Weblogic:

To pass a correlator to a J2EE-instrumented WebLogic Application Server use the

weblogic.trace.Trace class. The approach below works only if it is run in a

Weblogic container.

Example:

rmiTxn.start();

rmiCorrelator = rmiTxn.getCorrelator();

byte[] corrBytes = rmiCorrelator.getBytes();

T3Payload payload = new T3Payload(corrBytes);

weblogic.trace.Trace.beginTrace(T3Payload.serialize(payload));

// T3Payload class

import java.io.ByteArrayInputStream;

import java.io.ByteArrayOutputStream;

import java.io.IOException;

import java.io.ObjectInputStream;

import java.io.ObjectOutputStream;

import java.io.Serializable;

class T3Payload implements Serializable {

private static int MONITORING_APP_ID = 1;

private String hostName = null;

private int appId = -1;

private String threadName = null;

private byte[] correlator = null;

T3Payload(byte[] c)

{

this("localhost",MONITORING_APP_ID,Thread.currentThread().getName(),c);

}

T3Payload(String h, int id, String t, byte[] c)

{

hostName = h;

appId = id;

threadName = t;

correlator = c;

Appendix A. Tracking a transaction into a J2EE application server 55

Page 70: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

}

static byte[] serialize(T3Payload p)

{

byte[] rv = null;

if (p != null) {

try {

// Create a Output stream to serialize to

ByteArrayOutputStream bos = new ByteArrayOutputStream();

ObjectOutputStream s = new ObjectOutputStream(bos);

// Serialize the payload

s.writeObject(p);

rv = bos.toByteArray();

// Reset and flush the ObjectOutputStream

s.reset();

s.flush();

bos = null;

s = null;

} catch (IOException e) {

e.printStackTrace();

rv = null;

}

}

return rv;

}

static T3Payload deserialize(byte[] c)

{

T3Payload rv = null;

if (c != null) {

try {

//Create a Input stream to deserialize from

ByteArrayInputStream bis = new ByteArrayInputStream(c);

ObjectInputStream s = new ObjectInputStream(bis);

// De-serialize the payload

rv = (T3Payload) s.readObject();

//To satisfy a jtest rule.

if (s.markSupported()) {

s.reset();

}

bis = null;

s = null;

} catch (Exception e) {

e.printStackTrace();

rv = null;

}

}

return rv;

}

}

56 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 71: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Appendix B. libSWARM function calls

arm_set_name_rt

Sets the base ARM pattern for all subsequent libSWARM arm_start_rt()

calls.

The defaultTransactionName variable specifies the value for the default

transaction name. A naming pattern must be adopted for the libSWARM

calls for ARM to recognize a Robot transaction. The pattern requires the

ARM calls to begin with the script name followed by any characters:

ScriptName.*

Where:

ScriptName

Is the name of the recorded GUI or VU test script.

.* Is zero or more characters.

Returns zero (0) if successful and a negative value if an error occurs.

Example calls: If a recorded test is named AccountLoginTest:

GUI: arm_set_name_rt(″AccountLoginTest″)

external_C proc arm_set_name_rt(defaultTransactionName)

string defaultTransactionName;

{}

VU: arm_set_name_rt(″AccountLoginTest″);

external_C proc arm_set_name_rt(defaultTransactionName);

string defaultTransactionName;

{}

arm_start_rt

Note: arm_start_rt exists to simplify test instrumentation. To provide a

descriptive name to a transaction step use arm_start_using_name_rt.Signals the start of an ARM transaction, and assigns it a generated name

based on the current defaultTransactionName value.

The generated name is formatted:

TransactionName __LevelX _StepY

Where:

TransactionName

Is the name of the recorded test.

LevelX

Is the ARM nesting level.

StepY Is the step number within the nesting level.

For example, AccountLoginTest__Level2 _Step4 is the fourth step on the

second level of the recorded AccountLoginTest test.

Returns zero (0) if successful and a negative value if an error occurs.

Example calls:

57

Page 72: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

GUI: arm_start_rt()

external_C int func arm_start_rt()

{}

VU: arm_start_rt();

external_C int func arm_start_rt();

{}

arm_start_using_name_rt

Signals the start of an ARM transaction and assigns it the specified name.

Where:

transactionName

The name to assign to the transaction. For the top level ARM

transaction the transactionName must match the test name like

arm_set_name_rt. For subtransactions the transactionName does

not need to match the test name.

Returns zero (0) if successful and a negative value if an error occurs.

Example calls: If a recorded test was named AccountLoginTest

GUI: arm_start_using_name_rt("AccountLoginTest")

arm_start_using_name_rt("LoginPage")

external_C int func arm_start_using_name_rt(transactionName)

string transactionName;

{}

VU: arm_start_using_name_rt("AccountLoginTest");

arm_start_using_name_rt("LoginPage");

external_C int func arm_start_using_name_rt(transactionName);

string transactionName;

{}

arm_stop_rt

Signals the end of an ARM transaction. This does nothing when called

prior to an associated START call. The status of the stopped transaction is

set to ARM_GOOD. See page 59 for more information on status.

Returns zero (0) if successful and a negative value if an error occurs.

Example calls:

GUI: arm_stop_rt()

external_C int func arm_stop_rt()

{}

VU: arm_stop_rt();

external_C int func arm_stop_rt();

{}

arm_stop_failed_rt

Signals the end of an ARM transaction. This does nothing when called

prior to an associated START call. The status of the stopped transaction is

set to ARM_FAILED. See page 59 for more information on status.

Returns zero (0) if successful and a negative value if an error occurs.

Example calls:

GUI: arm_stop_failed_rt()

external_C int func arm_stop_failed_rt()

{}

58 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 73: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

VU: arm_stop_failed_rt();

external_C int func arm_stop_failed_rt();

{}

arm_stop_with_status_rt

Signals the end of an ARM transaction. This does nothing when called

prior to an associated START call. The status of the stopped transaction is

set to the specified status value.

Where:

status Is the status to use for the transaction stop call.

Returns zero (0) if successful and a negative value if an error occurs.

Example calls:

GUI: arm_stop_with_status_rt (ARM_GOOD)

external_C int func arm_stop_with_status_rt(status)

int status;

VU: arm_stop_with_status_rt (ARM_GOOD);

external_C int func arm_stop_with_status_rt(status);

int status;

Status codes used by rm_stop_with_status_rt:

ARM_GOOD = 0

ARM transaction status code indicating a successful transaction.

ARM_ABORT = 1

ARM transaction status code indicating an aborted transaction.

ARM_FAILED = 2

ARM transaction status code indicating a failed transaction.

ARM_IGNORE = 3

ARM transaction status code indicating an ignored transaction.

arm_copy_correlator_hex_rt

Accesses the current ARM Correlator. This returns the correlator as a string

that contains the hex value of the ARM correlator. This string can be added

to an HTTP request to correlate with components down stream from the

request (QoS, J2EE, DB2, CICS, etc). The header format is

ARM_CORRELATOR: Correlator where Correlator is the hex value returned.

outCorrelatorHexString

Is the string variable (defined in the accessing VU Script) to store

the hex string denoting the current ARM correlator.

Example calls:

GUI: HTTP correlator passing is not supported. GUI subtransaction

correlator passing is automatically handled by libSWARM.

VU:

string arm_corr;

arm_copy_correlator_hex_rt(&arm_corr);

sprintf(&http_corr, "ARM_CORRELATOR: %s", arm_corr);

http_request ["VuIEIbm~010"]

"GET /data/js/survey/esites/popup.js HTTP/1.1\r\n"

"Accept: */*\r\n"

"Referer: " + SgenURI_003 + "\r\n"

/* "Referer: http://www.ibm.com/us/" */

"Accept-Language: en-us\r\n"

Appendix B. libSWARM function calls 59

Page 74: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

"Accept-Encoding: gzip, deflate\r\n"

"If-Modified-Since: Wed, 09 Feb 2005 20:12:31 GMT\r\n"

"If-None-Match: \"260d9-1649-420a6eaf\"\r\n"

"User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows

NT 5.1; .NET CLR"

" 1.1.4322)\r\n"

"Host: www.ibm.com\r\n"

"Connection: Keep-Alive\r\n"

"Cookie: w3ibmProfile=2001111016254301611275733917|

gAME|897|BNT|null\r\n"

/*TMTP: Added ARM Correlator to HTTP Header*/

+ http_corr + "\r\n"

"\r\n";

external_C proc arm_copy_correlator_hex_rt(outCorrelatorHexString)

reference string outCorrelatorHexString;

{}

arm_get_status_rt

Accesses the last known status code for the armWrapper instance and

returns the last known status code.

Example call:

external_C int func arm_get_status_rt()

{}

60 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 75: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Appendix C. Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in

other countries. Consult your local IBM representative for information on the

products and services currently available in your area. Any reference to an IBM

product, program, or service is not intended to state or imply that only that IBM

product, program, or service may be used. Any functionally equivalent product,

program, or service that does not infringe any IBM intellectual property right may

be used instead. However, it is the user’s responsibility to evaluate and verify the

operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter

described in this document. The furnishing of this document does not give you

any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation

North Castle Drive

Armonk, NY 10504-1785 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM

Intellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation

Licensing

2-31 Roppongi 3-chome, Minato-ku

Tokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any other

country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS

PUBLICATION ″AS IS″ WITHOUT WARRANTY OF ANY KIND, EITHER

EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED

WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS

FOR A PARTICULAR PURPOSE.

Some states do not allow disclaimer of express or implied warranties in certain

transactions, therefore, this statement might not apply to you.

This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be

incorporated in new editions of the publication. IBM may make improvements

and/or changes in the product(s) and/or the program(s) described in this

publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for

convenience only and do not in any manner serve as an endorsement of those Web

sites. The materials at those Web sites are not part of the materials for this IBM

product and use of those Web sites is at your own risk.

61

Page 76: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

IBM may use or distribute any of the information you supply in any way it

believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose

of enabling: (i) the exchange of information between independently created

programs and other programs (including this one) and (ii) the mutual use of the

information which has been exchanged, should contact:

IBM Corporation

2Z4A/101

11400 Burnet Road

Austin, TX 78758 U.S.A.

Such information may be available, subject to appropriate terms and conditions,

including in some cases payment of a fee.

The licensed program described in this document and all licensed material

available for it are provided by IBM under terms of the IBM Customer Agreement,

IBM International Program License Agreement or any equivalent agreement

between us.

Any performance data contained herein was determined in a controlled

environment. Therefore, the results obtained in other operating environments may

vary significantly. Some measurements may have been made on development-level

systems and there is no guarantee that these measurements will be the same on

generally available systems. Furthermore, some measurement may have been

estimated through extrapolation. Actual results may vary. Users of this document

should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of

those products, their published announcements or other publicly available sources.

IBM has not tested those products and cannot confirm the accuracy of

performance, compatibility or any other claims related to non-IBM products.

Questions on the capabilities of non-IBM products should be addressed to the

suppliers of those products.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which

illustrate programming techniques on various operating platforms. You may copy,

modify, and distribute these sample programs in any form without payment to

IBM, for the purposes of developing, using, marketing or distributing application

programs conforming to the application programming interface for the operating

platform for which the sample programs are written. These examples have not

been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or

imply reliability, serviceability, or function of these programs. You may copy,

modify, and distribute these sample programs in any form without payment to

IBM for the purposes of developing, using, marketing, or distributing application

programs conforming to IBM‘s application programming interfaces.

Trademarks

AIX, DB2®, IBM, the IBM logo, Tivoli, and the Tivoli logo are trademarks or

registered trademarks of International Business Machines Corporation in the

United States, other countries, or both.

62 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 77: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Linux is a trademark of Linus Torvalds in the United States, other countries, or

both.

Microsoft and Windows NT® are registered trademarks of Microsoft Corporation in

the United States, other countries, or both.

Java™ and all Java-based trademarks and logos are trademarks or

registered trademarks of Sun Microsystems, Inc. in the United States,

other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other

countries.

Other company, product, and service names may be trademarks or service marks

of others.

Appendix C. Notices 63

Page 78: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

64 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 79: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Index

Aaccessibility ix

agentARM 2

applicationsending

ARM Version 2 20

registeringARM Version 2 17

supported 2

ARM agentagent

definition 2

ARM APIalternate

language bindings 47

callssimple 7

Version 1 7

case sensitivity 10

returnscodes 10

handles 10

usingefficiently 13

simple 7

Version 1 7

Version 1arm_end 9

arm_getid 7

arm_init 7

arm_start 8

arm_stop 8

arm_update 8

example 9

ARM Version 2applications

ending 20

registering 17

correlators 23

consuming 28

generating 27

passing 28

working with 26

debugging 33

instrumentation 17

Java applications 29

problem determination 33

Software Developer’s Kit 48

transactionsadditional metrics 32

correlating 21

ending 20

registering 18

starting 19

stopping 19

using 17

arm_copy_correlator_hex_rtgeneric windows 59

libSWARM calls 59

arm_endARM Version 1 9

arm_getidARM Version 1 7

arm_initARM Version 1 7

arm_set_name_rtgeneric windows 57

libSWARM calls 57

arm_startARM Version 1 8

arm_start_rtgeneric windows 57

libSWARM calls 57

arm_start_using_name_rtgeneric windows 58

libSWARM calls 58

arm_stopARM Version 1 8

completion status 13

arm_stop_failed_rtgeneric windows 58

libSWARM calls 58

arm_stop_rtgeneric windows 58

libSWARM calls 58

arm_stop_with_status_rtgeneric windows 59

libSWARM calls 59

status codes 59

arm_updateARM Version 1 8

Bbooks

feedback on vii

online vii

ordering vii

Ccalls

simple 7

Version 1 7

arm_end 9

arm_getid 7

arm_init 7

arm_start 8

arm_stop 8

arm_update 8

example 9

codes, return 11

commandsspecial characters x

syntax x

commercial applicationssupported 2

compilewith ARM 14

completion statusarm_stop

ARM Version 1 13

conventionstypeface x

correlatorsARM Version 2 21, 23

consuming 28

generating 27

passing 28

working with 26

transaction 21, 23

Ddebugging 33

ARM Version 2C 33

diagnosticscontrol 35

performance considerations 35

directory names, notation x

Eeducation

see Tivoli technical training ix

environment variables, notation x

Ggeneric windows

insertingARM timers 39

instrumentation 37

operations 37, 38

libSWARM calls 57

arm_copy_correlator_hex_rt 59

arm_set_name_rt 57

arm_start_rt 57

arm_start_using_name_rt 58

arm_stop_failed_rt 58

arm_stop_rt 58

arm_stop_with_status_rt 59

goal tableinstrumentation 3

Hhandles 11

HTTPcorrelator passing

J2EE 51

transaction trackingJ2EE 51

65

Page 80: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

Iinstrumentation

ARM Version 2 17

debugging 33

ARM Version 2 33

generic windows 37

libSWARM calls 57

operations 37, 38

goal table 3

performance considerations 35

detail control 35

diagnostic control 35

problem determination 33

ARM Version 2 33

introductionARM i

JJ2EE

correlator passing 51

HTTP 51

JMS 51

RMI 53

SOAP 52

transaction tracking 51

HTTP 51

JMS 51

RMI 53

SOAP 52

Java applicationsARM Version 2 29

JMScorrelator passing

J2EE 51

transaction trackingJ2EE 51

Llanguage bindings

alternate 47

ARM Version 2 Software

Developer’s Kit 48

PowerBuilder 47

Visual Basic 48

libSWARM callsarm_copy_correlator_hex_rt 59

arm_set_name_rt 57

arm_start_rt 57

arm_start_using_name_rt 58

arm_stop_failed_rt 58

arm_stop_rt 58

arm_stop_with_status_rt 59

generic windows 57

Mmanuals

feedback on vii

online vii

ordering vii

Nnotation

environment variables x

path names x

typeface x

Ooperations

generic windows 37, 38

ordering publications vii, ix

overviewARM for IBM Tivoli Monitoring for

Transaction Performance 3

Ppath names, notation x

performance considerationsARM instrumentation 35

detail control 35

diagnostic control 35

PowerBuilder 47

problem determination 33

ARM Version 2C 33

publicationsfeedback on vii

online vii

ordering vii, ix

Rregister

applicationsARM Version 2 17

ARM Version 2applications 17

transactions 18

transactionsARM Version 2 18

returnscodes 11

handles 11

RMIcorrelator passing

J2EE 53

transaction trackingJ2EE 53

SSOAP

correlator passingJ2EE 52

transaction trackingJ2EE 52

TTivoli technical training ix

training, Tivoli technical ix

transactionsadditional metrics

ARM Version 2 32

correlatingARM Version 2 21

endingARM Version 2 20

nested 11

overlapping 11

registeringARM Version 2 18

startingARM Version 2 19

stoppingARM Version 2 19

typeface conventions x

Vvariables, notation for x

VersionsARM 5

supported 5

Visual Basic 48

66 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide

Page 81: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and
Page 82: Tivoli Tivoli Monitoring Transaction Performancepublib.boulder.ibm.com/tividd/td/ITMFTP/SC32-9412-00/en...documents. It also describes how to access Tivoli ® publications online and

����

Printed in USA

SC32-9412-00