APM - 9.5 - Transaction Generator Implementation Guide

Transaction Generator Implementation
Guide
Release 9.5
CA Application Performance
Management

This Documentation, which includes embedded help systems and electronically distributed materials, (hereinafter referred to
as the Documentation) is for your informational purposes only and is subject to change or withdrawal by CA at any time.
This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part, without
the prior written consent of CA. This Documentation is confidential and proprietary information of CA and may not be disclosed
by you or used for any purpose other than as may be permitted in (i) a separate agreement between you and CA governing
your use of the CA software to which the Documentation relates; or (ii) a separate confidentiality agreement between you and
CA.
Notwithstanding the foregoing, if you are a licensed user of the software product(s) addressed in the Documentation, you may
print or otherwise make available a reasonable number of copies of the Documentation for internal use by you and your
employees in connection with that software, provided that all CA copyright notices and legends are affixed to each reproduced
copy.
The right to print or otherwise make available copies of the Documentation is limited to the period during which the applicable
license for such software remains in full force and effect. Should the license terminate for any reason, it is your responsibility to
certify in writing to CA that all copies and partial copies of the Documentation have been returned to CA or destroyed.
TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION AS IS WITHOUT WARRANTY OF ANY
KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE,
DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST
INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE
POSSIBILITY OF SUCH LOSS OR DAMAGE.
The use of any software product referenced in the Documentation is governed by the applicable license agreement and such
license agreement is not modified in any way by the terms of this notice.
The manufacturer of this Documentation is CA.
Provided with Restricted Rights. Use, duplication or disclosure by the United States Government is subject to the restrictions
set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)(3), as applicable, or
their successors.
Copyright 2013 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein belong to
their respective companies.

CA Technologies Product References
This document references the following CA Technologies products and features:
CA Application Performance Management (CA APM)
CA Application Performance Management ChangeDetector (CA APM
ChangeDetector)
CA Application Performance Management ErrorDetector (CA APM ErrorDetector)
CA Application Performance Management for CA Database Performance (CA APM
for CA Database Performance)
CA Application Performance Management for CA SiteMinder (CA APM for CA
SiteMinder)
CA Application Performance Management for CA SiteMinder Application Server
Agents (CA APM for CA SiteMinder ASA)
CA Application Performance Management for IBM CICS Transaction Gateway (CA
APM for IBM CICS Transaction Gateway)
CA Application Performance Management for IBM WebSphere Application Server
(CA APM for IBM WebSphere Application Server)
CA Application Performance Management for IBM WebSphere Distributed
Environments (CA APM for IBM WebSphere Distributed Environments)
CA Application Performance Management for IBM WebSphere MQ (CA APM for
IBM WebSphere MQ)
CA Application Performance Management for IBM WebSphere Portal (CA APM for
IBM WebSphere Portal)
CA Application Performance Management for IBM WebSphere Process Server (CA
APM for IBM WebSphere Process Server)
CA Application Performance Management for IBM z/OS (CA APM for IBM z/OS)
CA Application Performance Management for Microsoft SharePoint (CA APM for
Microsoft SharePoint)
CA Application Performance Management for Oracle Databases (CA APM for Oracle
Databases)
CA Application Performance Management for Oracle Service Bus (CA APM for
Oracle Service Bus)
CA Application Performance Management for Oracle WebLogic Portal (CA APM for
Oracle WebLogic Portal)
CA Application Performance Management for Oracle WebLogic Server (CA APM for
Oracle WebLogic Server)
CA Application Performance Management for SOA (CA APM for SOA)

CA Application Performance Management for TIBCO BusinessWorks (CA APM for
TIBCO BusinessWorks)
CA Application Performance Management for TIBCO Enterprise Message Service
(CA APM for TIBCO Enterprise Message Service)
CA Application Performance Management for Web Servers (CA APM for Web
Servers)
CA Application Performance Management for webMethods Broker (CA APM for
webMethods Broker)
CA Application Performance Management for webMethods Integration Server (CA
APM for webMethods Integration Server)
CA Application Performance Management Integration for CA CMDB (CA APM
Integration for CA CMDB)
CA Application Performance Management Integration for CA NSM (CA APM
Integration for CA NSM)
CA Application Performance Management LeakHunter (CA APM LeakHunter)
CA Application Performance Management Transaction Generator (CA APM TG)
CA Cross-Enterprise Application Performance Management
CA Customer Experience Manager (CA CEM)
CA Embedded Entitlements Manager (CA EEM)
CA eHealth Performance Manager (CA eHealth)
CA Insight Database Performance Monitor for DB2 for z/OS
CA Introscope
CA SiteMinder
CA Spectrum Infrastructure Manager (CA Spectrum)
CA SYSVIEW Performance Management (CA SYSVIEW)

Contact CA Technologies
Contact CA Support
For your convenience, CA Technologies provides one site where you can access the
information that you need for your Home Office, Small Business, and Enterprise CA
Technologies products. At http://ca.com/support, you can access the following
resources:
Online and telephone contact information for technical assistance and customer
services
Information about user communities and forums
Product and documentation downloads
CA Support policies and guidelines
Other helpful resources appropriate for your product
Providing Feedback About Product Documentation
If you have comments or questions about CA Technologies product documentation, you
can send a message to techpubs@ca.com.
To provide feedback about CA Technologies product documentation, complete our
short customer survey which is available on the CA Support website at
http://ca.com/docs.

Contents 7

Contents

Chapter 1: The CA APM Transaction Generator 11
CA APM TG monitoring architecture .......................................................................................................................... 11
Addressing the 3 A.M. problem .......................................................................................................................... 11
CA APM TG features ................................................................................................................................................... 12
Load ramping ...................................................................................................................................................... 12
Script creation and maintenance ........................................................................................................................ 13
Integration with CA Introscope ......................................................................................................................... 13
Integration with the CA Customer Experience Manager .................................................................................... 14
Chapter 2: Installing the CA APM Transaction Generator 15
Before you begin ........................................................................................................................................................ 15
Operating system requirements ......................................................................................................................... 15
Additional operating system support for the CA APM TG agent ........................................................................ 16
Recommended minimum hardware requirements ............................................................................................ 16
Installing the CA APM Transaction Generator ........................................................................................................... 17
CA APM TG components ..................................................................................................................................... 17
Installing CA APM TG on Windows...................................................................................................................... 18
Installing CA APM TG on Linux ............................................................................................................................ 20
Displaying CA APM TG information in CA Introscope Investigator ................................................................... 21
Managing CA APM TG user access in a standalone configuration ...................................................................... 24
Displaying CA APM TG agent availability in CA CEM ........................................................................................... 26
CA APM TG agent startup settings ............................................................................................................................. 26
Installing CA APM TG-specific CA Introscope components ...................................................................................... 27
Installing CA Introscope tab views .................................................................................................................... 28
The Command line and the CA APM TG agent ........................................................................................................... 28
Linux DHCP considerations ......................................................................................................................................... 29
Chapter 3: Configuring the CA APM Transaction Generator Agent 31
Overview of configuring agents ................................................................................................................................. 31
Setting Hierarchy ................................................................................................................................................. 32
The CA APM TG Agent Configuration ......................................................................................................................... 32
The Dashboard tab .............................................................................................................................................. 33
The Connect to Agent tab .................................................................................................................................. 35
Configuring the CA APM TG agent ...................................................................................................................... 37
Using Configuration Tab buttons ........................................................................................................................ 41
Groups and scripts...................................................................................................................................................... 42

8 Transaction Generator Implementation Guide

The Scripts By Group tab ..................................................................................................................................... 43
The All Scripts tab................................................................................................................................................ 47
Working with scripts in the Script Requests page ............................................................................................... 49
Viewing script request details ............................................................................................................................. 50
Testing a script .................................................................................................................................................... 51
Sending scripts to CA CEM .................................................................................................................................. 52
Load ramping ...................................................................................................................................................... 52
Viewing status messages .................................................................................................................................... 55
Chapter 4: Creating and Editing CA APM TG Scripts 57
Starting the Script Editor ............................................................................................................................................ 57
Creating a script .................................................................................................................................................. 58
Using the Script Recorder ........................................................................................................................................... 59
Configuring the Script Recorder .......................................................................................................................... 59
Starting the recording session............................................................................................................................. 63
Logically grouping requests using Set Request ID ............................................................................................... 67
Monitoring web services ..................................................................................................................................... 68
Using a script template .............................................................................................................................................. 69
Manually creating scripts ........................................................................................................................................... 70
Specifying script parameters ............................................................................................................................... 71
Specifying requests ............................................................................................................................................. 71
Specifying request tags ....................................................................................................................................... 72
Specifying conditions .......................................................................................................................................... 73
Checking syntax ................................................................................................................................................... 74
Deploying scripts to multiple agents .......................................................................................................................... 74
Copying a single script at a time ......................................................................................................................... 74
Manually copying multiple scripts ...................................................................................................................... 74
Securing scripts .......................................................................................................................................................... 76
Securing access to the Script Editor ........................................................................................................................... 77
XML tag syntax ........................................................................................................................................................... 78
XML special character substitutions........................................................................................................................... 83
Script samples ............................................................................................................................................................ 83
Basic script sample .............................................................................................................................................. 84
Script conditions and content variables .............................................................................................................. 84
Script reserved variables ..................................................................................................................................... 86
Reserved variable sample ................................................................................................................................... 87
<setvar> samples ................................................................................................................................................ 88
Stopping a script using the <stop> tag or stop attribute .................................................................................... 89
Chapter 5: Viewing CA APM TG Metrics 91
Viewing CA APM TG data with CA Introscope .......................................................................................................... 91

Contents 9

CA APM TG agent metrics in CA Introscope ...................................................................................................... 92
Other metrics ...................................................................................................................................................... 92
CA APM TG-specific tab views ............................................................................................................................. 95
Viewing CA APM TG data with CA CEM ...................................................................................................................... 96
Identifying CA APM TG transactions ................................................................................................................... 96
CA APM Transaction Generator to CA CEM integration terminology ................................................................. 96
Appendix A: Configuring the RTM Server 99
Appendix B: CA APM TG command line utility (WTGUtil) 101
Basic command description ..................................................................................................................................... 101
WTGUtil Command syntax ................................................................................................................................ 102
Examples ........................................................................................................................................................... 103
Trace messages ................................................................................................................................................. 103
Index 105


Chapter 1: The CA APM Transaction
Generator

CA Application Performance Management Transaction Generator (CA APM TG) is an
intelligent, programmable agent that helps you monitor the availability, health, and
performance of web sites and web services from the perspective of a user attempting to
access web sites. The CA APM TG agent generates synthetic transactions that you can
monitor using CA Customer Experience Manager (CA CEM) and CA Introscope. Use the
load ramping feature of CA APM TG to generate a load against a web application to test
how well the application handles changes in the load.
When operational issues arise during business hours, any amount of down time can
mean a significant loss of revenue and a significant reduction in customer satisfaction.
By using synthetic transactions to identify problems during off-hours, you can find and
fix problems before real users and customers are affected.
This section contains the following topics:
CA APM TG monitoring architecture (see page 11)
CA APM TG features (see page 12)
CA APM TG monitoring architecture
The CA APM TG agent uses scripts to run synthetic transactions against LAN or WAN
web sites and web services for an organization. When you send these scripts to CA CEM
for monitoring, CA CEM automatically creates business processes and business
transactions from the scripts. CA CEM then monitors the synthetic transactions to
determine the overall health of the selected web sites and web services and to
proactively address issues within a web site or web application before real users are
affected. For more information about integrating CA APM TG with CA CEM, see Viewing
CA APM TG data with CA CEM (see page 96)
Addressing the 3 A.M. problem
The 3 A.M. problem occurs when maintenance of web sites and web services is
performed during off hours, while there is little to no traffic to a specific web site or
application. If a problem occurs during maintenance, it is often not detected until the
start of the business day due to a lack of monitoring. This leads to loss of revenue and
bad customer experience.
CA APM TG features


When no one is using a web site or web application, CA CEM and CA Introscope cannot
measure its availability and performance because no transactions are being monitored.
When a problem occurs, IT support personnel have no information to begin
investigating the problem and finding the solution. CA APM TG helps you address the 3
A.M. problem.
The synthetic transactions you create with CA APM TG are an essential component of an
overall application monitoring strategy. Should a problem occur during off hours,
synthetic transaction data viewed through the CA Introscope Workstation or CEM
console indicates where a problem is located and how to best resolve the situation.
With the alert capabilities of CA Introscope and the incident reporting features of CA
CEM, you can assess the problem before the start of business and implement a solution
before any real users are impacted.
CA APM TG features
CA APM TG is easily integrated into a web application monitoring system using CA
Introscope and CA CEM. The features described in this section make CA APM TG an
excellent addition to your IT application suite. The following sections describe these
features:
Load ramping (see page 12)
Script creation and maintenance (see page 13)
Integration with CA Introscope (see page 13)
Integration with the CA Customer Experience Manager (see page 14)
Load ramping
You can also use CA APM TG synthetic transactions to test a new application under load
using the CA APM TG load ramping feature. This feature simulates load on the servers to
determine if the application can perform adequately under production load demands.
When application performance issues occur, one of the first questions that application
and IT support personnel ask is: "Which other users are experiencing the same
problem?" Knowing the scope of a problem helps you to prioritize the problem and
determine which other teams to involve in a search for the solution. The challenge
facing global enterprises is that it is always off hours for business somewhere in the
world. With CA APM TG synthetic transactions, you can determine web application
performance from all locations, ensuring top performance and customer satisfaction.
CA APM TG features


Script creation and maintenance
Web sites and web applications are becoming more complex, using intricate
technologies to execute complicated requests. Manually creating scripts to monitor web
applications utilizing newer and newer technologies leads to script errors and incorrect
data being reported.
Create scripts by recording your actions on a specific web site using the CA APM TG
Script Editor. As you navigate through the site, the click stream events are recorded in a
script. Save the scripts to the CA APM TG agent and deploy them. The saved scripts run
against the web sites and web applications creating data that you can monitor using CA
Introscope and CA CEM.
As IT organizations continually deploy new versions of web applications, script
maintenance also becomes key. The CA APM TG Script Editor allows you to edit, update,
and maintain scripts with ease. This decreases the number of false alarms and
guarantees up-to-date information for all monitored web sites and applications.
CA APM TG scripts can also automatically create business processes and transactions in
CA CEM. When scripts are migrated from CA APM TG to CA CEM, a new business
process is automatically created and populated with business transactions from the
script, resulting in a substantial time savings.
For more information about script creation and maintenance, see Creating and Editing
CA APM TG Scripts (see page 57).
Integration with CA Introscope
CA Introscope enables you to monitor complex web applications in production
environments, detect problems before they affect your customers, and resolve these
issues quickly and collaboratively. CA Introscope provides comprehensive end-to-end
transaction visibility and diagnostic capabilities across your entire infrastructurethe
application itself, application servers, web servers, messaging middleware, databases
and transaction serverswithout degrading performance.
CA APM TG script information can viewed in the CA Introscope Investigator. For more
information about using CA Introscope with CA APM TG, see Viewing CA APM TG
Metrics (see page 91). For more information about using CA Introscope, see the CA
APM Configuration and Administration Guide.
CA APM TG features


Integration with the CA Customer Experience Manager
CA CEM enables both business managers and IT personnel to understand and respond
to the online experience of each customer. Whether they are external customers,
suppliers, or employees, CA CEM creates actionable information that allows you to
optimize the experience for all end-users and ensure that your applications are fully
serving your business needs.
The CEM console tracks and monitors synthetic transactions generated by CA APM TG,
automatically creating business transaction definitions for the synthetic transactions. All
synthetic transactions are marked as synthetic in the CEM console, allowing you to
easily identify and use the transactions to proactively address issues within a web site or
web application.
For more information about integration with CA CEM, see CA CEM configuration (see
page 18).


Chapter 2: Installing the CA APM
Transaction Generator

This chapter describes how to install the CA APM TG. The following topics are discussed:
Before you begin (see page 15)
Installing the CA APM Transaction Generator (see page 17)
CA APM TG agent startup settings (see page 26)
Installing CA APM TG-specific CA Introscope components (see page 27)
The Command line and the CA APM TG agent (see page 28)
Linux DHCP considerations (see page 29)
Before you begin
In order to monitor transactions generated by CA APM TG, you must first have CA CEM
or CA Introscope installed.
You must have the following system requirements for your environment before
installing the CA APM TG.
Operating system requirements (see page 15)
Additional operating system support for the CA APM TG agent (see page 16)
Recommended minimum hardware requirements (see page 16)
Operating system requirements
The following operating systems are supported by all components of CA APM TG:
Windows 2003 Server with Service Pack 2
Windows XP Professional with Service Pack 3
Before you begin


Additional operating system support for the CA APM TG agent
The following operating systems are supported by all components of CA APM TG:
Windows 2003 Server
Windows XP Professional
Additional operating system support for the CA APM TG agent
Red Hat Enterprise Linux ES
Red Hat Enterprise Linux AS
SUSE Linux Enterprise Server
For more information about specific supported versions, please see the CA APM
Compatibility Guide.
Recommended minimum hardware requirements
The following hardware requirements are the minimum required for CA APM TG
installation.
Windows
A Pentium III 866 MHz processor
At least 1 GB of RAM
At least 300 MB of hard disk storage
Note: Storage use varies depending on the configuration of the CA APM TG agent.
Although installation requires less than the recommended amount, more storage space
is needed for the proper operation of CA APM TG.
Linux
A Pentium III 500 MHz processor
At least 512 MB of RAM
At least 300 MB of hard disk storage
Note: Storage use varies depending on the configuration of the CA APM TG agent.
Although installation requires less than the recommended amount, more storage space
is needed for the proper operation of CA APM TG.
One 10/100 MB network interface card (NIC)
Installing the CA APM Transaction Generator


You must get the installation package from the CA APM software download area on CA
Support. The following installation packages are available for the CA APM TG:
CA APM TG installation package for Windows
CA APM TG installation package for Linux
The CA APM TG consists of the following components:
CA APM TG agent (see page 17)
CA APM TG Script Editor (see page 17)
CA APM TG Administration Server and Agent Configuration Interface (see page 17)
For more information, see CA APM TG components (see page 17).
CA APM TG components
The CA APM TG consists of the following components:
CA APM TG agent
The CA APM TG agent runs synthetic transactions against web sites and web services.
For more information, see The CA APM TG agent Configuration (see page 32).
CA APM TG Script Editor
The CA APM TG Script Editor lets you view, create, modify, and delete scripts. You also
use the Script Editor to record synthetic transactions to scripts that are then loaded into
the CA APM TG agent for execution. For more information, see Creating and Editing CA
APM TG Scripts (see page 57).
Note: The CA APM TG Script Editor runs only on Windows platforms.
CA APM TG Administration Server and Agent Configuration Interface
The CA APM TG Administration Server and Agent Configuration Interface administer the
CA APM TG agent. The CA APM TG Administration Server can be configured to use login
credentials from:
CA CEM configuration (see page 18)
Standalone configuration (see page 18)


CA CEM configuration
The CA APM TG Administration Server can be configured to use the same login
credentials as the CEM console, allowing the system administrator to manage a single
set of credentials. Users benefit by having to remember a single username and
password for both the CEM console and the agent configuration.
To use the same credentials as the CEM console, install the CA APM TG Administration
Server component on a Windows or Linux platform with network access to Enterprise
Manager. Contact the CEM console administrator regarding the management of user
credentials.
Note: For more information about installing the CA APM TG Administration Server, see
Installing CA APM TG on Windows (see page 18) or Installing CA APM TG on Linux (see
page 20).
Standalone configuration
The CA APM TG Administration Server can be deployed in a standalone configuration in
which it reads user information from a simple text-based security file into memory for
authentication and authorization. This simple configuration allows you to get
acquainted with the operation of CA APM TG quickly. It is not intended for production
use. For information about managing user access in a standalone configuration, see
Managing CA APM TG user access in a standalone configuration (see page 24).
For a standalone configuration, install the CA APM TG Administration Server component
on a Windows or Linux platform. For more information about installing the CA APM TG
Administration Server, see Installing CA APM TG on Windows (see page 18) or Installing
CA APM TG on Linux (see page 20).
Installing CA APM TG on Windows
The following section explains how to install CA APM TG on Windows. CA APM TG files
should have already been downloaded before you begin these steps. For more
information, see Installing the CA APM Transaction Generator (see page 17) for details.
Note: You must have Administrator privileges to install CA APM TG.
To install the CA APM TG on Windows:
1. Click setup.exe to begin CA APM TG installation.
2. The InstallShield setup launches. Select where to install CA APM TG, or accept the
default location and click Next.


3. Select the components you want to install. The following components are available
for installation:
Transaction Generator: Use the plus (+) symbol to open the Transaction
Generator tree and select the components to install. Selecting the check box
next to the Transaction Generator selects all the sub-components for
installation. Some sub-components have configuration options.
The following sub-components are available for installation:
Agent: Installs the CA APM TG agent. To configure RTMCServer, proxy
server and secure (SSL) proxy server information, click Configuration.
The CA APM TG agent uses the RTMCServer process to access web
applications. You can change the port used by the CA APM TG agent to
communicate with the RTMCServer process. RTMCServer can be
configured later using the RTM Configuration tool. Navigate to Start > CA
APM Transaction Generator > RTM Configuration.
<apmtg-site1>: Installs a CA APM TG agent named <apmtg-site1>. To
change the name of the CA APM TG agent, click Configuration. For more
information about configuring the CA APM TG agent, see Configuring the
CA APM TG agent at installation (see page 19).
Script Editor: Installs the Script Editor. The Script Editor allows you to
record and edit scripts used to monitor web applications.
Administration Server: Installs the administration server, a J2EE application
that provides the Administration Interface for the CA APM TG agent. Click
Configure to select a port option or to configure the CA APM TG Administration
Server to use the same user credentials as the CEM console. The Enterprise
Manager host name and port will be required if configuring to share credentials
with CA CEM.
Note: Only one administration server is needed per CA APM TG installation.
Multiple CA APM TG agents can be accessed through a single Administration
Interface.
4. Click Next when you have selected and configured the CA APM TG components for
installation. A confirmation dialogue opens, presenting your installation
information. Click Start Setup to begin the installation, Back to return to the
previous screen to select other options, or Cancel to cancel the installation.
Configuring the CA APM TG agent at installation
When you install a CA APM TG agent, you can configure the name of the agent, or you
can accept the default agent name.
If you do not assign a specific name at the time of installation, renaming the agent later
requires you to uninstall and then reinstall the agent.


When naming a CA APM TG agent, choose a meaningful name, such as one that relates
to the geographic location of the agent, or the application being monitored. For
example: Princeton, 3rdFloorWest, or SAP_HR.
Note: The CA APM TG agent name cannot contain any spaces or any special characters
other than the underscore, as seen in the agent name SAP_HR.
You can optionally specify a location that will appear on the Administration Interface to
provide additional identification. The location string may contain any characters.
You can also configure the CA APM TG agent to send information to CA Introscope. If
you choose not to enable this feature at this time, you can configure each CA APM TG
agent later. For more information on configuring the CA APM TG agent to send
information to CA Introscope, see Displaying CA APM TG information in CA Introscope
Investigator (see page 21).
Note: Only one CA APM TG agent may be installed per machine.
Installing CA APM TG on Linux
The CA APM TG agent and Administration server can be installed on a Linux platform.
This installation process assumes you are familiar with Linux platforms. You need to
have already downloaded the files before you begin these steps. See Installing the CA
APM Transaction Generator (see page 17) for details.
Note: You must have root authority to install CA APM TG.
To install a CA APM TG agent on a Linux platform:
1. From a terminal session on a Linux platform, log in as root or switch to superuser
with the su command.
2. Create a working directory, such as /apmtg_tmp.
mkdir /apmtg_tmp
3. Copy the CA APM TG installation .tar file to the working directory you created.
4. Untar the installation .tar file.
tar -xvf name.tar


5. Launch the install file:
./install.setup install
The install script launches, asking you which components you want to install,
directory paths, and other configuration information. You can accept the defaults or
supply different information. The following components are available for
installation:
CA APM Transaction Generator AgentIf you accept the defaults, the CA APM
Transaction Generator Agent apmtg_site1 is installed using port 7700, the
RTMCServer port is 7201, and no proxy server or secure proxy server is used.
You can also configure the CA APM Transaction Generator Agent to send
Information to Introscope. If you choose to not enable this feature at this time,
you can configure it later.
CA APM Transaction Generator Administration ServerThe CA APM
Transaction Generator Administration Server will be on port 9090 and will be
deployed in a standalone configuration. You can select to use the same
credentials as the CEM console. The Enterprise Manager host name and port
will be required if configuring to share credentials.
6. Once installation is complete, you must log out and log back in again.
Note: There is a problem with using the Script Editor (which only runs on Windows)
when connecting to a CA APM TG agent running on Linux that is using DHCP to
acquire an IP address as opposed to using a static IP. For details, see Linux DHCP
considerations (see page 29)
Displaying CA APM TG information in CA Introscope Investigator
When this feature is enabled, CA APM TG sends information about the status of the CA
APM TG agent and its scripts to CA Introscope where this data appears in the
Investigator tree. You can enable and configure this feature during the installation of the
CA APM TG agent or after the CA APM TG agent has been installed. For details, see:
Integrating with CA Introscope on Windows (see page 21)
Integrating with CA Introscope on Linux (see page 23)
Integrating with CA Introscope on Windows
The following sections explain how to enable the CA Introscope integration on the CA
APM TG agent running on Windows. You can enable and configure the CA Introscope
integration either during or after the installation.
Enabling and configuring CA Introscope during installation (see page 22)
Enabling and configuring CA Introscope after installation (see page 22)


Enabling and configuring CA Introscope during installation
1. While installing the CA APM TG agent, expand the agent installation component
and highlight the default instance name apmtg_site1.
2. Click the Configuration button.
3. In the Introscope Metric Data group, check Enable Introscope and enter the
Introscope EM Host and Introscope EM Port.
Note: The installer attempts to verify that the Enterprise Manager is present on the
specified host and port. However, if the Enterprise Manager is not currently running,
you are given the option to continue with these settings or to change them.
Enabling and configuring CA Introscope after installation
The following section describes how to enable the CA Introscope integration if you
chose not to enable CA Introscope during the installation, but want to enable it later.
1. From a command prompt, change the directory to:
<apmtg_home>\Introscope\config
2. Edit the IntroscopeEPAgent.properties file and set the following variables to the CA
Introscope Enterprise Manager hostname and port:
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=emhostname
introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT=emport
3. Start the CA Introscope integration either manually or automatically using the
following steps.
To manually start the CA Introscope integration:
<apmtg_home>\Introscope
2. Run StartAgent.bat to activate the CA Introscope integration in the active console
window.
3. Log in to the CA APM TG agent Configuration UI and configure the agent to send
data to CA Introscope:
a. Navigate to Connect to Agent > AgentPort > Configuration tab > Configure
Agent.
b. On the Configure Agent page, set Send Data to Introscope to Yes.


To automatically start the CA Introscope integration:
<apmtg_home>\WTGService
2. Edit the wtgservice.ini file and add iscope to the [LAUNCH] section.
Note: Rebooting (or stopping and restarting wtgservice) activates the CA
Introscope integration.
3. Log in to the CA APM TG Agent Configuration UI and configure the agent to send
data to CA Introscope:
Agent.
Integrating with CA Introscope on Linux
The following sections explain how to enable the CA Introscope integration on the CA
APM TG agent running on Linux. You can enable and configure the CA Introscope
integration either during or after the installation.
Enabling and configuring CA Introscope during installation (see page 23)
Enabling and configuring CA Introscope after installation (see page 23)
Enabling and configuring CA Introscope during installation
While installing the CA APM TG agent, you are asked if you want to send CA APM TG
metrics to CA Introscope. If you reply yes, you are prompted for the CA Introscope
Enterprise Manager host address and port. After rebooting Linux, the CA Introscope
interface component starts automatically.
Enabling and configuring CA Introscope after installation
The following section describes how to enable the CA Introscope integration if you
chose not to enable CA Introscope during the installation, but want to enable it later.
<apmtg_home>/Introscope/config
2. Edit the IntroscopeEPAgent.properties file and set the following variables to the
Introscope <EM> hostname and port:
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=emhostname
introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT=emport
3. Start the CA Introscope integration either manually or automatically using the
following steps.


To manually start the CA Introscope integration:
<apmtg_home>\Introscope
2. Execute the StartAgent.sh script with the start option:
./StartAgent.sh start.
data to CA Introscope.
Agent.
To automatically start the CA Introscope integration:
<apmtg_home>/install_files/scripts
2. Create the startup script by executing MkStartIScope with the install option:
./MkStartIScope i
Note: Rebooting activates the CA Introscope integration.
data to CA Introscope.
Agent.
Managing CA APM TG user access in a standalone configuration
When deployed in a standalone configuration, the CA APM TG Administration Server is
delivered with two pre-defined user names: cemadmin and wtgoperator. The cemadmin
user has the administrator role, and the wtgoperator has the operator role. The Security
page is where administrators create other users, which you can designate as having
administrator rights (or not).
Note: In a standalone configuration, the CA APM TG Administration Server reads user
information from a simple text-based security file into memory for authentication and
authorization. This is a simple configuration that allows you to get acquainted with the
operation of CA APM TG quickly. It is not intended for production use.


If CA APM TG Administration Server is configured to share credentials with CA CEM,
contact the CA CEM administrator regarding the management of user credentials.
There are two panes on the Security page:
List of Userswhere you view, edit, or delete users
User Informationwhere you add new users
To create a new user account:
1. On the Dashboard tab, click the Security link (top right corner).
Note: The Security page is only available when the CA APM TG Administration
Server is configured for standalone operation. The Security page is only available to
CA APM TG Administrators.
2. Enter the appropriate information in the User Information pane to add a new user:
User NameThe login user name for the new CA APM TG user.
RolesSelect the administrator role to allow this user full access to the CA
APM TG Agent Configuration. Select the operator role to give this user limited
access.
Account EnabledBy default, the new user is enabled; clear the check box if
you do not want to enable this user account.
PasswordMust be at least 6 characters. Passwords are case sensitive.
Reset buttonClears the current user information.
Save User buttonSaves the user information.
3. Click Save User.
To edit a user account:
In the List of Users, click the User Name link to display this account in the User
Information pane.
You can modify the roles, enable or disable the account, and change the password.
To delete a user:
In the List of Users, select the check box next to the user name and click Delete.
The user name is deleted.
CA APM TG agent startup settings


Displaying CA APM TG agent availability in CA CEM
You can send information about the availability of the CA APM TG agent to the CEM
console. If the CA APM TG agent is unavailable, CA APM TG notifies CA CEM and the
event appears in the CEM console under System > Events. When the CA APM TG agent
is once again available, CA APM TG sends another notification. You can enable this
feature after installing the CA APM TG agent.
To enable CA APM TG agent notification in CEM console:
In the wtg.properties file, specify the IP address and port number of the CA CEM
host that you are sending the notifications to.
The wtg.properties file is under %WTG_HOME%\Tomcat\webapps\wtg\WEB-INF
and contains:
CEM.Tess.Host=127.0.0.1
CEM.Tess.HostPort=80
# CEM Tang notification interval. Set to -1 to disable CEM Tang notification.
CEM.Tang.Notification.Interval=-1
The notification interval is specified in seconds. The status of agents in the known
agents list is checked at this interval.
Note: If you are using shared CA CEM credentials, the CEM.Tess.Host property is
already set. In that case you just need to set the CEM.Tang.Notification.Interval
property.
To disable CA APM TG Agent notification in CA CEM:
Set the CEM.Tang.Notification.Interval to -1 to disable CEM Tang notification.
CA APM TG agent startup settings
You can define settings that control CA APM TG agent behavior. You specify these
settings in the CA APM TG agent initialization file, wtgagent.ini, located in the
<apmtg_home>/wtgagent_name directory. These settings are read in when the CA APM
TG agent starts. Some settings are set based on selections made at installation and
should not be modified.
Note: The IntroscopeSend parameter is set during installation and is only in effect the
first time the agent starts. After that, CA Introscope settings are controlled from the
Configure Agent page in the CA APM TG Administration Interface. For more information
about this tab, see Configuring the CA APM TG agent (see page 37).
Installing CA APM TG-specific CA Introscope components


The following CA APM TG agent Startup Setting entries can be modified:
LogFileSizeLimit=10000000 and LogFileRetain=5
These entries control the size in bytes of the daily activity logs and how many days
of logs should be retained. When a log exceeds the size limit, a new log is opened
with a filename containing a new timestamp. The LogFileSizeLimit is not applicable
for XML format logs.
The LogFileSizeLimit file can be found in the <apmtg_home>/wtgagent_name
directory. The LogFileRetain file can be found in the wtgagent.ini directory.
TraceFileSizeLimit=10000000 and TraceFileRetain=5
These entries control the size in bytes of the CA APM TG agent trace logs and how
many days of logs should be retained. When a log exceeds the size limit, a new log
is opened with a filename containing a new timestamp
Location=
Optional location information can be specified to identify a particular CA APM TG
agent. The entered string appears in the CA APM TG Administration Interface under
the Configuration tab, and as a CA APM TG agent metric in the CA Introscope
Investigator tree. For more information, see Configuring the agent (see page 37).
ListenPort=7700
The port that the agent will use to communicate with the CA APM TG
Administration Server.
IntroscopeMetrics=
Specify which CA APM TG metrics to send to CA Introscope. See Other metrics (see
page 92)
RTMAddress=localhost and RTMPort=7201
This is the address and port to be used when connecting to RTMCServer. This is the
CA APM TG process that polls monitored scripts. If the port is changed here then it
must also be changed in the rtm file located in the <apmtg_home>/WTGService
directory.
Installing CA APM TG-specific CA Introscope components
To use CA Introscope to monitor and display CA APM TG information, install and
configure the CA Introscope components described in Installing CA Introscope tab
views (see page 28).
The Command line and the CA APM TG agent


Installing CA Introscope tab views
CA APM TG uses tab views in the CA Introscope Investigator to summarize metric
information. You can view the same metrics data by browsing the Investigator tree
nodes. The CA APM TG-specific tab view file must be copied to the Enterprise Manager
installation location.
To install CA Introscope tab views:
1. From the CA APM TG install image, open the IntroscopeFiles\TypeViews directory.
Windows: Copy the WTGAgent-TV9.xml file.
Linux: Copy the WTGAgent-TV9.xml file from the Linux install tar file.
2. Paste the copied files into this directory:
<EM_Home>\ext\ddtv
Note: You may have to create the ddtv folder if it does not already exist in the ext
directory. Any CA Introscope Workstation that is open shows the tab views after
reconnecting to the Enterprise Manager.
The Command line and the CA APM TG agent
After the CA APM TG agent is installed, you can start, check the status, and stop the CA
APM TG agent by executing different commands from the command line. You can use
the same commands on all platforms.
Note: On Windows the CA APM TG agent runs as a service so the recommended way of
starting and stopping is via the Windows Service Control Manager.
To start the CA APM TG agent:
At the command prompt, enter:
wtgagent start <apmtg_site1>
where <apmtg_site1> is the name of the agent. This name must match the name
assigned to the agent at installation.
The following message appears:
wtgagent : <apmtg_site1> - Started
If the agent is already running when you issue the command, then the following
message appears:
wtgagent <apmtg_site1> - Already Running
Linux DHCP considerations


To check the CA APM TG agent status:
wtgagent status <apmtg_site1>
where <apmtg_site1> is the name of the CA APM TG agent. This name must match
the name assigned to the CA APM TG agent at installation.
wtgagent : <apmtg_site1> - Running
The following message appears if the agent is not running:
wtgagent : <apmtg_site1> - Not Running
To stop the CA APM TG agent:
wtgagent stop <apmtg_site1>
where <apmtg_site1> is the name of the CA APM TG agent. This name must match
the name assigned to the CA APM TG agent at installation.
wtgagent : <apmtg_site1> - Stopping
wtgagent : <apmtg_site1> - Stopped
The following message appears if the CA APM TG agent has already stopped:
wtgagent : <apmtg_site1> - Not Running
There is a problem when using the Script Editor (which only runs on Windows) when
connecting to a CA APM TG agent running on Linux that is using DHCP to acquire an IP
address as opposed to using a static IP.
If you have a static IP address, the /etc/hosts file is specified as in this example:
127.0.0.1 localhost.localdomain localhost
111.222.123.4 mylinux.ca.com mylinux
This works fine with the Script Editor, which needs to communicate with the JAVA RMI
component of CA APM TG to access scripts on the agent machine.
If you are using DHCP, the /etc/hosts is specified as in this example:
127.0.0.1 mylinux.ca.com localhost.localdomain localhost mylinux
By default Linux is configured to look in the /etc/hosts file first before accessing the DNS
to resolve a name to an IP address. The CA APM TG remote Java RMI component on
Linux listens for connections on an IP address it gets by resolving the host name. In the
case of the Linux default settings, the host name resolves to 127.0.0.1, which is the
loopback address, so any Script Editor from another machine trying to connect will fail.


Linux can be configured to first access the DNS when resolving addresses by editing the
/etc/nsswitch.conf file and specifying the hosts entry as in this example:
hosts: dns files
The result is that the host name resolves to the IP address provided by DHCP and
connections are successful.
Whether Linux is configured to use a certain name or the name is assigned by DHCP, the
requirement remains that a machine name must exist. This can be confirmed from a
terminal session by typing:
hosthame
The result should be a name, not just localhost.localdomain. After making the
modification to nsswitch.conf and restarting, execute the following command using the
name returned by hostname:
host <name>
should result in the IP address assigned by DHCP, not 127.0.0.1.


Chapter 3: Configuring the CA APM
Transaction Generator Agent

This chapter describes how to configure the CA APM Transaction Generator (CA APM
TG) agent using the CA APM TG agent Configuration. The following topics are discussed:
Overview of configuring agents (see page 31)
The CA APM TG Agent Configuration (see page 32)
Groups and scripts (see page 42)
Overview of configuring agents
The configuration of a CA APM TG agent determines which scripts a CA APM TG agent
uses to poll Web sites and also determines the polling parameters and provides various
script handling capabilities.
You connect to a CA APM TG agent using the CA APM TG agent tab. After installing an
agent, you can configure the agent and set the agent defaults.
Here is an overview of the CA APM TG agent configuration process:
1. Optionally configure the agent settings or accept the default settings. To change the
settings for all the scripts, see Setting CA APM TG agent defaults (see page 40). To
change settings for a group, see Configuring a group (see page 46).
2. Determine which web sites and web services need CA APM TG synthetic
transactions to facilitate your application monitoring strategy. Optionally, you can
create groups to facilitate the monitoring of the web sites and web services, such as
creating groups for specific sites or services. For more information, see Groups and
scripts (see page 42).
3. Create the scripts for this monitoring process. For more information, see Groups
and scripts (see page 42). Scripts detail procedures you want the CA APM TG agent
to perform against monitored web sites and web services. For information on script
creation, see Creating and Editing CA APM TG Scripts (see page 57).
4. Update the scripts in the agent. Connect to the CA APM TG agent and click the
Update Modified Scripts button on either the All Scripts tab or the Group Scripts
page (Scripts By Group > GroupName).
5. Set agent default information. When you know more about the work being done,
you can choose suitable default settings. For more information, see Setting
Hierarchy (see page 32).
The CA APM TG Agent Configuration


Setting Hierarchy
A hierarchy exists for the settings of scripts, groups of scripts, and all the scripts on an
agent. The CA APM TG agent uses groups to organize scripts. A script uses as its defaults
the settings of the group to which it belongs, unless script-specific settings are
configured in the Script Editor. A group uses as its defaults the settings of the agent it is
associated with, unless group-specific settings are configured on the Configure Group
page. You can configure both scripts and groups to use different settings, depending on
the desired polling outcome. You can keep the default agent settings or modify them
(recommended).
The configuration of a CA APM TG agent determines which scripts the agent executes,
how the agent gathers resource data, and how the agent determines the status of the
script. The Configuration tab on the CA APM TG agent View page displays the current
settings and polling statistics.
Interval settings allow you to fine tune the performance of the CA APM TG agent. The
CA APM TG agent default and polling interval settings determine the error status for the
groups and scripts associated with the CA APM TG agent. The polling interval values are
global in scope and apply to every group and script a CA APM TG agent monitors, unless
the group or script is configured with different settings. The default interval values
should be adjusted to match the worst acceptable response time.
The CA APM TG Agent Configuration displays two tabs that you can use to connect to
the CA APM TG agent you want to configure:
The Dashboard tab (see page 33)displays the users CA APM TG Shortcuts and the
List of Known Agents for quick access to CA APM TG agents
The Connect to Agent tab (see page 35)allows you to connect to new CA APM TG
agents and to edit the List of Known Agents
For details, see The Dashboard tab (see page 33) and The Connect to Agent tab (see
page 35).
When the CA APM TG Agent Configuration is configured in a standalone configuration,
the system displays a Security link to enable the administrator to manage users. For
more information, see Managing CA APM TG user access in a standalone configuration
(see page 24).


To connect to the Agent Configuration:
1. Open a web browser.
Enter the URL for the CA APM TG Agent Configuration. The URL depends on how
and where the CA APM TG Administration Server is installed. Typically it is the name
of the machine the CA APM TG Administration Server is installed on, the port
number, and the application path. See Installing the CA APM Transaction Generator
(see page 15) for details.
In the following example, the CA APM TG Administration Server machine is wtgtest,
the port number is 9090, and the application path is wtg.
http://wtgtest:9090/wtg
2. Enter the user name and password for the CA APM TG Agent Configuration.
The initial username and password depends on how the Administration Server is
configured. When sharing CA CEM credentials, the CA CEM System Administrator is
also a CA APM TG Administrator, and all other CA CEM users are CA APM TG
Operators.
When CA APM TG is installed on the CA Introscope Enterprise Manager, the CA
Introscope Administrator is also a CA APM TG Administrator. Contact your CA APM
TG Administrator for access information.
In a standalone configuration, the initial username and password for an
Administrator is cemadmin / quality. For a CA APM TG Operator, the initial
username and password is wtgoperator / quality.
The Dashboard tab
The CA APM TG dashboard displays your saved CA APM TG shortcuts and the list of
known agents.
CA APM TG Shortcuts (see page 34)allow you to navigate directly to saved
locations within the Agent Configuration for easier access to important information.
List of Known Agents (see page 35)displays the current status of an agent and
allows you to quickly connect to known agents
For details, see CA APM TG Shortcuts (see page 34) and List of Known Agents (see
page 35).


CA APM TG Shortcuts
For quicker access to pages with information of particular interest to you, add the pages
to your list of shortcuts in the CA APM TG Shortcuts pane in the Dashboard tab. When
the Add to CA APM TG Shortcuts link appears on a page of the Agent Configuration, you
can add that page to the shortcut list.
To add an item to the CA APM TG Shortcuts:
1. Navigate to the CA APM TG agent tab that you want to add to the shortcuts list:
Scripts By Group tab
All Scripts tab
Status Messages tab
Configuration tab
Note: By default, each user already has a shortcut to the Connect to Agent tab.
2. Click the Add to CA APM TG Shortcuts link at the top right of the page.
3. The Add to CA APM TG Shortcuts page opens.
The name of the page to be added and the agent host name are in the Name field
by default. You can accept the default shortcut name, or rename the shortcut to a
unique name of your choice. To revert to the default name, click Reset.
4. Click Save.
A confirmation message displays on the page to indicate that the shortcut was
added.
5. Click the Return to link to return to the previous page.
The next time you visit the Dashboard, the new shortcut will be in your CA APM TG
Shortcuts list.
To remove an item from the CA APM TG Shortcuts:
1. Navigate to the Dashboard in the CA APM TG agent Configuration.
2. In the CA APM TG Shortcuts section, click the Edit button to display the Edit CA
APM TG Shortcuts page.
3. Select the check box next to the shortcut link to be removed.
You can select more than one link at a time.
4. Click Delete.
The shortcuts are deleted from your Shortcut list.


List of Known Agents
The List of Known Agents displays a list of known agents and their status. If your agent is
in this list, click on the link in the Agent Port column to access the agent. Use the
Refresh button to display the current Error Status. Use the Edit button to delete agents
from the list. The Edit button is only available to CA APM TG Administrators. For
information about error status, see Checking the error status of agents. (see page 36)
The Connect to Agent tab
The CA APM TG Connect to Agent tab enables you to connect to a CA APM TG agent.
There are two panes on the Connect to Agent tab:
Connect to Agent allows you to connect to any CA APM TG agent when you know
its host and agent port. Use this pane to connect to an agent that is not on the List
of Known Agents. To connect to a CA APM TG agent that is not on the List of Known
Agents, see Connecting to an Agent (see page 35).
List of Known Agents displays the current status of an agent and allows you to
quickly connect to known agents. For more information, see List of Known Agents
(see page 35).
Connecting to an Agent
To use the Agent Configuration to configure a CA APM TG agent, you must first connect
to the CA APM TG agent. Once you connect to a CA APM TG agent in the Agent
Configuration, you can access the agent by clicking a link in the List of Known Agents on
the Dashboard or the Connect to Agent tab.
To connect to a CA APM TG agent the first time:
1. Navigate to the Connect to Agent tab in the Agent Configuration.
2. In the Agent Host field in the top section, enter the name of the machine where the
CA APM TG agent was installed.
3. In the Agent Port field, enter the port for the agent.
4. Click OK.
The system attempts a connection to the CA APM TG agent. If the connection is
successful, the CA APM TG agent View page displays and this CA APM TG agent is added
to the List of Known Agents. The next time you visit the Dashboard or Connect to Agent
tab, this agent appears in the list. See also The CA APM TG agent View page (see
page 36).


The CA APM TG agent View page
The CA APM TG agent View page displays the following tabs:
Scripts By Group: Displays information about the groups on the agent. Controls for
creating, deleting, and displaying the scripts in a group are here. For more
information on the Scripts By Group tab, see The Scripts By Group tab (see
page 43).
All Scripts: Displays all the scripts associated with the agent. For more information
on scripts, see Viewing all scripts in all groups (see page 48).
Status Messages: Displays recent messages for the selected agent. You can specify
the number of messages to display on the Configure Agent page. The default is 100.
Use the Clear Last Message button on this tab to clear the Last Message field at the
bottom of all CA APM TG agent view pages. For more information, see Viewing
status messages (see page 55).
Configuration: Displays the current settings of the agent. Controls for setting
default parameters for the agent, resetting counters, and for sending scripts to CA
CEM are here. For more information about default settings, see Configuring the CA
APM TG agent (see page 37) and Using Configuration Tab buttons (see page 41).
Checking the error status of agents
The List of Known Agents indicates the current error status for each agent listed. The
error statuses are:
this indicator lets you know the agent is running normally.
this indicator lets you know the agent is running and has detected an error
with one or more scripts. Script errors include the HTTP status code error and a
response that exceeds the specified timeout value.
the indicator lets you know the status of the agent is unknown, which usually
means the agent is not running or cannot communicate with the CA APM TG
Administration server.
Removing agents
The following section explains how to remove agents from the List of Known Agents.
To remove a CA APM TG agent from the List of Known Agents:
1. Navigate to the Connect to Agents tab.
2. Select the agent in the List of Known Agents and click Delete.
The agent is removed from the List of Known Agents.


To remove all CA APM TG agent:
Select the check box next to the column heading Select and click Delete. All agents
will be removed from the List of Known Agents.
Note: Because the List of Known Agents is shared by all users of this CA APM TG
agent Configuration, only a CA APM TG Administrator can delete CA APM TG agents
from the List of Known Agents.
Troubleshooting connecting to an agent
This table provides some tips that might help you troubleshoot connecting to a CA APM
TG agent.
Symptom: The CA APM TG agent doesnt appear to be running.
Possible Solution: Make sure the agent you are trying to connect to is up and
running. To display the status of a CA APM TG agent, run the following command on
the agent machine:
wtgagent status <agentname>
where <agentname> is the name of the agent. For example:
wtgagent status apmtg_site1
Symptom: The agent host machine isnt reachable.
Possible Solution: To check if the agent host machine is reachable, run the
following command:
ping <agenthost>
where <agenthost> is the name of the machine running the agent.
Configuring the CA APM TG agent
This section describes how to configure the CA APM TG agent to work with CA CEM and
CA Introscope, in addition to setting general settings about polling and logging.
To set agent configuration settings:
1. Connect to the CA APM TG agent you want to configure.
See Connecting to an agent (see page 35) for more information.
2. Once the CA APM TG agent has been connected, navigate to the Connect to Agent
> AgentPort > Configuration tab > Configure Agent, where AgentPort is the port of
the agent being configured. The Configure Agent page opens.
3. Set the default values for the CA APM TG agent and click Save. To return the
settings to a previously saved state, click Reset.
Complete the fields found on the Configure Agent page. For more information
about these fields, see CA APM TG agent configuration fields and descriptions (see
page 38).


CA APM TG agent configuration fields and descriptions
When you configure the CA APM TG agent, you can set properties for these
components:
CA CEM Integration
Enterprise Manager Host NameThe IP address or name of the Enterprise
Manager. This is required if you want to send scripts to CA CEM for automatic
creation of business services.
Enterprise Manager Host PortThe host port of the Enterprise Manager. This
is required if you want to send scripts to CA CEM for automatic creation of
business services.
CA CEM Application NameThe name of the application in CA CEM to
associate with scripts that are sent to CA CEM and the business services that
are created from them. If left blank, the default CA CEM application is used. If
you enter an application name that does not exist on CA CEM, it will be
created. You can change the application name at any time in CA CEM.
Note: To send all scripts to CA CEM, see Using Configuration Tab buttons (see
page 41). To send a single script to CA CEM, see Working with scripts in the
Script Requests page (see page 49).
CA Introscope Integration
Send Data To CA IntroscopeThis setting determines if the CA APM TG agent
sends information to CA Introscope. By default, the CA APM TG agent does
not send data to CA Introscope unless you configure it to do so. This can be
done during CA APM TG agent installation or using the Agent Configuration.
When this feature is disabled, no data is sent to CA Introscope. CA APM TG
continues to drive synthetic transactions, but does not send information to CA
Introscope. When this feature is enabled, monitored scripts and script
information are reported and are available to view in CA Introscope. Enable
this feature by selecting Yes.
General Settings
Counter Auto Reset Interval (Days)Determines how often counters are reset.
Initial Concurrent PollsThe initial number of concurrent polls performed by
the agent. The agent schedules the Initial Concurrent Polls value plus the
number of items in error status up to the Maximum Concurrent Polls value.
Maximum Concurrent PollsThe maximum concurrent polls to be performed
by the agent. The agent schedules the Initial Concurrent Polls value plus the
number of items in timeout status up to the Maximum Concurrent Polls value.
Status Message Table SizeDetermines how many entries are kept in the
message table. The message table contains entries for all script activity,
including adding, deleting, disabling scripts, and any resulting errors. You can
view the message table on the Status Messages tab.


Agent Log Settings
Agent Log FormatSpecifies the format for the monitored scripts logs. When
a poll completes for a script, statistics are written to a log. The monitored script
logs are in the <apmtg_home>\log\wtgagent_apmtg_site1 directory. The
default is a text log with entries delimited by a vertical bar. If XML is selected,
the log is written in XML format.
Agent Log Trace LevelControls the level of detail in the CA APM TG agent
trace log. The following options are available:
Info
Warning
Critical
Debug
Debug2
Debug3
Note: The Debug settings are used for in-depth tracing of CA APM TG. If you
are working with CA APM Support to triage a problem, the support group may
request a specific debug level.
The trace log is located in the <apmtg_home>\wtgagent_apmtg_site1
directory.
CA APM TG agent performance settings example
The following is an example of how the CA APM TG agent uses the Initial Concurrent
Polls and Maximum Concurrent Polls settings.
Suppose the CA APM TG agent is monitoring 300 scripts; the Initial Concurrent Polls
value is set to 10, and the Maximum Concurrent Polls value is set to 30. Suppose 15
scripts are in timeout status. The CA APM TG gent polls as many as 25 scripts
concurrently. Now, suppose the number of scripts in timeout status climbs to 40. The
agent polls as many as 30 scripts concurrently.
The CA APM TG agent reaches "too busy" status when it is unable to complete the next
concurrent poll within the interval. To remedy the situation, you could adjust the
default polling intervals. Alternatively, you could increase the values for the Initial
Concurrent Polls and Maximum Concurrent Polls.
Note: When the Configuration Tab indicates a Busy Status of "Agent Is Too Busy," it
indicates that the CA APM TG agent is too busy to poll a URL at the requested interval.
Each time the CA APM TG agent is ready to poll an item, it checks the previous time
stamp to determine if the interval is greater than 110 percent of the specified interval.
For example, if the polling interval is 60 seconds, and 70 seconds have passed before the
CA APM TG agent performs the next poll, the CA APM TG agent increments the too-busy
count.


Setting CA APM TG agent defaults
The CA APM TG agent default settings are used when a new group is created either
automatically by specifying a group name in the Script Editor Recorder or by using
Create Group (see Creating a group (see page 45)). Once created, the group settings can
be modified on the Configure Group page (see Configuring a group (see page 46) for
details). Use the Set Agent Defaults page to change the CA APM TG agent default
settings. There are two sections on the Set Agent Defaults page:
The Interval settings affect how often a script is run.
The General settings affect script execution.
To set CA APM TG agent defaults:
1. Navigate to Connect to Agent > AgentPort > Configuration tab > Set Agent
Defaults. The Set Agent Defaults page opens.
2. Set the desired default values. To return the settings to a previously saved state,
click Reset.
Interval Settings
Changing the default settings allows you to adjust the polling interval. For example, you
may not want to let 300 seconds pass between polls when a web site or service has a
timeout status. Adjust the Error Interval to indicate the number of seconds between
polls when a web site or service has a timeout status.
The Interval Settings section of the Set Agent Defaults page contains these fields:
Polling Interval (sec)Specifies the number of seconds between polls when the
script's status is Normal.
Error Interval (sec)Specifies the number of seconds between polls when the
script's status is Critical.
Timeout Value (ms)Specifies the expected response time, in milliseconds. If the
threshold is reached, the script's status changes to indicate an Error.


General Settings
The following table describes the fields in the General Settings section of the Set Agent
Defaults page:
Detail LevelSpecifies which URL components to request. Set the detail level of
monitoring for web pages. The following options are available:
Page+Frames: requests the page and any frames that may be on that page.
Page+Components: requests the page and all the image components on that
page.
PageOnly: requests only the initial page.
Max ConnectionsDetermines how many simultaneous connections are used for
requesting components when Detail Level is set to anything other than PageOnly.
Max Connections are limited to 20 total.
Note: Depending on network traffic, you may improve the polling performance by
increasing this value.
Bypass ProxyDetermines whether a proxy server is used when retrieving a URL.
Select Yes to bypass the proxy server defined in the RTMCServer configuration or
No to use the proxy server. The default setting is No.
Note: A proxy server may have been specified in the RTMCServer configuration in
order to access the internet, but some URLs may be on web servers within a
corporate network and not accessible to the proxy. You can avoid using proxy
servers by setting Bypass Proxy to Yes.
Using Configuration Tab buttons
Use buttons on the Configuration tab to perform immediate actions on the counters and
scripts associated with the agent:
Configure AgentClick to set the basic configuration values to for a CA APM TG
agent. For more information, see Configuring the CA APM TG agent (see page 37).
Set Agent DefaultsClick to set the default values for a CA APM TG agent. For more
information, see Setting CA APM TG agent defaults (see page 40).
Reset CountersClick to reset the counters for all your groups. This sets all scripts
with critical counts back to zero, returning them to a Normal status.
Send All Scripts to CA CEMClick to send all scripts associated with the CA APM TG
agent to CA CEM for monitoring. The next time each script polls successfully, it is
sent to CA CEM for automatic business process creation.
Groups and scripts


Groups and scripts
Groups are containers for scripts. You can use groups to collect similar scripts, such as
scripts that refer to a specific web site or service or scripts that are monitored for
mission-critical functions. A group can contain any number of scripts. You specify the
name and description for a group and then add scripts to it. For more information, see
The Scripts By Group tab (see page 43) and Viewing scripts in a group (see page 47).
Important! Scripts use the interval settings for the group to which they belong, unless
the script contains its own settings specified via an <attributes> tag. To configure group
threshold and interval settings, see Configuring a group (see page 46).
Groups and scripts


The Scripts By Group tab
The Scripts By Group tab lists all groups associated with the selected CA APM TG agent,
including the group names and descriptions, error status, the number of scripts in the
group, the number of scripts with an error status, and the number of enabled scripts.
To display groups by status:
Click the relevant Show link to display groups that have Normal, Error, or Disabled
status.
To search for groups:
1. In the Search For dropdown list, choose to search by either the group name or part
of the description.
2. In the Keywords field, enter a portion of the group name or description.
The keywords search is not case sensitive and does not support wildcard regular
expressions.
3. Click Go.
The table is updated to list the groups matching the specified criteria.
You can perform the following in the Scripts By Group tab:
Creating a group (see page 45)
Configuring a group (see page 46)
Enabling, disabling, resetting, or deleting a group (see page 46)
Viewing scripts in a group (see page 47)
The Scripts By Group tab contains these fields:
SelectThis column allows you to disable, enable, reset, or delete a group,
multiple groups, or all groups. The delete operation is only available to CA APM
TG Administrators.
Error StatusIndicates the overall status of the groups monitored by the
agent. The status of each group is propagated up to the overall agent status. If
the status of any group is Error (timeout), then the overall status is displayed as
Error:
rederror status
greennormal status
grayunknown (unavailable)
Group NameThe name of the group. Click on the Group Name to display the
Group Scripts page which lists the scripts in the group.
Script CountIdentifies the number of scripts in each group.
Error CountIdentifies the total number of scripts that in each group that are
in Error status.
Groups and scripts


EnabledIdentifies the total number of enabled scripts in each group.
DescriptionIdentifies the group description.
Groups and scripts


Creating a group
A group can contain any number of scripts. You can specify the name and description for
a group here and then add scripts to it. You can also specify the name of a group in the
Script Recorder. If that group doesnt already exist when you enter it in the Script
Recorder, the agent automatically creates it.
The fields available when creating or configuring a group are the same as those for
setting the agent defaults. However, these additional fields are available:
Group NameGive a unique meaningful name to the group. Group Names are case
sensitive
DescriptionSpecifies a text string that provides additional information about the
group being created or configured.
SecurityIf basic authentication is required to access the web sites accessed by
scripts in this group, enter the user name and password here delimited by double
quotes(""). For example:
"Username" "Password"

For more information, see Setting CA APM TG agent defaults (see page 40).
Tip: Specifying security at the group level rather than in the script makes it easy to
update multiple scripts.
To create a new group:
1. From the Connect to Agent tab > AgentPort > Scripts By Group tab, click the Create
Group button. The Create Group page opens.
Note: The Create Group button is only available to CA APM TG Administrators.
2. Enter the group information and accept or change the interval settings, then click
OK.
Note: Initially, the Create Group page displays the CA APM TG agent default values
for the fields. You can accept these defaults, or change them as appropriate for this
group.
The command to create the group is sent to the CA APM TG agent. The CA APM TG
agent View page appears with a message indicating if the command was successfully
sent.
The Scripts By Group tab displays immediately. If the new group does not appear in the
list, it indicates that the CA APM TG agent is in the process of creating the group. Wait a
moment or two, then press the Refresh button to refresh the group list. If the group still
is not in the list, verify that the Show setting is either All Groups or Normal Groups. The
Last Message field may display a message indicating that the group was added or
explaining why the group could not be added.
Groups and scripts


Configuring a group
After a group is created, you can change the group settings, or add or delete scripts in
the group. For more information, see Creating a group (see page 45) for details about
fields.
To configure a group:
1. Navigate to the Connect to Agent tab > AgentPort > Scripts By Group tab.
2. Click the name of the group to configure.
The Group Scripts page opens, listing the scripts in the selected group.
3. Click the Configure Group button.
The Configure Group page opens.
4. Modify the group settings as desired and click Save. To reset the group settings to
their initial values, click Reset.
The new settings are applied to each script in the group that is not individually
configured. To adjust the settings for a script, see Creating and Editing CA APM TG
Scripts (see page 57).
Enabling, disabling, resetting, or deleting a group
You can enable, disable, reset, or delete individual groups or all groups at one time.
To enable, disable, reset or delete groups:
2. Select the check box next to the group or groups you want.
3. Click the desired action link: Enable, Disable, Reset, or Delete.
Note: The delete operation is only available to CA APM TG Administrators.
The Scripts By Group tab refreshes and displays the current status of all groups.
Groups and scripts


Viewing scripts in a group
You can view the scripts in each group.
To view the scripts in a group:
2. Under Group Name, click the name of the group.
The Group Scripts page opens displaying the scripts in the selected group. The
following fields provide details about scripts:
SelectThis column allows you to disable, enable, reset, or delete a scripts.
Note: The delete operation is only available to CA APM TG Administrators.
Error StatusIndicates the current error status.
ScriptThe name of the script. Click the name of the script to open the Scripts
Request detail page, where script settings are displayed.
Last PollIdentifies the time of the last poll.
%AvailIdentifies the percentage of the time the script was available (not
critical) since the last reset.
Error CountIdentifies the number of polls with errors since the last reset.
DescriptionThe script description.
You can select specific scripts on the Group Scripts tab and Enable, Disable, Reset,
or Delete the script. The Delete function is available only to CA APM TG agent
Administrators.
The All Scripts tab
The All Scripts tab lists all the scripts in all groups for the selected CA APM TG agent,
including the script names and descriptions, error status, when last polled, availability
percentage, and the error count.
You can perform the following in the All Scripts tab:
Viewing all scripts in all groups (see page 48)
Adding a script to a group (see page 48)
Enabling, disabling, resetting, or deleting a script (see page 49)
Groups and scripts


Viewing all scripts in all groups
You can view all scripts in all groups in the All Scripts tab. You can also view scripts by
status and search for scripts.
To display scripts by status:
Click the relevant Show link to display scripts that have Normal, Error, or Disabled
status.
To search for scripts:
1. In the Search For dropdown list, choose to search by script name, group name, or
part of the description.
2. In the Keywords field, enter a portion of the script name or description.
The keywords search is not case sensitive and does not support wildcard regular
expressions.
3. Click Go.
The table is updated to list the scripts matching the specified criteria.
Adding a script to a group
To add a script to a group, you must first create the script with the Script Editor and
specify the group in either the Script Editor or in the <script> tag. After adding a script to
a group, you can load the script into the agent for execution with either of two
methods:
Update Modified ScriptsClick to update all scripts that have been changed and
saved using the Script Editor to the CA APM TG agent. This command does not load
scripts that have not been changed.
Important! If you make changes to a script without using the Script Editor, the CA APM
TG agent will not recognize that the script has changed. In that case, you will have to
reset all scripts. We recommend you use the Script Editor to make changes to scripts.
Reset All ScriptsClick to reset all scripts associated with the CA APM TG agent. All
scripts currently in the agent will be deleted and reloaded.
For more information on creating and using scripts, see Creating and Editing CA APM TG
Groups and scripts


Enabling, disabling, resetting, or deleting a script
You can enable, disable, reset, or delete individual scripts or all scripts at one time.
To enable, disable, reset or delete scripts:
1. Navigate to the Connect to Agent tab > AgentPort > All Scripts tab.
2. Select the check box next to the script or scripts you want.
3. Click the desired action link: Enable, Disable, Reset, or Delete.
Note: The delete operation is available to CA APM TG Administrators only.
The All Scripts tab refreshes and displays the current status of all scripts.
Working with scripts in the Script Requests page
The following section describes how to modify script settings without using the Script
Editor, using the Script Requests page. For information about modifying the content of a
script, see Creating and Editing CA APM TG Scripts (see page 57).
Note: Modifying script settings does not modify the content of the script; it only
changes the settings that affect script execution.
To modify script settings:
1. Access the script to be modified from the Scripts By Group tab or the All Scripts
tab.
2. Click the name of the script to be modified.
The Script Requests page opens, with the name of the script at the top of the page.
The Script Requests page allows you to do the following:
RefreshClick to refresh the information presented on the page.
Test Script NowClick to perform an immediate poll against the script. For
details, see Viewing status messages (see page 55).
ResetClick to reset all the counters for the script to zero, returning the script
to normal status.
DeleteClick to delete the script from the CA APM TG agent.
Note: The delete operation is only available to CA APM TG Administrators. This
does not delete the script file itself, only removes it from the CA APM TG agent.
DisableClick to disable the script. The script is not executed and no data is
collected.
Note: This is a toggle button. If the script is disabled, the button says "Enable";
click to enable the script.
Groups and scripts


Send Script to CA CEM Click to send this script to CA CEM for monitoring.
After clicking, the script executes. If the script completes successfully it is then
sent to CA CEM for automatic business process creation.
View Request DetailsClick a request URL to view details of that request.
The Script Requests page has sections at the bottom of the page that contain more
information about the script:
Load Rampingprovides you with the ability to configure and execute load
ramping. For details about load ramping, see Load ramping (see page 52).
More Detailsprovides you with more details about the script, such as if the
script is enabled or not, when the script was last modified using the Script
Editor, and polling statistics.
Current Global Attributesdisplays the current settings for the script. These
settings are configured when a script is created.
For more information about these settings, see Creating and Editing CA APM TG
Viewing script request details
The following section describes how to view additional script request details.
To view script request details:
From Script Requests page click a URL hyperlink in the URL column.
The Script Request Details page opens and lists the results for a specific request poll
including the following information:
ResponseIndicates the current response status.
%AvailIdentifies the percentage of time that the URL is available, the
number of polls versus the number of timeouts.
First Byte (ms)Indicates the request URL on the Script Requests page. It
shows elapsed time in milliseconds, from the time the request is made to
the time the first byte of data is received.
Min/Avg/MaxIndicates the minimum, average, and maximum time in
milliseconds, calculated since the last reset for first byte.
Last Byte (ms)Indicates the elapsed time in milliseconds, from the time
the request is made to the time the last byte of data is received.
Min/Avg/MaxIndicates the minimum, average, and maximum time in
milliseconds, calculated since the last reset for last byte.
Poll/ErrorIndicates the number of polls and errors recorded since the
last reset.
Groups and scripts


AccuracyIndicates the current accuracy status for CRC, content, or length. For
more information about accuracy checking, see Creating and Editing CA APM
TG Scripts.
CheckSpecifies how the content retrieved from the URL is being verified.
You can choose a quoted string, a CRC check, or None. The default is none.
First DetectedIndicates the time when the content check failure first
occurred.
Expected CRCIndicates the CRC used to check the data received.
Actual CRCIndicates the CRC computed from the data received.
Size (bytes)Indicates the size of the returned page in bytes
Auto CRC ResetSpecifies whether this option is in effect or not.
Note: Used only when a CRC content check is being performed.
Copy CRCClick to copy the value for Actual CRC to Expected CRC.
Additionally, the Script Request Details page has the following sections at the bottom
that contain more information about the request:
ComponentsProvides you with statistics on the URLs components. Note: The
components retrieved are determined by the Detail setting.
More DetailsProvides you with more details on the request. such as the
settings used, connect time, and ping time.
Testing a script
You can force immediate polling of a script to make sure it is properly configured.
Polling of a script generates synthetic transactions. You can send these scripts
containing synthetic transactions to CA CEM or CA Introscope for monitoring. See
Viewing CA APM TG data with CA Introscope (see page 91) and Viewing CA APM TG
data with CA CEM (see page 96).
To test a script:
1. Access the script to be modified from the Scripts By Group tab or the All Scripts
tab.
2. Click the name of the script to be tested.
The Script Requests page opens.
3. Click the Test Now or Test Script Now button. The previous page is displayed with a
confirmation message indicating that the test command was sent to the CA APM TG
agent.
Groups and scripts


Sending scripts to CA CEM
To send all scripts to CA CEM, see Using Configuration Tab buttons (see page 41). To
send a single script to CA CEM, see Working with scripts in the Script Requests page (see
page 49).
Note: CA APM TG scripts can be sent to a MOM or a Collector running the TIM Collector
Service. However, the MOM or Collector must be running the TIM Collector Service.
Load ramping
Use the load ramping feature of CA APM TG to generate a load against a web
application to test how well the application handles changes in load.
The following sections describe load ramping:
Configuring and launching load ramping (see page 52)
Checking load ramping status (see page 54)
Load ramping example (see page 54)
Configuring and launching load ramping
You can configure load ramping in various ways to create different load scenarios, such
as a gradual increase in load over time or a sudden burst of activity in a short period of
time.
A long ramp interval combined with a small ramp increment results in a gradual load
slope. A short ramp interval combined with a large ramp increment results in a "burst"
load slope. Once defined, the same load ramp can be repeated at any time to produce
consistent test measurements with monitoring tools such as CA CEM and CA
Introscope.
To configure and launch load ramping:
1. From the All Scripts tab, click on the script name. (You can also navigate to the
script name from the Scripts By Group tab.)
The Script Requests page opens.
2. In the Load Ramping section, click the Configure button.
Groups and scripts


3. Enter the configuration settings.
The settings are described here:
Ramp Interval (sec): The interval that the CA APM TG agent uses to schedule
additional instances of this script for execution. The Ramp Interval is the time
lapse between each incremental increase in the number of replicated scripts.
This setting controls the speed at which you want CA APM TG to add copies of
this script to the ramp process.
Ramp Increment: The number of copies of this script to add at each ramp
interval. Set the Ramp Increment to the number of copies of this script to be
replicated at each ramp interval.
Ramp Maximum: The total number of scripts to replicate. Once this number
has been reached no additional scripts will be added. Set the Ramp Maximum
to the total number of scripts you would like to run.
Note: Ramp Maximum is limited to 100.
Ramp Poll Interval (sec): How frequently the generated scripts will poll. Set the
Ramp Poll Interval to the frequency of execution of the scripts.
Ramp Maximum Polls: The number of times the generated scripts will poll at
the specified Ramp Poll Interval. Once the Ramp Poll Max has been reached,
the generated script will be set to the disabled state and stop polling. Set the
Ramp Maximum Polls to the number of times you would like each script to run.
Ramp Group Name: By default the generated scripts are placed in a group with
a name consisting of the object identifier with a suffix of _loadramp. You can
change this group name so you can compare the results of multiple runs of load
ramping with different settings.
Delete When All Complete: When set to no, all generated scripts remain in
their respective load ramping groups after all polling is complete, which allows
you to review their final status. The load ramp group is then disabled. When set
to yes, the generated load ramping group and all generated objects are deleted
when polling is complete. If the final poll status of the generated scripts is not a
concern, set to yes.
Run At Hour (0-23): / Minute (0-59): Set the time when the load ramp begins.
If there is no time set, load ramping starts only when manually started using
the Start Now button on the Scripts Request page. If you enter a time that is
earlier than the current time, the time is scheduled for the next day.
Note: The time is used only once and then removed. To repeatedly execute
load ramping, see CA APM TG command line utility (WTGUtil) (see page 101).
4. Click Save to save your settings.
You are returned to the Script Requests page.
5. If you didnt enter a time for the load ramp to begin automatically, click on the Start
Now button in the Load Ramping section to launch the load ramp.
Groups and scripts


Checking load ramping status
After load ramping has started, the Load Ramping section on the Script Requests page
shows the current settings.
The Start Now button becomes a Stop Now button to disable any executing load
ramp process.
You can click on the Stop Now button to disable or delete the generated ramping
group. (If Delete When All Complete is set to yes, the load ramp group is deleted
rather than disabled.)
The Configure button is disabled because settings cannot be changed once the
process has started.
The Current Ramp Count indicates how many scripts have been generated up to the
Ramp Max.
If a start time was set, the Will Start At: field shows the time the load ramping will
start.
The usual detail fields for the script are also displayed, indicating the number of polls,
last time polled, and next poll time.
Load ramping example
If the following settings are used to configure load ramping, the load ramping will begin
at midnight after these configuration settings are saved. Scripts are generated every 10
seconds until 100 scripts have been loaded and finish polling. Every 10 seconds the
number of scripts generated increases by 5 (the Ramp Increment amount). Each script
continues to poll at the Ramp Poll Interval of 5 seconds until the Ramp Maximum Polls
count of 20 has been reached. As each generated script reaches its Ramp Maximum Poll
count, it will disable and stop polling. When all generated scripts in the load ramp group
have stopped, then the group will show a disabled status (because the Delete When All
Complete option was set to No).
Ramp Interval: 10 (a clone of the script is generated every 10 seconds)
Ramp Increment: 5 (the number of clones increases by 5 every 10 seconds)
Ramp Maximum: 100 (the number of clones increases by 5 every 10 seconds until
100 scripts have been loaded)
Ramp Poll Interval: 5 (each script polls every 5 seconds)
Ramp Maximum Polls: 20 (each script polls every 5 seconds until it has polled 20
times)
Ramp Group Name: test_loadramp
Delete When All Complete: No
Run At Hour: 0
Minute: 0
Groups and scripts


Suppose the first script generated is called test_one_ID01. After the specified Ramp
Interval of 10 seconds, a clone of this script (named test_one_ID02) will be generated. In
the meantime, test_one_ID01 has polled twice (the Ramp Poll Interval is 5 seconds).
Additional scripts are generated until the Ramp Maximum of 100 is reached.
Viewing status messages
Status messages can give you insight into the cause of script problems.
To view status messages:
Navigate to the WTG Connect to Agent tab > AgentPort > Status Messages tab,
where AgentPort is the port of the agent whose status messages you want to view.
The Status Messages tab opens for the selected agent. This tab displays all
messages recorded for the selected agent, regarding all scripts associated with the
agent. You can search for status messages using the search fields at the top of the
tab.
All script activity is logged here, such as adding, deleting, or disabling a script. At the
bottom of every script detail page there is a Last Message field that contains the
last activity for the script as recorded by the CA APM TG agent. This message will
remain until replaced by another one.
To clear the Last Message from the Status Message page:
Click the Clear Last Message button at the top right side of the tab.


Chapter 4: Creating and Editing CA APM TG
Scripts

The Script Editor lets you view, create, modify, and delete scripts. The Script Editor uses
a special set of Extensible Markup Language (XML) tags to build a script the CA APM
Transaction Generator uses to generate synthetic transactions.
Starting the Script Editor (see page 57)
Using the Script Recorder (see page 59)
Using a script template (see page 69)
Manually creating scripts (see page 70)
Deploying scripts to multiple agents (see page 74)
Securing scripts (see page 76)
Securing access to the Script Editor (see page 77)
XML tag syntax (see page 78)
XML special character substitutions (see page 83)
Script samples (see page 83)
Starting the Script Editor
The Script Editor runs on Windows only. It comes installed with the CA APM TG agent
component, although it can be installed separately.
To start the Script Editor:
1. On a Windows machine, navigate to Start > Programs > CA APM Transaction
Generator > Script Editor.
The CA APM TG Script Editor opens. The Script Editor main window consists of the
following:
Title barDisplays the name of currently loaded script.
Menu barProvides commands for editing and maintaining scripts.
ToolbarProvides buttons for commonly-used commands. Hover over each
button for a tooltip identifying the button.
Edit paneDisplays the XML for your script. This pane is located at the top
portion of the window below the toolbar.
Errors paneDisplays errors after you perform a syntax check. This pane is
located below the Edit pane.
Starting the Script Editor


Creating a script
A script consists of one or more request specifications. Each request is submitted
sequentially and must minimally contain a URL. You can define variables to be parsed
from the page content returned from a request. Variables that are parsed from one
request are available for use in subsequent requests.
Note: If you do not configure a CA CEM business application, then any CA APM TG
scripts sent to CA CEM will be associated with the CA CEM default application, which is
included with CA CEM in the original configuration. (If the CA CEM default application
does not exist in CA CEM, then a new CA APM TG Application will be created when CA
APM TG scripts are sent to CA CEM.)
The Script Editor provides the following ways to build XML scripts:
Using the Script RecorderUse this method if you want the Script Editor to record
transactions, including posting and getting data requested from web sites. For
example, record multiple transactions to simulate how a user might complete an
order, view the status of an order, or request technical support. When you finish
your transactions, save the script and then load it into the CA APM TG agent to test
it on a specified interval.
For more information on using the Script Recorder to create scripts, see Using the
Script Recorder (see page 59).
Note: This is the recommended method for creating scripts. With the increasing
complexity of web applications, it is extremely difficult to manually create a script.
Using a Script TemplateUse this method if you want to quickly create a script for
just a single URL. A template includes the minimum number of tags for a script. Use
the commands in the Edit Insert menu to add script parameters, requests, request
tags, and conditions.
For more information on using a Script Template to create scripts, see Using a script
template (see page 69).
Manually Creating ScriptsUse this method after you have become an XML and
Script Editor tag expert. The commands in the Edit Insert menu provide some tag
generation features that you can add to your script.
For more information on manually creating scripts, see Manually creating scripts
(see page 70).
Using the Script Recorder


Due to the complex nature of modern web applications, it is easier to record a script of
the actions you want to perform rather than code this information in the Script Editor.
You can easily create a script by turning on the Script Recorder and executing
transactions on a web site as a user would from a web browser.
Recording a script is done in two steps:
Configuring the Script Recorder (see page 59)
Starting the recording session (see page 63)
Note: You must configure the Script Recorder before the first use.
Configuring the Script Recorder
The CA APM TG Script Recorder lets you create scripts by recording the actions you take
from your browser. The Script Recorder acts as a proxy to capture URLs and posted
data.
By default, the Script Recorder uses the proxy settings specified in the browser specified
by Browser Type. If you want to change those settings, or if you use a Browser Type of
Other, you must configure the CA APM TG Script Recorder. If your proxy server requires
authentication, you must specify that information in the Recorder Configuration.
Note: The Script Recorder works with HTTP and HTTPS protocols only. The Script
Recorder does not support automatically detecting settings or automatic configuration
of scripts.
To configure the Script Recorder:
1. From the open Script Editor, navigate to Settings > Recorder Configuration.
The Configure Recorder dialog box opens.
2. Specify changes and click OK.
You can configure the following properties:
Recorder PortEnter the number of the port that the recorder will use to
listen to the session. Change the default if this port is already in use by another
application.
Recorder SSL PortEnter the number of the port that the recorder will use to
listen for HTTPS requests. Change the default if this port is already in use by
another application.


Use WininetSelect this check box if Integrated Windows authentication is
being used by the web server or by the proxy.
Note: Wininet functionality is not available on the Linux platform. If you create
a script that requires Wininet functionality, you will only be able to execute it
on a CA APM TG agent running on Windows
NTLM User and PasswordWhen Use Wininet is enabled, you must supply the
User name and Password for web server authentication.
Connection TimeoutEnter the time, in seconds, that the recorder should wait
to connect to a web server.
Bypass any proxy settingsCheck this option if you have proxy information
specified in your browser but you do not want the recorder to use these
settings.
SSL VersionSelect the check box next to the SSL versions supported by the
web server. By turning on both SSLv2 and SSLv3, you will be able to record on
the largest number of web servers.
Note: Specify SSLv3 if the web server is the IBM WebSphere version or the
Apache web server.
Log LevelEnter 1 to create a basic log file. Enter 2 or 3 to get a more detailed
log. A log level of 3 is recommended and is the default. The log name is the
script name and is located in <apmtg_home>/ScriptEditor/log directory.
Browser TypeChoose the appropriate browser to enable automatic proxy
setting modification and browser opening. If you are using one of the
supported browsers, the script recorder automatically extracts HTTP proxy and
SSL proxy settings from the browser configuration. Any proxy and proxy port
information specified in the recorder configuration will override any settings
that the recorder retrieves from the browser.
Choose from the following:
Other: Select to indicate a browser other than the supported versions of
Internet Explorer or Firefox. You must modify the browser connection
settings manually. For example, in your browser configuration, indicate
that you want to use a proxy server and specify Localhost as the name of
the proxy server. Additionally, when you specify the port used by the
LocalHost proxy, you must specify that same port number in the Recorder
Port field.
Internet Explorer 6.x, 7.x: Select to indicate IE 6.x and above.
Firefox 1.5, 2.X: Select to indicate FireFox 1.5 and above.
Note: For Firefox, you can specify a Firefox Profile Name if you have defined
one.


Encrypt ConfigurationSelect this check box to encrypt the configuration file.
You might want to do this if your proxy server requires security information
such as the user name and password. Leave the check box blank to leave the
configuration file unencrypted.
Note: The following proxy information is required if you specified Other for
Browser Type and you require a proxy to access the web server you are going
to record. If you are using one of the supported browsers, this information is
automatically extracted from the browser settings. The values you specify here
override any values the recorder retrieves from the browser settings.
HTTP ProxyEnter the name of a proxy server used to connect to a web
server.
HTTP Proxy PortEnter the port number for the proxy.
HTTP Proxy UserEnter the user ID, if required, to access the proxy server.
HTTP Proxy PswdEnter the password for the user ID, if required, to access
the proxy server.
SSL ProxyEnter the name of a secure proxy server used to connect to a web
server.
SSL Proxy PortEnter port number for the secure proxy.
SSL Proxy UserEnter the user ID, if required, to access the secure proxy
server.
SSL Proxy PswdEnter the password for the user ID, if required, to access the
proxy server.
Certificate FileThe fully qualified name of the client certificate file.
Note: For more information, see Client certification considerations (see
page 62).
Key FileThe fully qualified name of the private key file that is associated with
the client certificate. The private key may be embedded in the certificate, in
which case this file will be the same as the Certificate File.
Pass PhraseA private key may optionally be further protected using a pass
phrase. If required, enter the pass phrase in this field.


Client certification considerations
If you are recording a Secure Socket Layer (SSL) URL from a secure server, it may require
a client certificate to prove your identity. Normally this certificate is installed in your
browser. For CA APM TG to record this URL, it will also require access to this client
certificate.
The certificate must be in X.509 (PEM) format rather than PKCS12, which is typically
what Internet Explorer imports. Internet Explorer certificate export (which can create a
PEM format certificate) does not allow you to export if the certificate includes the
private key. If you have the private key that was used to create the certificate signing
request (CSR), you can use Internet Explorer to export the certificate as a Base 64
encoded X.509 (.CER) file. Otherwise, you can use the OpenSSL utility to convert it. The
utility is included in the <apmtg_home>\bin directory. The command is:
Openssl pkcs12 in mycert.pfx clcerts out mycert.pem.
Note: After recording a script that requires client certification information, you must
insert a certificate tag. Use the Insert > Certificate menu to create the required
certificate tag.
HTTPS protocol
The Script Recorder uses two separate SSL sessions when recording a secure transaction
using HTTPS URLs. The Script Recorder acts as a server to the client browser and acts as
a client to the web server application. The Script Recorder intercepts the encrypted data
from the browser, decrypts it in order to record it, then encrypts it again before securely
sending it out to the secure web site.
When the browser initializes an SSL session with the Script Recorder, it validates the
server certificate provided by the recorder. The browser issues a warning because the
Script Recorder has a certificate that was not created by a trusted certificate authority.
The warning also indicates that the certificate was not issued by the web site you are
trying to record. Continue recording by clicking Yes to any warning dialogues that
appear.
Note: The Script Recorder supports SAML authentication.


Starting the recording session
You can use the CA APM TG Script Recorder to create scripts by recording your browser
clickstream. The Script Recorder acts as a proxy to capture URLs and posted data.
To start recording a session:
1. From the open CA APM TG Script Editor, choose File > New.
The New Script dialog box opens.
2. In the New Script dialog, enter:
A New Script Name for the script.
Note: When migrating scripts to CA CEM, this name is also used for the
automatically created business process name.
A Group Name (optional, but recommended).
Note: If a group name is not specified, the default group name of HTTP Scripts
will be used. This group name appears in the Scripts By Group tab of the Agent
Configuration interface.
3. Choose whether to use default settings or to specify settings.
Use Default Settingsthe script is defined with default settings. When the
script is loaded into the CA APM TG agent it uses the settings specified in its
group.
Specify Settingsyou can set parameters just for this script using the Global
Parameters dialog. The Global Parameters dialog opens after you choose the
Specify Settings option and click OK.
The Global Parameters are in effect for the entire script. These settings do not
affect the recorder; they are used only when the script is executed in the agent.
These settings apply only to this script and override the group or agent settings for
this script.
You can specify these settings in the Global Parameters dialog:
Normal Interval (sec)Specifies the number of seconds between polls when
the scripts status is Normal.
Error Interval (sec)Specifies the number of seconds between polls when the
scripts execution results in an error.


Timeout Value (ms)Specifies the expected response time for each request in
the script, in milliseconds. If the threshold is reached, the requests status
changes to Error.
Detail LevelSpecifies which URL components to request. Set the detail level
of monitoring for web pages. The following options are available:
Page+Frames: requests the page and any frames that may be on that page.
Page+Components: requests the page and all the image components on
that page.
PageOnly: requests only the initial page.
Max Connections: Determines how many simultaneous connections are
used for requesting components when Detail Level is set to anything other
than Page Only. Max Connections are limited to 20 total.
Note: Depending on network traffic, you may improve the polling performance
by increasing this value.
Enable monitoringEnable the monitoring of this script.
Create debug filesSpecifies whether you want a file written that contains the
request and response headers and the content of the returned page. You can
use this information to help determine why a request returns an error status.
The debug files are saved to the
<apmtg_home>/RTM_7201/machine_agentname directory.
Note: 7201 in the directory name is the default port number specified at install
time or configured later. This port is for communication between the CA APM
TG agent and RTMCServer. The port number is configurable via the CA APM TG
agent configuration file, wtgagent.ini, but the default is 7201.
Send script information to CA IntroscopeDetermines if the CA APM TG
agent sends information to CA Introscope for this script.
By default, the CA APM TG agent does not send data to CA Introscope unless
you configure it to do so. This can be done during CA APM TG agent installation
or using the Agent Configuration interface. Once the agent is configured to
send data, each script can be individually configured to send data or not.
When this feature is disabled, no data is sent to CA Introscope. CA APM TG
continues to drive synthetic transactions, but does not send information to CA
Introscope.
When this feature is enabled, script information is available to view in CA
Introscope.


Use Wininet for Windows Extended AuthenticationCA APM TG uses
Microsoft's Wininet interface to support web sites that use Windows Extended
Authentication. RTMCServer can be configured to use Wininet, but once this is
done, all URL requests will use it. Since Wininet uses shared session memory
and the Internet Explorer permanent cookie cache, it is desirable to use wininet
only when necessary.
The default setting is Use RTM settings. Whatever is specified in the
RTMCServer configuration will be used.
If set to Yes, Wininet will be used for this request or if set to No, Wininet will
not be used, irrespective of what is configured in RTMCServer.
Note: This functionality is not available on the Linux platform. Setting this
option for a CA APM TG agent on Linux will have no effect.
Remove control characters from parsing buffer Removes carriage returns and
line feeds if selected.
When <parse> tags are implemented in a script, CA APM TG can remove
carriage returns and line feeds from the buffer it uses for parsing. This aids in
uniquely identifying the string to be parsed.
Stop script on first errorScript execution stops when any request returns an
error. Specify this option if do not want a script to continue after it encounters
an error.
Valid CodesDefines one or more HTTP status codes that when returned by
the script request indicate an OK status. Separate codes with a space.
For example, if a URL responds with an HTTP 401 code to indicate that
authentication is required, you could specify 401 as the valid code to verify that
your web application is checking authentication.
Valid Component CodesFor page components only, this defines one or more
HTTP status codes that when returned by the script request indicates an OK
status. Separate codes with a space.
SSL VersionTurn on the SSL versions supported by the web server. By turning
on both SSLv2 and SSLv3, you will be able to record on the largest number of
web servers.
Note: Specify SSLv3 if the web server is the IBM WebSphere version or the
Apache web server.
Bypass any CA APM TG agent proxy settingsCheck this option if you have
proxy information specified in the CA APM TG agent RTMCServer configuration
and it should not be used for this script.


Specify an override proxy for this scriptCheck this option if you want to
specify a proxy to be used just for this script. When checked the following
proxy fields will be enabled:
Override Proxy: Addressthe address of an alternate proxy server to be
used just for this script.
Portthe port of the alternate proxy server to be used just for this script.
Security: User and Pswdthe user name and password for the URL of the
alternate proxy server to be used just for this script.
4. Select the Record option and click OK.
If you chose to specify settings, the Global Parameters dialog opens. Enter the
settings in the dialog and click OK.
The Script Recorder opens.
5. Click Start to begin the recording session using one of the browsers specified when
configuring the Script Recorder.
The browser opens to a blank page.
6. Enter the URL of the web site to be monitored and perform the tasks you want to
record.
Note: By default, all script requests (your recorded clickstream events) are listed in
the CA APM TG agent Configuration interface and in CA CEM with identifiers of
sequence numbers. See Logically grouping requests using Set Request ID (see
page 67) for tips on using the Set Request ID to name your script requests.
7. When you are finished recording, toggle back to the Script Recorder (Alt-Tab) and
click Stop.
8. Save the script by choosing File > Save.
The Script Editor saves the script to the following directory on the agent machine:
<apmtg_home>\wtgagent_name\scripts
Note: You can review and edit the script in the Script Editor and save your changes.
9. Update the script in the Agent Configuration. Connect to the Agent Configuration
and click the Update Modified Scripts button on either the All Scripts tab or the
Group Scripts page (Scripts By Group > GroupName).
10. Click on the script to view its details. The script launches based on the interval
setting for the agent.


Logically grouping requests using Set Request ID
By default, script requests are listed in the CA APM TG agent Configuration interface
(and in CA CEM) with identifiers of sequence numbers. You can give requests a more
meaningful identifier by logically naming them during recording using the Set Request ID
field in the Script Recorder dialog.
1. Click Start in the Script Recorder.
2. After your default browser opens, toggle back to the Script Recorder using Alt-Tab.
3. The Set Request ID button is now enabled and you can enter a name.
4. Click Set Request ID and toggle back to your browser using Alt-Tab.
Any requests generated by entering the first URL are now tagged in the recorded
script with this name.
Repeat this procedure before clicking on the next transaction link.
Note: If you do not toggle back to enter a new Set Request ID for each click you are
recording, the requests will use the same identifier. The name you entered in the
Set Request ID is used again until you change it. To ensure unique names for each
request, toggle back before each click and enter a unique name.
You may want to use a combination of numbers and names to keep the sequence
with the logical names. This is particularly useful when migrating scripts to CA CEM
so that the automatically created business transactions are identified descriptively.
For example:
1 Start Page
2 Login Screen
3 Entered Login Info
By using both a name and a number in the Set Request ID, requests invoked for
specific functions in the web application are now more easily identified and listed
when viewing the script or the generated transactions in the CEM console.


Monitoring web services
You can monitor a web service by creating a script that posts a SOAP request to that
web service. The SOAP request is built by using the Script Editor recording function. A
Web Services Description Language (WSDL) definition is retrieved from the web service
provider or from a file, it is parsed, and the resulting methods and data are displayed in
a form in your browser.
Enter any required input data for the selected method. A SOAP request is generated and
sent to the Web server. The XML response is then displayed. When you stop recording,
the generated SOAP request is saved to the script, which is loaded into the CA APM TG
agent and monitored.
To record a web services script:
1. From the open CA APM TG Script Editor, navigate to File > New.
The New Script dialog opens.
A New Script Name for the script.
Note: When migrating scripts to CA CEM, this name is also used for the
automatically created business process name.
A Group Name (optional, but recommended).
Note: If a group name is not specified, the default group name of HTTP Scripts will
be used. This group name appears in the Scripts By Group tab of the Agent
Configuration interface.
3. Choose whether to use default settings or to specify settings.
Use Default Settingsthe script is defined with default settings. When the
script is loaded into the CA APM TG agent it uses the settings specified in its
group.
Specify Settingsyou can set parameters just for this script using the Global
Parameters dialog. The Global Parameters dialog opens after you choose the
Specify Settings option and click OK.
The Global Parameters are in effect for the entire script. These settings do not
affect the recorder; they are used only when the script is executed in the agent.
These settings apply only to this script and override the group or agent settings for
this script.
4. Select the Record Web Service option, and click OK.
If you chose to specify settings, the Global Parameters dialog opens. Enter the
settings in the dialog and click OK.
The Script Recorder opens.
Using a script template


5. Click Start to start recording.
Your default web browser launches the WSDL Entry Form.
6. Enter the WSDL URL or the file path if the WSDL is available locally.
If you have selected Other in the Recorder Configuration, you must manually start
your selected browser.
7. Press Enter.
The WSDL is retrieved and parsed for supported methods and data. The WSDL is
then presented as a form in the browser.
The method to test is selected by entering any required data and then pressing
Enter. The request is sent to the web server and the resulting XML data displayed.
You can use the browser Back button to go back and select another method to test.
When you stop recording, the SOAP request is saved in the created script.
You can save, load, and execute the script in the agent.
Using a script template
Use this method of creating a script if you have some knowledge of Script Editor tags or
want to quickly create a script for a single URL.
To create a script using a template:
1. Open the CA APM TG Script Editor, and navigate to File > New. The New Script
dialog box opens.
A name for the script.
A group name (optional).
Note: If a group name is not specified, a default group name of HTTP Scripts is used.
Manually creating scripts


3. Select the Template button and click OK.
The default template script appears in the script window. The following is an
example of a default template script:
Note: The configuration options on the New Script dialog are not used.
<?xml version="1.0"?>
<script>name=TemplateOne group=HTTP Scripts
<request>1
<url>www.ca.com</url>
</request>
</script>
4. Enter any additional tags manually, or use the commands in the Edit > Insert menu
to insert script parameters, requests, and conditions. You can also right-click and
select Insert from the right-click menu.
5. You can verify the syntax of your script by clicking the Check Syntax toolbar button,
or by navigating to Check > Syntax.
The syntax checker reports lines that are not well-formed. It does not check to
ensure that you have used the correct parameters within a tag.
6. When you are finished with your script, click the Save button.
Scripts can be created manually using the CA APM TG Script Editor, but because the task
is complex and error-prone, CA APM recommends that you use the Script Recorder to
create scripts. See Using the Script Recorder (see page 59).
To create a script manually:
1. Open the CA APM TG Script Editor.
2. Position the cursor at the beginning of the first line and enter the following:
<?xml version="1.0"?>
3. Enter the <script> tag to begin specifying your script.
4. Specify a name for your script after the <script> tag.
For more information on script tags, see CA APM TG XML tag syntax (see page 78).
5. You can use the Edit > Insert commands to create script parameters, requests,
request tags, and conditions.
For more information, see Specifying script parameters (see page 71), Specifying
requests (see page 71), Specifying request tags (see page 72), and Specifying
conditions (see page 73).


6. You can verify the syntax of your script by clicking the Check Syntax button, or by
navigating to Check > Syntax.
7. When you are finished with your script, click the Save button.
Specifying script parameters
Script parameters let you specify polling details, such as intervals that apply to the
entire script.
To set script parameters:
1. In the script window, position the cursor on a blank line after the <script> tag and
before the first <request> tag (if present).
2. Navigate to Edit > Insert > Global Parameters.
The Global Parameters dialog box appears.
3. Enter values in the fields.
For the indicated fields, if you do not specify a value, group values are used when
processing the script.
4. Click OK.
The values you specify are added to the script window. The <attributes> tag begins
the parameter specification and the </attributes> tag ends it.
Specifying requests
A request specifies a URL and contains details about how you want to poll that URL. For
example, does the URL require authentication, do you want to post data to the URL, and
so on. You can even specify request parameters that override the script parameters. For
example, you might want to increase the timeout value if you know that this request
requires more time to complete.
To specify a request:
1. In the script window, position the cursor on a blank line after the <attributes> tag (if
present). Also ensure that the new line is not within an existing request <request>,
condition <if>, or parse <parse> tag.
2. Navigate to Edit > Insert > Request.
The Insert Request dialog appears.


3. Use the buttons in the dialog box to specify script request tags and conditions.
If you click Tags, the Create Tags dialog box opens. Complete the fields in this
dialog box and click OK.
Important! You must specify a value for the URL field. All other fields are optional.
If you click Conditions, the Create Condition dialog box opens. Complete the
fields in this dialog box and click OK.
Note: You do not have to specify any conditions. The conditions you specify apply
when this request runs.
4. If you have specified a condition, it appears in the list box. Double-click the list box
to view or edit it.
5. When you are finished, click OK. The <request> tag begins the request specification
and the </request> tag ends the specified condition.
Specifying request tags
A request tag is a tag, such as <url> or <post> that contains data for the request. It
occurs between the <request> and </request> tags.
You can specify request tags by using the Edit > Insert > Request Tag command.
To specify a request tag:
1. In the script window, position the cursor on a blank line after the <request> tag.
2. Navigate to the Edit > Insert > Request Tag.
The Insert Tags dialog box appears.
3. Complete any fields in the Insert Tags dialog and click OK.
Note: You do not have to specify every field, just the ones you want to add to the
request. For example, you can click Post and add post data to the request.


Specifying conditions
A condition lets you control the flow of processing in a script. You can specify conditions
that apply at the script level and conditions that apply to individual requests. For
example, you can write a condition at the script level that specifies how you want the
requests in the script to be processed. Similarly, you can specify a condition at the
request level to process the components of a request.
CA APM TG evaluates conditions before submitting the request to determine content
and attributes for the request. CA APM TG also evaluates conditions after the response
is received to set the status or halt the script.
To specify conditions:
1. In the script window, position the cursor on a blank line after the <attributes> tag (if
present). If the blank line is not within a <request> tag, it applies to the script. If the
blank line is within a <request> tag, the condition applies to the request.
Also, ensure that the new line is not within an existing condition <if> (unless you
want to create a nested condition) or parse <parse> tag.
2. Navigate to Edit > Insert > Condition.
The Create Condition dialog appears.
3. Use the Left, Operator, and Right drop-down menus to create a Boolean condition,
for example: if size = 400.
4. Click Build to create the expression in the list box at the top of the dialog box. You
can specify another condition and click the AND button to create a statement such
as: if size = 400 AND respstatus is not equal to critical. You can also join two
conditions by clicking the OR button.
If you make a mistake, you can click the Clear button to remove all the text from
the list box.
5. Click Then Request to specify a request that you want to run when the condition is
true.
6. Click Else Request to specify a request that you want to run when the condition is
false. See Specifying requests (see page 71) for details.
You must specify at least one Then Request. After you add a request, you can
modify it by double-clicking its entry in the list.
Note: You can also specify conditions in a Then or Else request; this is known as a
nested condition.
7. When you finish specifying this condition, click OK.
The <if> tag begins the condition specification and the </if> tag ends it. Depending
on your choices, there can also be <then>, <request>, <attribute>, and nested <if>
tags between the opening <if> and the closing </if> tags.
Deploying scripts to multiple agents


Checking syntax
If you manually create or edit a script, check the syntax before you activate the script.
To check the syntax of a script:
With the script open in the Script Editor, navigate to Check > Syntax, or click the
Check Syntax button at the top of the Script Editor.
The syntax checker reports lines that are not well-coded. It does not check to
ensure that you have used the correct parameters within a tag.
You may want to run the same script on more than one agent to compare how the
generated transaction performs from different locations. There are two basic ways to
copy a script from one agent to another:
Copying a single script at a time (see page 74)
Manually copying multiple scripts (see page 74)
Copying a single script at a time
1. Launch the Script Editor to connect to your local agent.
2. Open the script you want to copy.
3. Choose File > Connect and enter the Remote Host Name.
4. Enter the correct authentication information and click OK.
If successful, the status bar on the bottom of the Script Editor indicates you are
connected to the agent host you specified.
5. Click on the Save Script button.
This script is now available for the second agent.
6. Using the Agent Configuration interface, connect to the second agent.
7. From the All Scripts tab, click the Update Modified Scripts button.
Manually copying multiple scripts
You cannot just copy scripts from one agent script directory to another. Each agent has
a script control file to identify what scripts to load when the agent is started. This
control file is also used by the agent to identify what scripts have been updated by the
Script Editor. Without an entry in the script control file, a script is unknown to the agent.


The CA APM TG agent component includes the batch utility scriptimport to provide a
mechanism for updating the script control file maintained by the agent. At the very
minimum, the utility synchronizes the contents of the active scripts directory with the
script control file. You can also specify a path to a directory of script files. Any scripts
found in the specified directory are copied into the active scripts directory and the script
control file is updated to include the new scripts.
On Windows
Use this command syntax:
scriptimport [ -sync | -path pathname [ - replace ] ]
On Linux
On Linux, first change directories to the <WTG_HOME>/bin directory where the
scriptimport utility is located.
Use this command syntax:
./scriptimport.sh [ -sync | -path pathname [ - replace ] ]
where
-sync
Synchronizes the agent with scripts in active scripts directory.
-path
Enter the full path name to the directory containing the scripts you want to import.
-replace
Valid only if path is specified. Specifies whether a script with the same name in the
active scripts directory should be replaced.
Examples
To manually copy scripts into the active scripts directory:
1. Copy scripts to the agents script directory located at:
<apmtg_home>\wtgagent_agentname
2. Synchronize the scripts control file to include the scripts you just copied that it
doesnt already know about:
Windows:
scriptimport -sync
Linux shell script:
./scriptimport.sh -sync
Securing scripts


To copy and synchronize multiple scripts from a directory:
Specify the path to a directory of scripts and indicate whether any duplicate script
names are to be replaced:
Windows:
scriptimport -path c:\SavedScripts -replace
Linux shell script:
./scriptimport.sh -path /SavedScripts replace
Securing scripts
Because scripts can contain sensitive information, such as test client information, user
IDs, and passwords, you can encrypt your scripts to protect them. By default, the Script
Editor does not encrypt scripts.
Note: Only the Script Editor can display an encrypted script. You can further secure
access to the Script Editor by specifying a password for the Administrator user. See
Securing access to the Script Editor (see page 77).
To secure new scripts:
1. From the open Script Editor, navigate to Settings > Encrypt Scripts.
The Set Encryption dialog box opens.
2. Do one of the following:
Select the Encrypt Scripts check box option to encrypt scripts when you save
them.
Clear the Encrypt Scripts check box to turn off the Encrypt Scripts option.
Scripts will no longer be encrypted when saved.
3. Click OK.
Securing access to the Script Editor


To secure existing scripts:
1. Open a script in the Script Editor.
2. Check the status of the Encrypt Scripts option by navigating to Settings > Encrypt
Scripts.
The Set Encryption dialog box opens. Do one of the following:
a. If Encrypt Scripts is turned on and you want to encrypt the script, save the
script by clicking the Save button.
b. If Encrypt Scripts is turned off and you want to encrypt the script, turn on the
Encrypt Scripts option and click OK. Save the script by clicking the Save button.
c. If Encrypt Scripts is turned on and you want to decrypt the script, turn off the
Encrypt Scripts option and click OK. Save the script by clicking the Save button.
Securing access to the Script Editor
The Script Editor comes with the default user name of Administrator and a null
password (no password). We recommend securing the Script Editor by changing the
user name and the password. Otherwise, any user with access to the system where the
CA APM TG is installed can display and modify scripts.
To change the Script Editor user name and password:
1. From the open Script Editor, navigate to Settings > Change User/Password. The
Change User/ Password dialog box opens.
2. To change only the password for the Administrator:
a. Enter a value in the New Password field and enter the same value in the
Confirm Password field.
b. Click OK.
The next time you start the Script Editor, it prompts you for the user ID and
password before it starts.
3. To change the user name and password for the Administrator:
a. Specify all the fields in the dialog box.
b. Click OK.
The next time you start the Script Editor, it prompts you for the user name and
password before it starts.
Important! The Script Editor supports only one user name. Be sure you note the new
user name and password and keep them in a secure location if you change from
Administrator and a null password.
XML tag syntax


XML tag syntax
A script consists of one or more request specifications. A script submits each request
sequentially and must minimally contain a URL. You can define variables to be parsed
from the page content returned from a request. Variables that are parsed from one
request are available for use in subsequent requests.
You can use XML tags in the creation of your scripts. The permissible XML tags and their
parameters are as follows:
<script>name
Name is the identifier for this script.
<attributes>
Attributes that apply to a script separated by commas or spaces. Most of these
attributes match current CA APM TG URL settings. You can use the following
attributes:
nintervalThe normal interval.
cintervalThe error interval.
debugSpecify "Y" to write the HTTP headers, page content, and values of the
variables to a debug file for each request within a transaction. Script Editor
writes the debug to the <apmtg_home>/RTM_7201/machine_agentname
directory with the name scriptname@request.debug. For example, the debug
file for the first request of the sample script is named: sample@1.debug.
detailThe detail level:
1 for Page+Frames
2 for Page+Components
3 for PageOnly
enableEither y for enabled or n for disabled.
proxybypassEither "Y" to bypass the proxy server or n to use the proxy
server. This value is overridden if proxy= is specified.
maxconnThe maximum number of connections to use when retrieving
components.
proxyThe proxy server to use for this script. This value overrides the default
proxy server.
proxyportThe proxy port to use for this script. This value overrides the
default proxy port.
XML tag syntax


proxysecurityThe "userid" "password" required to connect to the proxy
server. Any request attributes specified at the script level remain in effect for
each request unless overridden by an attribute tag in the request.
sslversionThe SSL version. Values are 23 (for versions 2 and 3), 2 (for version
2), and 3 (for version 3).
stopcritical. When specified, script execution will halt when a request returns
with an error.
timeoutThe timeout value.
validcodesOne or more http codes that result in an OK status.
validcompcodesOne or more http codes that result in an OK status for page
components.
autocrcresetEither "Y" or n to specify that the expected CRC value should be
automatically reset after a CRC accuracy check fails.
sendtoiscopeSpecify "Y" to send the information to CA Introscope, n to not
send information.
nocrlfRemoves carriage returns and line feeds if selected. When <parse> tags
are implemented in a script, CA APM TG can remove carriage returns and line
feeds from the buffer it uses for parsing. This aids in uniquely identifying the
string to be parsed.
<comment>
Indicates the beginning of a comment.
commentThe string to be displayed in the script description.
Note: You can also specify a comment tag in a request
<request>
Indicates the beginning of a request. Use the following tags to specify the request.
<attributes>
Attributes that apply to an individual request, separated by commas or spaces. Any
attributes specified at the request level will override any global script attributes just
for this request. You can specify the following attributes for a request:
detailThe detail level:
1 for Page+Frames
2 for Page+Components
3 for PageOnly
XML tag syntax


maxconnThe maximum number of connections to use when retrieving page
components.
timeoutThe timeout value.
validcodesA list of HTTP return codes that result in an OK status. Separate
multiple codes using commas.
validcompcodesA list of HTTP return codes that result in an OK status for
page components. Separate multiple HTML return for page components codes
using commas.
<url>
Indicates the beginning of a URL specification.
urlThe URL to get or post. This tag is required
<security>
Indicates the beginning of security information required for this URL.
userid and passwordThe user ID and password required to access this URL
<post>
Indicates the beginning of a data you want to post to this URL.
name=value The name and value to be posted. Specifying post data results in a
POST rather that a GET for this URL. You can specify multiple post tags.
<check>
Indicates the content check to be done on the page returned from this submit,
consistent with the following:
("string","NOT "string"",CRC,none,"Length {=|>|<} size")
CRC: A Cyclic Redundancy Check is performed on the page content.
"<string>": Checks for matching string patterns. Specify the string in quotes, for
example "welcome". You can specify multiple strings by providing each string in
quotes separated by a space. For example, "logon" "successful". All strings
must be found for the accuracy check to be successful.
NOT "<string>": Checks for matches to a negative string pattern. For example,
NOT "foo". If multiple strings are specified, then the presence of any one of the
strings will cause the accuracy check to fail.
Length: Checks the length of the string. Specify the length as "Length operator
(=, >, or <) size" in bytes, for example: Length>500
<stop>
Stops the script processing where specified.
XML tag syntax


<localaction>
Indicates the name of a batch file, program, or script that you run at a specific point
in the script.
actionThe action you want to run. For example: <localaction>cmd.exe /c
test.bat</localaction>
</localaction>
Indicates the end of local action.
<cookie>
Indicates the name of a cookie to be sent for this request. The cookie is temporary
and will only be sent on this request. You can specify multiple cookies for a request.
For example:
<cookie>cookiename=cookievalue;path=pathvalue;domain=domainvalue</cookie>
Specify the following variables:
cookienameThe name of the cookie.
cookievalueThe value of the cookie.
pathIndicates that you are providing a path to where the cookie resides. If
not specified, the Script Editor uses the path of the request.
pathvalueThe path where the cookie resides.
domainIndicates that you are providing a domain. If not specified, the Script
Editor uses the domain of the request.
domainvalueThe name of the domain.
<setvar>
Indicates the name of a script variable and its value. You can set the value to a
string, an arithmetic expression, or the output of a command. Values can also
include other variables. Specify the <setvar> tag as follows:
<setrvar>variable=expression</setvar>
variableThe name of the variable.
expressionThe value of the variable. For example, the following <setvar> tag
indicates that anywhere in the script that %%var1%% is specified, testvalue will
be substituted for it when the script runs. <setvar>var1=testvalue</setvar>
See <setvar> samples (see page 88) for more samples.
<upload>
Indicates a sample file that you want to upload in this request in the script. You
must specify the following variables:
controlnameThe file identifier. This is the value of NAME= as specified on the
INPUT tag in a form.
filenameThe file to be uploaded including its path.
XML tag syntax


contenttypeThe MIME type of the file to be uploaded, such text/plain or
image/gif. For example, here is a sample form that uploads a file:
<FORM METHOD="POST" ACTION="/testupload.cgi
ENCTYPE="multipart/form-data" > <INPUT TYPE="FILE" NAME="userfile">
<INPUT TYPE="SUBMIT" VALUE="Submit"></FORM>
The script tag to upload the file identified on this page is as
follows:<upload>userfile=c:\testfile.txt=text/plain</upload>
<parse>
Indicates the beginning of variable declarations.
string%%name%%stringDeclares a variable and a value based on what text
occurs on the page before and after. You can specify multiple parse tags. If
multiple matches occur, then a variable array will be returned with
%%name%% as the first occurrence, %%name[1]%% as the second occurrence,
etc.
<if>
Indicates the beginning of a condition. You must also specify a <then> tag.
expressionConditions are limited to comparisons between variables or
between variables and constants. You can specify any request tag within a
<then> or an <else> tag. You can also specify conditions outside of a request to
control subsequent request processing.
<then>
Indicates the beginning of a then statement.
tagsA number of requests to process if the condition evaluates true.
<else>
Indicates the beginning of an else statement.
tagsA number of requests to process if the condition evaluates false.
<certificate>
If your web application requires a client certificate for authentication, this tag is
used to define it to CA APM TG agent. See Client certification considerations (see
page 62) for more details.
certfileThe fully-qualified name of the client certificate file.
certkeyfileThe fully-qualified name of the private key file that is associated
with the client certificate. The private key may be embedded in the certificate,
in which case this file will be the same as the certfile.
passphraseA private key may be further protected using a pass phrase. If
required, enter the pass phrase in this field.
Important! To close all XML tags, use the / symbol. For example: <else> variables
</else> closes the beginning <else> tag.
XML special character substitutions


XML special character substitutions
XML syntax reserves the use of certain characters, but provides alternate specifications
so that these characters may be used in data. This table lists the special characters and
the alternate characters accepted by the XML processor:
Special Character Alternate
& &
< <
> >
'
" "
Use these alternate characters in a web response monitor script to be compatible with
XML parsers. For example, specify a compound condition using the AND operator as
follows:
<if>%%V1%%=Associates & %%respstatus%%=normal
XML has a method of escaping an entire line of data using the CDATA specification. For
example, to parse an HTML page that contains any of the XML special characters,
specify <![CDATA[ before the data and ]]> after the data as follows:
<parse><![CDATA[this is a sample < %%VAR1%% >]]></parse>
Use Edit > Insert > Request Tag > Parse to create the <parse> tag and the escape
sequence is created for you.
Script samples
This section contains the following:
Basic script sample (see page 84)
Script conditions and content variables (see page 84)
Content variable sample one (see page 85)
Content variable sample two (see page 85)
Script reserved variables (see page 86)
<setvar> samples (see page 88)
Stopping a script using the <stop> or stop attribute (see page 89)
Script samples


Basic script sample
In the following XML sample, three requests are submitted sequentially. A timeout value
is specified at the script level. It is in effect for all requests except the third, which has its
own timeout value of 30,000 ms.
<script>sampleone
<attributes>timeout=20000</attributes>
<request>
<url>www.aaa.com</url>
</request>
<request>
<url>www.bbb.com</url>
</request>
<request>
<attributes>timeout=30000</attributes>
<url>www.ccc.com</url>
</request>
</script>
Script conditions and content variables
You can use conditions to control the processing flow of a script. Conditions can specify
how you want the requests to be processed. They can also specify how you want to
process components within a request. Using the <parse> tag, you can set variable values
from page content. If the leading and trailing strings are not unique within the page,
then a variable array is returned. The parsing is limited to a single line at a time to
facilitate unique matches and to prevent large strings for values. You must delimit
variable names using %% (two percentage signs) and you can use only alphanumeric
characters for variable names.
Conditions are evaluated before the request is submitted to determine content and
attributes for the request. Conditions are also evaluated after the response is received
to set the status or halt the script.
You can specify compound conditions using & for AND conditions and | for OR
conditions. Compound conditions are evaluated left to right. You can also nest
conditions.
The following operators are supported:
= equal
> greater than
< less than
!= not equal
Script samples


Content variable sample one
In the following XML sample, a variable is parsed from the content of the page returned
by the first request. Either request 2 or request 3 is submitted based on the variable
value.
<script>sampletwo
<request>
<parse>Computer %%V1%% International</parse>
</request>
<if>%%V1%%=Associates
<then>
<request>
</request>
</then>
<else>
<request>
</request>
</else>
</if>
</script>
Content variable sample two
The following XML sample is similar to the previous one. It specifies a condition within a
request. Logically the results are the same, but two requests are submitted in this
sample. A check for the response status of the first request is added to demonstrate a
compound condition.
<script>samplethree
<request>
<parse>Computer %%V1%% International</parse>
</request>
<request>
<if>%%V1%%=Associates & %%respstatus%%=normal
<then>
</then>
<else>
</else>
</if>
</request>
</script>
Script samples


Script reserved variables
The following variables are built into the script language, and their values are updated
following each request. They are global in scope within a script. You can test the
response from one request to control subsequent requests and request components.
See also Reserved variable sample (see page 87).
Request variables
The following reserved variables apply at the request level:
%%respstatus%%
The response status: Normal or Critical.
%%statuscode%%
The HTTP status code.
%%firstbyte%%
The response time (ms) to retrieve the first byte.
%%lastbyte%%
The response time (ms) to retrieve all the last byte of all content.
%%size%%
The size (bytes).
%%avgresponse%%
Average cumulative response time (ms) for this request.
%%critpolls%%
Count of error responses cumulative for this request.
Script variables
The following reserved variables apply at the script level:
%%tranresponse%%
The response time (ms) of the entire script.
%%transize%%
The total size (bytes) of the entire script.
%%transtatus%%
The overall script status: Normal or Critical. The combined status for all requests
executed.
%%trantotalavgresponse%%
Average response time (ms), cumulative for this script.
Script samples


%%trantotalcritpolls%%
Count of error responses, cumulative for this script.
Date variables
The following built-in variables are updated at the start of every script execution:
%%day%%
day
%%month%%
month
%%year2%%
2-digit year
%%year4%%
4-digit year
Global variables
The following is the only reserved variable that is global in scope between script
executions:
%%prevtranstatus%%
The status of the previous execution of this script (Normal or Critical). You can use
this variable to create a condition that is true only the first time a status change
occurs.
You can code your own global variables whose values persist across script executions.
Any variable name that starts with GLOBAL does not have its value cleared when the
script starts.
Reserved variable sample
In the following XML sample, the response status from the first request is tested to
determine if the second or the third request will be submitted. The fourth request's
timeout value is dependent on the response from the previous request submitted. Note
that you can specify multiple tags on a line. We recommend that you indent XML script
code as necessary to improve readability.
<script>samplefour
<request>
</request>
<if>%%respstatus%%=normal
Script samples


<then>
<request>
</request>
</then>
<else>
<request>
</request>
</else>
</if>
<request>
<if>%%respstatus%%=critical
<then><attributes>timeout=30000</attributes></then>
</if>
<url>www.ddd.com</url>
</request>
</script>
<setvar> samples
You can set the <setvar> value to a string, an arithmetic expression, or the output of a
command. Values can also include other variables.
Variables
For example, a <setvar> tag can contain other variables, so that you can use it to
increment a variable or combine variables:
<setvar>var1=%%day%% + 1</setvar>
This tag results in a variable, var1, with a value of the day incrementally increased by 1.
Global variables
Normally, script variables only keep their value for a single execution of the script.
However, you can specify global variables whose values will persist across script
executions. Any variable name that starts with GLOBAL will not have its value cleared
when the script starts.
Programs and timeout values
You can also use external programs or scripts to assign values to a variable. The process
specified on the <setvar> tag is executed and whatever is written to stdout is used as
the value for that variable. Consider the following example:
<setvar>var1=exec(cmd.exe /c testext.bat)</setvar>
Script samples


Every time var1 is evaluated, testext.bat is executed and the resulting stdout is
redirected to a file that CA APM TG agent reads to get the value to use for var1. The files
are written to the <WTG_Home>/wtgaent_instance directory with a file name of
scriptname.variablename.
By default, the CA APM TG agent waits two seconds for the process to execute. If more
time is required, you can specify an optional timeout value in seconds in the <setvar>
tag:
<setvar>var1=exec(c:\longprogram.exe),timeout=5</setvar>
If the timeout period expires and no value is found, the CA APM TG agent tries to kill the
running process.
Stopping a script using the <stop> tag or stop attribute
CA APM TG scripting contains several methods that let you stop a script, such as the
<stop> tag and the stop attribute. You can use the <stop> tag at any point. You can use
the stop attribute at the script level.
Stop script sample one
In the following XML sample, the response from the first request is checked. If the
response is critical, then the script is halted and the second request is not submitted.
<script>samplefive
<request>
</request>
<if>%%respstatus%%=critical<then><stop></stop></then></if>
<request>
</request>
</script>
Script samples


Stop script sample two
In the following XML sample, the response from any request is checked. If any response
is critical, then the script is halted and any subsequent requests are not submitted.
<script>samplefive
<attributes>stop=critical</attributes>
<request>
</request>
<request>
</request>
<request>
</request>
</script>


Chapter 5: Viewing CA APM TG Metrics

This chapter describes CA APM TG-specific aspects of the CA Introscope Workstation.
Viewing CA APM TG data with CA Introscope (see page 91)
Viewing CA APM TG data with CA CEM (see page 96)
Viewing CA APM TG data with CA Introscope
The CA Introscope Investigator allows you to view metric data collected by CA
Introscope from many different sources.
The left side of the Investigator uses a tree structure to organize metric data reported
by the agents that report to the Enterprise Manager. Metrics are organized
hierarchically by host, process, agent, and resource type. When you select an item in the
tree, the Investigator displays a view of the data associated with that element in the
viewer pane.
The viewer pane on the right side of the Investigator presents details, often graphical,
for the resource or metric currently selected in the tree. Depending on the item selected
in the tree, tabs at the top of the viewer pane allow you to select one or more views. For
some views, options are available in the bottom section of the viewer pane that controls
the data displayed in the viewer.
For more information about the CA Introscope Investigator, see the CA Introscope
Workstation User Guide.
To view CA APM TG metrics in the CA Introscope Investigator:
1. Ensure that the CA APM TG agent is active and enabled to send data to CA
Introscope.
See Displaying CA APM TG information in CA Introscope Investigator (see page 21)
and Configuring the CA APM TG agent (see page 19).
2. Start the CA Introscope Enterprise Manager.
3. Launch and log in to the CA Introscope Workstation.
4. Open an Investigator window and navigate to the machine hosting the CA APM TG
agent.
All CA APM TG-specific metrics appear under the CA APM TG agent node in the
Investigator tree.


CA APM TG agent metrics in CA Introscope
The following CA APM TG agent-specific metrics are available for viewing through the
CA Introscope Investigator:
HeartbeatSwitches between 0 and 1 to indicate active connectivity between the
Enterprise Manager, the EPAgent, and CA APM TG agent.
IP AddressThe primary IP address of CA APM TG agent.
Launch TimeThe date and time the CA APM TG agent started.
LocationOptional, can be set in the wtgagent.ini file.
Note: This metric information is not sent to CA Introscope unless it contains a
value.
Script CountNumber of scripts monitored in the CA APM TG agent even if they
are not sending metrics to CA Introscope.
Site StatusStatus of the CA APM TG agent:
0 = down
1 = normal
3 = critical
Time ZoneThe CA APM TG agent time zone in relation to GMT.
VersionThe CA APM TG agent version.
Other metrics
Script, request, and component metrics are also available for CA APM TG.. Metrics are
enabled by adding the configuration property to the IntroscopeMetrics keyword in the
CA APM TG agent startup configuration file. For more information, see CA APM TG
agent startup settings (see page 26).
Script metrics
The following are the available script metrics that can be enabled by adding the
configuration property:
Script Status
Configuration property: status
Description
Configuration property: descript
Poll Start
Configuration property: pollstart


Poll End
Configuration property: pollend
Next Poll
Configuration property: pollnext
Script Last Modified
Configuration property: lastmod
Critical Poll Count
Configuration property: critpolls
Request metrics
The following are the available request metrics.
Component Count
Configuration property: compcount
Description
Configuration property: descript
Detail Level
Configuration property: detail
Request Status
Configuration property: status
Status Message
Configuration property: statusmsg
Total Bytes
Configuration property: totalbytes
URL
Configuration property: url
Error Timeout Specification
Configuration property: critthresh
Response Time
Configuration property: resptime
First Byte Time
Configuration property: firstbyte


Download Time
Configuration property: download
Connect Time
Configuration property: connect
Ping Time
Configuration property: ping
Throughput
Configuration property: throughput
Accuracy Specification
Configuration property: accuracy
Response Status
Configuration property: respstatus
Accuracy Status
Configuration property: accstatus
Percent Available
Configuration property: avail
Component metrics
The following are the available component metrics.
Component Type
Configuration property: comptype
Component Total Bytes
Configuration property: compbytes
Component Status
Configuration property: compstatus
Component Status Message
Configuration property: compstatusmsg
Component Response Time
Configuration property: compresptime
Component Download Time
Configuration property: compdownload


CA APM TG-specific tab views
CA APM TG-specific tab views have been added to the CA Introscope Workstation
interface to expand the metric-tracking capabilities of CA Introscope. For more
information about the CA Introscope Investigator, see the CA Introscope Workstation
User Guide.
CA APM TG - agent Tab
The CA APM TG - agent tab is available when a CA APM TG agent is selected from the CA
Introscope tree view. The CA APM TG - agent tab also is available when a script
associated with the CA APM TG agent is selected from the Investigator tree view, for
example a Request node under a script.
Metric List Tab
The Metric List tab displays CA APM TG agent or script information, such as the agent IP
address, how many scripts are associated with the agent, and which version of the agent
is running on the selected machine. Several metrics can be used to create alerts in CA
Introscope dashboards. For example, the heartbeat metric, which switches between 0
and 1 depending on connectivity, can be used to build an alert to determine if
connectivity is lost between the Enterprise Manager and the CA APM TG agent.
The contents of the Metric List tab depend on the type of script selected from the tree
view.
Viewing CA APM TG data with CA CEM


The CEM console tracks and monitors synthetic transactions generated by CA APM TG,
automatically creating business transaction definitions for the synthetic transactions. All
synthetic transactions are marked as synthetic in the CEM console, allowing you to
easily identify and use the transactions to proactively address issues within a web site or
web application.
Note: If you do not configure a CA CEM business application, then any CA APM TG
scripts sent to CA CEM will be associated with the CA CEM default application, which is
included with CA CEM in the original configuration. (If the CA CEM default application
does not exist in CA CEM, then a new CA APM TG Application will be created when CA
APM TG scripts are sent to CA CEM.)
To view CA APM TG metrics in the CEM console:
1. Ensure that the CA APM TG agent is active and enabled to send data to CA CEM.
See Displaying CA APM TG agent availability in CA CEM (see page 26) and
Configuring the CA APM TG agent (see page 19).
2. Send scripts to CA CEM.
See Sending scripts to CA CEM (see page 52).
Identifying CA APM TG transactions
CA APM TG sends an HTTP header that CA CEM recognizes as a synthetic transaction
(x-wtg-info header). The CA CEM response metrics can then be grouped within CA CEM
reporting to differentiate real users from synthetic, as well as correlate the activity with
the CA APM TG monitored object that created it.
The header is included in every request generated by CA APM TG. You can use the
header to identify CA APM TG transactions so you can monitor them separately from
real transactions. You may do this by creating a separate user group for CA APM TG
transactions. When creating a user group in CA CEM, you can select x-wtg-info header
from the drop-down list of parameters. You can also rename a business transaction or
user group to something like "Robot Transaction" or "Robot User" to identify CA APM
TG transactions.
CA APM Transaction Generator to CA CEM integration terminology
An important aspect of product integration is terminology. You need to learn the
language of the products that are unfamiliar to you. You also need to be aware of how
terms and definitions in CA CEM map to the terms in CA APM TG.


CA APM Transaction Generator terms
These CA APM TG terms are related to the product integration:
request
An individual URL that is polled.
script
One or more requests that simulate a specific action or actions by a user when
accessing a web application.
error
A request that does not return a successful response.
CA APM Transaction Generator to CA CEM term mapping
Products can have different evolution cycles and different core audiences. These
differences often mean that the product terms and definitions also differ.
Sometimes there is a one-to-one mapping (for example an incident in one product
might be a ticket in another). And sometimes the same term can have a slightly different
meaning in a different product, which can be confusing.
These term mappings will help you navigate the product integration.
defect
The only defects in CA APM TG are when a script request gets an error.
transaction
A CA CEM transaction maps to one CA APM TG request, which represents one web
page.


Appendix A: Configuring the RTM Server

Before you specify URLs to monitor, you might have to specify proxy server information
so that the CA APM TG agent can access web sites. If you use a proxy server to access
the internet, the CA APM TG agent uses the RTMCServer Configuration application to
provide proxy information in a single location. The RTMCServer Configuration
application lets you specify proxy information used by the CA APM TG agent as it tests
web sites.
To set proxy server information:
1. Access the RTM Configuration window:
From your Windows desktop, navigate to Start > Programs > CA APM
Transaction Generator > RTM Configuration.
From your Linux console, navigate to the <apmtg_home>bin directory and
execute the RTM Configuration script:
./RTMConfig.sh
Note: If you are accessing Linux via a terminal session, you will need to manually
edit the <apmtg_home>/RTM_7201/RTMCServer.ini file.
The RTMCServer Configuration window opens.
2. Provide the required information and click OK.
Note: If the CA APM TG agent must access both types of proxy servers, specify
information for both HTTP and SSL proxies.
The following options are available:
User AgentThe header tag that the CA APM TG agent uses to identify itself to
proxy and web servers. The default will display in this field.
Note: Some web applications use this header to check for browser type and
may return an error if it is not from a particular browser. Modify this field to
meet your web sites requirement.
Use WininetSelect the check box if the web sites you are monitoring use
Windows NT Challenge/Response or Extended Windows Authentication.
Note: This functionality is not available on the Linux platform.
Encrypt ConfigurationSelect this check box to encrypt the configuration file
(RTMCServer.ini). You do this if your proxy server requires security information
such as the user name and password. Leave the check box blank to leave the
configuration file unencrypted.
Note: Your enterprise security policy might require you to encrypt the
configuration file. The file is named RTMCserver.ini and is saved to the
<apmtg_home>/RTM_7201 directory.


DebugChecking this option enables detailed tracing of the RTMCServer.
Additionally, debug dump files of all requests are created. The trace logs are
saved to the <apmtg_home>/RTM_7201 directory.
Note: 7201 in the directory name is the default port number specified at install
time or configured later. This port is for communication between the CA APM
TG agent and RTMCServer. 7201 is the default setting, but can be configured.
Log Size (bytes)Enter the size limit for the RTMCServer log files. The default is
10000000 bytes. When a log file exceeds this size, a new log file is started.
Retain logsSpecifies how many trace logs to retain. When this count is
reached, the oldest log will be deleted when a new log is started.
Ping CountSpecifies the number of ICMP pings that are attempted for each
request made by the RTMCServer.
If a value greater than one (> 1) is specified, the average response is calculated.
This value is then shown in the Ping (ms) metric in the CA APM TG
Administration Interface and in the CA Introscope Workstation. The Ping (ms)
metric reflects minimal amount of time it takes to access a web application.
Note: Most proxy servers and firewalls are configured to block ICMP pings,
which can result in Windows issuing more pings. To address this "ping attack",
a Ping Count of 0 turns this functionality off in RTMCServer.
HTTP ProxyEnter the name of a proxy server used to connect to a web server.
HTTP Proxy PortEnter the port number for the proxy server.
HTTP Proxy UserEnter the user ID, if required, to access the proxy server.
HTTP Proxy PswdEnter the password for the user ID, if required, to access the
proxy server.
SSL ProxyEnter the name of a secure proxy server used to connect to a web
server.
SSL Proxy PortEnter port number for the secure proxy server.
SSL Proxy UserEnter the user ID, if required, to access the secure proxy
server.
SSL Proxy PswdEnter the password for the user ID, if required, to access the
secure proxy server.
3. Except for the Log Size and Retain Logs, you change the RTMCServer configuration
while the RTMCServer process is executing. RTMCServer must be restarted before
log settings take effect.


Appendix B: CA APM TG command line
utility (WTGUtil)

This section describes the CA APM TG command line utility (WTGUtil), a utility that
supports seven basic commands.
You typically use WTGUtil to disable a script or group of scripts configured to make
requests to a server during the servers scheduled maintenance period, and to enable
the script or group at the conclusion of that period, when the server is fully operational.
You invoke the utility manually, or via a Windows batch file or a Linux shell script. You
can schedule the batch file or script to execute at specific times through the Task
Scheduler in Windows or via a cron job in Linux.
The following sections explain how to use WTGUtil:
Basic command description (see page 101)
Basic command description
All commands are made in the form of a request message to the CA APM TG agent. The
agent sends a reply message, indicating if the command was accepted, is in proper form,
and can be performed after the command executes.
list agentRequest the last status message recorded by the CA APM TG agent.
load agentRequest that the CA APM TG agent load modified or all scripts.
disable groupDisable a group.
enable groupEnable a group.
enable objectEnable a script.
disable objectDisable a script.
StartrampStart load ramping for a specific, pre-configured script.


WTGUtil Command syntax
wtgutil verb type ID=[-hHOST] [-pPORT]
Verb =
disable | enable | list | load | startramp
disable/enable applies to type group/object
startramp applies to type object only
list/load applies to type agent
Type =
group | object | agent
ID =
Verb-specific argument:
For type group/object, ID = GroupName/ScriptName
For load type agent, ID = modscripts or allscripts (case sensitive)
Not required for list agent.
Note: The ID for types is case sensitive. Parameters containing spaces must be put
in quotes.
HOST =
CA APM TG agent host name of IP address (Default=localhost).
This argument is optional. If not provided, the default host localhost is used.
PORT =
CA APM TG agent port (Default=7700).
This argument is optional. If not provided, the default port 7700 is used.
Note: If you run the utility with omitted or incorrect arguments, it displays the usage
syntax.\


Examples
The first command example requests the last status message from the CA APM TG agent
on localhost, port 7700.
wtgutil list agent
wtgutil list agent -husmb78.ca.com -p7890
wtgutil load agent id=allscripts
wtgutil disable group id=TestGroup
wtgutil enable group id=TestGroup
wtgutil disable object id=test1
wtgutil enable object id=test1
wtgutil startramp object id=sample
Trace messages
WTGUtil writes all time-stamped trace messages to STDOUT, as well as to a log file. The
log file is named wtgutil.log and can be found at: <apmtg_home>\log.
The Successful command to local CA APM TG agent (see page 103) is a typical trace
message.
Successful command to local CA APM TG agent
C::\>wtgutil list agent

10/17/2007 17:21:45.265 - [INFO ] List Agent
10/17/2007 17:21:45.343 - [INFO ] Connected - Host: pc-2, IP: 127.0.0.1, Port: 7700
10/17/2007 17:21:45.343 - [INFO ] Batch process complete - Added:1
10/17/2007 17:21:45.343 - [INFO ] Disconnecting...
10/17/2007 17:21:45.375 - [INFO ] Successful

Index 105

Index

<
<setvar> samples 88
A
Adding a script to a group 48
Additional operating system support for the CA APM
TG agent 16
Addressing the 3 A.M. problem 11
B
Basic command description 101
Basic script sample 84
Before you begin 15
C
CA APM TG - agent Tab 95
CA APM TG Administration Server and Agent
Configuration Interface 17
CA APM TG agent 17
CA APM TG agent configuration fields and
descriptions 38
CA APM TG agent metrics in CA Introscope 92
CA APM TG agent performance settings example
39
CA APM TG agent startup settings 26
CA APM TG command line utility (WTGUtil) 101
CA APM TG components 17
CA APM TG features 12
CA APM TG monitoring architecture 11
CA APM TG Script Editor 17
CA APM TG Shortcuts 34
CA APM TG-specific tab views 95
CA APM Transaction Generator terms 97
CA APM Transaction Generator to CA CEM
integration terminology 96
CA APM Transaction Generator to CA CEM term
mapping 97
CA CEM configuration 18
CA Technologies Product References 3
Checking load ramping status 54
Checking syntax 74
Checking the error status of agents 36
Client certification considerations 62
Component metrics 94
Configuring a group 46
Configuring and launching load ramping 52
Configuring the CA APM TG agent 37
Configuring the CA APM TG agent at installation 19
Configuring the CA APM Transaction Generator
Agent 31
Configuring the RTM Server 99
Configuring the Script Recorder 59
Connecting to an Agent 35
Contact CA Technologies 5
Content variable sample one 85
Content variable sample two 85
Copying a single script at a time 74
Creating a group 45
Creating a script 58
Creating and Editing CA APM TG Scripts 57
D
Deploying scripts to multiple agents 74
Displaying CA APM TG agent availability in CA CEM
26
Displaying CA APM TG information in CA Introscope
Investigator 21
E
Enabling and configuring CA Introscope after
installation 22, 23
Enabling and configuring CA Introscope during
installation 22, 23
Enabling, disabling, resetting, or deleting a group
46
Enabling, disabling, resetting, or deleting a script
49
Examples 75, 103
G
General Settings 41
Groups and scripts 42
H
HTTPS protocol 62
I
Identifying CA APM TG transactions 96


Installing CA APM TG on Linux 20
Installing CA APM TG on Windows 18
Installing CA APM TG-specific CA Introscope
components 27
Installing CA Introscope tab views 28
Installing the CA APM Transaction Generator 15,
17
Integrating with CA Introscope on Linux 23
Integrating with CA Introscope on Windows 21
Integration with CA Introscope 13
Integration with the CA Customer Experience
Manager 14
Interval Settings 40
L
Linux DHCP considerations 29
List of Known Agents 35
Load ramping 12, 52
Load ramping example 54
Logically grouping requests using Set Request ID 67
M
Managing CA APM TG user access in a standalone
configuration 24
Manually copying multiple scripts 74
Manually creating scripts 70
Monitoring web services 68
O
Operating system requirements 15
Other metrics 92
Overview of configuring agents 31
R
Recommended minimum hardware requirements
16
Removing agents 36
Request metrics 93
Reserved variable sample 87
S
Script conditions and content variables 84
Script creation and maintenance 13
Script metrics 92
Script reserved variables 86
Script samples 83
Securing access to the Script Editor 77
Securing scripts 76
Sending scripts to CA CEM 52
Setting CA APM TG agent defaults 40
Setting Hierarchy 32
Specifying conditions 73
Specifying request tags 72
Specifying requests 71
Specifying script parameters 71
Standalone configuration 18
Starting the recording session 63
Starting the Script Editor 57
Stopping a script using the <stop> tag or stop
attribute 89
Successful command to local CA APM TG agent 103
T
Testing a script 51
The Connect to Agent tab 35
The All Scripts tab 47
The CA APM TG Agent Configuration 32
The CA APM TG agent View page 36
The CA APM Transaction Generator 11
The Command line and the CA APM TG agent 28
The Dashboard tab 33
The Scripts By Group tab 43
Trace messages 103
Troubleshooting connecting to an agent 37
U
Using a script template 69
Using Configuration Tab buttons 41
Using the Script Recorder 59
V
Viewing all scripts in all groups 48
Viewing CA APM TG data with CA CEM 96
Viewing CA APM TG data with CA Introscope 91
Viewing CA APM TG Metrics 91
Viewing script request details 50
Viewing scripts in a group 47
Viewing status messages 55
W
Working with scripts in the Script Requests page 49
WTGUtil Command syntax 102

Index 107

X
XML special character substitutions 83
XML tag syntax 78

APM - 9.5 - Transaction Generator Implementation Guide

Transféré par

Informations du document

Description originale:

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

APM - 9.5 - Transaction Generator Implementation Guide

Transféré par

Droits d'auteur :

Formats disponibles

Transaction Generator Implementation

Vous aimerez peut-être aussi