Tivoli® IBM Tivoli Monitoring for Transaction Performance
Application Response Measurement (ARM) Instrumentation Guide
Version 5.3
SC32-9412-00
���
Tivoli® IBM Tivoli Monitoring for Transaction Performance
Application Response Measurement (ARM) Instrumentation Guide
Version 5.3
SC32-9412-00
���
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.
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
iv IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide
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
vi IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide
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
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
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
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
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
xii IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide
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
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
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
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
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
6 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide
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
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
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
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
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
Figure 3. Overlapping transactions
12 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide
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
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
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
16 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide
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
*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
*
* 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
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
* 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
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
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
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
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
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
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
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
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
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
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
* 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
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
34 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide
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
High Trace Level
All information relevant to this transaction is gathered.
36 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide
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
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
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
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
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
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
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
/*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
/*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
46 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide
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
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
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
50 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide
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
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
*/
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
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
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
}
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
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
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
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
"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
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
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
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
64 IBM Tivoli Monitoring for Transaction Performance: Application Response Measurement (ARM) Instrumentation Guide
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
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
����
Printed in USA
SC32-9412-00