APM - 9.5 - APM For SOA Implementation Guide

for SOA 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: About CA Application Performance Management for SOA 17
What is a Service-Oriented Architecture? .................................................................................................................. 17
Common components of the SOA infrastructure ...................................................................................................... 18
How to Monitor SOA Performance Using CA Introscope ......................................................................................... 19
Monitoring Web Service Clients and Servers ...................................................................................................... 20
Using SOA-Specific Dashboards for Proactive Management .............................................................................. 21
Viewing Dependencies and Using Metrics for Triage and Diagnosis .................................................................. 21
Tracing transactions that involve SOA components ........................................................................................... 21
Monitoring Across Multiple Platforms and Transports ....................................................................................... 22
Understanding the Architecture for Monitoring SOA ................................................................................................ 23
Additional SOA Platform Support ............................................................................................................................... 25
Chapter 2: Installing and Configuring CA APM for SOA 27
Installation and Configuration .................................................................................................................................... 27
CA Introscope Components and Versions ................................................................................................................ 28
Basic system requirements for agents ................................................................................................................ 28
SOAP and Application Server Requirements for Agents ..................................................................................... 28
Understanding Directory and File Naming Conventions ..................................................................................... 29
Backing Up Before Upgrading From a Previous Version ..................................................................................... 30
How to Add CA APM for SOA to an Agent .................................................................................................................. 31
Selecting CA APM for SOA in the Standalone Agent Installer ............................................................................. 31
Use Silent Mode to Enable CA APM for SOA for the Agent ................................................................................ 32
Adding CA APM for SOA Manually to an Agent .................................................................................................. 33
Agent Properties Configuration After Installation .............................................................................................. 35
How to Enable SOA Platform Extensions ............................................................................................................ 35
Enable Extensions on the Enterprise Manager .......................................................................................................... 37
Verify the CA APM for SOA Deployment .................................................................................................................... 40
Remove CA APM for SOA ........................................................................................................................................... 41
Chapter 3: Monitoring a Service-Oriented Architecture 43
Viewing SOA-Specific Information in CA Introscope ................................................................................................ 43
About Client and Server Web Services and Operations ...................................................................................... 44
About service namespaces and operation names .............................................................................................. 44
About Unidentified Services and Operations ...................................................................................................... 45
About virtual agents ............................................................................................................................................ 45
Use the SOA Performance Dashboards ...................................................................................................................... 46

8 for SOA Implementation Guide

SOA Performance Overview Dashboard ............................................................................................................. 49
SOA Performance Client Health Dashboard ........................................................................................................ 50
SOA Performance Server Health Dashboard ....................................................................................................... 50
SOA Performance Most Critical Operations Dashboard ..................................................................................... 51
SOA Performance Most Dependent Operations Dashboard .............................................................................. 51
SOA Performance Busiest Operations Dashboard .............................................................................................. 52
Using Investigator to view SOA performance metrics ............................................................................................... 52
The Available Metrics .......................................................................................................................................... 52
View Summarized Metrics on Overview Tabs ..................................................................................................... 53
View Dependency Metrics on the Dependencies Tab ........................................................................................ 55
Viewing Deviation Metrics on the Deviations Tab .............................................................................................. 59
View Critical Operation Metrics on the Most Critical Tab................................................................................... 60
View Dependent Operations on the Most Dependent Tab ................................................................................ 60
Viewing SOAP Fault and Error Metrics on the Errors Tab ................................................................................... 61
Viewing boundary blame in the Investigator ............................................................................................................. 62
View the Default SOA-Specific Metric Groupings ...................................................................................................... 62
View the Default CA APM for SOA Alerts ................................................................................................................... 63
Chapter 4: Using the SOA Dependency Map 65
Understanding the use of the SOA Dependency Map ............................................................................................... 65
Understanding the challenge of the SOA environment ...................................................................................... 65
Understanding what the SOA Dependency Map provides ................................................................................. 66
Understanding dependencies and SOA terminology .......................................................................................... 66
Understanding what you can do with the SOA Dependency Map ...................................................................... 67
How the SOA Dependency Map Gets Data ................................................................................................................ 68
About Persisted Data for the SOA Dependency Map ......................................................................................... 68
Updating the dependency map with new services and operations .................................................................... 70
Aging and removal for obsolete map nodes ....................................................................................................... 71
What to do if the dependency map displays incomplete data ........................................................................... 71
About logical equivalence rules .......................................................................................................................... 72
Understanding context in the SOA Dependency Map ............................................................................................... 73
Understanding how the content type affects what you see ............................................................................... 73
Understanding how the Investigator node affects what you see ....................................................................... 74
Displaying the SOA Dependency Map ........................................................................................................................ 74
About Investigator tree nodes and map nodes .................................................................................................. 75
About standalone and dependent map nodes ................................................................................................... 75
About map nodes for operations ........................................................................................................................ 76
Choosing a physical or logical view ............................................................................................................................ 76
Select a Content Type ................................................................................................................................................ 77
Set a Primary Metric for Dependency Map Nodes .................................................................................................... 78
Selecting ToolTip metrics for dependency map nodes .............................................................................................. 78

Contents 9

Changing the dependency levels displayed ............................................................................................................... 79
Checking for additional dependencies for a map node ...................................................................................... 80
Hiding dependencies for a map node ................................................................................................................. 80
Checking for additional dependencies for all items in the map.......................................................................... 81
Hiding dependencies for all items in the map .................................................................................................... 81
Navigating within the SOA Dependency Map ............................................................................................................ 82
Panning, zooming, and fitting the SOA Dependency Map .................................................................................. 82
Jumping from a map node to the associated Investigator tree node ................................................................. 83
Showing all operations for a service ................................................................................................................... 83
Showing all services for an agent ........................................................................................................................ 84
Saving SOA Dependency Map images ........................................................................................................................ 84
SOA Dependency Map Sharing ........................................................................................................................... 84
Saving the SOA Dependency Map as a snapshot ................................................................................................ 85
Starting a Transaction Trace from a map node .......................................................................................................... 86
SOA Dependency Map for a Cluster ........................................................................................................................... 87
Chapter 5: Using Transaction Tracing in SOA Environments 89
About cross-process transaction tracing .................................................................................................................... 89
Understanding how segments of a transaction are linked ................................................................................. 90
Understanding context for a cross-process transaction trace ............................................................................ 91
Using transaction tracing to solve problems .............................................................................................................. 91
Start and View Transaction Traces ............................................................................................................................. 92
Using the Summary View .................................................................................................................................... 93
Use the Trace View ............................................................................................................................................. 94
Use the Tree View ............................................................................................................................................... 94
Using the Sequence View .................................................................................................................................... 95
Set Filters for Transaction Traces ............................................................................................................................... 98
Adding and saving filters ................................................................................................................................... 100
Removing filters ................................................................................................................................................ 100
Using complex filters ......................................................................................................................................... 101
Querying the event database for SOA services ........................................................................................................ 101
Viewing error event information ...................................................................................................................... 102
Viewing correlated event information .............................................................................................................. 102
Chapter 6: Configuring SOA-Specific Properties 103
Configuring the name displayed for web services ................................................................................................... 103
Configuring correlated tracing ................................................................................................................................. 105
Configuring properties for clients and servers .................................................................................................. 106
Disabling correlated tracing .............................................................................................................................. 106
Configuring the Insertion Point for SOAP Handlers ................................................................................................. 107
Client and Server Properties for Inserting the SOAP Handler ........................................................................... 107


Changing the Default Order for SOAP Handlers ................................................................................................ 108
Configuring limits for the SOA dependency map ..................................................................................................... 108
Chapter 7: Monitoring Oracle Service Bus 111
About Oracle Service Bus (OSB) ............................................................................................................................... 111
How to Enable Monitoring for Oracle Service Bus ................................................................................................... 114
Enabling the agent for monitoring Oracle Service Bus ..................................................................................... 114
Enable the Oracle Service Bus Enterprise Manager Extension ......................................................................... 116
Use Dashboards to Monitor Oracle Service Bus....................................................................................................... 118
Understanding and viewing metrics for Oracle Service Bus .................................................................................... 120
Metrics for BusinessServices ............................................................................................................................. 121
Metrics for Pipelines ......................................................................................................................................... 122
Metrics for ProxyServices .................................................................................................................................. 122
Metrics for Transports ...................................................................................................................................... 123
Metrics for UDDI ............................................................................................................................................... 124
Metrics for XQueries ......................................................................................................................................... 124
View Default Oracle Service Bus Metric Groupings ................................................................................................. 124
View Default Oracle Service Bus Alerts .................................................................................................................... 125
Viewing Oracle Service Bus dependencies ............................................................................................................... 126
Tracing transactions for Oracle Service Bus ............................................................................................................. 127
Understanding the value of cross-process transaction tracing ......................................................................... 127
Starting and Viewing a Sample Transaction Trace ............................................................................................ 127
Chapter 8: Monitoring TIBCO BusinessWorks 129
About TIBCO BusinessWorks .................................................................................................................................... 129
How to Enable Monitoring for TIBCO BusinessWorks .............................................................................................. 131
Enabling the agent for monitoring TIBCO BusinessWorks ................................................................................ 131
Configure TIBCO BusinessWorks to Use the Agent ........................................................................................... 135
Configuring automatic agent naming ................................................................................................................ 136
Enable the Enterprise Manager Extension ........................................................................................................ 137
Use Dashboards to Monitor TIBCO BusinessWorks ................................................................................................. 138
Understanding and viewing metrics for TIBCO BusinessWorks ............................................................................... 140
Metrics for Activities ......................................................................................................................................... 142
Metrics for Group Actions ................................................................................................................................. 142
Metrics for Hawk ............................................................................................................................................... 142
Metrics for jobs and job pools .......................................................................................................................... 150
Metrics for Processes ........................................................................................................................................ 152
Metrics for Transports ...................................................................................................................................... 154
Metrics for WebServices ................................................................................................................................... 157
View Default TIBCO BusinessWorks Metric Groupings ............................................................................................ 158
Viewing default TIBCO BusinessWorks alerts........................................................................................................... 158

Contents 11

Viewing TIBCO BusinessWorks dependencies ......................................................................................................... 159
Tracing transactions for TIBCO BusinessWorks ........................................................................................................ 161
How to Use the Transaction Trace Data in Tibco ............................................................................................. 162
Starting and viewing a sample transaction trace .............................................................................................. 163
About frontends and backends for BusinessWorks ................................................................................................. 164
Understanding the limitations for spawned processes .................................................................................... 165
Disabling the association of multiple backends with a frontend ...................................................................... 165
Adding a custom TIBCO BusinessWorks backend ............................................................................................. 166
Customizing metric aging and removal .................................................................................................................... 167
Configuring correlated tracing for TIBCO BusinessWorks ........................................................................................ 167
Chapter 9: Monitoring TIBCO Enterprise Message Service 169
About TIBCO Enterprise Message Service ................................................................................................................ 169
How to Install the SOA Extension for TIBCO EMS .................................................................................................... 170
Run the Standalone Agent Installer ......................................................................................................................... 171
Use a Response File for Silent Installation ........................................................................................................ 171
Manually Extract an Installation Archive .......................................................................................................... 172
Prepare the TIBCO EMS Server for Monitoring ........................................................................................................ 172
Configuring the TIBCO EMSMonitor agent............................................................................................................... 173
Configuring basic connection properties .......................................................................................................... 174
Configuring polling intervals for the server ...................................................................................................... 175
Configuring filters for selective monitoring ............................................................................................................. 176
Configuring filters for queues and topics .......................................................................................................... 176
Defining the advanced components to include ................................................................................................ 177
Defining regular expression filters for advanced components ......................................................................... 177
Replacement of Special Characters in EMS Names ........................................................................................... 178
Defining a monitoring level ...................................................................................................................................... 178
Using the default monitoring level definitions ................................................................................................. 179
Modifying the default monitoring level definitions .......................................................................................... 180
Creating encrypted passwords ................................................................................................................................. 182
Connecting to TIBCO EMS server instances using SSL .............................................................................................. 183
Starting the EMSMonitor agent ............................................................................................................................... 185
Start EMSMonitor With a Startup Script ........................................................................................................... 185
Running the EMSMonitor agent as a Windows service .................................................................................... 186
Enable the Enterprise Manager Extension ............................................................................................................... 186
Use Dashboards to Monitor TIBCO EMS .................................................................................................................. 187
Understanding and viewing TIBCO EMS metrics ...................................................................................................... 189
Metrics for Last Check ....................................................................................................................................... 192
Metrics for Queues ........................................................................................................................................... 193
Metrics for the Server ....................................................................................................................................... 197


Metrics for Topics ............................................................................................................................................. 205
Metrics for Routes............................................................................................................................................. 209
Metrics for Channels ......................................................................................................................................... 210
Metrics for Bridges ............................................................................................................................................ 212
Viewing default TIBCO EMS metric groupings ......................................................................................................... 212
Viewing default TIBCO EMS alerts ............................................................................................................................ 213
Summary of agent configuration properties ............................................................................................................ 214
Chapter 10: Monitoring webMethods Broker 221
About webMethods Broker ...................................................................................................................................... 221
How to Install the SOA Extension for webMethods Broker ..................................................................................... 223
Verify Prerequisites ........................................................................................................................................... 223
Run the Standalone Agent Installer .................................................................................................................. 223
Prepare webMethods Broker for Monitoring ................................................................................................... 225
Configure the Agent for the webMethods Broker ............................................................................................ 226
Enable the Enterprise Manager Extension for webMethods Broker ................................................................ 231
Use Dashboards to Monitor webMethods Broker ................................................................................................... 232
Understanding and Viewing Metrics for the Broker ................................................................................................ 234
Metrics for Brokers ........................................................................................................................................... 238
Metrics for Client groups .................................................................................................................................. 239
Metrics for Clients ............................................................................................................................................. 239
Metrics for Document Types ............................................................................................................................. 241
Metrics for the Retry Queue ............................................................................................................................. 241
Metrics for Territory Stats ................................................................................................................................. 242
Metrics for the Trace queue ............................................................................................................................. 243
Metrics for Utilization ....................................................................................................................................... 244
View Default Broker Metric Groupings .................................................................................................................... 244
View Default Broker Alerts ....................................................................................................................................... 245
Chapter 11: Monitoring webMethods Integration Server 247
About webMethods Integration Server ................................................................................................................... 247
How to Enable Monitoring for webMethods Integration Server ............................................................................. 250
Manually Enable the Agent for Monitoring webMethods Integration Server .................................................. 251
About the Directive Files for webMethods Integration Server ......................................................................... 252
Enable the Enterprise Manager Extension ........................................................................................................ 253
Use Dashboards to Monitor webMethods ............................................................................................................... 253
Filtering the services monitored and displayed ....................................................................................................... 258
About the Default Configuration File ................................................................................................................ 259
Including and excluding services using regular expressions ............................................................................. 259
Specifying a Different Location for the Configuration File ................................................................................ 260
View and Navigate Metrics for webMethods .......................................................................................................... 260

Contents 13

Metrics for Adapters ......................................................................................................................................... 261
Metrics for Authorization .................................................................................................................................. 263
Metrics for Business Processes ......................................................................................................................... 264
Metrics for Flow Services .................................................................................................................................. 267
Metrics for Java Services ................................................................................................................................... 267
Metrics for JDBC Pools ...................................................................................................................................... 268
Metrics for Thread Pools ................................................................................................................................... 268
Metrics for Trading Networks ........................................................................................................................... 269
Metrics for Triggers ........................................................................................................................................... 272
Metrics for WebServices ................................................................................................................................... 272
Metrics for XSLT Services .................................................................................................................................. 274
Viewing default webMethods metric groupings ...................................................................................................... 274
Viewing default webMethods alerts ........................................................................................................................ 275
Viewing webMethods dependencies ....................................................................................................................... 276
Tracing transactions for webMethods ..................................................................................................................... 277
About Configuring Cross-Process Transaction Tracing...................................................................................... 277
Using the Sequence View for webMethods processes ..................................................................................... 278
Chapter 12: Monitoring WebSphere Process Server and WESB 281
About WebSphere Process Server and WESB .......................................................................................................... 281
Monitoring WebSphere Process Server Components ....................................................................................... 282
Monitoring WebSphere Enterprise Service Bus standalone ............................................................................. 285
How To Enable Monitoring for WebSphere Process Server or WESB ...................................................................... 285
Enabling the agent for monitoring WPS or WESB ............................................................................................. 286
Enable the Enterprise Manager Extension for WPS or WESB ........................................................................... 289
Using dashboards to monitor WPS or WESB ............................................................................................................ 292
About WebSphere Process Server dashboards ................................................................................................. 292
About WESB dashboards ................................................................................................................................... 294
View WebSphere Process Server or WESB Dashboards.................................................................................... 295
View and Navigate Metrics for WPS/WESB ............................................................................................................. 296
Metrics for Business Objects Maps ................................................................................................................... 297
Metrics for Business Processes ......................................................................................................................... 297
Metrics for Business Rules ................................................................................................................................ 297
Metrics for Business State Machines ................................................................................................................ 298
Metrics for Data Bindings .................................................................................................................................. 298
Metrics for Human Tasks .................................................................................................................................. 298
Metrics for Interface Maps ............................................................................................................................... 298
Metrics for J2CA Adapters................................................................................................................................. 299
Metrics for Java Components ........................................................................................................................... 299


Metrics for Mediation flows and primitives ...................................................................................................... 299
Metrics for Relationships .................................................................................................................................. 303
Metrics for Selectors ......................................................................................................................................... 303
Metrics for Service Integration Bus Communication ........................................................................................ 303
Metrics for WebSphere Process Server Faults .................................................................................................. 303
Viewing default WPS and WESB metric groupings ................................................................................................... 303
Viewing default WPS and WESB alerts ..................................................................................................................... 304
Viewing WPS or WESB dependencies ...................................................................................................................... 305
Tracing transactions for WPS or WESB..................................................................................................................... 306
Using the Sequence View for WebSphere processes ........................................................................................ 307
Configure Tracing to Include Business Process/Business State Machine Activities .......................................... 308
Appendix A: SOA-Specific Agent Configuration Properties 311
Understanding where agent properties are located ................................................................................................ 311
Configure Agent Properties ...................................................................................................................................... 311
About SOA-Specific Agent Properties ...................................................................................................................... 312
agent.httpheaderinsertion.enabled .................................................................................................................. 313
agent.httpheaderread.enabled ......................................................................................................................... 314
agent.soapheaderinsertion.enabled ................................................................................................................. 315
agent.soapheaderread.enabled ........................................................................................................................ 316
agent.soa.metricNameFormatting .................................................................................................................... 316
agent.transactiontrace.boundaryTracing.cacheFlushFrequency ...................................................................... 317
agent.transactiontrace.boundaryTracing.enable .............................................................................................. 318
soa.client.prependhandler ................................................................................................................................ 318
soa.server.appendhandler ................................................................................................................................ 319
Appendix B: SOA-Specific Enterprise Manager Configuration Properties 321
Configuring Enterprise Manager properties ............................................................................................................ 321
About SOA-specific Enterprise Manager properties ................................................................................................ 322
soa.dependencymap.aging.refresh.interval ..................................................................................................... 325
soa.dependencymap.aging.expire.interval ....................................................................................................... 326
soa.dependencymap.heuristics.clientside.enable ............................................................................................ 326
soa.dependencymap.heuristics.namematch.enable ........................................................................................ 327
soa.dependencymap.heuristics.serverside.enable ........................................................................................... 328
soa.dependencymap.log.suppress .................................................................................................................... 330
soa.dependencymap.max.edge.ratio ................................................................................................................ 331
soa.dependencymap.max.vertices.................................................................................................................... 332
soa.deviation.enable ......................................................................................................................................... 333
soa.deviation.art.enable ................................................................................................................................... 334

Contents 15

soa.deviation.dependencymetric.enable .......................................................................................................... 334
soa.deviation.count.per.metric ......................................................................................................................... 335
soa.deviation.dependency.refreshrate ............................................................................................................. 336
soa.deviation.errors.enable .............................................................................................................................. 337
soa.deviation.max.metric.count ....................................................................................................................... 337
soa.deviation.mean.days .................................................................................................................................. 338
soa.deviation.metric.expressionlist .................................................................................................................. 338
soa.deviation.metric.calledbackends ................................................................................................................ 339
soa.deviation.usage.enable .............................................................................................................................. 340
soa.dashboard.typeviewer.average.enable ...................................................................................................... 341
soa.dashboard.typeviewer.errors.enable ......................................................................................................... 342
soa.dashboard.typeviewer.response.enable .................................................................................................... 343
soa.dashboard.typeviewer.mostcritical.enable ................................................................................................ 344
soa.dashboard.typeviewer.mostcritical.count.................................................................................................. 345
soa.dashboard.typeviewer.mostdependent.enable ......................................................................................... 346
soa.dashboard.typeviewer.mostdependent.count ........................................................................................... 347
Appendix C: SOA-Specific Workstation Configuration Properties 349
Configuring Workstation properties ........................................................................................................................ 350
About SOA-Specific Workstation Properties ............................................................................................................ 351
soa.dependencymap.ui.view.nodecount .......................................................................................................... 352
com.wily.introscope.soa.dependencymap.ui.view.edgecount ......................................................................... 353
soa.dashboard.typeviewer.average.enable ...................................................................................................... 354
soa.dashboard.typeviewer.errors.enable ......................................................................................................... 355
soa.dashboard.typeviewer.response.enable .................................................................................................... 356
soa.dashboard.typeviewer.mostcritical.enable ................................................................................................ 357
soa.dashboard.typeviewer.mostcritical.count.................................................................................................. 358
soa.dashboard.typeviewer.mostdependent.enable ......................................................................................... 359
soa.dashboard.typeviewer.mostdependent.count ........................................................................................... 360
workstation.soa.dependencymap.fetchmetrics ............................................................................................... 361
workstation.traceview.crossprocess.duration.full ............................................................................................ 362
workstation.traceview.crossprocess.duration.net............................................................................................ 363
Appendix D: SOA-Specific WebView Configuration Properties 365
Configure WebView Properties ................................................................................................................................ 365
About SOA-Specific WebView Properties ................................................................................................................ 366
soa.dependencymap.ui.view.nodecount .......................................................................................................... 366
com.wily.introscope.soa.dependencymap.ui.view.edgecount ......................................................................... 367


Index 369


Chapter 1: About CA Application
Performance Management for SOA

A service-oriented architecture (SOA) is an application platform that enables
organizations to share and reuse loosely coupled services to accomplish business goals.
There are several benefits to deploying applications using a service-oriented
architecture, but there are also unique challenges to monitoring SOA environments. This
section highlights the key ways you can use CA Application Performance Management
for SOA (CA APM for SOA) to meet those challenges.
This section contains the following topics:
What is a Service-Oriented Architecture? (see page 17)
Common components of the SOA infrastructure (see page 18)
How to Monitor SOA Performance Using CA Introscope (see page 19)
Understanding the Architecture for Monitoring SOA (see page 23)
Additional SOA Platform Support (see page 25)
What is a Service-Oriented Architecture?
A service-oriented architecture (SOA) is an application platform that relies on
standardized communication protocols to enable loosely coupled services to accomplish
business goals.
The benefits of using SOA include greater business agility and flexibility, improvements
in customer service and efficiency, and reduced development costs. Monitoring and
managing a complex SOA environment, however, can be far more difficult than
managing a traditional client-server environment.
In a traditional client-server environment, there is direct communication between
clients and a limited number of servers. When problems occur, finding the cause of the
failure is typically straightforward because only a few systems are involved in any
individual business transaction. You can isolate the source of the problem by
investigating the specific systems directly involved in the transaction.
Identifying the source of a problem becomes more difficult when web application
servers act as a central point for distributing access to applications across multiple
client-server systems. Performance degradation, errors, or operation failures can be
caused by virtually any component or computer that participates in the web server
connected infrastructure.
Common components of the SOA infrastructure


A service-oriented architecture introduces an additional layer of complexity for
monitoring application performance and availability. With SOA, loosely coupled services
rely on standardized communication to integrate and extend applications that run on
different platforms. Because the services separate the business logic from the
underlying operating system or platform, organizations can be more agile and respond
quickly to changes in market or product dynamics. Individual services can be designed to
handle specific parts of complex or multistep business processes, creating chains of
dependencies across a heterogeneous environment.
Using a service-oriented architecture enables organizations to develop and deploy
applications faster and in a more cost-effective way because services can be reused,
modified, or replaced as independent components. This efficient, modular approach to
application architecture, however, presents its own challenges for application
management.
Common components of the SOA infrastructure
Although using SOA simplifies the implementation and integration of business
processes, the underlying SOA infrastructure typically relies on a complex interaction of
multiple components. For example, completing a simple business transaction typically
involves multiple individual services running on different components exchanging
messages with each other using different protocols. Monitoring the key components of
the transaction requires visibility into how the services communicate, how requests and
responses are routed from one service to another, which services have dependencies on
other services, and where critical bottlenecks occur.
Although the specific monitoring requirements depend on your SOA implementation, a
typical SOA infrastructure includes:
multiple services that use standard interfaces to enable client-side and server-side
components to exchange messages with each other
a message handling system that enables requests and responses to be routed,
transformed, and delivered from one component to another
adapters that enable external or legacy systems to connect and use the services
deployed
a registry that records and publishes information about the services available
How to Monitor SOA Performance Using CA Introscope


The following figure illustrates a simplified SOA infrastructure that uses the Simple
Object Access Protocol (SOAP) and eXtensible Markup Language (XML) to enable web
services (WS) to communicate with each other through an enterprise service bus (ESB)
that controls the delivery of messages to the appropriate destinations.

Because the SOA infrastructure depends on the modular delivery of reusable and
adaptable components, transactions in these environments typically involve more
components. As the number of components involved in transactions increase, tracking
the flow of a transaction becomes increasingly difficult. There are also more potential
points of failure as more messages are passed from process to process or from one
platform to another, often over different transport protocols. In addition, once
organizations commit to deploying applications in a SOA environment, they tend to
move an increasing number of mission-critical services to that environment, making the
monitoring of that infrastructure increasingly important to the health of the business.
CA APM for SOA addresses these unique challenges by providing visibility into the health
of the SOA infrastructure and the real-time performance of the components that
participate in SOA transactions.
CA APM for SOA provides real-time and historical views into application performance
for the SOA environment. It extends the core CA Introscope capabilities to enable you
to monitor and track web service transactions from the frontend where a user requests
service to the backend systems used to fulfill the request. By using CA Introscope with
CA APM for SOA, you can proactively monitor SOA client and server performance, triage
incidents, and analyze service-related problems in depth without access to application
source code or SOA architects.


Adding CA APM for SOA to CA Introscope helps you monitor the SOA environment by
providing:
dashboard visibility of SOA client and server health and performance for proactive
management of the environment
overviews and detailed metrics that help you isolate problems to the web service,
application, or back-end
visual representation of dependencies between agents, services, and operations to
help you assess how a problem in one component may affect other components
correlated transaction tracing across platforms, transport protocols, and application
servers
visibility and context for application errors or SOAP faults produced by web service
components
In addition to these default features that enable the monitoring and application
management for SOA clients and servers, you can customize CA Introscope and CA
APM for SOA to suit your needs. For example, you can:
build a web service audit trail by verifying web service invocation receipt and
completion
create application groups of web services, and know whether a group is exceeding
response time, transaction volume, or error thresholds
set up virtual agents to collect aggregated metrics for web service clients and
services
Monitoring Web Service Clients and Servers
In most cases, web service transactions consist of a client that makes requests to a web
service and a server that responds to the request. For example, a Java class that enables
a user or program to request a stock quote can be considered a web service client. The
Stock Quote web service that provides the price in response to the request is considered
the web service server.
The agent tracks and displays client and server metrics separately, enabling you to
monitor and set thresholds for client-side and server-side performance separately.
Keeping the client-side and server-side separate also allows you to see dependencies in
the proper context.
In most cases, the client and server for a web service run in separate Java Virtual
Machines (JVMs) or Microsoft Common Language Runtime environments (CLRs).
Therefore, the metrics for client-side and server-side operations are typically reported
by two or more agents. If you want to see the metrics for the client and server
aggregated together, you can do so by configuring a virtual agent (see page 45).


Using SOA-Specific Dashboards for Proactive Management
With CA APM for SOA, you can monitor critical services around the clock, in real-time
and with production load. SOA-specific dashboards summarize key performance
indicators and provide default thresholds and alert indicators to give you early
notification when response time increases or there is unusual activity, such as increased
load or reduced throughput. The dashboards and alert indicators enable you to identify
potential problems quickly and proactively, and then analyze issues in detail to
determine the nature of the problem and who is responsible for resolution.
Using CA Introscope and CA APM for SOA dashboards, you can monitor web service
client and server performance continuously to detect potential problems at a glance as
they are developing. In many cases, taking this proactive approach helps you identify
and correct a failing component before it affects your customers or end users.
Viewing Dependencies and Using Metrics for Triage and Diagnosis
When a problem appears in complex SOA environments, it is often a challenge to know
where to start looking for the source. Because the application architecture is more
modular, there are more components involved in each transaction and more potential
points of failure.
Dashboards and alert indicators provide early visibility of potential issues. The SOA
dependency map provides visibility into how modular components are interrelated and
how those relationships are affecting performance. Dependencies let you analyze where
there are potential bottlenecks or critical operations and compare the average response
time or other metrics for services that have dependencies on each other.
High-level views summarize overall application performance, alert you to potential
problems, and illustrate the dependency relationships between components. CA
Introscope with CA APM for SOA also provides both high-level summaries and detailed
operation-level metrics that architects and developers in your organization can use to
review, isolate, and resolve problems. See Using Investigator to view SOA performance
metrics (see page 52) for more information about using metrics to evaluate web
services performance and operation.
Tracing transactions that involve SOA components
In the SOA environment, it is common for messages to pass between loosely coupled
components using multiple protocols, making the tracking of transaction flow more
difficult. Transaction traces provide detailed information about individual transactions in
which web services are involved, the number and nature of web service faults, and
component interactions. For example, transaction traces identify where each segment
of a transaction took place and how well each segment performed in real-time.
Application experts can then use the information to identify the root cause of errors or
performance degradation.


When an incident occursfor example, if the response time for a particular web service
slowsan alert can notify the appropriate stakeholders before a service level
agreement (SLA) is violated or an end-user is affected. Application Support personnel
can then gather more detailed information about the nature of the problem by
monitoring individual transactions to visually identify the parts of the transaction that
are taking the most time and the sequence of calls synchronously or asynchronously to
complete each captured transaction.
Monitoring Across Multiple Platforms and Transports
CA Introscope with CA APM for SOA lets you monitor and manage your entire
infrastructure, including transactions that span multiple operating systems, application
platforms, or transport protocols. In a typical SOA environment, it is common for
transactions to use a combination of SOAP, XML, HTTP, HTTPS, and JMS transport
protocols and to include processing on multiple application server environments.
With CA APM for SOA, you can trace transactions across any combination of supported
J2EE or .NET servers. For example, you can trace the full path of a transaction that
includes a service running on WebLogic sending a request to a service running on SAP
NetWeaver or on a .NET application server. Depending on the additional SOA extensions
you enable, you can also monitor transactions across any combination of Oracle Service
Bus, IBM WebSphere Process Server, IBM WebSphere Enterprise Service Bus, TIBCO
BusinessWorks, webMethods Integration Server, or IBM WebSphere MQ components.
It is also common for the SOA environment to include both composite applications that
are linked to the SOA infrastructure through adapters and new applications that use
standardized protocols such as SOAP and XML. Because the environment includes both
legacy and new applications, you may need to monitor applications that use various
transports and payload types. For example, with CA APM for SOA, you can monitor
applications that use SOAP over HTTP, SOAP over JMS, XML over HTTP, or other
messaging transports and protocols.
Understanding the Architecture for Monitoring SOA


CA APM for SOA provides the following lightweight components for CA Introscope:
A SOA-specific extension to the Java or .NET Agent
A SOA-specific management module for the Enterprise Manager
The agent extension enables the agent to monitor Java- and .NET-based web services on
supported application servers and send information about the performance of those
web services to the Enterprise Manager.
The SOA-specific extension to the Enterprise Manager enables the SOA-specific
information collected by the agent to be displayed using the CA Introscope
Workstation in SOA-specific dependency maps, dashboards, Investigator nodes, and
tabs.


The following figure illustrates the basic architecture with the agent and CA APM for
two application servers. The application servers send and receive web service requests
and report web service data to a single Enterprise Manager with CA APM for SOA
enabled.

Additional SOA Platform Support


In addition to the functionality provided by CA APM for SOA, there are several additional
SOA platforms that you can monitor. Depending on your environment, you may be able
to monitor the following additional SOA platforms:
Oracle Service Bus (OSB) is an Enterprise Service Bus that handles message
distribution and transformation for Oracle WebLogic.
TIBCO BusinessWorks is a business service development and processing engine.
TIBCO Enterprise Message Service enables synchronous and asynchronous
communications between systems throughout the enterprise using queues, topics,
and advanced components such as bridges, multicast channels, and routes.
webMethods Broker provides asynchronous processing and message handling
services to publish and deliver documents.
webMethods Integration Server provides infrastructure components to enable
organizations to create, orchestrate, and integrate business processes and web
services.
IBM WebSphere Process Server (WPS) with IBM WebSphere Enterprise Service Bus
(WESB) is an integration platform that includes message handling through
WebSphere Enterprise Service Bus.
IBM WebSphere Enterprise Service Bus (WESB) as a standalone product.
WebSphere Enterprise Service Bus manages message flow, data transformation,
and routing between services and clients with the help of mediation flows and
primitives.


Most of the SOA platform extensions add files to the agent and Enterprise Manager. For
example, the following figure illustrates adding the SOA extension for TIBCO
BusinessWorks to the application server and the Enterprise Manager:

For some SOA extensions, the agent cannot be used. For example, the SOA extension for
TIBCO Enterprise Message Service uses a standalone agent. For more information about
any SOA extension, see the appropriate chapter for that extension.


Chapter 2: Installing and Configuring CA
APM for SOA

Installation and Configuration (see page 27)
CA Introscope Components and Versions (see page 28)
How to Add CA APM for SOA to an Agent (see page 31)
Enable Extensions on the Enterprise Manager (see page 37)
Verify the CA APM for SOA Deployment (see page 40)
Remove CA APM for SOA (see page 41)
Installation and Configuration
You can install and configure CA APM for SOA on the agent and Enterprise Manager in
the following ways:

Is the Agent Installed? Is CA APM for SOA Enabled? Next Steps
Yes Yes Enable Extensions on the
Enterprise Manager (see
page 37).
Yes No Add CA APM for SOA
Manually to an Agent (see
page 33).
No No Review CA APM for SOA
Prerequisites (see page 28).
Add CA APM for SOA to an
Agent (see page 31).
Note: Use this information
with the information in the
CA APM Java Agent
Implementation Guide or the
CA APM .NET Agent
Implementation Guide to
complete the installation.

CA Introscope Components and Versions


CA APM for SOA provides an extension to CA Introscope that enables monitoring of
service-oriented architectures and web services. You can install CA APM for SOA at the
same time you install core CA Introscope components or separately after you install
core CA Introscope components. Whether you install CA APM for SOA with CA
Introscope or you install CA APM for SOA separately, install the following CA
Introscope components and versions:
The Java agent or the .NET agent must be at the same version as CA Introscope.
The Enterprise Manager must be at the same version as the agent or at a higher
version than the agent.
Basic system requirements for agents
CA APM for SOA adds files to the Enterprise Manager and the agent. Because CA APM
for SOA extends the agent, the minimum system requirements for processing, memory,
and available disk space are the same as the requirements for the agent.
See the following guides for specific information about CA APM system requirements:
For basic memory and disk space requirements, see CA APM Installation and
Upgrade Guide.
For guidelines on adjusting processing load and managing system resources, such as
CPU, see the CA APM Sizing and Performance Guide.
For the minimum JVM and JRE versions and related JVM memory requirements, see
the CA APM Java Agent Implementation Guide.
In addition to the basic agent requirements, CA APM for SOA-enabled agents require a
supported SOAP engine to be available in the local operating environment. For
supported SOAP engines, see to the CA APM Compatibility Guide. The SOAP engine you
use determines the SOAP stack implementation and type of web service message
exchanges the agent can support.
SOAP and Application Server Requirements for Agents
The operating system and application server you use determine the SOAP engine and
SOAP stack implementation available to handle web service messages. For example,
applications on a computer using Apache Axis 2.0 can process SOAP messages using
either JAX-RPC or JAX-WS.


Native SOAP Engine Support for Java Agents
If you add CA APM for SOA to a Java agent, the agent can support various SOAP engines
and application programming interfaces (APIs). Depending on the application server and
version, the agent supports SOAP stack implementations that adhere to native,
JAX_RPC, or JAX-WS standards.
Note: For a complete list of the application servers and SOAP stack implementations
that the agent supports in the current version, see the CA APM for SOA section of the
Compatibility Guide.
Native SOAP Engine Support for .NET Agents
By default, the .NET agent supports the monitoring of ASP.NET web services. If you add
CA APM for SOA to a .NET agent, the agent provides standard web service naming and
additional dependency-related metrics and dependency-based mapping for the SOAP
communication services you are using. To support the monitoring of web services on
the .NET agent using the .NET Framework, you can use the following web services:
Standard ASP.NET web services
Windows Communication Foundation (WCF) web services
In addition to the .NET Framework, use the following attributes to monitor ASP.NET web
services:
Server-side web services must have the WebMethod attribute applied.
Client-side web services must have the SOAPDocumentMethod, HttpMethod, or
SoapRpcMethod attribute applied.
Note: For information about SOAP support, see the SOA Performance Management
section of the Compatibility Guide. For information about these attributes or how to
apply them to methods or classes, see the Microsoft Developer Network (MSDN)
Library.
Understanding Directory and File Naming Conventions
This guide uses the following conventions in file names and directory paths:

Where you see It indicates

<Agent_Home>

The top-level directory where the agent is installed. This directory
is typically named wily.
<EM_Home> The top-level directory where the Enterprise Manager is installed.


Where you see It indicates
<version> Version-specific identifier included in file names or displayed in
the user interface.
For example, the following file name:
com.wily.introscope.soa.dependencymap_<version>.jar
represents a version-specific file name, such as:
com.wily.introscope.soa.dependencymap_v9.1.0.0.jar

Forward slash (/)
path separators

The path separator used in directory names on the platform you
are using.
The forward slash (/) is used on UNIX platforms and in examples
throughout this guide, but you should use the separator
appropriate to the platform you are using.
Dollar sign ($)
environment
variables
The environment variable notation used on your platform.
The dollar sign ($) is used on UNIX platforms and in examples
throughout this guide, but you should use the character
appropriate to the platform you are using.

Backing Up Before Upgrading From a Previous Version
If you are upgrading from a previous version of Web Services Manager or CA APM for
SOA, back up your current environment and save the existing files in a backup directory
before adding the CA APM for SOA agent or Enterprise Manager files.
If you are upgrading from a previous version, do the following:
Copy the existing <Agent_Home>/IntroscopeAgent.profile file to a backup directory.
Copy the existing <Agent_Home>/webservices.pbd file to a backup directory.
Copy the existing <EM_Home>/modules/SPM_ManagementModule.jar file to a
backup directory.
If you are upgrading from a previous version and the agent is a .NET agent, do the
following:
Verify that you have uninstalled the older version of the .NET agent before installing
a new version of the .NET agent.
Verify that the .NET agent and the CA APM for SOA files you want to upgrade are at
the same version level. A mismatch in version information can cause errors and
prevent applications from being monitored.
How to Add CA APM for SOA to an Agent


You can add CA APM for SOA and SOA-related extensions to an agent automatically
when you install the agent interactively or silently using a response file. You can also
add CA APM for SOA and other SOA-related extensions to an agent manually after
installing the agent.
Depending on the type of installation you choose, perform the appropriate task:
Selecting CA APM for SOA in the Standalone agent installer (see page 31)
Adding CA APM for SOA during silent installation (see page 32)
Adding CA APM for SOA manually to an agent (see page 33)
After installing or updating an agent to include CA APM for SOA, see Configuring agent
properties after installation (see page 35) for information about configuring the
application environment. If you want to monitor other SOA platforms, such as Oracle
Service Bus or TIBCO BusinessWorks, you can also install those files interactively, using a
response file, or manually after installing the agent and selecting CA APM for SOA. For
more information, see How to enable SOA platform extensions (see page 35).
Selecting CA APM for SOA in the Standalone Agent Installer
If you install the agent interactively, you have the option to add CA APM for SOA and
other monitoring extensions as a step in the installation process. The specific options
displayed in the Standalone agent installer depend on the agent and the application
server you select. For example:
Select Default, JBoss, Tomcat, WebLogic, or WebSphere as the application server if
you want to enable CA APM for SOA
Select WebLogic as the application server if you want to enable CA APM for Oracle
Service Bus
Select Default as the application server if you want to enable CA APM for TIBCO
BusinessWorks or CA APM for webMethods Integration Server
Select WebSphere as the application server if you want to enable CA APM for
WebSphere Process Server with WESB or CA APM for WebSphere Enterprise Service
Bus (WESB) as a standalone product.
For example, if you run the Standalone agent installer interactively on Windows and
select Default as your application server, you can select CA APM for SOA and CA APM
for TIBCO BusinessWorks or CA APM for webMethods Integration Server as monitoring
options.


If you select the CA APM for SOA option in the Standalone agent installer, the related
files for the agent are automatically copied to the appropriate directory in the agents
home directory and the agents profile is automatically updated to include the
appropriate ProbeBuilder directives files for monitoring SOA environments. For
example, appmap-soa.pbd and webservices.pbd are automatically added to the
introscope.autoprobe.directivesFile property.
If you install CA APM for SOA using the Standalone agent installer, perform the next
steps for configuring (see page 35) Java and .NET agents.
Use Silent Mode to Enable CA APM for SOA for the Agent
If you install the agent in silent mode, you can use settings in the response file. These
settings let you specify whether you want to enable CA APM for SOA for the agent. With
a response file, you can install and configure agent properties remotely and without
user interaction. This method lets you automate the process using scripts or other
software delivery options.
Note: For more information about installing the agent in silent mode, see the CA APM
Java Agent Implementation Guide or the CA APM .NET Agent Implementation Guide.
Follow these steps:
1. Open the SampleResponseFile.Agent.txt file, located in the same directory as the
Standalone agent installer.
2. Edit the SampleResponseFile.Agent.txt file to reflect your preferred installation
settings.
3. Set the shouldEnableSPM property to true to add CA APM for SOA to the agent. For
example:
shouldEnableSPM=true
If you set this property to false the SPM-specific files are automatically copied to
the <Agent_Home>/examples directory, but the agent profile is not updated.
You can also enable monitoring for specific SOA platforms using properties in the
response file. If you want to enable monitoring for additional SOA platforms, set the
shouldEnableSPM property to true.
4. Save the SampleResponseFile.Agent.txt file.
5. Enter the appropriate command at the command line to invoke the installer.
If you install CA APM for SOA silently using a response file, the next steps are
configuring agent properties after installation (see page 35).


More information:
CA Introscope Components and Versions (see page 28)
How to Enable SOA Platform Extensions (see page 35)

Adding CA APM for SOA Manually to an Agent
If you did not enable CA APM for SOA in the Standalone agent installer or in the
response file for silent installation, you can manually update the agent after installation.
Manually updating the agent to include CA APM for SOA requires you to modify the
agent profile. Depending on the type of agent you need to update manually, see the
appropriate section:
Updating the Java agent manually (see page 33)
Updating the .NET agent manually (see page 34)
Update the Java Agent Manually to Use CA APM for SOA
You can manually update the Java agent to use CA APM for SOA after installing. You
move files from the <Agent_Home>/examples directory to the <Agent_Home>/core/ext
directory. Then you edit the agent profile to include the appropriate ProbeBuilder
directive files for CA APM for SOA.
Follow these steps:
1. Navigate to the <Agent_Home>/examples/SOAPerformanceManagement/ext
directory.
2. Copy and paste the files from the directory into the <Agent_Home>/core/ext
directory.
3. Stop the application server.
4. Open the <Agent_Home>/core/config/IntroscopeAgent.profile file in a text editor.
5. Add the spm.pbl value to the introscope.autoprobe.directivesFile property in the
IntroscopeAgent.profile file.
For example:
introscope.autoprobe.directivesFile=websphere-full.pbl,hotdeploy,spm.pbl
6. Modify any additional agent properties in the IntroscopeAgent.profile file if you
want to change the default settings. Then save the file and exit the text editor.
7. Restart the application server.
The application server restarts the agent and instruments the applications to enable
SOA performance monitoring.
After you manually configured the Java agent profile, you configure agent
properties after installation (see page 35).


Update the .NET Agent Manually to Use CA APM for SOA
You can manually update the .NET agent to use CA APM for SOA after installing. You
move files from the <Agent_Home>/examples directory to the <Agent_Home>/ext
directory and edit the default ProbeBuilder list to include CA APM for SOA files. After
you update the agent profile, you configure agent properties after installation (see
page 35).
Follow these steps:
1. Navigate to the <Agent_Home>\examples\SOAPerformanceManagement folder.
2. Copy the files from the
<Agent_Home>\examples\SOAPerformanceManagement\ext folder to the
<Agent_Home>\ext folder.
3. Copy the wily.WCFServicesAgent.ext.dll file from the
<Agent_Home>\examples\SOAPerformanceManagement\wcf\ext folder to the
<Agent_Home>\ext folder.
4. Stop the IIS application server.

5. Open the <Agent_Home>\IntroscopeAgent.profile file in a text editor and verify the
introscope.autoprobe.directivesFile property setting.
For example:
introscope.autoprobe.directivesFile=default-full.pbl,hotdeploy

6. Save the changes and close the IntroscopeAgent.profile file.
7. Open the default-full.pbl or default-typical.pbl you have specified for the
introscope.autoprobe.directivesFile property in a text editor.
8. Save and close the default*.pbl file.
9. Restart the IIS server after you finish the configuration.
The .NET agent is updated to use CA APM for SOA.


Agent Properties Configuration After Installation
After installing, you can configure other agent properties and update the application
server, as needed. For example, you can customize the agent profile to adjust the
components monitored or the handling of correlation information. Depending on your
application environment, you may also need to configure settings in the application
server or modify server startup scripts.
Note: If you have installed a Java agent, see the CA APM Java Agent Implementation
Guide for more information about configuring the application environment. For more
information about installing and configuring .NET agents and setting properties for the
.NET environment, see the CA APM .NET Agent Implementation Guide. There are no
specific additional changes required for Java or .NET agents to work with CA APM for
SOA.
How to Enable SOA Platform Extensions
If you have an agent with CA APM for SOA enabled, you can extend monitoring to
components of the following SOA platforms:
AquaLogic Service Bus (ALSB) and Oracle Service Bus (OSB)
IBM WebSphere Process Server (WPS) and WebSphere Enterprise Service Bus
(WESB) or WebSphere Enterprise Service Bus (WESB) as a standalone product
TIBCO BusinessWorks or TIBCO ActiveMatrix BusinessWorks (BW)
Software AG webMethods Integration Server (IS)
Depending on your application server and agent environment, you can enable CA APM
for these SOA platforms when you run the Standalone agent installer interactively,
when you install the agent silently using the response file, or manually after installing
the agent.
In addition to the SOA-related extensions that rely on the agent and CA APM for SOA,
there are standalone extensions for monitoring the following SOA platforms:
TIBCO Enterprise Message Service (EMS)
webMethods Broker
These standalone extensions are installed and configured separately from the agent.
Note: For information about installing and configuring standalone extensions, see the
appropriate section.


Adding SOA-Related Extensions Interactively
If you run the Standalone agent installer interactively, you can select the SOA-related
extensions to enable in the installer. The specific monitoring options you can select
depend on the application server you select. For example, if you select WebLogic as the
application server, you can select CA APM for SOA and CA APM for Oracle Service Bus. If
you select Default as the application server, you can select CA APM for SOA and CA APM
for TIBCO BusinessWorks or CA APM for webMethods Integration server.
Based on your selections in the installer, the appropriate files are automatically copied
to the appropriate directory in the agents home directory and the appropriate
ProbeBuilder directives are automatically added to the agents profile.
Add SOA-Related Extensions Using the Silent Installation Response File
If you install the agent in silent mode, you can use settings in the response file to specify
whether you want to enable SOA extensions for the agent.
To enable SOA platform extensions for an agent in silent mode
1. Open the SampleResponseFile.Agent.txt file, located in the same directory as the
Standalone agent installer.
2. Edit the SampleResponseFile.Agent.txt file to reflect your preferred installation
settings.
3. Set the shouldEnableSPM property to true to add CA APM for SOA to the agent. For
example:
shouldEnableSPM=true
You must set this property to true if you want to enable CA APM for Oracle Service
Bus (OSB), CA APM for IBM WebSphere Process Server (WPS), CA APM for
WebSphere Enterprise Service Bus (WESB), CA APM for TIBCO BusinessWorks (BW)
or CA APM for webMethods Integration Server.
Enable Extensions on the Enterprise Manager


4. Set the appropriate shouldEnable* property to true to add SOA extensions to the
agent. For example:
shouldEnableSOAExtForOSB=true enables CA APM for Oracle Service Bus (OSB)
shouldEnableSOAExtForWPSandWESB=true enables CA APm for IBM
WebSphere Process Server (WPS) with WebSphere Enterprise Service Bus
(WESB) or CA APM for WebSphere Enterprise Service Bus as a standalone
product
shouldEnableSOAExtForTibcoBW=true enables CA APM for TIBCO
BusinessWorks
shouldEnableSOAExtForWebMethodsIS=true enables CA APM for webMethods
Integration Server
If you set a property to false, the extension-specific files are copied to the
<Agent_Home>/examples directory, but the agent profile is not updated. For
information about enabling an extension after installing the agent, see Adding SOA
extensions manually after installing the agent (see page 37).
5. Save the SampleResponseFile.Agent.txt file.
Adding SOA-Related Extensions Manually After Installing the Agent
If you did not enable SOA-related extensions in the Standalone agent installer or in the
response file, you can manually update the agent after installation. Manually updating
the agent typically involves the following steps:
Copying files from the appropriate <Agent_Home>/examples directory to the
<Agent_Home>/core/ext directory.
Configuring the agent profile to include the appropriate ProbeBuilder directives
(.pbd or .pbl) for the platform-specific agent extension.
Configuring the server to invoke the agent or restarting the server.
Depending on the SOA platform, however, manually updating the agent may require
additional platform-specific steps.
Note: For information about platform-specific steps, see the appropriate section for the
SOA extension you want to enable.
The Management Module and other files for CA APM for SOA and SOA-related
extensions are installed by default in the <EM_Home>/examples directory when you
install the Enterprise Manager. For example, the files for CA APM for SOA are installed
by default in the <EM_Home>/examples/SOAPerformanceManagement directory.


To enable any extension, move the files from the <EM_Home>/examples subdirectory
of the extension to the appropriate <EM_Home> directory and deploy the Management
Module for the extension.
To add CA APM for SOA to the Enterprise Manager
1. Stop the Enterprise Manager.
2. Navigate to the <EM_Home>/examples/SOAPerformanceManagement directory.
3. Copy and paste the contents of the
<EM_Home>/examples/SOAPerformanceManagement/config/modules directory
into the <EM_Home>/config/modules directory.
The <EM_Home>/examples/SOAPerformanceManagement/config/modules
directory contains the CA APM for SOA Management Module
(SPM_ManagementModule.jar). When you have multiple Enterprise Managers in a
clustered environment, copy only this file to the <EM_Home>/config/modules
directory on the Enterprise Manager you are using as the MOM computer.
<EM_Home>/examples/SOAPerformanceManagement/ext directory into the
<EM_Home>/ext directory.
The <EM_Home>/examples/SOAPerformanceManagement/ext/xmltv directory
contains the CA APM for SOA tab definitions that enable the Workstation to display
SOA overview, deviation, and dependency metrics.
5. Copy and paste the
<EM_Home>/examples/SOAPerformanceManagement/product/
enterprisemanager/plugins directory into the
<EM_Home>/product/enterprisemanager/plugins directory.
The
<EM_Home>/examples/SOAPerformanceManagement/product/enterprisemanager
/plugins directory contains files that support transaction tracing, deviation metrics,
and the SOA Dependency Map. Copy the files from
/plugins to <EM_Home>/product/enterprisemanager/plugins on all Enterprise
Managers in the cluster if you have deployed the Enterprise Manager as a cluster. If
the files are not found on the Collector Enterprise Managers, the Dependency Map
fails to display properly.
6. Copy and paste the
<EM_Home>/examples/SOAPerformanceManagement/ws-plugins directory into
the <EM_Home>/ws-plugins directory.
The <EM_Home>/examples/SOAPerformanceManagement/ws-plugins directory
contains additional files that support the SOA Dependency Map, dependency
metrics, and transaction tracing.
7. Restart the Enterprise Manager.


By default, CA APM for SOA includes Enterprise Manager properties (see page 311) that
control operations such as how frequently the relationships in the Dependency Map are
refreshed or which deviation metrics to report. For most organizations, the default
settings are appropriate and you do not need change them; however, you can modify
the properties.
If you want to enable monitoring for additional SOA platforms, enable CA APM for SOA
on the Enterprise Manager first.
To add platform-specific SOA extensions to the Enterprise Manager
2. Navigate to the appropriate <EM_Home>/examples directory. For example, change
to one of the following directories:
SOAExtensionForOSB
SOAExtensionForTibcoBW
SOAExtensionForTibcoEMS
SOAExtensionForWebMethodsBroker
SOAExtensionForWebMethodsIS
SOAExtensionForWPSandWESB
<EM_Home>/examples/<extension>/config/modules directory into the
<EM_Home>/config/modules directory.
The <EM_Home>/examples/<extension>/config/modules directory contains the
Management Module for the SOA extension. When you have multiple Enterprise
Managers in a clustered environment, copy only the Management Module to the
modules directory on the Enterprise Manager you are using as the MOM computer.
Alternatively, if the Enterprise Manager is running, you can copy Management
Module files to the <EM_Home>/deploy directory.
4. Copy and paste the contents of the <EM_Home>/examples/<extension>/ext/xmltv
directory into the <EM_Home>/ext/xmltv directory.
The <EM_Home>/examples/<extension>/ext/xmltv directory contains the tab
definitions that enable the Workstation to display metrics that are specific to the
extension.
Verify the CA APM for SOA Deployment


5. Copy and paste the contents of any additional directories in the corresponding
directory under the <EM_Home> directory.
For example, copy the contents of the
<EM_Home>/examples/<extension>/product/enterprisemanager/plugins directory
into the <EM_Home>/product/enterprisemanager/plugins directory.
Note: Copy the files from
/plugins to <EM_Home>/product/enterprisemanager/plugins on the MOM and all
Enterprise Managers in the cluster if you have deployed the Enterprise Manager as
a cluster.
The additional directories depend on the SOA extension you are enabling.
Note: For more information about configuring and working with a specific SOA platform,
see the appropriate section for that platform.
Verify the CA APM for SOA Deployment
You can verify the deployment of CA APM for SOA and SOA-related extensions by
invoking applications that include web services or other SOA components and verifying
that the WebServices node exists in the Investigator tree.
Follow these steps:
1. Start the Enterprise Manager, if it is not already running.
2. Start the application server, if it is not already running.
Restarting the application server starts the agent and instruments the applications
to enable SOA performance monitoring.
3. Start any application that uses a web services and execute one or more
transactions.
4. Start the Workstation and open the Investigator.
5. Expand the agent where CA APM for SOA is installed.
6. Verify that you can access the WebServices > Client or WebServices > Server node
under the agent.
If the transaction includes both client-side operations and server-side operations on
the same agent, you should be able to see both the WebServices > Client and
WebServices > Server nodes on the agent.
If you have used the discovered web services to execute transactions, you should
be able to expand the service namespace node to view metrics associated with the
client- or server-side of the transaction.
Remove CA APM for SOA


In some cases, sample applications that simulate transactions to demonstrate web
service operations may not generate any metrics. For example, WebLogic test
clients run against services hosted by WebLogic that cannot be detected by CA APM
for SOA.
7. Select the agent node, then click the Overview tab to verify that the Enterprise
Manager ws.overview.tv.xml file loads properly.
If you decide to remove CA APM for SOA and SOA-related extensions from your
environment, do the following:
Remove all of the agent extensions that have been installed and configured.
Remove the Enterprise Manager extensions that have been deployed.
To remove CA APM for SOA from the Java agent
1. Stop the application server.
2. Navigate to the <Agent_Home>/core/config directory, and open the
IntroscopeAgent.profile file in a text editor.
3. Remove the appmap-soa.pbd and webservices.pbd values from
introscope.autoprobe.directivesFile property. Save and close the file.
4. Remove webservices.pbd from the <Agent_Home> directory.
5. Change to the <Agent_Home>/core/ext directory and remove the following files:
WebServicesAgent.jar
BoundaryOnlyTrace.jar
6. Start the application server.
CA APM for SOA is removed from the Java agent.
To remove CA APM for SOA from the .NET agent
1. Stop the IIS application server.
2. Open a command prompt and change to the <Agent_Home>/ext directory. Remove
the following files:
wily.WebServicesAgent.ext.dll
wilyHttpCorrelationTracers.ext.dll
wilyBoundaryOnlyTrace.ext.dll
3. Start the IIS application server.
CA APM for SOA is removed from the .NET agent.


To remove CA APM for SOA from the Enterprise Manager
2. Change to the <EM_Home>/config/modules directory and delete the following file:
SPM_ManagementModule.jar.
3. Change to the <EM_Home>/ext/xmltv directory and delete the following files:
ws.overview.tv.xml
ws.wsdependency.tv.xml
ws.wsdeviation.tv.xml
4. Change to the <EM_Home>/product/enterprisemanager/plugins directory and
delete the following files:
com.wily.introscope.soa.tracefilters.common_<version>.jar
com.wily.introscope.soa.tracefilters.em_<version>.jar
com.wily.introscope.soa.dependencymap.common_<version>.jar
com.wily.introscope.soa.deviationmetrics_<version>.jar
5. Change to the <EM_Home>/ws-plugins directory and delete the following files:
com.wily.introscope.soa.crossprocessviewer.workstation_<version>.jar
com.wily.introscope.soa.dependencymap.ui_<version>.jar
com.wily.introscope.soa.dependencymetrics.typeviewer_<version>.jar
com.wily.introscope.soa.tracefilters.common_<version>.jar
com.wily.introscope.soa.tracefilters.workstation_<version>.jar
com.wily.introscope.ui.tomsawyer_<version>.jar
6. Start the Enterprise Manager.
CA APM for SOA is removed from the Enterprise Manager.


Chapter 3: Monitoring a Service-Oriented
Architecture

CA APM for SOA enables you to monitor a SOA infrastructure by viewing information
about web service clients and providers and their underlying operations, including
process dependencies, critical operations, process flow, and SOAP faults.
This section describes the default dashboards and metrics for monitoring the SOA
infrastructure and how to access SOA-specific information for client and server
operations.
Viewing SOA-Specific Information in CA Introscope (see page 43)
Use the SOA Performance Dashboards (see page 46)
Using Investigator to view SOA performance metrics (see page 52)
Viewing boundary blame in the Investigator (see page 62)
View the Default SOA-Specific Metric Groupings (see page 62)
View the Default CA APM for SOA Alerts (see page 63)
Viewing SOA-Specific Information in CA Introscope
After you install CA APM for SOA, you can monitor the SOA infrastructure by viewing
information about web service clients and web service providers using the Workstation
and SOA-specific dashboards, tabs, and metrics.
The following list summarizes what the product adds to the Workstation specifically for
monitoring the SOA environment:
SOA Performance dashboards let you monitor the overall health of the SOA
environment across deployed agents at a glance.
The SOA Dependency Map provides a visual representation of dependencies across
SOA components and helps you understand how web services and operations relate
to each other.
A Dependencies tab lets you view dependency metrics, such as the number of
direct or indirect critical operations a specific service relies on.
A Deviations tab enables you to view deviation metrics, such as the deviation from
the average response time for a particular namespace or operation.
A Most Critical tab lets you view the operations with the highest number of
operations that depend on them.


A Most Dependent tab lets you view the operations with the highest number of
dependencies on other operations.
The Errors tab provides additional information about SOAP fault errors generated
by web service operations.
You can also view detailed information about SOA-specific components using the
Investigator to drill down into standard and SOA-specific metrics and monitor
SOA-related transactions that cross JVM or CLR boundaries using the Transaction Trace
Viewer.
About Client and Server Web Services and Operations
When you restart the application server after installing CA APM for SOA, the agent
instruments the applications it finds based on the directives defined in its list of
directive files. As part of this process, the agent identifies web service operations, which
are equivalent to method calls, from the remote procedure call or the SOAP message
used to invoke the operation. Individual operations within each web service are
identified as client (or outbound) requests or server responses and placed under the
WebServices|Client or WebServices|Server node for an agent application server.
In most cases, the client and server for a web service run in separate Java Virtual
Machines (JVMs) or Microsoft Common Language Runtime environments (CLRs).
Therefore, the Client and Server nodes are often listed under separate agents. If the
same JVM or CLR handles both requests and responses, then both the Client and the
Server nodes are listed under the WebServices node for that agent. For example, if the
Client and Server use the same JVM, the Investigator tree displays both the Client and
Server nodes under the <hostname>|<process_name>|<agent_name>|WebServices
node.
About service namespaces and operation names
When you expand the Client and Server nodes in the Investigator, individual web
services are displayed by web service namespace. The web service namespace is a
modified version of the web services Uniform Resource Identifier (URI). There are two
types of URIs:
Uniform Resource Locator (URL)
Uniform Resource Name (URN)
The namespace displayed in the Investigator is modified to replace characters that have
a reserved meaning, such as the colon (:) in a URL, but is otherwise the same as the web
service URL or URN. For example, a typical namespace may be similar to the following:
http_//CreditManagement.demobank.ca.com


You can expand any web service namespace to view its operations. Operation names in
a web service are equivalent to method names, enabling you to drill down to the lowest
level in an application when analyzing poor performance. For example, a typical
operation name may describe a granular activity to be performed, such as
getSmallBusinessAcctBalance or isAcctNumberValid.
About Unidentified Services and Operations
In some cases, the CA APM for SOA agent extension may not be able to identify a web
service namespace or operation. The failure to identify a web service name or operation
can affect the metrics reported and the aggregation of data. For example, you may see
UnknownService instead of a namespace or UnknownOperationName instead of an
operation name displayed in the Investigator tree.
If you see an UnknownService or UnknownOperationName for a WebServices client or
server, review the following:
The implementation of the web service for the protocol, APIs, and application
server version being used.
The construction of incoming and outgoing messages.
About virtual agents
By default, metrics are displayed for each agent independently. If you want to view web
service metrics aggregated across multiple agents or client and server namespaces, you
must define a virtual agent. For example, if both the web service client and the web
services server use the same JVM, you may want to define a virtual agent to see web
services metrics as aggregated data that includes both the client and the server.
You can define virtual agents by modifying the <EM_Home>/config/agentclusters.xml
file for the Enterprise Manager to which the agents report. Within the agentclusters.xml
file, you specify the agents and metrics you want aggregated. For example, you can
configure a virtual agent to collect and aggregate data for Average Response Time
across all server-side web services or to combine Average Response Time metrics across
both server- and client-side web services.
Use the SOA Performance Dashboards


The following example illustrates how to define a virtual agent named
WebServicesVirtualAgent that aggregates server metrics across all non-custom agents:
<agent-cluster name="WebServicesVirtualAgent" domain="SuperDomain" >
<agent-specifier>(.*)\|[^Custom.*](.*)\|(.*)</agent-specifier>
<metric-specifier>WebServices\|Server\|(.*):Average Response Time
$ms$</metric-specifier>
<metric-specifier>WebServices\|Server\|(.*):Concurrent
Invocations</metric-specifier>
<metric-specifier>WebServices\|Server\|(.*):Errors Per
Interval</metric-specifier>
<metric-specifier>WebServices\|Server\|(.*):Responses Per
<metric-specifier>WebServices\|Server\|(.*):Stall Count</metric-specifier>
<metric-specifier>WebServices\|Server\|(.*):SOAP Faults Per
</agent-cluster>
You can then expand the WebServicesVirtualAgent node to view aggregated server
metrics. The following figure illustrates the virtual agent defined in the
agentclusters.xml file displayed as a node in the Investigator tree:

Note: For more information about configuring virtual agents, see the CA APM
Configuration and Administration Guide.
CA APM for SOA includes preconfigured dashboards that you can use to monitor the
overall health of the SOA environment. Dashboards aggregate data across agents to
summarize performance and availability information and provide high-level visibility
into potential problems.
Typically, you use dashboards as the starting point for monitoring your environment
because they let you do the following:
Monitor the overall health, performance, availability, and status of key components
of the SOA infrastructure at-a-glance
Get early notification of potential problems in the production application
environment when lower-level metrics signal that a caution or danger threshold has
been crossed
Drill down into performance information to isolate and identify which web service
clients, providers, or operations are experiencing delays or producing errors


The Enterprise Manager extension for CA APM for SOA includes preconfigured
SOA-specific dashboards that are packaged in the SPM_ManagementModule.jar file.
Follow these steps:
1. Start the Enterprise Manager if it is not currently running.
2. Start the Workstation and log in to the Enterprise Manager where the SOA
extension is installed.
3. Click Workstation > New Console.
4. Select one of the SOA Performance dashboards from the Dashboard drop-down list.
For example, select the SOA Performance Overview dashboard as the starting point
for monitoring web services. The SOA Performance Overview dashboard displays
information about the overall health of the services deployed.

From the SOA Performance Overview dashboard, you can navigate the following
dashboards to view more detailed information about client or server operations:
Client Health
Server Health
Most Critical Operations
Most Dependent Operations
Busiest Operations


For example, if the problem seems to be average response time on the client-side,
you can double-click the Client Health tab to view that dashboard with details about
the slowest client operations, average response time, responses per interval, and
SOAP faults per interval:



5. From any dashboard, you can double-click a service or operation name to open the
Workstation Investigator for further analysis. For example, if you select a slow
service in the Client Health dashboard, the Investigator opens to display the related
metric for that client service:

Note: For information about starting and using the Workstation, accessing dashboards,
or opening and navigating Investigator, see the CA APM Workstation User Guide.
More information:
Using Investigator to view SOA performance metrics (see page 52)

SOA Performance Overview Dashboard
The SOA Performance - Overview dashboard provides an overview of monitored web
services, separated into client-side and server-side service operations.
The Overview dashboard includes the following:
Lists of the slowest client and server services
Graphs of the average response times for client and server services
Alert indicators for Response Time, SOAP Faults, Errors, and Stalls for client and
server services
You can use this dashboard to view summarized information for the web services you
are monitoring.


SOA Performance Client Health Dashboard
The SOA Performance - Client Health dashboard provides detailed information about
web service operations from the client-side perspective.
The Client Health dashboard includes the following:
A list of the ten slowest client operations
The average response time aggregated for each client-side operation
The average response time aggregated for all operations in each client-side web
service
The total number of SOAP faults aggregated for each client-side web service per
interval
The total number of responses aggregated for each client-side web service per
interval
You can use this dashboard to view more detailed information about client-side
operations when you are alerted to a problem in the client-side web services you are
monitoring.
SOA Performance Server Health Dashboard
The SOA Performance - Server Health dashboard provides detailed information about
web service operations from the server-side perspective.
The Server Health dashboard includes the following:
A list of the ten slowest web service operations
The average response time for each server-side operation
The average of response time aggregated for all methods or operations in each
server-side web service
The total number of SOAP faults aggregated for each server-side web service per
interval
The total number of responses aggregated for each server-side web service per
interval
You can use this dashboard to view more detailed information about server-side
operations when you are alerted to a problem in the server-side web services you are
monitoring.


SOA Performance Most Critical Operations Dashboard
The SOA Performance - Most Critical Operations dashboard provides deviation metrics
for the operations with the highest number of dependent operations. Because critical
operations have the most potential to affect whether other operations succeed or fail,
monitor these operations closely.
The Most Critical Operations dashboard includes a list of the operations with the highest
number of dependent operations and graphs for the following:
Average Response Time Deviation
Errors Per Interval Deviation
Responses Per Interval Deviation
High deviation values may indicate that critical operations are not performing reliably or
that downstream operations are not executing properly.
If you enable monitoring for additional SOA platforms, such as CA APM for TIBCO
BusinessWorks, this dashboard can also include information about the most critical
processes for the extension.
SOA Performance Most Dependent Operations Dashboard
The SOA Performance - Most Dependent Operations dashboard provides deviation
metrics for the operations with the highest number of dependencies on other
operations.
The Most Dependent Operations dashboard includes a list of the operations with the
most dependencies on other operations and graphs for the following:
High deviation values may indicate that upstream operations are not performing
reliably.
If you enable monitoring for additional SOA platforms, such as CA APM for TIBCO
BusinessWorks, this dashboard can also include information about the most dependent
processes for the extension.
Using Investigator to view SOA performance metrics


SOA Performance Busiest Operations Dashboard
The SOA Performance - Busiest Operations dashboard provides detailed information
about the highest web service invocation rates per interval experienced by the
client-side and the server-side.
The Busiest Operations dashboard includes the following:
A list of the busiest client and server operations
The total responses per interval for all client-side operations
The total responses per interval for all server-side operations
You can use this dashboard to view more detailed information about the current
throughput for the client and server web services you are monitoring.
Where dashboards provide you with an overview of client and server health and
potential points of failure such as most critical or busiest operations, the Investigator
enables you to drill down into specific details about the SOA environment to help you
identify the root cause of a problem.
Through the Investigator, you can analyze aggregated metrics from the top-level of the
application down to granular metrics for individual operations within individual services
to find the source of poor performance or error activity.
The Available Metrics
In addition to the standard CA Introscope metrics for each monitored operation or
service namespace, CA APM for SOA provides several SOA-specific metrics. The metrics
for individual operations are aggregated into metrics for individual web services and can
be used to evaluate client-side and server-side performance of an application.
The following standard and SOA-specific metrics are commonly available for
applications that are implemented as web services:
Average Response Time (ms)Average time in milliseconds for invoked methods,
operations, or services to complete in a 15-second time period.
Average Response Time DeviationDeviation from the mean for average response
time per interval.
Concurrent InvocationsNumber of concurrent requests that are in progress but
not complete at the end of a 15-second time period.
Errors Per IntervalNumber of exceptions, HTTP errors, or SOAP faults generated
in a 15-second time period.


Errors Per Interval DeviationDeviation from the mean for the number of
exceptions, HTTP errors, or SOAP faults in an interval.
Responses Per IntervalNumber of operation requests or service requests
completed in a 15-second time period.
Responses Per Interval DeviationDeviation from the mean for invocations
finished within an interval.
Stall CountNumber of requests that are not complete at the end of a 30-second
time period.
SOAP Faults Per IntervalNumber of SOAP message errors produced or consumed
by the SOAP engine in a 15-second time period.
Critical DirectNumber of downstream operations that rely directly on a current
operation executing successfully.
Critical IndirectNumber of downstream operations that rely directly or indirectly
on a current operation executing successfully.
Dependent DirectNumber of upstream operations upon which a current
operation directly depends.
Dependent IndirectNumber of upstream operations upon which a current
operation directly or indirectly depends.
View Summarized Metrics on Overview Tabs
In general, the best place to start looking for the root cause of a problem using the
Investigator is an Overview tab. The information displayed on an Overview tab depends
on the Investigator node you have selected. For example, when you select the agent
node, the Overview tab displays high-level health indicators of all the applications
instrumented on the agent. This Overview tab is provided by default in the Workstation.
CA APM for SOA provides additional Overview tabs for the following:
WebServices nodeWhen you select the WebServices node, the Overview tab
displays all of the client or server web service namespaces associated with the
selected agent application. If the agent has both client and server web services, the
Overview tab displays both the client and server namespaces in separate tables.
Client nodeWhen you select the Client node, the Overview tab lists the web
service namespaces associated with client-side operations on the selected agent
application.
Server nodeWhen you select the Server node, the Overview tab lists the web
service namespaces associated with server-side operations on the selected agent
application.


<web_service_namespace> nodeWhen you select an individual web service
namespace, the Overview tab lists the operations that belong to the selected client
or server web service identified by selected <web_service_namespace>.
<operation_name> nodeWhen you select an individual operation, the Overview
tab displays graphs showing the current level of activity using the standard CA
Introscope metrics plus SOAP Faults Per Interval for the operation identified by the
selected <operation_name>.
Follow these steps:
1. Open the Investigator, select an agent node, and then click the Overview tab in the
Viewer pane.
The Overview displays alert indicators for each web service instrumented on the
selected agent.
2. Expand the agent node and select WebServices in the Investigator tree. Click the
Overview tab.
Separate tables for client and server web service metrics appear. You have the
following options:
Select a particular service namespace in either the Client or Server table.
An Average Response Time graph appears for that service.
Change the graph displayed by clicking the metric column header for the metric
you want to view. For example, to display the graph for Errors Per Interval, click
the Errors Per Interval metric column header.
3. Expand the WebServices node and select the Client or Server node in the
Investigator tree. Click the Overview tab.
Only the client namespace list or the server namespace list appear.
4. Expand the Client or Server node and select a specific <web_service_namespace> in
the Investigator tree. Click the Overview tab.
The operations and related metrics for the selected web service namespace appear.
5. Expand the <web_service_namespace> node and select an <operation_name> in
the Investigator tree. Click the Overview tab.
The graphs of the metrics for that operation appear.


View Dependency Metrics on the Dependencies Tab
In addition to the standard CA Introscope metrics, CA APM for SOA provides metrics to
determine the most critical and most dependent operations in a web service
transaction. These metrics are based on the number of direct and indirect dependencies
for each operation.
To view these dependency-based metrics on the Dependencies tab, select an
appropriate Investigator node.
The information displayed on the Dependencies tab depends on the Investigator node
you select. For example, when you select:
The WebServices node, the Dependencies tab displays the client and server web
service namespaces, operations, and dependency metrics associated with the
selected agent application.
The Client node, the Dependencies tab displays the web service namespaces,
operations, and dependency metrics associated with client-side operations on the
The Server node, the Dependencies tab displays the web service namespaces,
operations, and dependency metrics associated with server-side operations on the
An individual <web_service_namespace> node, the Dependencies tab displays the
operations and dependency metrics associated with the selected client or server
web service identified by the selected <web_service_namespace>.
About direct and indirect operation dependencies
In a web service transaction, any operation that calls another operation creates a
dependency chain, in which the called operation is dependent on the calling operation.
Additional calls or replies from called operations create additional dependencies. The
dependencies between operations can be either direct dependencies or indirect
dependencies, based on where the operation is located in the dependency chain.
For example, if operation A calls operation B, and operation B calls operation C, the
transaction looks like this:
A --> B --> C.
In this transaction:
Operations A and B have a direct dependency relationship
Operations B and C have a direct dependency relationship
Operations A and C have an indirect dependency relationship


An operation can also be identified as occurring upstream or downstream from another
operation depending on where it sits in the dependency chain. In a transaction
consisting of multiple operations, direct dependencies are operations that are
immediately upstream or downstream from each other. In the example above,
operation A is upstream from both operations B and C, but is only directly upstream
from operation B.
Similarly, indirect dependencies can occur either upstream or downstream for
operations that are not called directly. For example, if operation A calls operation B, and
operation B then calls operations C and D, then both C and D have downstream indirect
dependencies on operation A.
About critical operations and metrics
Operations in a web service can be considered critical or dependent, or both critical and
dependent based on their interaction with other operations.
A critical operation is an operation that downstream operations rely on. The
downstream operations may have direct or indirect dependencies on the critical
operation, but the critical operation must execute successfully for the downstream
operations to execute.
There are two metrics associated with critical operations:
The Critical Direct metric tracks only the number of operations directly upstream
for an operation. If an operation does not depend on any upstream operations, that
is, the operation is not downstream from any other operation, its Critical Direct
metric is zero.
The Critical Indirect metric tracks the number of operations directly and indirectly
upstream for an operation.
For example, if the Critical Indirect metric value for the getAccountNum operation is 5, it
indicates that there are five direct or indirect operations that require the
getAccountNum operation to execute prior to those operations executing.
About dependent operations and metrics
A dependent operation is an operation that relies on the execution of upstream
operations. The dependent operation may have direct or indirect dependencies on the
upstream operations, but the upstream operations must execute successfully for the
dependent operation to execute.


There are two metrics associated with critical operations:
The Dependency Direct metric tracks the number of operations directly
downstream from an operation. If an operation does not have any dependent
operations, that is, the operation is not upstream from any other operation, its
Dependency Direct metric is zero.
The Dependency Indirect metric tracks the number of operations directly and
indirectly downstream for an operation.
For example, if the Dependency Indirect metric value for the sendConfirmation
operation is 8, it indicates that there are eight direct or indirect operations that must
execute before the sendConfirmation operation can execute.
A closer look at critical and dependency metrics
To better understand how Critical Direct/Indirect and Dependency Direct/Indirect
metrics work, consider the example of a Test server operation that calls four sayHello
client operations. Each client operation then calls one downstream sayHello server
operation, as illustrated in the following sample dependency map:



For this example, the following critical and dependency metric values that apply:
Test server
There are no upstream operations, so the metric values for critical operations are
Critical Direct = 0 and Critical Indirect = 0.
There are 4 direct downstream operations and 4 additional indirect downstream
operations, so the metric values for dependent operations are Dependency Direct =
4 and Dependency Indirect = 8
sayHello clients
There is a direct upstream operation, so the metric values for critical operations are
Critical Direct = 1 and Critical Indirect = 1.
There is a direct downstream operation, so the metric values for dependency are
dependent operations are Dependency Direct = 1 and Dependency Indirect = 1.
sayHello servers
There is a direct upstream dependency on sayHello and an indirect dependency on
the Test Servers, so the metric values for critical operations are Critical Direct = 1
and Critical Indirect = 2.
There are no direct or indirect downstream operations, so the metric values for
dependent operations are Dependency Direct = 0 and Dependency Indirect = 0.
To view dependency metrics on the Dependencies tab:
1. Expand the agent node, select WebServices in the Investigator tree, then click the
Dependencies tab in the Viewer pane to view separate tables for client and server
dependency metrics.
For each operation, the Dependencies tab displays the Critical Direct, Critical
Indirect, Dependency Direct, and Dependency Indirect metric values.
2. Expand the WebServices node and select the Client or Server node in the
Investigator tree, then click the Dependencies tab in the Viewer pane to display
only the client namespaces or only the server namespaces and the associated
dependency metrics.
3. Expand the Client or Server node and select a specific <web_service_namespace> in
the Investigator tree, then click the Dependencies tab in the Viewer pane to display
the list of operations and associated dependency metrics for the selected web
service namespace.


Viewing Deviation Metrics on the Deviations Tab
CA APM for SOA provides metrics to monitor deviations from the mean value for
Average Response Time, Errors Per Interval, and Responses Per Interval. A low deviation
value indicates that the metric data, such as Average Response Time, is clustered
around the mean. A high deviation value indicates that metric data is widely spread with
higher or lower values than the mean.
Note: When an operation has not been invoked in an interval, it has an Average
Response Time metric value of zero. Zero value metrics are not included in the average
response time calculation. Therefore, at times the Deviation tab appears to stop
monitoring. This apparent pause is normal.
To view the deviation metrics, select an Investigator node then click the Deviations tab.
For example:
The WebServices node displays the client and server web service namespaces,
operations, and deviation metrics that are associated with the selected agent
application.
The Client node displays the web service namespaces, operations, and deviation
metrics that are associated with the client.
The Server node displays the web service namespaces, operations, and deviation
metrics that are associated with the server.
An individual <web_service_namespace> node displays the operations and
deviation metrics that are associated with the selected client or server web service.
Note: By default, deviations are calculated for the namespace level only. To enable
deviations for WebService, Client, and Server nodes, configure the
com.wily.introscope.soa.deviation.metric.expressionlist (see page 338) property to
calculate additional metrics.
Deviation Metrics Calculations
Deviation metrics require CA APM for SOA to calculate a mean value. The product
determines the mean value, which is based on operation metrics over a rolling "n" day
period. The default number of days over which rolling averages are computed is seven.
To adjust the number of days, set the com.wily.introscope.soa.deviation.mean.days
property value.
To minimize the performance impact on the Enterprise Manager, CA APM for SOA limits
the number of operations for which you can calculate deviation metrics. By default,
deviation metrics are computed for the top 25 operations from each type of
dependency metric. To change the maximum number of operations for which deviations
are computed, modify the com.wily.introscope.soa.deviation.count.per.metric property
in the Enterprise Manager properties file.


To reduce the performance overhead for generating deviation metrics, you also can
selectively enable or disable specific types of deviation metrics. For example, you can
set configuration properties to generate only the Average Response Time Deviation
metric. Or set the com.wily.introscope.soa.deviation.enable property to false to
calculate no deviation metrics.
More information:
Configuring Enterprise Manager properties (see page 321)

View Critical Operation Metrics on the Most Critical Tab
The most critical operations in the SOA environment are the operations with the highest
number of operations that depend on them. These operations are the most important
potential points of failure and should be monitored closely through the Most Critical
Operations dashboard and the Most Critical tab in the Investigator. You can view a list of
the most critical operations and their the deviation metrics on the Most Critical tab
when you select the WebServices node in the Investigator.
Follow these steps:
Most Critical tab in the Viewer pane.
2. Select an individual operation in the list of critical operations to view graphs of the
deviation metrics for that operation.
View Dependent Operations on the Most Dependent Tab
The most dependent operations in the SOA environment are the operations with the
highest number of dependencies on other operations. You can view a list of the most
dependent operations and their the deviation metrics on the Most Dependent tab when
you select the WebServices node in Investigator.
Follow these steps:
Most Dependent tab in the Viewer pane.
2. Select an individual operation in the list of dependent operations to view graphs of
the deviation metrics for that operation.


Viewing SOAP Fault and Error Metrics on the Errors Tab
The Investigator provides a default Errors tab that displays error messages and details
for the node you select in the Investigator tree. If the CA APM for SOA extension is
installed, the Errors tab also displays information about client- and server-side SOAP
faults.
The Errors Per Interval metric is a standard CA Introscope metric that the agent
generates. The SOAP Faults Per Interval metric is an SOA-specific metric generated by
CA APM for SOA agent extension. No direct correlation exists between these metrics.
SOAP faults are messages that the SOAP engine produces or consumes when a web
service returns a fault response instead of a normal response. SOAP faults can be
automatically generated in response to a condition or explicitly coded in the logic of an
application. How the faults are captured and handled depends on the SOAP engine you
are using.
The Errors Per Interval metric tracks thrown exceptions and HTTP errors. Depending on
the business logic of a web service and the behavior of the application server, a SOAP
fault may have a corresponding error in the Errors Per Interval metric.
If an application server encounters a problem and issues a SOAP fault, both the client
and the server SOAP Faults Per Interval metric record the fault. If the application server
throws an exception related to the SOAP fault, its Errors Per Interval count is also
updated. When no code exists to catch the SOAP fault as an exception on the client, the
Errors Per Interval metric is not updated for the client.
Because the Errors Per Interval metric only tracks caught exceptions and error codes in
the CA APM for SOA instrumented application server or SOAP stack methods, the metric
may not include SOAP faults.
Follow these steps:
1. Expand the agent node, select WebServices in the Investigator tree or expand the
WebServices node, and select the Client or Server node.
2. Right-click the Errors tab in the Viewer pane.
The top pane of the Errors tab lists the time, description, and error message for
each error. Error messages generated by the SOAP engine display SOAP Fault at the
beginning of the error message.
3. Select an individual error to display detailed information about that error.
Detailed information for the SOAP fault displays on the Stack View tab with the
message text highlighted in red.
Viewing boundary blame in the Investigator


Viewing boundary blame in the Investigator
Boundary blame isolates metrics to include only front-end and back-end components in
the Investigator tree to help you determine whether a response time problem is internal
to the application server, for example, the result of a slow servlet, or the result of an
external call to a back-end system, such as a database server. CA APM for SOA extends
this capability to SOA components by automatically detecting web services calls to
back-end systems.
This extended capability to isolate metrics for front-end and back-end components is
enabled by default.
Note: For information about configuring, disabling, or customizing boundary blame for
an application, see the CA APM Java Agent Implementation Guide, CA APM .NET Agent
Implementation Guide, and CA APM Workstation User Guide.
View the Default SOA-Specific Metric Groupings
CA APM for SOA includes default metric groupings that are used to define the default
dashboards and alerts. You can also use the default metric groupings in custom
dashboards or alerts. The default metric groupings are included in the Enterprise
Manager extension for CA APM for SOA and packaged in the
SPM_ManagementModule.jar file. You can view the default metric groupings using the
Workstation Management Module Editor.
Follow these steps:
1. In the Investigator, click Workstation > New Management Module Editor.
2. Expand *SuperDomain* > Management Modules > SOA Performance Management
(*Super Domain*).
3. Expand the Metric Groupings node to view all of the metric groupings defined for
the SOA Performance management module.
4. Click a specific metric grouping to view its definition in the Viewer pane.
You can modify the default settings for any metric grouping or create your own custom
metric groupings, as needed.
Note: For more information about creating and using metric groupings, see the CA APM
View the Default CA APM for SOA Alerts


CA APM for SOA includes default alert definitions that are used in the preconfigured
dashboards. The default alert definitions are included in the CA APM for SOA Enterprise
Manager extension and packaged in the SPM_ManagementModule.jar file.
You can view the default alert definitions using the Workstation Management Module
Editor. You can also extend the CA APM for SOA Management Module to include
custom alert definitions and notification types or use the default alert definitions in
custom dashboards.
Follow these steps:
2. Expand *SuperDomain* > Management Modules > SOA Performance Management
(*Super Domain*).
3. Expand the Alerts node to view all of the alerts defined for CA APM for SOA.
4. Click a specific alert to view its definition in the Viewer pane.
In particular, review the default settings for Caution and Danger thresholds and
adjust the values, if necessary. You may also want to add notifications or corrective
actions.
The following table summarizes the default Caution and Danger threshold values
associated with the preconfigured CA APM for SOA alert definitions.

Alert Caution Danger
Client Operation Average Response Time
Server Operation Average Response Time
Server Service Average Response Time
2000 ms 5000 ms
Client Service Average Response Time 2500 ms 5500 ms
Client Operation Errors Per Interval
Client Service Errors Per Interval
Server Operation Errors Per Interval
Server Service Errors Per Interval
10 errors 15 errors
Client Operation Responses Per Interval
Client Service Responses Per Interval
Server Operation Responses Per Interval
Server Service Responses Per Interval
5 responses 10 responses


Alert Caution Danger
Client Operation Average Response Time
Server Operation Average Response Time
Server Service Average Response Time
2000 ms 5000 ms
Client Operation SOAP Faults Per Interval
Client Service SOAP Faults Per Interval
Server Operation SOAP Faults Per Interval
Server Service SOAP Faults Per Interval
10 faults 15 faults
Client Operation Stall Count
Client Service Stall Count
Server Operation Stall Count
Server Service Stall Count
1 stall 2 stalls
To create custom alerts for agents with CA APM for SOA
1. In the Management Module Editor, click Elements > New Alert.
2. In the Name field, enter a name for the alert.
3. Select SOA Performance Management from the Management Module drop-down
list, and click OK.
Note: For more information about creating alerts and customizing alert notifications,
see the CA APM Configuration and Administration Guide.


Chapter 4: Using the SOA Dependency Map

The SOA Dependency Map provides a visual representation of the web services or
business process workflows you have deployed in the SOA environment. You can use
this map to view and navigate the real-time dependencies between components,
monitor key metrics across related components, and start transaction traces or drill
down into the dependencies for problem services.
Understanding the use of the SOA Dependency Map (see page 65)
How the SOA Dependency Map Gets Data (see page 68)
Understanding context in the SOA Dependency Map (see page 73)
Displaying the SOA Dependency Map (see page 74)
Choosing a physical or logical view (see page 76)
Select a Content Type (see page 77)
Set a Primary Metric for Dependency Map Nodes (see page 78)
Selecting ToolTip metrics for dependency map nodes (see page 78)
Changing the dependency levels displayed (see page 79)
Navigating within the SOA Dependency Map (see page 82)
Saving SOA Dependency Map images (see page 84)
Starting a Transaction Trace from a map node (see page 86)
SOA Dependency Map for a Cluster (see page 87)
Understanding the use of the SOA Dependency Map
In a typical SOA environment, there are complex relationships between the web services
or business processes available. Because those services are loosely coupled, however,
the relationships between components are typically difficult to trace or understand. The
SOA Dependency Map provides a visual representation of the services you have
deployed and helps you monitor and understand how various components relate to one
another.
Understanding the challenge of the SOA environment
In most organizations, multiple groups are involved in developing and deploying
services, and typically there is no single architectural diagram that summarizes how the
services are being used. In some cases, you may have a registry that records the services
deployed, but that list may or may not be up-to-date. Even in an environment where a
registry of services is well-maintained, it may not be readily available to the right
personnel or accurately describe the complex relationships between services.


For example, it is common for applications to embed multiple layers of services that are
developed by different groups. These additional service layers are not easily apparent
and may be completely unknown to the application developer, but their performance
can become a mission-critical issue for the application that depends on them. Exposing
these "hidden" services provides additional levels of visibility for locating, isolating, and
resolving problems.
Understanding what the SOA Dependency Map provides
To address the challenges of the SOA environment, you need to be aware of all the
services in the SOA environment in an automatic and timely way. You also need to be
able to navigate the relationships between components to understand where and how
one service is used by other services or where there are potential bottlenecks. This
information is critical if you want to monitor the health and availability of all services in
real time and production environments.
The SOA Dependency Map provides this visibility. With the dependency map, you can
see at a glance and in real time:
what services are actually deployed
when new services are deployed or dependencies are changed
how services are related to each other
how client-side requests and server-side responses are performing
Understanding dependencies and SOA terminology
Within the context of the SOA Dependency Map, the term service is used generally to
represent a series of operations designed to accomplish a specific result. Details about
the components of a service can vary or be defined differently in different
environments. For example, selecting a Services view of the dependency map may
display information about web services, business processes, adapters, or messaging
services.
A dependency exists when one operation invokes a subsequent operation. The
subsequent operation may belong to an entirely separate service and may run on a
different application server. For example, a user entering a travel web site can start a
transaction to book a flight. The booking service for the travel web site may invoke an
airline reservation service to reserve a seat, then a credit-card processing service to
purchase the ticket. With this example, the service on the travel web site that started
the transaction depends on the airline reservation service and on the credit-card
processing service to complete the transaction.


Dependencies are most often the result of lower-level services combining to form
higher-order services. For example, the travel web sites booking service depends on
successful processing by the airline reservation service and credit-card processing
service. A failure or performance problem with either of those services affects the
behavior of the travel web sites booking service.
Depending on the context you select, the SOA Dependency Map can display all of the
top-level services you have deployed or the detailed structure of individual services with
their dependencies and performance information for those dependent operations.
Because you can change the scope and detail displayed, the SOA Dependency Map
provides a great deal of flexibility for analyzing problems in the SOA environment. By
using the SOA Dependency Map, you can trace the dependencies between services and
operations in a process flow to help you determine the root cause of slow response
time, SOAP faults, or other problems.
Understanding what you can do with the SOA Dependency Map
You can use the SOA Dependency Map to accomplish the following important tasks:
View current and accurate information about services as deployed, not as designed.
Research and resolve service problems by viewing service dependencies and
clicking on map nodes to drill down into details about components in the
Investigator tree.
Work with IT architects to plan and act on enterprise-wide SOA initiatives by
providing both physical and logical views of application dependencies.
Create snapshot images of the map to share information about service
dependencies and service problems with other stakeholders in the organization.
Understand the dependency relationships of monitored agents, services, and
operations and how these dependencies are affecting service performance without
having to rely on the help of application experts.
Start a Transaction Trace on a problem service directly from the SOA Dependency
Map to begin diagnosing the problem without setting up a manual Transaction
Trace.
How the SOA Dependency Map Gets Data


When you first install CA APM for SOA and start the application server, the agent
automatically discovers all of the web services or business processes it finds and sends
this information to the Enterprise Manager.
As these services are invoked and executed, the agent tracks the sequence of calls
across processes and passes this information to the Enterprise Manager. The Enterprise
Manager uses the call sequencing information to identify the dependencies between
services. The Enterprise Manager saves the discovered dependencies in a file and sends
the map data to the Workstation for display.
After the initial discovery, the agent periodically checks for new applications and for
changes to previously discovered dependencies. If new services are detected, the agent
sends details about the service calls to the Enterprise Manager, and the Enterprise
Manager sends the new map data to the Workstation to update the SOA Dependency
Map displayed with any previously unknown services or any newly discovered
dependencies for already known services.
If there are new SOA dependencies discovered, the Enterprise Manager checks whether
the logical equivalence rules are enabled and, if they are, determines whether the new
dependency is logically equivalent to an existing dependency. If the new dependencies
are unique, they are added to the persisted dependency data stored on the Enterprise
Manager. The Workstation checks the data store once every 15 seconds see if the data
for the SOA Dependency Map has changed, then updates the SOA Dependency Map
displayed, as needed.
About Persisted Data for the SOA Dependency Map
The Enterprise Manager saves discovered SOA dependencies in a local data store so that
the information is available without requiring rediscovery. The data store for the SOA
dependencies consists of the following files in the <EM_Home>/data/dependencymap
directory:
dependencymap.sav contains the most recently saved dependency data.
dependencymap.bak provides a backup copy of the previously saved SOA
dependencies.
The Enterprise Manager saves all of the discovered dependencies in the
dependencymap.sav file once every hour and any time you manually shut down the
Enterprise Manager. The Enterprise Manager also holds currently discovered
dependencies in the SOA Dependency Map in memory between dependencymap.sav
file saves.


When the Enterprise Manager starts up, it loads the dependencies from the
dependencymap.sav file so that CA APM for SOA does not have to rediscover the
previously discovered dependencies. If the Enterprise Manager stops suddenly without
saving a new copy of the dependencymap.sav file, the data in the dependencymap.sav
file could be up to one hour old. If the dependencymap.sav file is not found, the
Enterprise Manager waits for the agent to rediscover service dependencies, and then
recreates the file.
Forcing the Enterprise Manager to rediscover dependencies
In most cases, loading persisted data from the dependencymap.sav file provides the
most up-to-date information without rediscovery. There are cases, however, when you
may want the Enterprise Manager to ignore previously saved dependencies at startup
time and force the rediscovery of all dependencies. For example:
If you want to change whether the logical equivalence heuristics are enabled or
disabled, you also may want to force the Enterprise Manager to rediscover all
dependencies and apply the new rules to the dependencies. For more information
about the logical equivalence heuristics, see About logical equivalence rules (see
page 72). For more information about setting the properties for logical equivalence
heuristics, see Configuring Enterprise Manager properties (see page 311).
If you disconnect an agent while the Enterprise Manager is stopped, the map nodes
and dependencies for that agent may continue to be displayed on the map until
they expire, which, by default, takes 60 days. You may want to force the Enterprise
Manager to rediscover dependencies to remove the disconnected agents data
from the dependency map without waiting for them to expire.
Ignoring or removing saved dependency data
If you want the Enterprise Manager to ignore saved dependency data and rediscover
dependencies at start up, you must delete, move, or rename both the
dependencymap.sav and dependencymap.bak files.
To delete, move, or rename the saved SOA Dependency Map file:
2. Navigate to the <EM_Home>/data/dependencymap directory.
3. Delete, move, or rename the dependencymap.sav file. For example, rename the file
as old_dependencymap.savedcopy to prevent the Enterprise Manager from using
the data in the file to display the dependency map.
4. Delete, move, or rename the dependencymap.bak file. For example, rename the file
as old_dependencymap.backupcopy to prevent the Enterprise Manager from using
the file to display the dependency map.
5. Start the Enterprise Manager to rediscover the current dependencies and create a
new dependency map and dependencymap.sav file.


Disconnecting and remounting agents
If an agent is disconnected from an Enterprise Manager while the Enterprise Manager is
running, the map nodes and dependencies for that agent become inactive. If you
unmount the agent from the Workstation, the unmount event causes all of the map
nodes and dependencies for that agent to be removed from the map, including any
dependencies that start from or end with a removed service.
When the agent is remounted, the Enterprise Manager rediscovers all of its
dependencies and adds them back to the map.
Updating the dependency map with new services and operations
Any time the agent discovers new services or operations, it sends the updated
information to the Enterprise Manager. The Enterprise Manager updates its dependency
map store and notifies the Workstation that new data is ready for display on the SOA
Dependency Map. When the Workstation receives this notification, it displays the
message Available data has changed. You can then reload the dependency map to
display the new services or operations in the Workstation.
To reload the SOA Dependency Map:
1. Check whether the Available data has changed message is displayed beneath the
SOA Dependency Map tool bar.
2. Use Click here to reload the dependencies and view the new services or operations
and related metrics. For example, after reloading, the Available data has changed
message is no longer displayed and the map includes the newly discovered services
and dependencies.
When you reload the dependency map, the view displayed is the default view
associated with the Investigator tree node you clicked last. For example, if you selected
the WebServices node and reloaded the map, the map displays in the Physical view for
Services.
If you change the content type, see that Available data has changed and reload the map,
the map reloads the Physical view for Services because that is the default view for the
WebServices tree node. If you click a different node in the Investigator tree, for example
an agent node, then reload the map, the map displays the Physical view for Agents.


Aging and removal for obsolete map nodes
The Enterprise Manager tracks the age of each discovered dependency, and periodically
rediscovers dependencies to make sure they still exist. If the map node for a particular
agent, service, or operation is not re-discovered over a period of time, the item expires
and is removed from the dependency map. If the removed agent, service, or operation
is invoked again at a later time, the Enterprise Manager adds the item to the
dependency map again.
By default, the Enterprise Manager checks for the most recent discovery of a
dependency every 6 hours and removes dependencies that have not been discovered
for 60 days.
You can configure how frequently the Enterprise Manager checks the age of discovered
dependencies and the period of time a dependency should remain in the map before
expiring when it is not re-discovered by setting property values in the
IntroscopeEnterpriseManager.properties file. For more information about configuring
properties for the Enterprise Manager, see Configuring Enterprise Manager properties
(see page 311).
What to do if the dependency map displays incomplete data
In most cases, the initial discovery of services and dependency relationships requires
time to complete because the agent must collect then deliver the information to the
Enterprise Manager. After the initial discovery, changes to services and dependencies
are not always displayed immediately. Typically, it only takes a few minutes for changes
to be displayed if you are running a standalone Enterprise Manager. It may take slightly
longer if you are running the Enterprise Manager on a cluster.
You should also keep in mind, however, that the agent requires services to be executed
or actively running to collect data on all the nodes and dependent relationships.
Services and operations that have not been called do not display on the map until they
are called.
If the dependency map does not display any data or displays incomplete data, it may be
because:
The application server or the services you are monitoring are not actively running or
have not yet been invoked. Verify that the server is running and services can be
invoked.
A running agent has lost the connection to the Enterprise Manager in a
non-clustered (no MOM) environment. Flush the agent cache to force the agent to
rediscover previously discovered dependencies so the information is available to
send to a new or restarted Enterprise Manager.


An agent cache flush has removed all of the services and dependency data. Allow
time after a cache flush for the agent to collect and deliver information to the
Enterprise Manager.
The mapping tracers required for the dependency map are disabled in the agents
profile. Verify that the
com.wily.introscope.agent.transactiontrace.boundaryTracing.enable property in the
IntroscopeAgent.profile file is not set to False.
You changed the name of the agent, resulting in no data for the associated map
nodes. Allow time for the agent to collect the data to display for the new agent map
nodes.
The missing services are running on an application server that is not monitored by
an agent.
The missing web services are implemented on an unsupported platform or an
unsupported SOAP engine.
About logical equivalence rules
CA APM for SOA provides three heuristics for determining logical equivalence for
services and operations. These heuristics can be enabled or disabled as needed for your
environment. By default, CA APM for SOA uses the following rules to determine
client-side and server-side equivalence:
For a client-side service, if the service depends on more than one server-side
service, then all of the server-side services must be logically equivalent.
For a server-side service, if the service is depended upon by more than one
client-side web service, then all of the client-side web services must be logically
equivalent.
For name matching, when two physical service operations have the same metric
path after deletion of the agent specifier, those operations are considered logically
equivalent.
For information about the properties used to configure the logical equivalence
heuristics, see Configuring Enterprise Manager properties (see page 311).
Understanding context in the SOA Dependency Map


What you see in the SOA Dependency Map depends on two factors, in the following
order:
the SOA Dependency Map content type you select.
the Investigator tree node for which you want to view information.
The content type and the Investigator tree node determine the SOA Dependency Map
context. This context changes as you select different data.
Understanding how the content type affects what you see
The first factor that determines what the SOA Dependency Map displays is the SOA
Dependency Map content type. The content types you can select are:
Agents
Services
Operations
Choosing Agents, for example, enables you to view high-level dependencies across
agents whereas choosing Operations enables you to view low-level dependencies
between operations. By choosing the appropriate content type, you can drill down to
specific subsets of dependencies without losing your sense of where you are in the
overall SOA topology.
Changing the content type without changing the selected node
If you choose Services, then click an agent node in the Investigator tree, the SOA
Dependency Map displays all of the services and service-level dependencies associated
with that agent.
If you remain on the same Investigator tree node and choose another content typefor
example Agentsthe SOA Dependency Map displays all the agents with dependencies
associated with the selected agent node. For example, if services on the agent
Tomcat01 have dependencies on services running on the agent WebLogic02, the SOA
Dependency Map displays the Tomcat01 agent icon with a dependency arrow pointing
to the WebLogic02 agent icon, indicating an agent-level dependency.
Displaying the SOA Dependency Map


Applying content type changes to all objects in the map
If you are displaying Agents as the content type, and the dependency map shows a
dependency between two agents, for example the Tomcat01 agent and the WebLogic02
agent, changing the content type to Services displays all of the service-level
dependencies on both the Tomcat01 and WebLogic02 agents. Any time you change the
content type, the change applies to everything that is currently displayed on the SOA
Dependency Map. In this case, changing from Agents to Services sets the context to
display all services on the agents currently displayed in the map.
Understanding how the Investigator node affects what you see
The second factor that determines what the SOA Dependency Map displays is the
Investigator tree node you have selected. Although the content type determines the
type of dependency displayed, the Investigator node determines the scope of the
information included in the map. The top map node and the dependencies under it is
always based on the currently selected Investigator tree node. If you select a different
Investigator tree node, the associated SOA Dependency Map may look quite different.
You can, however, also use the map nodes displayed for a currently selected
Investigator tree node to navigate to a new Investigator tree node. For example, you
can use the SOA Dependency Map to expand a broad network of services, then click a
map node to jump to a new Investigator tree node and redraw the map from that node.
This allows you to click once to focus in on a particular Investigator or SOA Dependency
Map node of interest and eliminate the clutter of uninteresting network branches.
You can display the SOA Dependency Map by selecting an Investigator tree node, then
clicking the SOA Dependency Map tab. If you have CA APM for SOA enabled for an
agent, you can select the agent or any WebServices node in the Investigator to display
the SOA Dependency Map. If you monitor any additional SOA platforms, such as CA
APM for Oracle Service Bus or TIBCO BusinessWorks, you mayalso be able to display the
SOA Dependency Map when you select Investigator tree nodes associated with the
extension. For example, if you are monitoring Oracle Service Bus, you can select the
Proxy Services node or a specific proxy service name in the Investigator tree to display
the dependency map for all proxy services or for a specific proxy service.
To display the SOA dependency map:
1. Select an appropriate node in the Investigator tree.
2. Click the SOA Dependency Map tab in the Viewer pane.


The SOA Dependency Map displays with a default view based on the Investigator node
you have selected. For example:
For agent nodes, the SOA Dependency Map displays the Physical view of agent-level
dependencies.
For the WebServices, Client, or Server node, the SOA Dependency Map displays the
Physical view of service-level dependencies.
For <web_service_namespace> nodes, the SOA Dependency Map displays the
Physical view of service-level dependencies.
For <operation_name> nodes, the SOA Dependency Map displays the Physical view
of operation-level dependencies.
For example, if you select WebServices > Server in the Investigator tree, then click the
SOA Dependency Map tab, the map displays all of the server-side services and one level
of downstream dependencies on other services.
About Investigator tree nodes and map nodes
When you select a node in the Investigator tree, that node is the starting point for the
SOA Dependency Map. Only the dependencies that originate from the selected node
display on the SOA Dependency Map.
Each item on the SOA Dependency Map is considered a map node. The map nodes
displayed depend on the content type you have selected. For example, there are map
nodes to represent agents, client- or server-side services, or individual operations.
About standalone and dependent map nodes
If an agent, service, or operation does not have any dependencies, it is displayed as a
standalone map node. Depending on the context you have set, the SOA Dependency
Map may display only standalone map nodes, a combination of standalone map nodes
and dependent map nodes, or only dependent map nodes. For example, if you select
Services as the content type and the Client or Server node in the Investigator tree, you
may see a SOA Dependency Map showing both standalone and dependent services
associated with the selected node.
If you change the content type to Agents without changing the Investigator node, you
may see only a single standalone agent map node if there are no agent level
dependencies.
If you change the content type to Operations, however, the map displays one level of
dependencies for all of the dependent operations associated with the selected
Investigator tree node. The dependent operations may include client-side operations or
server-side operations.
Choosing a physical or logical view


About map nodes for operations
If you set the content type to Operations or right-click on a service then choose Show All
Operations, the SOA Dependency Map displays the operation-level dependencies using
the following conventions:
client-side service namespaces are displayed as map nodes in green boxes.
server-side service namespaces are displayed as map nodes in blue boxes.
agent names are displayed as map nodes in gray boxes.
These conventions for colored boxes are used to help you identify the services and
agents to which specific operations belong.
Choosing a physical or logical view
SOA Dependency Map provides two ways of displaying the SOA components in your
environment:
the physical view is a representation based on the physical location of services and
operations, as detected by agents.
the logical view is a representation based on groupings of similarly named services
and operations, regardless of their physical location.
To illustrate the difference between the physical and logical views, and how switching
between them can help you solve problems, consider the following example.
In analyzing a service problem, you identify a specific service as the root cause but
discover that the service you have identified is a distributed service. A load balancer
distributes requests for the service to five separate application servers.
Finding the source of the problem in this scenario requires an understanding of:
the relationships between logical instances to determine when one service is calling
another service.
the relationships between physical instances to determine which physical instances
are actually being called (which instance of service A is calling which instance of
service B).
how performance varies between the physical instances.
how traffic to the service is distributed among its instances.
For example, if a logical service is experiencing 100 invocations per minute, but is made
up of five instances, then its critical for you to understand how those 100 invocations
break down over each individual instance. If you discover that 90 of the 100 invocations
are going to a single instance, you can isolate the problem to that instance, resolve the
issue, and further analyze the reason for the increased load on the instance.
Select a Content Type


The SOA Dependency Map allows you to toggle between the Physical and Logical view
using the Show drop-down list. This enables you to differentiate between the logical and
physical instances of the service to determine how a problem in a specific physical
instance may be affecting the overall performance of the logical service.
To choose a SOA Dependency Map physical or logical view:
Click the Show drop down list in the SOA Dependency Map tool bar, then select
either Physical or Logical.
The SOA Dependency Map refreshes and displays your SOA environment based on the
view that you selected. For example, if you had been looking at Operations in the
Physical view, then selected the Logical view, the SOA Dependency Map refreshes and
displays Operations based on a logical representation of the SOA Dependency Map.
By default SOA Dependency Map displays the Physical view, unless you select a Virtual
Agent node in the Investigator tree. For the Virtual Agent node and its sub-nodes, the
Logical view is displayed by default.
Select a Content Type
Because the content type affects what you see, you can display a map with
dependencies for Operations, Services, or Agents. The default content type depends on
the node you have selected in the Investigator tree. You can change the content type to
drill down into dependency relationships from different points of view. You can move
between views to help you diagnose problem services.
Follow these steps:
1. Click the drop-down list for content type in the SOA Dependency Map toolbar.
2. Select Agents, Services, or Operations.
Note: If you are displaying the Logical view or have selected a Custom Virtual Agent,
you can only select Operations or Services.
The SOA Dependency Map refreshes to display dependencies for the content type.
More information:
Understanding how the content type affects what you see (see page 73)

Set a Primary Metric for Dependency Map Nodes


You can view both standard CA Introscope and SOA-specific metrics on the SOA
Dependency Map. Under each SOA Dependency Map service and operation node, the
Primary metric displays the standard CA Introscope metric that is of primary interest to
you. In addition, when you mouseover any SOA Dependency Map agent, service, or
operation node, tooltips display the metrics you selected to view.
The metrics that the SOA Dependency Map displays for agents and services are the
aggregated values for all the operations under that agent or service, not only the map
nodes currently selected or displayed on the SOA Dependency Map. For example, if you
mouseover a server-side service map node, the Tooltip displays the metrics you selected
to see. The metrics for the map node, however, can include client invocations for a
dependent client node and nonmonitored clients, or clients that do not appear in the
SOA Dependency Map, for example, for C++ clients. All client invocations contribute to
server-side metrics calculations.
Follow these steps:
1. Click the Primary Metric drop-down list in the SOA Dependency Map toolbar.
2. Select one of the standard CA Introscope metrics you want displayed on every
dependency map node:
Average Response Time
Responses Per Interval
Errors Per Interval
Concurrent Invocations
Stall count
The default primary metric for the SOA Dependency Map is Average Response
Time.
After you set the primary metric, all of the map nodes in the dependency map display
the current metric value for the metric.
If you mouseover a map node, a tooltip displays additional information, such as
minimum and maximum values and the current count for the number of data points
collected.
Selecting ToolTip metrics for dependency map nodes
The SOA Dependency Map displays a ToolTip any time you hover the cursor over a map
node. The ToolTip displays primary metric data by default. You can also display
SOA-specific metrics in the ToolTip. For example, you can choose to display direct and
indirect dependency metrics or deviation metrics in the ToolTip.
Changing the dependency levels displayed


To set SOA Dependency Map ToolTips metrics:
1. Click the Tooltips button in the SOA Dependency Map tool bar to display the
Choose Tootips Metrics dialog box.
2. Select the metrics you want to display as SOA Dependency Map ToolTips. For
example, you can select SOA-specific metrics, such as Dependency Direct and
Critical Direct metrics.
3. Click OK.
Based on the Investigator node youve selected, when you hover over a SOA
Dependency Map node, the SOA Dependency Map displays all or some of the selected
metrics, depending on the metrics that the Enterprise Manager reports for that
Investigator tree node. For example, if you set the SOA Dependency Map to display the
associated Dependency Direct ToolTips metric and you hover over an operation node,
you see data for this metric in the ToolTip:

However, if you hover over a services node, the Dependency Direct metric is not
displayed because services dont generate data to calculate the Dependency Direct
metric.
When you select a node in the Investigator tree and click the SOA Dependency Map tab,
the SOA Dependency Map displays the dependencies for the selected node plus one
additional level of dependency by default. You can modify the dependencies displayed
in several ways:
You can check for additional dependencies for an individual item in the map.
You can hide lower-level dependencies for an individual item in the map.


You can expand or unroll another full level of dependencies for every item in the
map.
You can hide or roll up the lowest-level dependencies for every item in the map.
Checking for additional dependencies for a map node
By default, only one level of dependency is displayed in the SOA Dependency Map. If
you are interested in a specific map node, you can check for additional, lower-level
dependencies for that agent, service, or operation without expanding the lower-level
dependencies for other map nodes.
When you check for additional dependencies for an item in the map, you unroll one
dependency level at a time. Each time you check for additional dependencies, the next
lowest level of dependencies are added to the map. If you check the next level and no
additional dependencies are found, the map displays the message Additional
dependencies not found.
To check for additional dependencies on a specific map node:
Right-click an individual item in the map, then choose Show Next Dependency from
the menu.
The SOA Dependency Map unrolls the next level of dependency only for the selected
map node. For example, when a server-side operation is being unrolled, the next level of
dependency that unrolls is the associated client-side operation.
Hiding dependencies for a map node
If you have unrolled many dependency levels for a specific agent, service, or operation,
you may want to hide some dependencies levels for that item. When you hide
dependencies for an item in the map, you roll up one dependency level at a time. Each
time you hide dependencies, the next lowest level of dependencies are removed from
the map.
To remove dependencies for a specific map node:
Right-click an individual item in the map, then choose Hide Dependencies from the
menu.
The SOA Dependency Map rolls up all the dependency levels for the selected map node.


Checking for additional dependencies for all items in the map
By default, only one level of dependency is displayed in the SOA Dependency Map. To
check for additional, lower-level dependencies for all items in the current map, you can
unroll one dependency level at a time for the entire map. Each time you check for
additional dependencies, the next lowest level of dependencies are added to the map. If
you check the next level and no additional dependencies are found, the map displays
the message Additional dependencies not found.
To unroll dependencies for every item in the map:
Click the Show next dependencies button on the SOA Dependency Map tool bar.
For example:

The SOA Dependency Map unrolls dependencies for every lowest-level item in the map.
So if an initial map node displays three dependencies, clicking this button adds a new
level of dependencies for each of the three items.
Hiding dependencies for all items in the map
If you have unrolled many dependency levels for all agents, services, or operations in
the map, you may want to remove some dependencies levels from the entire map.
When you hide dependencies for all items in the map, you roll up one dependency level
at a time. Each time you hide dependencies, the next lowest level of dependencies are
removed from the map.
To hide dependencies for every item in the map:
Click the Hide last dependencies button on the SOA Dependency Map tool bar. For
example:

The SOA Dependency Map rolls up the lowest-level of dependencies in the map.
Navigating within the SOA Dependency Map


If you expand the SOA Dependency Map to display multiple dependency levels or your
organization has a particularly complex SOA infrastructure, you may find the SOA
Dependency Map becoming difficult to navigate or have difficulty finding the specific
information you are looking for. The SOA Dependency Map includes several tools to
help you navigate around the map, move between the map and the Investigator, and
show or hide information quickly.
Panning, zooming, and fitting the SOA Dependency Map
If the dependency map you are viewing is large, you may want to navigate to specific
sections or resize portions for better visibility. The SOA Dependency Map provides the
following tools moving, enlarging, and refitting the SOA Dependency Map within its tab:
Pan
Magnify a selection
Zoom in / Zoom out
Fit to tab
To move the SOA Dependency Map around the tab view:
1. Click the Pan tool button on the SOA Dependency Map tool bar. The Pan tool
button displays a hand icon.
2. Click within the SOA Dependency Map.
3. Drag the map within the tab to center and examine your areas of interest.
To magnify an area of the SOA Dependency Map:
1. Click the Magnify a selection tool button on the SOA Dependency Map tool bar. The
Magnify a selection button displays a magnifying glass inside of a selection area.
2. Click within the SOA Dependency Map.
3. Drag to select the rectangular area you want to magnify.
To zoom in and out of the SOA Dependency Map:
1. Click the Zoom in and out tool button on the SOA Dependency Map tool bar. The
Zoom in and out button displays a magnifying glass with up and down arrows.
2. Click and hold down the mouse button within the SOA Dependency Map.
3. Roll your mouse forward to zoom in and backward to zoom out on the SOA
Dependency Map.


To resize the SOA Dependency Map to fit in the tab:
1. Click the Fit to Tab tool button on the SOA Dependency Map tool bar.The Fit to Tab
button displays a magnifying glass with grid lines.
The SOA Dependency Map resizes to fit within the tab.
2. Use the Magnify a selection or Zoom in and out tools to customize the map for
readability.
Jumping from a map node to the associated Investigator tree node
If you are viewing the SOA Dependency Map node in the Physical view, you can click on
any map node to go to that component in the Investigator tree. When you jump to the
new Investigator tree node, the SOA Dependency Map is redrawn using that new
Investigator tree node as a starting point. This enables you to reorient yourself based on
map node location of your choice.
To jump from a map node to a new Investigator tree node and redraw the map:
1. Verify the SOA Dependency Map is displayed in Physical view
2. Select a map node in the SOA Dependency Map
3. Right-click, then select Jump Here in Tree.
The new Investigator tree node is selected and becomes the new focal point for the
SOA Dependency Map.
Showing all operations for a service
If you select the Services content type, you can expand the SOA Dependency Map to
display all the operations for a specific service.
To show all operations for a service:
1. In the Investigator tree, select any individual operation of a service under the Client
or Server node.
2. Click the SOA Dependency Map tab.
The SOA Dependency Map displays corresponding client or server operation along
with its first-level dependencies within boxes representing the corresponding
services and agents.
3. Select a service map node, then right-click, and choose Show all Operations.
The SOA Dependency Map displays all the operations for that client or server-side
service.
Saving SOA Dependency Map images


Showing all services for an agent
If you have chosen to display the Agents content type, you can expand the SOA
Dependency Map to display all the services for a specified agent.
To show all services for an agent:
1. In the Investigator tree, select any individual service under the Client or Server
node.
2. Click the SOA Dependency Map tab.
The SOA Dependency Map displays the corresponding client or server service along
with its first-level dependencies within one or more boxes representing the
corresponding agents.
3. Select an associated agent in the SOA Dependency Map, then right-click, and
choose Show all Services.
The SOA Dependency Map displays all the services for that agent.
You can save all or part of the SOA Dependency Map in a variety of formats to enable
you to:
share information with colleagues to help you resolve issues.
save a current map as a snapshot of your environment so you can return to it later.
SOA Dependency Map Sharing
Resolving service problems often requires you to collaborate with colleagues who are
unfamiliar with CA Introscope or the SOA environment. For example, if you are
responding to an alert, you may need to work with developers who are responsible for
different services to resolve an application problem. Saving the dependency map as an
image enables you to share valuable information about the relationships between
services and current metrics with these colleagues.
You also have the option to save the dependency map showing agent-, service-, or
operation-level dependencies, and with physical or logical views of the dependencies.
By providing a graphical view of the service dependencies, you can facilitate
communication and help your organization resolve issues more effectively.


Saving the SOA Dependency Map as a snapshot
The SOA Dependency Map always reflects the most recently discovered dependencies
between monitored services. The data is checked and refreshed periodically, but the
dependency information is not stored for historical purposes.
In most cases, the dependency relationships in the SOA Dependency Map are fairly
static because most organizations only deploy, modify, or remove applications in a
production environment occasionally. In some cases, however, you may find it useful to
save images of your live environment as "snapshots" of the dependency data that you
can return to at a later date.
To save all or part of the SOA Dependency Map as an image:
1. Click the Save as Image button on the SOA Dependency Map tool bar to display the
Export Image dialog box. The Save as Image button displays a disk icon.
2. Choose the following settings for the output file.
Type
Select the file format to use for the image. You can save the dependency map
as a JPEG, GIF, PDF, PNG, or SVG file.
Filename
Type the destination path and file name for the output image file.
Image Content
Select an option to save a specific part of the SOA Dependency Map in the
image file.
Visible Window
This option is only available if you choose the Current Zoom Level size
option. Select this option if you only want to save the portion of the map
that is visible in the current window. For example, if the SOA Dependency
Map includes 100 nodes, but you have zoomed in to view only 10 nodes,
this option creates an image of only those 10 nodes.
Draw Grid
This option is not enabled.
Selected Objects Only
This option is only available if you have a map node selected. Select this
option if you only want to save the object that you have selected in the
map. For example, if you select a client web service map node, this option
creates an image of that client web service only.
Starting a Transaction Trace from a map node


Image Characteristics
Slide the slider bar or pick a number from 1 to 100 to specify image quality and
file size, where 100 indicates the best image quality for the image output. The
higher the quality image, the larger the file size for the saved image.
Size
Select one of the following options to control the size of the image:
Current Zoom Level
Select this option if you have zoomed in on an area of the map. Use this
option with Visible Window Only if you want the image to only show the
zoomed-in area.
Actual Size
Select this option to save the entire map at its actual size. This option does
not shrink the map.
Fit in Canvas
Select this option to save the entire map fit in the window. This option
shrinks the map to fit the window, if needed.
Custom
Select this option to choose the image width and height settings in pixels.
3. Click OK to create the file.
The file is saved to the specified location.
Starting a Transaction Trace from a map node
You can start a Transaction Trace session directly from a map node. This allows you to
quickly navigate from a high-level view of the relationships in a service to a detailed
view of the actual transactions that are passing through that service.
For example, assume you are trying to resolve a problem in a particular service after
seeing a red alert on the SOA Performance - Overview dashboard. Because the service
you are investigating is used by a critical business transaction, its important for you to
view transactions associated with that service as quickly as possible.
Instead of having to manually start a transaction trace session and enter filter criteria,
you can save time by starting a new transaction trace session directly from the map
node for the service on the SOA Dependency Map.
SOA Dependency Map for a Cluster


To start a transaction trace session from a map node
1. Right-click any map node and select Launch Transaction Trace to start a transaction
trace session.
Starting a transaction trace from a dependency map node opens the New
Transaction Trace Session dialog with a default filter based on the map node
automatically selected.
2. Click Add to add the default filter to the filter list or modify the filter criteria, as
needed, then click Add.
3. Click Set Filter, then click OK to open the Transaction Trace Viewer. The Transaction
Trace Viewer collects and displays all of the traces associated with transactions that
involve the selected map node.
Note: For more information about using cross-process transaction tracing in a SOA
environment and working with filters, see Using transaction tracing in SOA
environments (see page 89). For more information about using the New Transaction
Trace Session and Transaction Trace Viewer, see the CA APM Workstation User Guide.
SOA Dependency Map for a Cluster
If you have a clustered CA Introscope environment, the SOA Dependency Map displays
services and discovered dependencies for the Collectors reporting to the MOM. For
example, if you have an environment with three Collector Enterprise Managers, you can
view dependencies between agents or services running on separate Collectors. The
dependencies are displayed in the same way they are for application servers that are
based on the content type and Investigator tree node.
The SOA Dependency Map data is saved only on Collectors. The MOM receives its data
from the Collectors. The MOM does not save any SOA Dependency Map data (see
page 68).
Displaying the SOA Dependency Map requires the following files be installed on both
the MOM Enterprise Manager and each Collector Enterprise Manager in the cluster:
These files are installed in the <EM_Home>/product/enterprisemanager/plugins
directory on all Enterprise Managers in the cluster. If the files are not found, the SOA
Dependency Map fails to display properly.


Chapter 5: Using Transaction Tracing in SOA
Environments

CA APM for SOA enables you to monitor services and business processes by collecting
metrics about the performance, operation, and overall health of service-related
components. When dashboards or specific metrics suggest there may be a problem with
a service, you can use transaction traces to view details about actual business
transactions to help you find the cause and resolve the issue.
About cross-process transaction tracing (see page 89)
Using transaction tracing to solve problems (see page 91)
Start and View Transaction Traces (see page 92)
Set Filters for Transaction Traces (see page 98)
Querying the event database for SOA services (see page 101)
About cross-process transaction tracing
In a SOA environment, it is common for transactions to run across multiple Java Virtual
Machines (JVM) or Common Language Runtime (CLR) instances. Processing is passed
from one service to another. To see the full path of a transaction, requires being able to
trace synchronous and asynchronous calls across JVM and CLR boundaries. Being able to
trace transactions across multiple platforms running either the Java or .NET agent can
also be required.
With CA APM for SOA enabled, you can trace the full path of any business transaction
that uses HTTP, HTTPS, or JMS transport protocols and runs on a supported platform.
The full transaction can include segments that are processed on many different
platforms. For example, you can trace a transaction that uses services running on
WebLogic then passed to services running on SAP NetWeaver or a .NET server.
Depending on the additional SOA extensions you enable, a transaction can also include
segments involving any of the following components:
Oracle Service Bus
WebSphere Process Server
WebSphere Enterprise Service Bus
TIBCO BusinessWorks
webMethods Integration Server
About cross-process transaction tracing


WebSphere MQ
Spring web service.
Spring web service support in the agent, provides web service internal metrics and web
service transport metrics for both the client and server.
The business transaction can include any combination of platforms as long as CA APM
for SOA is enabled for every node that is traced. With CA APM for SOA enabled for an
agent, you can drill down into the details of transactions that call services on multiple
JVMs or CLR instances running on different nodes.
After you enable CA APM for SOA, no additional configuration is necessary.
Note: For information about support, see the SOA Performance Management section of
the Compatibility Guide.
Understanding how segments of a transaction are linked
Typically, transactions consist of a series of calls and responses that are passed from one
process to another. Often different segments of the transaction run on different logical
or physical servers or may be distributed to different components or backend systems.
Assembling the full transaction, therefore, requires identifying which processing
segments are part of the same transaction, and when one process in a transaction calls
another process. To trace the full path of a transaction that calls processes that can run
on different JVMs or CLR instances, the agent adds a correlation identifier to the
transaction. The correlation identifier can be passed from one process to another to
identify the segments that are part of the same transaction.
In addition to identifying the components that are part of the same transactions, the
correlation identifier providing sequencing information to keep track of the order in
which different parts of a transaction are called. The sequencing information enables
you to see the order in which transaction segments are called. For synchronous
transactions, the order can help you identify caller-callee relationships between
transaction segments. For asynchronous transactions, the order can help you identify a
processing workflow across multiple processes for complex client and server transaction
segments.
The correlation identifier data set is automatically managed by the agent and delivered
to the Enterprise Manager. The information is then used to construct the graphical
representation of selected transactions displayed in the Transaction Trace Viewer.
Using transaction tracing to solve problems


Understanding context for a cross-process transaction trace
You can start a transaction trace session based on a service namespace or an operation
name. In most cases, the namespace provides appropriate information to help you
identify problematic services. If you have identified a specific operation that may be the
source of a problem, you may want to start a transaction trace for that operation.
If you use the operation name, however, you should keep in mind that the service
namespace provides the context for the operation. For example, the operation name
makeReservation may be used in an application that reserves a seat on an airline,
requests a table in a restaurant, or schedules an appointment at a doctors office. If you
start a transaction trace for the operation name makeReservation, you need to be
aware of the namespace where that operation is used.
The namespace information for an operation is displayed in the Component Details on
the Trace View tab when you select a specific trace. For example, if you select the
makeReservation operation on the Trace View tab, you can check the Component
Details to see whether the operation is part of a travel agency web service or a hotel
reservation service by checking the namespace associated with it.
Using transaction tracing to solve problems
To see how cross-process transaction tracing helps you identify and assess a problems
quickly and effectively, consider the following example. After running a transaction
trace session, application support finds a transaction with a six second (6000 ms)
execution time.
From the Trace View for the transaction, it is apparent that the transaction includes a
call from a client-side web service, dataservice.yourcompany.net/invoke, to a server-side
web service, cics.mycompany.net/invoke, and that the server-side web service is making
a large number of calls to a CICS mainframe.
Although the CICS processing time is not explicitly displayed in the trace because that
part of the transaction is not instrumented, the Trace View shows that the CICS
back-end is servicing the repeated requests in rapid succession. From this transaction
trace, the application support specialist can see that the repeated calls are most likely
caused by programming logic, such as a nested loop, in the server-side service and that
the services invoke operation is responsible for most of the transactions overall
execution time. With this information, the application support specialist can go directly
to the owner or developer of the server-side web service to request an in-depth
investigation into the application logic that calls the CICS back-end.
Start and View Transaction Traces


Cross-process transaction tracing lets you identify and resolve problems in a web service
when you have business transactions that include calls to different JVMs or CLR
instances on local or remote computers. Agents on the JVMs or CLRs that participate in
the transaction must report information to the same Enterprise Manager when it is not
part of a cluster otherwise you cannot see correlated traces. If the agents report
information to same Enterprise Manager, you can start a transaction trace session to
capture information about the entire business process. In a clustered environment as
long as the Workstation connects to the MOM, agents participating in a cross process
transaction can connect to any of the collectors and traces are correlated.
You can start a transaction trace session:
Directly from a map node in the SOA Dependency Map.
Manually from the Workstation by clicking Workstation > New Transaction Trace
Session.
Follow these steps:
1. Right-click a map node in the SOA Dependency Map or click Workstation > New
Transaction Trace Session to display the New Transaction Trace Session dialog.
2. Click the fourth check box to activate the SOA-related filters option.
The following example illustrates the check box to select for activating SOA filters
and a namespace filter definition:

3. Select the type of transaction trace filter you want to use from the list of
SOA-related filtering options and click Add.
CA APM for SOA includes SOA-specific transaction trace filters that let you select
transactions which are based on the service namespace or on a specific operation
name. Depending on the node that you select before starting a new transaction
trace, a default filter and value is set automatically.


You can select the namespace or operation name filter for tracing transactions
involving any web service or web service operations that match the criteria you
specify. This criteria can include web services that an SOA platform provides, such
as TIBCO BusinessWorks or webMethods Integration Server.
4. Click Set Filter.
5. In the Run Session for field, enter the number of minutes for the transaction trace
session to run.
6. In the Trace Agents section, select all or specific agents for which to trace
transactions.
7. Click OK.
The transaction trace session starts.
Note: For more information about starting a transaction trace from the Workstation,
see the CA APM Workstation User Guide.
More information:
Starting a Transaction Trace from a map node (see page 86)

Using the Summary View
After you start a transaction trace session, transaction trace results display in the top
portion of the Transaction Trace Viewer. The list displays all of the transactions for the
namespace or operation you are tracing. You can click the Duration column head to sort
the transactions by duration.
Select a transaction in the top portion of the viewer to display all of the calls that make
up the transaction, including calls to other JVMs or CLRs, on the Summary View tab.
After you select a transaction, the Summary View lists the services and operations that
were called in the selected transaction, including the number of calls, the length of the
call in milliseconds, and the minimum, average, and maximum call times.
Note: For more information about using the Summary View for a transaction trace, see
the CA APM Workstation User Guide.


Use the Trace View
To view details about the transaction in a graphical form, click the Trace View tab.
The Transaction Trace View displays each component in the transaction as a bar and
illustrates how much of the total transaction execution time each component is
responsible for. For synchronous transactions, the Trace View tab also indicates the
calling relationships between components on each node involved in the segment of the
transaction you are viewing.
If a transaction includes processing on more than one JVM, the traces for each JVM are
displayed in separate rows. For SOA transactions, it is common for processing to take
place on multiple JVMs.
As you select components of the transaction in the graph, additional details about the
component are displayed in the Component Details below the graph.
Note: For more information about using the Trace View or about the information
displayed for the Component Details in a transaction trace, see the CA APM Workstation
User Guide.
Use the Tree View
To see a hierarchical view of components for a selected transaction, click the Tree View
tab.
The Tree View displays the components of the transaction in a hierarchical structure
with a red, yellow, or green indicator based on how much time the component
contributes to the overall execution time for a transaction.
You can select and expand components to see more details. If you select any
component, the tab displays additional information in the Component Details pane.
Note: For more information about using the Tree View or about the information
displayed for the Component Details in a transaction trace, see the CA APM Workstation
User Guide.


Using the Sequence View
Because of the complex nature of distributed applications in SOA environments, it is
common for a single user transaction to span multiple threads running on separate
agent JVMs or CLRs and to include both synchronous and asynchronous calls. These
individual transaction segments need to accounted for to present the full path of a
transaction as a logical unit. The Sequence View tab displays the caller-callee
relationship between the segments of a transaction to make the sequencing order of
the calls visually apparent.
The Sequence View is particularly useful, if a transaction:
includes asynchronous calls
includes calls to processes running on agents that is not time synchronized with
each other
includes complex synchronous calls across multiple JVMs or CLRs
includes traces started automatically for downstream agents called from a
transaction trace session on another agent.
To display the calling order for the processes in a selected transaction, click the
Sequence View tab. In this tab, arrows point to the called process and a bar chart lists
the processes sorted by duration time. If there are traces identified as part of the
transaction but their correct location cannot be determined, they are added to the
sequence with dotted lines. If you select a process in the graph or the bar chart,
additional details are displayed in the right panel for that process.
The slowest processes are identified by their ranking in the bar chart and a slow process
icon. If there are any errors in a process execution, an error icon is displayed for that
process.
Selecting a method for labeling the process nodes
Each process listed in the Sequence View represents a component trace for the
processes involved in completing an operation. If the traces come from the same server
or agent, the labels displayed for the processes may be difficult or impossible to
identify.
By default, the process label is automatically selected using the component that
includes the operation name, the component that includes the EJB string, or the first
unique component resource name prepended with the agent name. If you dont want to
use the default selection, you can change the process label to use the first component
name, last component name, thread name, or description.
If you choose the last component name as the process label, the name used is the last
unambiguous name in the call stack. Depending on the call sequence and whether there
are synchronous or asynchronous calls, the name may or may not be the last
component of the process.


To select a different process labeling scheme:
Select an option for the Process Label on the Sequence View tab.
Selecting a method for calculating duration
There are two ways to calculate the duration time for traces on the Sequence View tab:
Full duration is calculated using the start and end times for a process. This
approach is similar to how duration times are displayed on the Trace View tab. With
this approach, the root trace is always the slowest in synchronous transactions. This
is the default calculation.
Net duration is calculated by subtracting duration times of a traces asynchronous
children from the full duration time. The primary advantage of this approach is that
the slowest process is readily apparent for synchronous transactions. Switching
from full to net duration changes the order of processes listed by ranked duration
and duration times vary depending on how the execution time is calculated.
To change how the duration is calculated:
Select Full or Net for the Duration Type on the Sequence View tab.
Navigating between Sequence View and Trace View
In many cases, you may find it convenient to navigate between the Sequence View and
the Trace View. A right-click menu option enables you to move quickly between these
views without losing the context of a specific process or component.
To jump from a process in the Sequence View to the Trace View:
1. Select a process in the graph.
2. Right-click, then click Select Thread in Trace View.
To jump from a component in the Trace View to the Sequence View:
1. Select a component in the graph.
2. Right-click, then click Select Thread in Sequence View.


Viewing details about processes in a transaction
If you select a process in the graph or the bar chart, you can view details about that
process in the right panel. Depending on the process selected, some or all of the
following information is available:
Thread Name
Name of the selected thread in the call stack.
Thread Group Name
Name of the thread group.
Application Name
Display name used for the application.
Class
Instrumented class.
Method
Instrumented method.
Method Descriptor
Instrumented method arguments or signature.
Resource Name
Type of application resource. For example, the resource type can identify servlets or
EJBs.
URL
Full Uniform Resource Locator (URL) used to identify an application frontend.
Normalized URL
Normalized portion of the Uniform Resource Locator (URL) defined in the agent
profile as a method for identifying an application frontend.
Referring URL
Uniform Resource Locator (URL) of the referring page.
Server Name
Name of the server where the process executed.
Server Port
Port number where the process executed.
Set Filters for Transaction Traces


Scheme
Type of Uniform Resource Identifier (URI) scheme used.
A URI scheme is the top level of the Uniform Resource Identifier naming structure,
which is formed by a scheme name followed by a colon character (:).
For example, the URI scheme for a web service accessed using Hypertext Transfer
Protocol can be http.
HTTP Method
Type of HTTP method used. For example, the most common HTTP methods are
POST and GET.
CrossProcessData
Unique correlation identifier used to identify the processes that are part of the
same transaction.
Trace Type
Type of transaction trace for the process. The trace type indicates whether the
process is part of a transaction trace session or collected in a sampled transaction.
Enabling CA APM for SOA adds the namespace filter and operationname filter to the
Workstation to help you isolate transactions that are of interest to you quickly. For
example, if a particular service is used in critical business transactions, the namespace
filter allows you to filter all incoming transactions for transactions with that specific
namespace. When you identify the namespace where a problem is occurring, you can
use the operationname filter to filter transactions for one or more specific operations to
help you triage the issue.
You can also use the namespace and operationname filters in combination with other
filters to give you increased control over the transaction results returned. For example,
you can combine the namespace filter with a User ID or Error filter to capture only
transactions that meet both criteria.
Follow these steps:
1. Click Workstation > New Transaction Trace Session.
The specific filters available depend on the components you have installed.
2. Click the check box to activate a particular filter.
For example, click the Lasting longer than check box to look for transactions that
last longer than the specified time. You can use a specific parameter filter, such as
User ID or Session ID, to limit the transactions to the criteria you specify.


3. Click the check box to activate the filters for CA APM for SOA and other SOA
platforms.
4. Select the filter type, filter condition, type a value, and select the case sensitivity.
Click Add to add this filter to the list of available filters.
The namespace and operationname options are standard filters for web services.
These filters can also apply to web services that are exposed through SOA platforms
such as Oracle Service Bus, TIBCO BusinessWorks, or webMethods Integration
Server.
If you are monitoring other SOA platforms, however, you can use the following
additional filter types to capture transactions:
adapternode
WebSphere Process Server outbound adapters
businessprocess
TIBCO BusinessWorks process instances
webMethods Integration Server business services
WebSphere Process Server business processes
businessservice
Oracle Service Bus business services
businessstatemachine
WebSphere Process Server business state machines
mediationflow
WebSphere Enterprise Service Bus mediation flows
mediationflowoperation
WebSphere Enterprise Service Bus mediation flow operations
messageserver
IBM WebSphere MQ message servers
proxyservice
Oracle Service Bus proxy services
If you are manually typing the namespace or operation name, use the correct
spelling of the name for the filter to find matching transactions.
5. Add more filters to the filter list, if needed, and combine the filters to build complex
filters (see page 101). For example, you can add a filter for a namespace, and then
add another filter for an operation name. Select both filters in the defined filter list,
and then click AND to filter transactions on both the namespace and operation
name you specify.


6. Select the filter you want to use for this session, then click Set Filter.
Any previously set filter is replaced. Only one filter is in effect at a time.
7. In the Run Session for field, enter the number of minutes for the Transaction Trace
session to run.
8. In the Trace Agents section, select all or specific agents for which to trace
transactions.
9. Click OK.
The Transaction Trace session starts.
Adding and saving filters
You can add as many different filters as you need by defining the filter and clicking Add.
When you click Add, you add the new filter to the list of available filters. Duplicate filters
are not allowed.
To specify the filter you want to use in any transaction trace session, you must select the
filter definition in the list of available filters, then click Set Filter.
When you click OK to start a transaction trace session, the filters you have defined are
stored, so they are available the next time you start a new transaction trace session.
Clicking OK automatically stores the filters on a per-user basis. The next time you log on
to the Workstation, you can select the filter for tracing using your own set of
previously-defined filters.
Removing filters
You can remove a filter by selecting it in the list of available filters, then clicking
Remove. Clicking Remove removes the selected filter from the list of available filters in
the New Transaction Trace Session dialog box. You must click OK to permanently
remove the selected filter. If you do not click OK, the removed filter is restored to the
available filter list the next time you start a New Transaction Trace Session.
You can only remove a filter if it is not used as a component of another filter. For
example, if namespace filter1 and namespace filter2 are combined to create the filter
namespace filter1 AND namespace filter2, then namespace filter1 cannot be deleted
until the AND filter has been deleted.
Querying the event database for SOA services


Using complex filters
You can create complex filters by combining one or more filters from the filter list using
either the AND or the OR operator. The filters that you are combining must already exist
in the list of defined filters. When you use the AND or the OR operator to join together
two simple filter statements, a new filter is created and that filter can then be used as a
filter by itself or as a building block for creating additional filters.
Using the AND operator means that the trace has to pass all components of the filter.
For example, the filter namespace contains demobank AND operationname starts with
process requires that an incoming trace passes both filter conditions.
Using the OR operator means that the trace has to pass at least one of the components
of the filter. For example, the filter namespace contains demobank OR namespace
contains creditcheck requires that an incoming trace passes either the first filter
condition, the second filter condition, or both filter conditions.
You use the Transaction Trace Viewer primarily to view live or recent data from a
transaction trace session. Results from transaction trace sessions are automatically
stored in the Transaction Event Database and available for viewing using the Historical
Query Viewer. If you need access to the information at a later time, you can query the
Transaction Event Database to display information about any of the business
transactions or errors related to SOA-related services.
To query the database for all transactions related to web services:
1. With the Workstation open, select Workstation > Query Historical Events.
2. In the Query field, enter query information to retrieve the appropriate information.
For example:
To query for any event containing web services, enter webservices
To query for any event related to a specific web service endpoint, enter the
desired URL
3. Select a time range for the query, if needed.
4. Click Go to display any business transactions or errors that contain web services
information.
5. Click any row in the table to see its details in the bottom pane.
For example, if the row you select is a transaction trace (T), you can click the
Summary View, Trace View, Tree View, and Sequence View tabs to see additional
information just as you do in the Transaction Trace Viewer.


Viewing error event information
If the historical event is an error (E), the bottom pane displays the Stack View tab. If the
event is a transaction, the bottom pane displays the Summary View, Trace View, Tree
View, and Sequence View tabs. You can navigate the information displayed to
determine which component in the web service is causing problems.
To query the database for errors related to web services:
1. Choose Workstation > Query Historical Events.
2. In the Query field, enter:
type:errorsnapshot AND webservices
3. Click a row in the table to see error details in the Stack View tab.
For an error on the server side, you can see the root cause of the error in the
red error message.
On the client and server sides, you can see the root cause along with the SOAP
fault exception.
SOAP fault error messages have the prefix SOAP Fault at the beginning of the
red Error Message.
Viewing correlated event information
If you are reviewing details about a transaction, you can check for events that are part
of the same transaction but run on other processes or other nodes that are called
during the transaction.
To view correlated events for a transaction trace:
1. Select a transaction trace from the list displayed in the Transaction Trace Viewer or
the Historical Query Viewer, then click the Trace View tab.
2. Select Trace > Correlated Events to display a list of the traces on other processes or
nodes that are part of the selected transaction trace.
You can then select any correlated trace to display the Summary View, Trace View,
Tree View, or Sequence View for that trace.


Chapter 6: Configuring SOA-Specific
Properties

This section describes ways you can customize CA APM for SOA using configuration
properties.
Configuring the name displayed for web services (see page 103)
Configuring correlated tracing (see page 105)
Configuring the Insertion Point for SOAP Handlers (see page 107)
Configuring limits for the SOA dependency map (see page 108)
Configuring the name displayed for web services
By default, web service nodes are named using the web service namespace. The web
service namespace is similar to its URL. For example, if a web service uses the following
URL:
http://ClearingHouse.demobank.ca.com
its node is displayed like this by default:
http_//ClearingHouse.demobank.ca.com
Optionally, you can configure the agent to use the web service endpoint as the node
name. The web service endpoint includes additional information, such as the server
name and port number for the service. For example, if you choose to display the web
service endpoint for the ClearingHouse.demobank.ca.com web service, its node in the
Investigator might look like this:
http_localhost_8383_demobank_services_ClearingHouseService
You can change the name displayed by editing the agents webservices.pbd file and
specifying whether you want to use {namespace} or {servicename}. In most cases, the
namespace is the most recognizable name to display in the Investigator and the SOA
Dependency Map. You can, however, use the service endpoint if you edit the
webservices.pbd file and the IntroscopeAgent.profile file.
To use the service endpoint as the node name in the Investigator and Dependency
Map:
1. Open the webservices.pbd file in the <Agent_Home> directory.
2. Search for and replace all instances of {namespace} with {servicename}.
Because it is included in tracers as part of the fully-qualified metric name, there are
many occurrences of the {namespace} string in the file.


3. Save the webservices.pbd file.
4. Open the appmap-soa.pbd file in the <Agent_Home> directory.
5. Search for and replace all instances of {namespace} with {servicename}.
6. Save the appmap-soa.pbd file.
After you restart the application server, the Investigator tree and SOA Dependency
Map display the web service endpoint name rather than namespace.
If you are using the service endpoint name instead of the namespace, you may also
want to change the Namespace labels displayed on the Client and Server Overview
tabs.
To change the label used in the client and server Overview tabs:
1. Open the ws.overview.tv.xml file in the <EM_Home>/ext/xmltv/ directory.
2. Search for and replace all instances of Namespaces with Services.
3. Save the ws.overview.tv.xml file.
After you restart the Enterprise Manager, the Overview tab displays the Services
label when you select the WebServices, Client, or Server node in the Investigator
tree.
To use the metric naming convention from Web Services Manager 7.0.x:
1. Open the IntroscopeAgent.profile file in the <Agent_Home> directory.
2. Add the com.wily.introscope.agent.soa.metricNameFormatting property to the file.
3. Set the com.wily.introscope.agent.soa.metricNameFormatting property as follows:
com.wily.introscope.agent.soa.metricNameFormatting=/:
This setting replaces the slash (/) and colon (:) characters with an underscore (_)
character in metric names. With this setting,
http://CheckingAccount/demobank.ca.com is displayed as
http_CheckingAccount_demobank.ca.com.
4. Save the IntroscopeAgent.profile file.
After you restart the application server, the Investigator tree and SOA Dependency
Map display the web service endpoint name rather than namespace.
Configuring correlated tracing


Cross-process transaction tracing requires the agent to insert a correlation identifier
that can be passed from one process to another. The agent can insert this correlation
identifier into either a SOAP or HTTP header.
Because most services use SOAP messaging, the correlation identifiers are inserted and
read from SOAP headers by default. In certain situations, however, you may prefer to
pass the correlation identifier using HTTP headers. For example, in rare cases, adding
the correlation identifier to the SOAP header can cause the message to be rejected
because the correlation ID changes the SOAP payload.
Depending on how your applications process SOAP messages and how you have
implemented security, you can choose whether to pass the correlation ID in the HTTP
header or the SOAP header by modifying the IntroscopeAgent.profile file.
There are four agent configuration properties that control the handling of the
correlation identifier on the client and the server. With these properties, you can specify
whether the identifier should be inserted into the SOAP header, the HTTP header, both
header protocols, or not inserted at all. These properties start with the standard agent
prefix com.wily.introscope.agent:
soapheaderinsertion.enabled
Enables the client to insert the correlation identifier in the SOAP header.
Set the property to true to allow the client to use the SOAP header.
Set the property to false if you want to prevent the client from inserting
correlation identifier in the SOAP header.
By default, this property is set to true.
httpheaderinsertion.enabled
Enables the client to insert the correlation identifier in the HTTP header.
Set this property to true to allow the client to use the HTTP header.
Set this property to false if you want to prevent the client from inserting
correlation identifier in the HTTP header.
By default, this property is set to false.


soapheaderread.enabled
Enables the server to read the correlation identifier from the SOAP header.
Set this property to true to allow the server to use the SOAP header.
Set this property to false if you want to prevent the server from reading the
SOAP header.
httpheaderread.enabled
Enables the server to read the correlation identifier from the HTTP header.
Set this property to true to allow the server to use the HTTP header.
Set this property to false if you want to prevent the server from reading the
HTTP header.
By default, this property is set to false.
Configuring properties for clients and servers
You can set these properties to enable or disable specific behavior on an agent-by-agent
basis. For example, if a server processes messages from both SOAP- and HTTP-based
services, you may want to configure the agent on that server to read the correlation ID
in either type of header, but prevent the agent from inserting the identifier in the SOAP
header:
com.wily.introscope.agent.soapheaderread.enabled=true
com.wily.introscope.agent.httpheaderread.enabled=true
com.wily.introscope.agent.soapheaderinsertion.enabled=false
com.wily.introscope.agent.httpheaderinsertion.enabled=true
With these settings, the local computer can read the correlation identifier from a SOAP
header sent to it by other agents, but it can only insert the correlation identifier in the
HTTP header. To enable tracing, however, you should keep in mind that the web service
client and server must insert and read correlation identifiers from the same type of
header. For example, if you configure clients to insert the correlation identifier in the
HTTP header, you must configure the server to read the identifier from HTTP headers.
Disabling correlated tracing
If you want to disable the insertion of the correlation identifier for both SOAP and HTTP
and turn off cross-process transaction tracing, you can set all four properties to false.
For example:
com.wily.introscope.agent.soapheaderread.enabled=false
com.wily.introscope.agent.httpheaderread.enabled=false
com.wily.introscope.agent.soapheaderinsertion.enabled=false
com.wily.introscope.agent.httpheaderinsertion.enabled=false
Configuring the Insertion Point for SOAP Handlers


Before modifying these properties, you should keep in mind that the SOA Dependency
Map and cross-process transaction tracing require correlation identifiers to be passed
from one process to another.
If you disable correlated tracing by setting these properties to false, the SOA
Dependency Map cannot display dependencies properly and dependency metrics
cannot be collected accurately, and transaction traces may be incomplete.
You can use configuration properties in the IntroscopeAgent.profile file to control where
the SOAP handler is inserted in the SOAP handler chain. These properties provide
flexibility for applications that include encryption or require signature verification
against the original SOAP message, so that the insertion of the SOAP header does not
interfere with the applications validation of the SOAP message.
Client and Server Properties for Inserting the SOAP Handler
For application servers that use SOAP handlers, the following configuration properties
let you control the CA APM for SOA SOAP header:
soa.client.prependhandler
Enables the SOAP header to be inserted first or last in the SOAP handler chain on
the client.
Set the property to true to insert SOAP header by the first handler in the SOAP
handler chain.
Set the property to false if you want the SOAP header appended by the last
handler in the SOAP handler chain.
soa.server.appendhandler
Enables the SOAP header to be read first or last in the SOAP handler chain on the
server.
Set this property to true to have the SOAP header read by the last handler in
the SOAP handler chain.
Set this property to false if you want the SOAP header read by the first handler
in the SOAP handler chain, and then removed.
Configuring limits for the SOA dependency map


Changing the Default Order for SOAP Handlers
By default, the first handler in the handler chain on the client inserts the SOAP header
and the last handler in the chain on the server reads the header. For some applications,
you may need to modify the default behavior to verify the proper passing of a CA APM
for SOA SOAP header and the original SOAP message. For example, if an application
must verify the signature of a SOAP message, you may need to modify the default
behavior.
To illustrate why you would change the default property settings, consider an
application in which the first handler in the chain inserts the SOAP header. The SOAP
message is then signed in the second handler. When the message is received on the
server, the first handler attempts to verify the signature. Because the CA APM for SOA
SOAP header has been inserted but not yet read and removed, the signature fails and
the message is rejected.
The configuration properties let you change the default behavior so that the first
handler in the chain reads the CA APM for SOA SOAP header, and then removes it. This
setup allows the next handler in the chain to verify the signature against the original
SOAP message. For example:
com.wily.introscope.agent.soa.client.prependhandler=true
com.wily.introscope.agent.soa.server.appendhandler=false
Although the default property settings are appropriate in most environments, these
configuration properties give you flexibility in adapting CA APM for SOA to different
application scenarios.
The dependency map data stored on the Enterprise Manager typically represents all of
the dependencies across discovered applications, providing a complete model of the
service-oriented architecture you have deployed. In a very large or complex SOA
environment, however, a full representation of all SOA components and their
dependencies may affect the performance and operation of the Enterprise Manager
itself.
To prevent the dependency map from affecting the performance of the Enterprise
Manager, there are configuration properties that limit the size and complexity of the
map. By default, these configuration properties limit the dependency map to a
maximum of 5000 nodes and a maximum of 25000 dependencies (a ratio of 5
dependency relationships per node).


You can set the following Enterprise Manager configuration properties in the
IntroscopeEnterpriseManager.properties file to control these limits:
dependencymap.max.vertices
Sets the maximum number of nodes for which dependency data can be stored on
standalone or Collector Enterprise Manager.
By default, this property is set to 5000.
dependencymap.max.edge.ratio
Set the maximum ratio of dependency relationships to nodes to control the overall
complexity of the dependency data that can be stored on a standalone or Collector
Enterprise Manager.
By default, this property is set to 5.
For most organizations, the SOA network requires fewer than 5000 components and a
typical dependency ratio is 1 or 2 dependencies per component. The default settings,
therefore, allow for greater size and complexity than most organizations need. In rare
cases, however, you may want to modify the default values. For example, you may want
to modify the properties:
to increase the size and complexity allowed for the dependency map if the default
values do not accommodate your SOA environment. You should consider how the
changes may affect performance of the Enterprise Manager.
to intentionally restrict the size and complexity of the dependency map if your SOA
environment does not require as many nodes and dependencies as the default
values allow. You should consider whether any changes may cause the SOA
dependency map model to be unnecessarily incomplete.
For example, to modify the properties to store data for fewer nodes but more
dependency relationships per node:
com.wily.introscope.soa.dependencymap.max.vertices=2000
com.wily.introscope.soa.dependencymap.max.edge.ratio=8


Chapter 7: Monitoring Oracle Service Bus

Oracle Service Bus (OSB) provides message processing and communication between
loosely coupled service consumers and service providers. The SOA extension for Oracle
Service Bus enables you to monitor Oracle Service Bus operation through key
components, such as pipelines, proxy services, and transport protocols.
This section describes the OSB-specific dashboards, metrics, and alerts you can use for
monitoring and analyzing the performance, availability, and overall health of the Oracle
Service Bus environment.
About Oracle Service Bus (OSB) (see page 111)
How to Enable Monitoring for Oracle Service Bus (see page 114)
Use Dashboards to Monitor Oracle Service Bus (see page 118)
Understanding and viewing metrics for Oracle Service Bus (see page 120)
View Default Oracle Service Bus Metric Groupings (see page 124)
View Default Oracle Service Bus Alerts (see page 125)
Viewing Oracle Service Bus dependencies (see page 126)
Tracing transactions for Oracle Service Bus (see page 127)
About Oracle Service Bus (OSB)
In a service-oriented architecture, the Enterprise Service Bus typically provides a
messaging layer between service consumers and service providers. The Enterprise
Service Bus enables validation, transformation, routing, and security for data and
messages across a distributed, heterogeneous environment.
Oracle Service Bus is an example of an Enterprise Service Bus that provides message
brokering, mediation, and service lifecycle management in a lightweight middle layer of
proxy interfaces.


If you have defined rules for processing messages using Oracle Service Bus, you can
monitor the operation of Oracle Service Bus with metrics for:
Business Services
Business services are definitions of external services for which Oracle Service Bus is
a client.
The external services are implemented in and hosted by external systems. To use
them Oracle Service Bus must know the interface to call, how to call it, and what to
expect as a result of a call. Business services within OSB model the external
interfaces so that the bus can invoke and interact with the external systems. Within
OSB, a business service configuration includes its interface, transport settings, and
security settings.
With the SOA extension for OSB, you can monitor how business services interact
with the external systems and collect data about their overall health under the OSB
> BusinessServices node.
Pipelines
Pipelines are named sequences that process the specific steps for a Request, a
Response, or an Error message flow.
To implement the processing logic of a proxy service, request and response
pipelines are paired together in pipeline pair nodes. These pipeline pair nodes can
be combined with other nodes into a single-rooted tree structure to control overall
flow. Error pipelines handle errors for stages and nodes in a message flow and
errors in the message flow or business service.
With the SOA extension for OSB, you can monitor the performance of the request
and response pipelines and collect data about their overall health under the OSB >
Pipelines node.
Proxy Services
Proxy services are definitions of intermediary web services that the service bus
implements and hosts locally.
Oracle Service Bus uses proxy services to route messages between business services
and service clients, such as presentation applications or other business services.
A proxy service configuration includes its interface, transport settings, security
settings, and a message flow definition. The message flow defines the logic that
determines how messages are handled as they flow through the proxy service.
With the SOA extension for OSB, you can monitor the performance of proxy
services and collect data about their overall health under the OSB > ProxyServices
node.


Transports
Transports define the mechanism for sending and delivering messages, and can
include any transport protocols Oracle Service Bus supports.
A transport provider manages the life cycle and runtime behavior of transport
endpoints. Target endpoints are resources where messages originate or are
targeted. The native providers in OSB let you configure proxy and business services
that require these transport protocols. You can also create or install custom
transport providers.
With the SOA extension for OSB, you can monitor all of the supported transport
protocols and collect metrics for inbound and outbound endpoints under the OSB >
Transports node.
UDDI
Universal Description, Discovery, and Integration (UDDI) is a platform-independent,
XML-based registry that enables businesses worldwide to list their services on the
Internet.
UDDI is an open industry initiative that enables businesses to publish service
listings, discover other businesses service listings, and define how the services or
software applications interact over the Internet.
With Oracle Service Bus and UDDI registries that are compliant with UDDI version
3.0, you can:
Publish information about any proxy service to a registry. The registry may be
based on Web Services Description Language (WSDL), SOAP, or XML.
Inquire for specific services in a registry or list all services available. You can
search on business entity, service name pattern, or both.
Import business services from a registry.
With the SOA extension for OSB, you can monitor the UDDI registries and collect
metrics for publish, import, and inquiry operations under the OSB > UDDI node.
XQueries
Oracle Service Bus supports XQueries for data transformation using the Oracle Data
Services Platform implementation of the XQuery engine.
The Oracle XQuery engine uses transformation maps to describe the mapping
between data types, and Oracle Service Bus supports data mapping using XQuery.
You can create, parse, and execute the transformations.
With the SOA extension for OSB, you can monitor the XQuery transformations for
creating, parsing, and executing XQueries and collect metrics for those operations
under the OSB > XQueries node.
How to Enable Monitoring for Oracle Service Bus


Enabling monitoring for Oracle Service Bus involves the following high-level steps:
1. Verify that you have a supported version of Oracle Service Bus installed.
Note: For system requirements, see the Compatibility Guide.
2. Verify the agent and CA APM for SOA are installed and enabled.
3. Enable the agent for monitoring Oracle Service Bus (see page 114) by configuring
the agent profile to include the appropriate directives for monitoring Oracle Service
Bus. If you have enabled the agent using the Standalone agent installer or using a
response file, you can skip this step.
4. Enable the Enterprise Manager extension (see page 116) by moving files from the
<EM_Home>/examples/SOAExtensionForOSB directory to the appropriate
Enterprise Manager directory.
Enabling the agent for monitoring Oracle Service Bus
You can add and enable the CA APM for Oracle Service Bus when you install the agent
and select WebLogic as the application server. You can also enable the CA APM for
Oracle Service Bus manually after installing the agent.
If you enabled CA APM for Oracle Service Bus when you installed the agent, the agent
profile is automatically configured with default settings and no further steps are
required to enable the agent extension.
If you did not enable CA APM for for Oracle Service Bus when you installed the agent,
you need to manually configure the agent profile to enable monitoring.
To enable CA APM for Oracle Service Bus manually:
2. Verify the CA APM for Oracle Service Bus directory, SOAExtensionForOSB, is in the
<Agent_Home>/examples directory and copy the files from the
<Agent_Home>/examples/SOAExtensionForOSB/ext directory to the
3. Open the IntroscopeAgent.profile file in a text editor.
4. Add the appropriate OSB-full.pbl or OSB-typical.pbl file to the
introscope.autoprobe.directivesFile property in the IntroscopeAgent.profile file.
For more information about selecting the appropriate ProbeBuilder directives, see
About the directive files for Oracle Service Bus (see page 115).


5. Modify any additional SOA-specific agent configuration properties in the
IntroscopeAgent.profile file if you want to change the default settings.
Depending on how you have implemented security, you should note that some
applications may require changes to the default settings.
For example, if you encrypt communication for web services, you should modify the
default configuration for the agent to enable the agent to use HTTP correlation and
disable SOAP correlation. By default, both SOAP and HTTP correlation are enabled
for Oracle Service Bus. For more information about setting the configuration
properties for HTTP or SOAP correlation, see Configuring correlated tracing (see
page 105).
6. Save your changes to the IntroscopeAgent.profile file and close the text editor.
About the directive files for Oracle Service Bus
When you set the introscope.autoprobe.directivesFile property in the
IntroscopeAgent.profile, you can choose the default typical or full instrumentation to
control the monitoring level, visibility of metrics, and the performance overhead as
appropriate to the environment in which you are deploying the agent. You can then use
the typical or full toggles file to fine-tune monitoring for specific components by turning
on or turning off tracing for specific tracer groups.
OSB-full.pbl
Full instrumentation for deep visibility into the operation of all Oracle Service Bus
components.
Full instrumentation provides detailed reporting, but requires more overhead. It is
recommended for test or development environments, but not usually for
production environments.
By default, the following directives files are listed in OSB-full.pbl file list:
OSB-toggles-full.pbd
OSB.pbd
OSB-typical.pbl
Typical monitoring of important Oracle Service Bus components in a production
environment where overhead is at a premium.
Typical instrumentation provides less detail with reduced overhead, and is
recommended for production environments.
By default, the following directives files are listed in OSB-typical.pbl file list:
OSB-toggles-typical.pbd
OSB.pbd


OSB-toggles-full.pbd
Toggles for turning on or turning off the monitoring of Oracle Service Bus
components when you are using full instrumentation.
This file provides directives for the tracing provided in other directives files. By
default, most tracer groups in this file are turned on.
OSB-toggles-typical.pbd
Toggles for turning on or turning off the monitoring of Oracle Service Bus
components when you are using typical instrumentation. This file provides
directives for the tracing provided in other directives files. By default, only a small
section of tracer groups are turned on.
You should note that all agents that report data to the same Enterprise Manager should
use the same instrumentation level and the Enterprise Manager should be configured to
operate with either all typical or all full instrumentation agents. For example, if you
configure agents with typical instrumentation, you should deploy the typical version of
Enterprise Manager files.
Enable the Oracle Service Bus Enterprise Manager Extension
You can add and enable CA APM for Oracle Service Bus when you install the Enterprise
Manager. You can also enable CA APM for Oracle Service Bus manually after installing
the Enterprise Manager.
CA APM for Oracle Service Bus files are installed by default in the
<EM_Home>/examples directory when you install the Enterprise Manager. To enable CA
APM for Oracle Service Bus, copy or move the Enterprise Manager files from the
<EM_Home>/examples directory to the proper location in the Enterprise Manager
home directory.
Note: CA APM for SOA must be enabled on the Enterprise Manager before you can use
CA APM for Oracle Service Bus.
Follow these steps:
1. Verify that the CA APM for Oracle Service Bus directory, SOAExtensionForOSB, is in
the <EM_Home>/examples directory.
2. Copy the appropriate files for typical or full instrumentation from the
<EM_Home>/examples/SOAExtensionForOSB directory to the corresponding
location in the Enterprise Manager directory structure. For example, if you are using
typical instrumentation, copy the
com.wily.powerpacks.osb.emext.calculator_typical.jar file from the
<EM_Home>/examples/SOAExtensionForOSB/ext directory to the <EM_Home>/ext
directory.


Note: Use the same instrumentation level for all agents that report data to the
same Enterprise Manager. For example, if you deploy the typical version of
Enterprise Manager files, configure all agents communicating with that Enterprise
Manager with typical instrumentation. No agents using full instrumentation should
report data to an Enterprise Manager configured for typical mode.
3. Remove the Oracle Service Bus Management Module,
OSB_ManagementModule_typical.jar or OSB_ManagementModule_full.jar, from
the <EM_Home>/config/modules directory if the Enterprise Manager is a Collector
in a clustered environment.
Only copy the Management Module to the <EM_Home>/config/modules directory
on the Enterprise Manager you are using as the MOM computer. All other files and
scripts should be installed on both the Collector Enterprise Managers and the MOM
Enterprise Manager.
4. Remove old versions of Enterprise Manager files, if you are upgrading from a
previous version of the SOA extension for Oracle Service Bus.
If you have a previous release of CA APM for Oracle Service Bus installed on the
Enterprise Manager, manually delete the old version of the Enterprise Manager
files before you begin using the new version of CA APM for Oracle Service Bus.
If you upgraded from a previous release of CA APM for Oracle Service Bus,
delete the following files from the Enterprise Manager home directory:
<EM_home>/config/modules/OSB_ManagementModuleV<version>.jar
<EM_home>/ext/xmltv/OSB.overview.tv.xml
<EM_home>/product/enterprisemanager/plugins/
com.wily.powerpacks.osb.emext.calculator_<version>.jar
For example, if you are upgrading from version 8.1.1, delete the following files:
OSB_ManagementModuleV8.1.1.0.jar
OSB.overview.tv.xml
com.wily.powerpacks.osb.emext.calculator_8.1.1.0.jar
5. Restart the Workstation.
The dashboards and Overview tabs that are specific to CA APM for Oracle Service
Bus are loaded.
More information:
Enable Extensions on the Enterprise Manager (see page 37)

Use Dashboards to Monitor Oracle Service Bus


The SOA extension for Oracle Service Bus includes several preconfigured dashboards
that you can use to monitor the overall health of the application environment.
Dashboards aggregate data across deployed agents to summarize performance
information and help you rapidly diagnose and resolve problems.
Monitor the overall health, performance, availability, and current status of key
components of the Oracle Service Bus at-a-glance.
been crossed.
Drill-down into performance information to isolate and identify which Oracle
Service Bus components, transport protocols, endpoints, or operations are
experiencing delays or producing errors.
The preconfigured Oracle Service Bus dashboards are packaged in the Enterprise
Manager extension for Oracle Service Bus as part of the OSB Management Module you
have deployed (OSB_ManagementModule_typical.jar or
OSB_ManagementModule_full.jar).
The OSB Management Module provides the following preconfigured dashboards for
Oracle Service Bus:
OSB Home
A top-level view of the workflow through key components of Oracle Service Bus,
including alert indicators for the overall health of all transports, proxy services,
pipelines, and business services.
OSB Proxy Services - Overview
Summarized status for all proxy services, including alerts and graphs for Average
Response Time, Errors Per Interval, and Stall counts, and a list of the ten slowest
proxy services.
OSB Proxy Services - Details
Separate summarized metrics for request and response operations across proxy
services, including alerts and graphs for Average Response Time, Errors Per Interval,
and Stall Counts.
OSB Business Services - Overview
Summarized status for all business services, including alerts and graphs for Average
Response Time and Errors Per Interval, and a list of the ten slowest business
services.


OSB Pipelines - Overview
Summarized status for all pipelines, including alerts and graphs for Average
Response Time, Errors Per Interval, and Stall Counts, and the ten slowest pipelines.
OSB Transports I - Overview
Summarized health for commonly used transport types (HTTP/HTTPS, JMS, EJB, FTP,
Email, and SFTP), including alerts for Average Response Time, Errors Per Interval,
and Stall Counts across all transport types, and separate Average Response Time
graphs for HTTP/HTTPS, JMS, EJB, FTP, Email, and SFTP transport types.
OSB Transports II - Overview
Separate Average Response Time graphs for additional transport types (Tuxedo,
MQ, WS, JPD, SB, DSP, File, and Local).
OSB Transport Endpoints - Overview
Summarized status for inbound services and outbound endpoints across all
transport types, including Average Response Time graphs and alerts for Errors Per
Interval and Stall Counts for all inbound services and outbound endpoints, a list of
the ten slowest Inbound Services, and a list of the ten slowest Outbound Endpoints.
OSB XQuery - Overview
Summarized status for all XQueries execution attempts, including graphs and alerts
for Average Response Time, Errors Per Interval, and Stall Counts for Execute
operations, and graphs for Average Response Time and Errors Per Interval for Parse
operations.
OSB UDDI - Overview
Summarized status for all UDDI registry operations, including alerts and graphs for
Average Response Time and Errors Per Interval for Import and Publish operations
for the UDDI registries.
You can view the preconfigured dashboards using the Workstation Console. You can
also extend the OSB Management Module to include custom dashboards or modify the
default dashboard definitions to include custom metrics or alerts.
Note: For more information about creating and modifying dashboards, see the CA APM
Follow these steps:
extension for Oracle Service Bus is installed.
Understanding and viewing metrics for Oracle Service Bus


4. Select one of the OSB dashboards from the Dashboard drop-down list.
For example, select the OSB Home dashboard to see an architectural overview of
Oracle Service Bus with alert indicators for all of the key components of the OSB
workflow, such as Transports, Proxy Services, Pipelines, and Business Services.
5. Double-click an alert in the dashboard to open that component's dashboard.
For example, double-click the Proxy Services Response Time alert to go to the OSB
Proxy Services - Overview dashboard to see a list of the slowest proxy services, and
top-level alert indicators for response time, stall count, and errors for all proxy
services.
6. Double-click a specific proxy service, pipeline, or transport in a dashboard to open
the Investigator for further analysis.
From the Proxy Services Overview dashboard, for example, you can double-click a
specific proxy service in the 10 Slowest Proxy Services list to view its details in the
Investigator and continue drilling down through aggregated metrics to individual
components of the selected pipeline to uncover the root cause of the delay or error
threshold a dashboard alert signaled.
Note: For more information about viewing OSB-specific information in the Investigator,
see Understanding and viewing metrics for Oracle Service Bus (see page 120). For more
information about navigating between dashboards or between dashboards and the
Workstation Investigator, see the CA APM Workstation User Guide.
When you navigate in the Investigator tree, you can view the standard CA Introscope
metrics for most Oracle Service Bus components and operations. Data for the standard
metrics is collected and aggregated into OSB-specific metric categories displayed as
nodes and sub-nodes in the Investigator tree. The specific metric categories and node
names displayed depend on the Oracle Service Bus resources your applications use.
As you navigate through the Investigator tree, you can choose to view low-level metrics
for individual operations or aggregated metrics depending on the node you select,
enabling you to monitor the overall health of various OSB components.


For an overview of the standard metrics and the additional metrics provided by CA CPM
for SOA, see The Available Metrics (see page 52). For additional information about the
metrics for OSB components, see the following sections:
Metrics for BusinessServices (see page 121)
Metrics for Pipelines (see page 122)
Metrics for ProxyServices (see page 122)
Metrics for Transports (see page 123)
Metrics for UDDI (see page 124)
Metrics for XQueries (see page 124)
To view and navigate Oracle Service Bus metrics in the Investigator:
1. Expand the agent node, then select OSB to display the Overview tab for Oracle
Service Bus components.
The Overview tab lists summary information for all of the proxy services and
business services you have defined for the Oracle Service Bus to use.
2. Double-click a proxy service or a business service on the Overview tab to view all
the aggregated metrics for that proxy service or business service in a graphical
format.
3. Expand the OSB node to display sub-nodes for the top-level Oracle Service Bus
metric categories: Business Services, Pipelines, Proxy Services, Transports, UDDI,
and XQueries.
4. Click a sub-node to display an Overview tab with summary information about that
metric category. For example, click the OSB > BusinessServices to view all of the
business services listed in the Overview tab.
5. Expand a sub-node to see individual services or operations and metrics associated
with each.
For example, expand the BusinessServices node to see all of the business services
you have configured in Oracle Service Bus. You can then expand an individual
business service name to see the standard metrics for that specific service.
Metrics for BusinessServices
For Oracle Service Bus, business services are defined as external enterprise services that
are hosted by external systems. Only the following standard metrics are available for
Oracle Service Bus business services under the OSB > BusinessServices node:
Average Response Time (ms)
Errors Per Interval


In the Oracle Service Bus platform, business services are external services with which
Oracle Service Bus can exchange messages. Because the message to a business service
represents a call to an external service, it does not consist of a request and response
transaction. Therefore, calculating the Average Response Time metric for business
services relies on determining the total business service execution time.
CA Introscope calculates the business service execution time based on the sum of
Oracle Service Bus transport time, the actual service execution time, and network laspe
time. For example, if the OSB transport time is 10 ms, the actual service execution time
is 18 ms, and the network lapse time is 5 ms, the business service execution time is 33
ms.
Metrics for Pipelines
Pipelines are named sequences that process the specific steps for a Request, a
Response, or an Error message flow. All of the standard CA Introscope metrics are
available for Oracle Service Bus pipelines under the OSB > Pipelines node if you are
using OSB full instrumentation.
If you are using OSB typical instrumentation, the Pipelines node is not displayed in the
Investigator. If you want to display metrics for pipelines in the Investigator, modify the
OSB-toggles-typical.pbd file to enable tracing for Pipelines.
Metrics for ProxyServices
Proxy services define how Oracle Service Bus routes messages between business
services. A message from an external web service or database could be routed to a
service client such as a presentation application or other business service. All of the
standard CA Introscope metrics are available for Oracle Service Bus proxy services
under the OSB > ProxyServices node.
Proxy services consist of a request and response transaction. All of the metrics under
individual proxy service names are aggregated metrics which are based on the metrics
that are listed under the Request and Response sub-nodes.
For example, the Concurrent Invocations for mortgageBroker1 to loanGateway1 proxy
service are determined by adding the loanGateway1 requests to the concurrent
loanGateway1 responses.
The response time of each transaction is defined as the total round-trip time. A
transaction starts when a request is received from a caller. The transaction ends when
the response is returned to the caller.
Average Response Time is calculated by dividing total transaction time by the number of
transactions.


Metrics for Transports
Transports define the mechanism for sending and delivering messages. For Oracle
Service Bus, you can collect metrics for most common transport protocols, including the
following transport types that are supported in Oracle Service Bus by default:
HTTP/HTTPS
JMS
EJB
FTP
Email
SFTP
Tuxedo
MQ
WS
JPD
SB
DSP
File
Local
If a proxy service uses a specific transport type, that transport type and its metrics are
displayed in the Investigator tree. If a transport type is not used by any service, that
transport type is not displayed in the Investigator tree.
If a proxy service uses a custom transport type, the Java package name defined for that
transport type is displayed in the Investigator. For example, if the OSB Console uses the
custom transport type com.bea.wli.sb.test.service, Investigator displays
com.bea.wli.sb.test.service as a transport type.
All of the standard CA Introscope metrics are available under the OSB > Transports
node for the specific transport protocols you are using. For each transport protocol, the
nodes displayed depend on whether you have configured typical or full instrumentation.
For example, if you are using typical instrumentation, metrics are summarized under
send and receive nodes. If you are using full instrumentation and expand a transport
type, inbound and outbound sub-nodes are displayed and metrics for individual
operations, such as getRequestPayload, send, or sendMessageAsync, are listed for the
transport type.
View Default Oracle Service Bus Metric Groupings


Metrics for UDDI
You must configure the AquaLogic or Oracle Service Bus Registry to interact with UDDI
3.0 compliant registries before you can collect and view UDDI metrics. If you have
configured Oracle Service Bus to use UDDI, you can collect and view aggregated metrics
for import, inquiry, and publish operations.
All of the standard CA Introscope metrics are available under the OSB > UDDI
sub-nodes for import, inquiry, and publish operations.
Metrics for XQueries
If you have configured Oracle Service Bus to use XQueries, you can collect and view
aggregated metrics for create, parse, and execute operations.
All of the standard CA Introscope metrics are available under the OSB > XQueries
sub-nodes for create, parse, and execute operations.
Metrics for the create and parse methods are populated only once for each XQuery.
Metrics for the execute method are populated with every execution of an XQuery
expression or condition.
The SOA extension for Oracle Service Bus includes default metric groupings that are
used to define the default dashboards and alerts. You can also use these default metric
groupings in custom dashboards and alerts.
The default metric groupings are packaged in the Enterprise Manager extension for
Oracle Service Bus as part of the OSB Management Module you have deployed
(OSB_ManagementModule_typical.jar or OSB_ManagementModule_full.jar).
You can view the default metric groupings using the Workstation Management Module
Editor. You can also extend the OSB Management Module to include custom metric
groupings or use the default metric groupings in custom dashboards or alerts.
Follow these steps:
2. Expand *SuperDomain* > Management Modules > OSB_ManagementModule
(*Super Domain*) you have deployed.
For example, if you have deployed typical settings, expand
OSB_ManagementModule Typical (*Super Domain*).
View Default Oracle Service Bus Alerts


the Oracle Service Bus management module.
metric groupings.
Note: For more information about creating or modifying metric groupings, see the CA
APM Workstation User Guide.
View Default Oracle Service Bus Alerts
The SOA extension for Oracle Service Bus includes default alert definitions that are used
in the preconfigured dashboards. You can also use these default alerts in custom
dashboards. Most of the default alerts are preconfigured with default Caution and
Danger thresholds and to send notification to the console if a threshold is crossed or
severity increases.
The default alert definitions are packaged in the Enterprise Manager extension for
Oracle Service Bus as part of the OSB Management Module you have deployed
(OSB_ManagementModule_typical.jar or OSB_ManagementModule_full.jar).
You can view the default alert definitions using the Workstation Management Module
Editor. You can also extend the OSB Management Module to include custom alert
definitions and notification types or use the default alert definitions in custom
dashboards.
Follow these steps:
2. Expand *SuperDomain* > Management Modules > OSB_ManagementModule
(*SuperDomain*) you have deployed.
For example, if you have deployed typical settings, expand
OSB_ManagementModule Typical (*SuperDomain*).
3. Expand the Alerts node to view all of the alerts defined for the Oracle Service Bus
management module.
In particular, you should review the default settings for Caution and Danger thresholds
and adjust the values, if necessary, and add notifications or corrective actions.
You can modify the default settings for any alert or create your own custom alerts.
Note: For more information about creating or modifying alerts, see the CA APM
Workstation User Guide.
Viewing Oracle Service Bus dependencies


Viewing Oracle Service Bus dependencies
You can view dependencies for Oracle Service Bus proxy services and business services
by selecting the ProxyServices or BusinessService node or an individual proxy service or
business service in the Investigator tree, then clicking the SOA Dependency Map tab. For
example, for a high level view of the dependencies for all proxy services on an agent,
you can select the ProxyServices node in the Investigator, then click the SOA
Dependency Map tab:

The node you select determines the context displayed in the dependency map. You can
then roll up to collapse or roll down to expand the context and level of detail you are
viewing. For example, for a high level view of dependencies in a specific proxy service,
you can select the proxy service name in the Investigator, then click the SOA
Dependency Map tab. The following example illustrates a proxy service for processing a
loan request selected in the Investigator tree and the dependency map expanded to
show additional dependencies:

You can continue to add dependency levels to the map to see the entire workflow for
the business process or zoom in on specific nodes of the map, as needed. For more
detailed information about navigating the dependency map, see Using the SOA
Dependency Map (see page 65).
Tracing transactions for Oracle Service Bus


Transaction tracing captures the specific steps involved in completing a transaction,
including operations passed in SOAP messages, HTTP or HTTPS headers, Java Message
Service calls, and through Oracle Service Bus components that perform message, data,
or protocol transformation.
If a transaction includes any messages routed through Oracle Service Bus proxy services
or other Oracle Service Bus components, you can view information about the operations
performed and the time each operation took to complete in the cross-process
transaction trace. You can track the business transaction across any combination of
platforms as long as CA APM for SOA and CA APM for Oracle Service Bus are enabled at
every node being traced.
Understanding the value of cross-process transaction tracing
Cross-process transaction tracing provides valuable information about the operations
being performed by loosely coupled services in a service-oriented architecture. You can
use cross-process transaction tracing to determine:
how messages are transformed and routed through Oracle Service Bus
components.
which business services and proxy services are being called during a transaction.
the sequence of calls being made during a transaction.
where the processing of a request or reply is slowest.
Starting and Viewing a Sample Transaction Trace
Session.
If you start the transaction trace from the dependency map, the map node type sets the
default filter automatically. If you manually start a new transaction trace session, you
can select one of the following filter types for Oracle Service Bus:
businessservice
proxyservice
namespace
operation


For example, to filter transactions for a specific Oracle Service Bus proxy service, you
can select the proxyservice filter and type all or part of the proxy service name.
After starting a transaction trace session, you can use the Transaction Trace Viewer to
view summary and detailed information about each segment of a selected transaction.
Because transactions involving Oracle Service Bus often include asynchronous calls, you
may find it useful to click the Sequence View to view the transaction workflow for the
processes that executed asynchronously as part of a transaction. The Sequence View
displays the order in which process execute to the extent the sequence can be
identified. For Oracle Service Bus transactions, the sequence does not necessarily
represent a traditional caller-callee relationship, but illustrates when one process
triggers the execution of another process.
Note: For more information about transaction tracing, see Using transaction tracing in
SOA environments (see page 89). For more detailed information about configuring
tracing for agents, see the CA APM Java Agent Implementation Guide or the CA APM
.NET Agent Implementation Guide. For more information about working with
transaction trace views and historical data, see the CA APM Workstation User Guide.


Chapter 8: Monitoring TIBCO
BusinessWorks

TIBCO BusinessWorks is a SOA platform consisting of multiple infrastructure
components and features. CA APM for TIBCO BusinessWorks enables you to monitor
many key elements of the TIBCO BusinessWorks processing engine, including process
starters, job instances, and transport protocols.
This section describes the TIBCO BusinessWorks-specific dashboards, metrics, and alerts
you can use to monitor and analyze the performance, availability, and overall health of
the TIBCO BusinessWorks environment.
About TIBCO BusinessWorks (see page 129)
How to Enable Monitoring for TIBCO BusinessWorks (see page 131)
Use Dashboards to Monitor TIBCO BusinessWorks (see page 138)
Understanding and viewing metrics for TIBCO BusinessWorks (see page 140)
View Default TIBCO BusinessWorks Metric Groupings (see page 158)
Viewing default TIBCO BusinessWorks alerts (see page 158)
Viewing TIBCO BusinessWorks dependencies (see page 159)
Tracing transactions for TIBCO BusinessWorks (see page 161)
About frontends and backends for BusinessWorks (see page 164)
Customizing metric aging and removal (see page 167)
Configuring correlated tracing for TIBCO BusinessWorks (see page 167)
About TIBCO BusinessWorks
TIBCO BusinessWorks enables companies to expose and integrate existing services and
legacy systems, design and test new services, and orchestrate and assemble
loosely-coupled services into applications.
As an integration platform, BusinessWorks encompasses multiple, distributed
subsystems. For example, TIBCO BusinessWorks supports multiple messaging services
and transport protocols.
About TIBCO BusinessWorks


You can monitor the operation of TIBCO BusinessWorks with metrics for the following
top-level components:
Activities
Activities are the individual units of work that carry out an operation in a TIBCO
business process definition.
With the TIBCO BusinessWorks extension, you can monitor the performance and
overall health of activities in business processes under the Tibco > Activities node.
Group Actions
Group actions identify the type of action a set of related activities participate in.
overall health of activities in business processes under the Tibco > Group Actions
node.
Hawk Metrics
TIBCO Hawk micro-agent provides the local agent with methods for monitoring the
host operating system.
With the TIBCO BusinessWorks extension, you can monitor the process engine
statistics collected by TIBCO Hawk micro-agent under the Tibco > Hawk Metrics
node.
Jobs
Jobs represent the execution of the process instances that are created in memory
and executed by the TIBCO BusinessWorks engine within a job pool.
overall health of process starters and job pools under the Tibco > Jobs node.
Processes
Processes are business workflows that are designed to complete a specific task. The
processes you defined in the TIBCO Designer can include subprocesses that run as
part of a parent process or in parallel with a parent process. An individual business
process is a runtime instance of a TIBCO BusinessWorks process definition.
overall health of business processes under the Tibco > Processes node.
How to Enable Monitoring for TIBCO BusinessWorks


Transports
Transports define the mechanism for sending and delivering messages.
overall health of HTTP, SOAP, and FTP transport protocols under the Tibco >
Transports node and the performance and overall health of Rendezvous with
metrics under the Tibco > Transports > RV node.
WebServices
WebServices metrics represent client and server business service endpoint and
associated operations within each service.
overall health of client and server web service endpoints under the WebServices
node.
To enable monitoring for TIBCO BusinessWorks, perform the following high-level steps:
1. Verify that you have a supported version of TIBCO BusinessWorks installed.
Note: For a complete list of the TIBCO BusinessWorks requirements, see the SOA
Performance Management section of the Compatibility Guide.
3. Configure the agent profile to monitor TIBCO BusinessWorks (see page 131) to
enable the agent to use CA APM for TIBCO BusinessWorks. If you enabled CA APM
for TIBCO BusinessWorks in the agent using the Standalone agent installer or using
a response file, you can skip this step.
4. Configure TIBCO BusinessWorks to use the agent (see page 135).
5. Enable the Enterprise Manager extension (see page 137) for TIBCO BusinessWorks.
Enabling the agent for monitoring TIBCO BusinessWorks
You can enable monitoring for TIBCO BusinessWorks when you install the agent and
select Default as the application server or manually after installing the agent.
If you selected CA APM for TIBCO BusinessWorks when you installed the agent, the
agent profile is automatically configured with default settings and no further steps are
required.
If you did not select CA APM for TIBCO BusinessWorks when you installed the agent, you
need to manually configure the agent profile to enable monitoring.


To enable the SOA extension for TIBCO BusinessWorks manually:
2. Verify the CA APM for TIBCO BusinessWorks directory, SOAExtensionForTibcoBW, is
in the <Agent_Home>/examples directory.
3. Copy the files from the <Agent_Home>/examples/SOAExtensionForTibcoBW/ext
directory to the <Agent_Home>/core/ext directory.
5. Add the appropriate directives file for typical or full instrumentation to the
introscope.autoprobe.directivesFile property in the IntroscopeAgent.profile file.
For more information about selecting the typical or full instrumentation, see About
typical and full instrumentation (see page 132). For more information about
customizing tracing with ProbeBuilder directive files, see About the directive files
for TIBCO BusinessWorks (see page 134).
6. Save your changes to the IntroscopeAgent.profile file and close the text editor.
About typical and full instrumentation
IntroscopeAgent.profile, you can choose the default typical or full instrumentation to
control the monitoring level, visibility of metrics, and the performance overhead as
appropriate to the environment in which you are deploying the agent. You can then use
the typical or full toggles file to fine-tune monitoring for specific components by turning
on or turning off tracing for specific tracer groups.
tibcobw-full.pbl
Provides full instrumentation for deep visibility into the operation of all TIBCO
BusinessWorks components.
Full instrumentation provides detailed reporting, but requires more overhead. It is
recommended for test or development environments, but not usually for
production environments.


By default, the following directives files are listed in tibcobw-full.pbl file list:
tibcobw-toggles-full.pbd
tibcobw-webservices.pbd
tibcobw-processes.pbd
tibcobw-tasks.pbd
tibcobw-RV.pbd
tibcobw-activities.pbd
tibcobw-jobs.pbd
tibcobw-correlation.pbd
tibcobw-transports.pbd
tibcobw-hawk.pbd
tibcobw-typical.pbl
Defines typical monitoring of important TIBCO BusinessWorks components in a
production environment where overhead is at a premium.
Typical instrumentation provides less detail with reduced overhead, and is
recommended for production environments.
By default, the following directives files are listed in tibcobw-typical.pbl file list:
tibcobw-toggles-typical.pbd
tibcobw-tasks.pbd
tibcobw-RV.pbd
tibcobw-toggles-full.pbd
Toggles for turning on or turning off the monitoring of TIBCO BusinessWorks
components when you are using full instrumentation.
This file provides directives for the tracing provided in other directives files. By
default, most tracer groups in this file are turned on.


tibcobw-toggles-typical.pbd
Toggles for turning on or turning off the monitoring of TIBCO BusinessWorks
components when you are using typical instrumentation. This file provides
directives for the tracing provided in other directives files. By default, only a small
section of tracer groups are turned on.
For more information about the directive files, see About the directive files for TIBCO
BusinessWorks (see page 134).
About the Directive Files for TIBCO BusinessWorks
The tibcobw-toggles-full.pbd and tibcobw-toggles-typical.pbd files enable you to control
the default tracing provided in the set of ProbeBuilder directive (.pbd) files. You can also
manually customize the tracing provided by modifying settings in the following files, as
needed:
Provides monitoring rules for activities and grouped activity actions within business
processes.
Enables cross-process transaction tracing for TIBCO BusinessWorks components
tibcobw-hawk.pbd
Provides monitoring rules for Hawk metrics within TIBCO BusinessWorks.
tibcobw-jobs.pbd
Provides monitoring rules for jobs and job pools running on TIBCO BusinessWorks.
Provides monitoring rules for TIBCO BusinessWorks business process definitions,
including process starters, and spawned and non-spawned subprocesses.
tibcobw-RV.pbd
Provides monitoring rules for Rendezvous messaging services within
BusinessWorks.
tibcobw-tasks.pbd
Provides monitoring rules for tasks within TIBCO BusinessWorks business processes.


tibcobw-transports.pbd
Provides monitoring rules for individual transport protocols, such as FTP, HTTP, and
SOAP.
Provides monitoring rules for BusinessWorks web service endpoints.
Note: For more information about configuring tracing, see the CA APM Java Agent
Implementation Guide or CA APM .NET Agent Implementation Guide.
Configure TIBCO BusinessWorks to Use the Agent
After you enable the agent using the installer or manually after installation, you must
configure TIBCO BusinessWorks to run the agent to instrument your applications. The
configuration steps depend on how you deploy archives in your environment.
When you create process definitions in the TIBCO Designer, you export them as Project
Archives (EAR). Each Project Archive can then consist of one or more Process Archives
(PAR).
In a typical TIBCO BusinessWorks deployment, each Process Archive runs inside its own
JVM. If each Process Archive runs in its own JVM in your environment, you can use the
following steps to configure TIBCO BusinessWorks to use the agent.
To configure TIBCO BusinessWorks without a service container
1. Open the bwengine.tra file in TIBCO BusinessWorks or the <application>.tra file of
the deployed application, and add the following entry to the
java.extended.properties property:
java.extended.properties=-javaagent:<Agent_Home>/Agent.jar -Dcom.wily.introsc
ope.agentProfile=<Agent_Home>/core/config/IntroscopeAgent.profile
Note: Escape the colon(:) and equal(=) in the java.extended.properties for TIBCO
BusinessWorks on UNIX.
If you have deployed applications, undeploy then redeploy those applications after
changing the bwengine.tra file. Alternatively, you can add the property to the .tra
file for individual applications. For example, you can add the property to the
<application_name>.tra file in the
<TIBCO_DOMAIN_HOME>/<DOMAIN_NAME>/application/<application_name>
directory.
2. Stop and restart any running service instances for the applications on the computer
where you have installed the SOA extension for TIBCO BusinessWorks.


As an alternative to running each Process Archive in its own JVM, you can decide to
deploy a TIBCO BusinessWorks service container. The service container enables you to
run multiple Process Archives in a single JVM. If you use a service container to deploy
Process Archives, you can use the following steps to configure TIBCO BusinessWorks to
use the agent.
To configure TIBCO BusinessWorks when using a service container
1. Open the bwcontainer.tra file in the <TIBCO_BW_HOME>/bin directory, and add
the following entry to the java.extended.properties property:
java.extended.properties=-javaagent:<Agent_Home>/Agent.jar
-Dcom.wily.introscope.agentProfile=<Agent_Home>/core/config/IntroscopeAgent.p
rofile -Dcom.wily.introscope.agent.agentName=<Agent_Name>
Note: Escape the colon(:) and equal(=) in the java.extended.properties for TIBCO
BusinessWorks on UNIX.
2. Verify that bwengine.tra or <application>.tra file for deployed applications does not
have the agent configured.
3. Stop and restart the service container instance.
Configuring automatic agent naming
Most TIBCO BusinessWorks domains have multiple business processes deployed in
multiple process archives (PAR). Because each process archive runs in its own JVM
instance, each process archive also starts its own agent instance.
To avoid manually having to name each agent instance using the
com.wily.introscope.agent.agentName property in each applications .tra file, the SOA
extension for TIBCO BusinessWorks provides a configuration file and property to enable
naming the agent dynamically using a prefix of the TIBCO BusinessWorks domain name
followed by an underscore (_) and the application name. For example, if the TIBCO
domain name is caDomain and the application name is soap_over_http-Process_Archive
and you enable automatic agent naming, the agent name is formed dynamically as:
caDomain_soap_over_http-Process_Archive
If the process archives name property is not found, the agent is automatically named
using the deployment name. For example:
caDomain_soap_over_http


To configure automatic agent naming:
1. Stop any running TIBCO BusinessWorks applications.
2. Verify whether the TibcoBWNaming.jar file is in the <Agent_Home>/core/ext
directory.
If you do not see the file, copy the it from the
<Agent_Home>/examples/SOAExtensionForTibcoBW/ext directory to the
4. Locate and set the introscope.agent.agentAutoNamingEnabled property to true. For
example:
introscope.agent.agentAutoNamingEnabled=true
5. Set the connection delay property to define how long the agent should delay
connecting to the Enterprise Manager while automatic naming is attempted. For
example, to delay the connection for 30 seconds, set the property as follows:
introscope.agent.agentAutoNamingMaximumConnectionDelayInSeconds=30
6. Set the renaming interval property to define how frequently the agent should check
its dynamically formed name when automatic naming is enabled. For example, to
check the agents automatically generated name every one minute, set the
property as follows:
introscope.agent.agentAutoRenamingIntervalInMinutes=1
7. Save your changes to the IntroscopeAgent.profile file.
8. Restart TIBCO BusinessWorks applications.
You should only use automatic agent naming for TIBCO BusinessWorks applications that
are deployed in separate process archives. If you are using a BusinessWorks Service
Container to deploy process archives, you should remove the TibcoBWNaming.jar file
from the <Agent_Home>/ext directory.
Enable the Enterprise Manager Extension
CA APM for TIBCO BusinessWorks files are installed by default in the
APM for TIBCO BusinessWorks, you need to copy or move the Enterprise Manager files
from the <EM_Home>/examples directory to the proper location in the Enterprise
Manager home directory.
Note: You must enable CA APM for SOA on the Enterprise Manager before you can use
the SOA extension for TIBCO BusinessWorks. For information about enabling CA APM
for SOA Enterprise Manager extensions, see Enabling extensions on the Enterprise
Manager (see page 37).
Use Dashboards to Monitor TIBCO BusinessWorks


Follow these steps:
1. Verify the CA APM for TIBCO BusinessWorks directory, SOAExtensionForTibcoBW, is
in the <EM_Home>/examples directory, then copy the files from the
<EM_Home>/examples/SOAExtensionForTibcoBW directory to the corresponding
location in the Enterprise Manager directory structure. For example, copy the files
from the <EM_Home>/examples/SOAExtensionForTibcoBW/ext directory to the
2. Remove the CA APM for TIBCO BusinessWorks Management Module,
TibcoBWManagementModule.jar, from the <EM_Home>/config/modules directory
if the Enterprise Manager is a Collector in a clustered environment.
You should only copy the Management Module to the <EM_Home>/config/modules
directory on the Enterprise Manager you are using as the MOM computer. All other
files and scripts should be installed on both the Collector Enterprise Managers and
the MOM Enterprise Manager.
3. Restart the Workstation to load the dashboards and Overview tabs that are specific
to CA APM for TIBCO BusinessWorks.
The SOA extension for TIBCO BusinessWorks includes several preconfigured dashboards
because they allow you to:
components of TIBCO BusinessWorks at-a-glance;
been crossed;
Drill-down into performance information to isolate and identify which TIBCO
BusinessWorks processes, transport protocols, or web services are experiencing
delays or producing errors.
The preconfigured TIBCO BusinessWorks dashboards are packaged in the Enterprise
Manager extension for TIBCO BusinessWorks as part of the SOA Extension for TIBCO
BusinessWorks Management Module (TibcoBWManagementModule.jar).


The TIBCO BusinessWorks Management Module provides the following preconfigured
dashboards for TIBCO BusinessWorks:
Tibco BW - Overview
A top-level overview of the key activity for TIBCO BusinessWorks, including alert
indicators for the overall response time, errors, stalls, and SOAP faults for all web
services, and alert indicators for the overall response time, errors, and stalls for
business processes.
Tibco BW - Business Processes
Summarized status for all business processes, including alert indicators and graphs
for the response time, error count, and stall count for business processes, and a list
of the slowest business processes.
Tibco BW - Activities
Summarized status for all activities, including alert indicators and graphs for the
response time, error count, and stall count for activities, and a list of the slowest
activities.
Tibco BW - Jobs
Summarized status for all jobs and job pools with graphs for the number of jobs
created, running, created per hour, and completed.
The dashboard also includes graphs indicating the number of monitored process
starters and the flow limit setting for monitored jobs.
Tibco BW - Transports
Summarized status for all transport types with graphs for the average response type
for all operations of each transport type. For example, if you are monitoring TIBCO
BusinessWorks processes that use SOAP, the dashboard displays the average
response time for SOAP operations such as writeSoapEnvelope and sendMessage.
also extend the TIBCO BusinessWorks Management Module to include custom
dashboards or modify the default dashboard definitions to include custom metrics or
alerts.
Follow these steps:
extension for TIBCO is installed.
Understanding and viewing metrics for TIBCO BusinessWorks


4. Select one of the TIBCO BusinessWorks dashboards from the Dashboard drop-down
list.
For example, select the Tibco BW - Overview dashboard to see top-level alert
indicators for TIBCO BusinessWorks frontends, backends, web services, and
business processes.
5. Double-click another tab or an alert to open the related dashboard to view more
detailed information.
For example, double-click the Business Processes tab or the Business Processes
Response Time alert to see more detailed information about the slowest business
processes and the average response time, errors per interval, and stall count for all
business processes.
6. Double-click a specific business process, activity, or job name in a dashboard to
open the Investigator for further analysis. For example, double-click the slowest
process in the Tibco - Business Processes dashboard to open the Investigator
displaying that process.
Note: For more information about viewing TIBCO-specific information in the
Investigator, see Understanding and viewing metrics for TIBCO BusinessWorks (see
page 140). For information about starting and using the Workstation, accessing
dashboards, or opening and navigating Investigator, see the CA APM Workstation User
Guide.
metrics for most components of the TIBCO BusinessWorks infrastructure. Data for the
standard metrics is collected and aggregated into TIBCO-specific metric categories
displayed as nodes and sub-nodes in the Investigator tree. The specific metric categories
and node names displayed depend on the processes, services, and resources you have
deployed in your environment.
As you navigate through the Investigator tree, you can view low-level metrics for
individual operations or aggregated metrics depending on the node you select, enabling
you to monitor the overall health of various TIBCO BusinessWorks components.


For an overview of the standard and additional metrics provided by CA APM for SOA,
see Understanding the metrics available (see page 52). For additional information about
metrics that are specifically for monitoring TIBCO BusinessWorks or for specificTIBCO
BusinessWorks components, see the following metric categories.
Metrics for Activities (see page 142)
Metrics for Group Actions (see page 142)
Metrics for Hawk (see page 142)
Metrics for jobs and job pools (see page 150)
Metrics for Processes (see page 152)
Metrics for Transports (see page 154)
Metrics for WebServices (see page 157)
To view and navigate TIBCO BusinessWorks metrics in the Investigator:
1. Expand the agent node, then click the Tibco node to display the Overview tab,
which lists summary information for all of the TIBCO BusinessWorks processes you
are monitoring.
2. Double-click a process to view all the metrics for that process in a graphical format.
Depending on the level of instrumentation, you may also see the list of tasks
associated with the selected process.
3. Expand the Tibco node to display sub-nodes for the top-level TIBCO BusinessWorks
metric categories.
4. Click or expand a sub-node to display an Overview tab with summary information
about that metric category. For example, click the Jobs node to display job pool
metrics on the Overview tab.
To see overview information for transports, expand the Transports node, then
select the FTP, HTTP, or SOAP node to display the Overview tab. For Rendezvous
metrics, expand Transports > RV, then select a sub-node to display the Overview
tab.
5. Expand any sub-node to see more detailed information about individual
components, such as subprocesses, activities, or jobs in memory and the metrics
associated with each.


Metrics for Activities
Activities are the individual units of work in a TIBCO business process definition.
Activities are often operations that interface to external systems, but activities can also
be used for internal processing. In the TIBCO Designer, activities are grouped by type
and available from a choice of palettes. For example, you can use the General Activities
palette for common operations, such as calling a process, setting a timer, or writing to a
log file or the File palette to define file handling activities.
In the Investigator tree, activities are also grouped by the type of activity to be
performed, and the node names reflect the specific action for an activity type. For
example, the File node in the Investigator can include metrics for FileCreateActivity,
FileReadActivity, and FileWriteActivity. The node names may be similar to the palette
names used in the TIBCO Designer for some activities, but it is not always the case. For
example, activities from the General Activities palette may be listed under the
CallProcess, Error Handling, or Flow nodes in the Investigator tree.
All of the standard CA Introscope metrics are available for TIBCO BusinessWorks
activities under the Tibco > Activities node.
Metrics for Group Actions
Groups are used to create sets of activities that, taken together, accomplish a particular
type of action. For example, groups can be used to define the set of activities that
repeat until a condition is true, that execute conditionally, or that participate in the
same transaction and are committed and rolled back together. Group actions identify
the type of action the activities participate in, such as an If Group for a set of activities
that execute if-then conditions, or an Iterative Loop Group for a set of activities that
repeat for every item in a sequence.
The metrics for Group Actions monitor the performance of the group executing an
action, such as committing or rolling back a transaction or iterating through a series of
steps. The metrics are not based on aggregated data from individual activities within the
group.
All of the standard CA Introscope metrics are available for TIBCO BusinessWorks
groups under the Tibco > Group Actions node.
Metrics for Hawk
TIBCO Hawk micro-agent provides monitoring for the BusinessWorks processing engine,
process definitions and activities metrics, and memory usage.


You can view Hawk micro-agent metrics using the following metric categories under the
Tibco > Hawk Metrics node:
ExecInfo (see page 143) metrics provide information about execution operations for
the process engine, such as the system uptime and number of threads being
executed.
MemoryUsage (see page 144) metrics describe the available and used memory.
ProcessDefs (see page 144) metrics provide detailed information about individual
process definitions and the activities that are executed for each process definition.
Processes (see page 147) metrics provide summary information about active
process instances. (These metrics are only valid for Hawk version 4.8.1.)
ServicesInfo (see page 148) metrics provide information about all of the services
deployed.
Status (see page 149) metrics provide general information about the status of the
process engine.
Execution metrics
The following metrics are available for TIBCO BusinessWorks under the Tibco > Hawk
Metrics > ExecInfo node:
Status
Current status for the execution engine. The metric value indicates whether the
engine is ACTIVE, SUSPENDED, in STANDBY or STOPPING on the monitored server.
Threads
Number of worker threads in the engine.
Uptime
Total elapsed time since process engine was started.
Version
Configuration version information for the monitored server.


Memory usage metrics
Metrics > MemoryUsage node:
FreeBytes
Total number of available bytes.
PercentUsed
Percentage of total bytes that are currently in use.
TotalBytes
Total number of bytes allocated to the engine process.
UsedBytes
Total number of bytes currently being used.
Process definition and activity metrics
Metrics > ProcessDefs node for individual process sub-nodes:
Aborted
Number of times the selected process definition has aborted.
AverageElapsed
Average elapsed time in milliseconds for all processes completed using the selected
process definition.
AverageExecution
Average execution time in milliseconds for all processes completed using the
selected process definition.
Checkpointed
Number of times the selected process definition has been checkpointed.
Completed
Number of times the selected process definition has completed.
CountSinceReset
Number of processes completed since the last reset.
Created
Number of processes created for the selected process definition.
MaxElapsed
Maximum elapsed time in milliseconds for all processes completed using the


MaxExecution
Maximum execution time in milliseconds for all processes completed using the
MinElapsed
Minimum elapsed time in milliseconds for all processes completed using the
MinExecution
Minimum execution time in milliseconds for all processes completed using the
MostRecentElapsedTime
Most recent elapsed time in milliseconds.
MostRecentExecutionTime
Most recent execution time in milliseconds.
Name
Name of the process definition.
Queued
Number of times the selected process definition has been placed in a queue.
Starter
Name of the selected process definitions process starter activity.
Suspended
Number of times that processes using the selected process definition have been
suspended.
Swapped
Number of times the selected process definition has been swapped.
TimeSinceLastUpdate
Number of milliseconds since the most recent values were updated.
TotalElapsed
Total elapsed time in milliseconds for all processes completed using the selected
process definition.
TotalExecution
Total execution time in milliseconds for all processes completed using the selected
process definition.


Metrics > ProcessDefs > process_name node for individual activity names:
ActivityClass
Name of class that implements the selected activity.
CalledProcessDefs
Names of the process definitions called by the selected activity.
ElapsedTime
Total elapsed time in milliseconds used by all calls of the selected activity, including
all time spent waiting for Sleep, Call process, and Wait activities.
ErrorCount
Number of times the selected activity has returned an error.
ExecutionCount
Number of times the selected activity has been executed by the TIBCO
BusinessWorks engine instance.
ExecutionCountSinceReset
Number of times the selected activity has been executed since the last reset.
ExecutionTime
Total execution time in milliseconds used by all calls of the selected activity.
This metric does not include waiting time for Sleep, Call process, and Wait activities.
LastReturnCode
Status returned by most recent execution of the selected activity. The valid return
codes for this metric are OK, ERROR, DEAD, or DEBUG.
MaxElapsedTime
Maximum elapsed time in milliseconds for the selected activity.
MaxExecutionTime
Maximum execution time in milliseconds for the selected activity.
MinElapsedTime
Minimum elapsed time in milliseconds for the selected activity.
MinExecutionTime
Minimum execution time in milliseconds for the selected activity.
MostRecentElapsedTime
Most recent elapsed time in milliseconds.


MostRecentExecutionTime
Most recent execution time in milliseconds.
Name
Name of the activity.
TimeSinceLastUpdate
Number of milliseconds since the most recent values were updated.
Tracing
Indicates whether tracing is enabled for the selected activity.
Processes metrics
Valid for Hawk version 4.8.1:
Metrics > Processes if you are using Hawk version 4.8.1:
CurrentActivityName
Name of activity currently being executed by the selected process.
CustomId
Custom identifier for the selected process, if one exists.
Duration
Elapsed wall-clock time since the selected process started in milliseconds.
MainProcessName
Name of the main process definition.
Name
Name of the process for the selected process.
StartTime
Time at which the process started in milliseconds.
StarterName
Name of process starter that started the selected process instance.
Status
Current status for the selected process. For example, this metric indicates whether
the job is currently active or not.


SubProcessName
Name of subprocess definition for the selected process, if applicable.
TrackingId
Tracking identifier for the selected process, if one exists.
Services metrics
Metrics > ServicesInfo node:
Description
Service description.
EndpointURL
Endpoint URL address for the service.
Name
Name of the service.
PortName
Name of the port for the service.
PortTypeName
Port type description for the service.
TransportType
Transport type description for the service.
WSDL_Namespace
Concrete Web Services Description Language (WSDL) namespace for the service.
WSDL_URL
Web Services Description Language (WSDL) URL address for the service.
bindingName
Binding name for the service.


Status metrics
Metrics > Status node:
Adapter Name
Name of the application.
Host
Name of host machine on which the TIBCO BusinessWorks engine process is
running.
Instance ID
Instance identifier for the engine instance.
New Errors
Number of new errors since the last call to this metric.
Process ID
Process identifier for the TIBCO BusinessWorks engine process.
Total Errors
Total number of errors since startup.
Uptime
Number of seconds since startup.
Enable Hawk Metrics
Collecting Hawk metrics is a performance-intensive option and is not enabled by default.
Consider the performance overhead before enabling this option. You enable the
collection of Hawk metrics using the Hawk micro-agent.
Follow these steps:
2. Set the introscope.autoprobe.directivesFile property to use the full instrumentation
monitoring level. For example:
introscope.autoprobe.directivesFile=tibcobw-full.pbl
3. Uncomment and set the following Hawk property to true:
com.wily.soaextension.tibcobw.hawkmonitor.enabled=true
Setting this property to true enables monitoring for TIBCO Hawk.


4. Control the polling interval for collecting the metrics from the Hawk micro-agent by
uncommenting the following property. For example:
com.wily.soaextension.tibcobw.hawkmonitor.frequency
Note: By default, the polling interval for collecting metrics is 30 seconds (30000
milliseconds).
The changes take effect.
Metrics for jobs and job pools
When the process starter for the process definition receives data to begin execution, it
creates a job. The job represents the execution of tasks in the process instance. In most
cases, jobs are created in memory, and executed by the TIBCO BusinessWorks engine
within a job pool. Each job in the job pool can execute a finite number of tasks before it
yields to the next job. The maximum number of tasks that can be executed in a job pool
is controlled by the StepCount property. The maximum number of jobs that can be
executed concurrently by the BusinessWorks engine is defined by the ThreadCount
property.
The metrics in the Jobs and Job Pools category help you monitor the number of jobs
created, held in memory, and executed in each job pool. The metrics for jobs and job
pools are refreshed every 30 seconds by the agent.
The following metrics are available for TIBCO BusinessWorks jobs and job pools under
the Tibco > Jobs node:
Active Jobs in Job Pool
Total number of active and non-paged processes in the selected job pool.
Job Error Count in Job Pool
Total number of errors since startup for all of the jobs in the selected job pool.
Running Jobs in Job Pool
Total number of running processes and queued processes in the selected job pool.
Thread Count
Maximum number of worker threads configured for the BusinessWorks engine.
Completed Jobs
Number of processes that have completed execution since startup.
Created Jobs
Number of processes that have been created inside the BusinessWorks engine since
startup.


Flow Limit
Value of the TIBCO BusinessWorks Flow Limit setting.
Jobs Created Per Hour
Number of processes created per hour inside the TIBCO BusinessWorks engine.
Process Starter State
Indicates the current status of the process starter for a job.
Running Jobs
Number of business processes running on the TIBCO BusinessWorks engine.
You can expand any individual job pool name to display sub-nodes for jobs that have
been created for that process instance.
Enabling or disabling metrics for jobs and job pools
Monitoring for jobs and job pools is on by default when you use full instrumentation
with a default polling interval of 30 seconds. You can use the following properties to
enable or disable monitoring for jobs and job pools and control the frequency of the
polling interval:
com.wily.soaextension.tibcobw.jobmonitor.enabled
com.wily.soaextension.tibcobw.jobmonitor.frequency
For example, set the com.wily.soaextension.tibcobw.jobmonitor.enabled property to
true to enable monitoring if you are using typical instrumentation or false to disable
monitoring if you are using full instrumentation:
com.wily.soaextension.tibcobw.jobmonitor.enabled=true
You can then use the com.wily.soaextension.tibcobw.jobmonitor.frequency property to
control the polling interval for collecting the metrics. For example:
com.wily.soaextension.tibcobw.jobmonitor.frequency=30000
If you are using typical instrumentation and set the
com.wily.soaextension.tibcobw.jobmonitor.enabled property to true, you also need to
uncomment the following lines in the tibcobw-toggles-typical.pbd file to enable job and
job pool monitoring:
#TurnOn: JobTracing
#TurnOn: JobPoolTracing
For example, set the com.wily.soaextension.tibcobw.jobmonitor.enabled property to
true and modify the tibcobw-toggles-typical.pbd file to enable job and job pool
monitoring tracers when using typical instrumentation:
TurnOn: JobTracing
TurnOn: JobPoolTracing
If you change either of the job monitoring properties, you should restart the application
server to have the change take effect.


Metrics for Processes
A major component of TIBCO BusinessWorks is its process engine. The process engine
includes tools for designing, deploying, and managing business processes. In TIBCO
BusinessWorks, a business process is a runtime instance of a TIBCO process definition. A
process definition can include activities, subprocesses, and tasks, and you can monitor
the process engine by monitoring these elements of your business processes.
All of the standard CA Introscope metrics are available for business processes,
spawned subprocesses, and tasks under the Tibco > Processes node. For non-spawned
subprocesses, only Average Response Time, Concurrent Invocations, Errors Per Interval,
and Responses Per Interval are available.
In addition to the standard metrics, the following metrics are available for processes and
spawned subprocesses:
Running Average Response Time
Average time in milliseconds that a business process spends actively executing on
the TIBCO BusinessWorks engine, not including time spent awaiting input.
Running Concurrent Invocations
Number of business processes that are actively running on the TIBCO
BusinessWorks engine.
Running Responses Per Interval
Number of business processes that have run successfully on the TIBCO
BusinessWorks engine in an interval.
This metric does not indicate the business processes completed in the interval. For
example, the metric can include business processes that suspended execution.
For example, expand Tibco > Processes to display the business process names you have
defined in the TIBCO Designer for TIBCO BusinessWorks. The Processes node may
include spawned and non-spawned subprocesses at the same level as the parent
business process and nodes for individual tasks:



You can also collect dependency and deviation metrics for TIBCO BusinessWorks
processes. For information about the standard dependency and deviation metrics, see
Using Investigator to view SOA performance metrics (see page 52).
About complete and active execution for business processes
Because business process definitions can include timers or suspend execution to wait
for user input, the Processes metric category provides metrics that measure:
Business process completion: These metrics describe the end-to-end processing
health of a business process, regardless of whether a process is suspended or
active.
Business process active execution: These metrics provide the processing health of
the business process only when it is actively executing on the TIBCO BusinessWorks
engine.
The Average Response Time metric for a business process measures the average
response time from start to finish, including any time the process is suspended awaiting
input or user response. For example, if a business process is started and takes 15ms of
active execution time on the BusinessWorks engine, waits 30ms for user input, then
executes for 10 ms to complete its operation, the total response time from start to
finish is the sum of 15ms, 30ms, and 10ms, for a total of 55ms. For example:
Average Response Time (ms) = Execution time + Suspended time
Because the Average Response Time metric includes time during which processing is
suspended, it does not reflect the performance of the BusinessWorks engine itself. A
separate Running Average Response Time metric tracks the time a business process
spends actively executing on the BusinessWorks engine.
The Running Average Response Time metric only measures the active execution time for
a business process. It does not include any time spent waiting for input. For example, if
a business process is started and executes on the BusinessWorks engine for 15ms, stops
executing awaiting user input, then executes on the BusinessWorks engine for 10 ms to
complete the business process, the Running Average Response Time is 15 ms for the
first execution and 10 ms for the second execution. The time during which the process
was suspended awaiting user input is not included. For example:
Running Average Response Time (ms) = Total execution time - Suspended time
Similarly, the standard Concurrent Invocations and Responses Per Interval metrics
include all processes in the count, regardless of whether they are actively running or
suspended. The Running Concurrent Invocations and Running Responses Per Interval
metrics reflect only the processing activity as it takes place on the BusinessWorks
engine.


The Running Average Response Time, Running Concurrent Invocations, and Running
Responses Per Interval metrics are all only applicable for business processes and
spawned processes, and are not provided for non-spawned subprocesses or individual
tasks.
About the stall count for business processes
For business processes, the Stall Count metric only considers processes that are actively
running on the BusinessWorks engine. Processes that are suspended awaiting user input
are not included in the stall count.
About errors per interval in subprocesses
The Errors Per Interval metric is only displayed for non-spawned subprocesses if an
error occurs when that particular subprocess executes. If an error occurs when the
non-spawned subprocess runs, the Errors Per Interval count for the subprocess and its
parent process are both incremented by one.
For parent processes and spawned subprocesses, the Errors Per Interval metric is always
displayed by default. If an error occurs when a spawned subprocess runs, the error is
recorded in the Errors Per Interval metric for that subprocess. However, the error for
the spawned subprocess is not added to the Errors Per Interval count for the parent
process.
Metrics for Transports
Transports define the mechanism for sending and delivering messages. For TIBCO
BusinessWorks, you can collect metrics for a range of transport protocols including
TIBCO Rendezvous, which is an enterprise messaging system that can be used to handle
message routing and processing in TIBCO BusinessWorks, and standard transport
protocols such as HTTP, SOAP, JMS, FTP, and XML.
With the TIBCO BusinessWorks extension, you can monitor the performance and overall
health of HTTP, SOAP, and FTP transport protocols under the Tibco > Transports node
and the performance and overall health of Rendezvous with metrics under the Tibco >
Transports > RV node.
You can also monitor the performance and overall health of JMS and XML by turning on
JMS and XML tracing in the standard j2ee.pbd file. The j2ee.pbd file is delivered with the
agent by default, but can be used with the TIBCO BusinessWorks extension to provide
additional monitoring.
All of the standard CA Introscope metrics are available for operations under the
Transports node for the specific transport protocols, such as SOAP and HTTP, that you
are using. You can then expand the transport protocol node to display transport classes,
such as driver, handler, or requestor classes, then expand sub-nodes to drill down into
metrics for individual operations, such as sendMessage or writeSoapEnvelope.


If you are monitoring JMS or XML using the agents j2ee.pbd file, you can view the JMS
and XML transport protocol nodes are under the agent node rather than the Tibco >
Transports node.
Metrics for Rendezvous (RV)
Rendezvous is an enterprise messaging system that enables distributed applications to
exchange data across a network. As an integration platform, TIBCO BusinessWorks uses
Rendezvous as one of its supported messaging services to reliably handle the high
volume of messages sent and received.
The metrics for Rendezvous provide detailed information about Rendezvous message
delivery, queues, and transports. Within TIBCO BusinessWorks, you can monitor
Rendezvous with metrics for the following metric categories under the Tibco >
Transports > RV node:
Message Listeners
Message Listeners are objects that listen for Inbound Rendezvous messages. When
new inbound messages arrive, the listener calls a Message Processor object to
process the message.
Message Processors
Message processors are callback methods that process the messages discovered by
the Message Listener.
Queue Groups
Queue groups allow fine-grained control over the order in which events are
dispatched. The relative priority of each queue in a group determines the order in
which the dispatch process calls the queue to dispatch its events.
The metrics in this category monitor the response time, throughput, and errors for
dispatch methods.
Queues
Queues are used to store asynchronous events, such as inbound messages or timer
processes, in the order received until they can be processed by a message
processor. When an event occurs, the event is placed in an event queue to wait for
a dispatch routine to deliver it for processing.
The metrics in this category monitor the response time, throughput, and errors for
dispatch methods.
Transport
Transports define the mechanism for sending and delivering messages. For
Rendezvous with TIBCO BusinessWorks, you can collect metrics for the Reliable
Transport (Standard Rendezvous Transport) and Certified Transport (RVCM)
transport types.


Message Listeners, Message Processors, and Transport Metrics
All of the standard CA Introscope metrics are available for Rendezvous under the
Tibco > Transports > RV sub-nodes for Message Listeners, Message Processors, Reliable
and Certified transport protocols.
Queue Groups Metrics
The following dispatch-related metrics are available under the Tibco > Transports > RV >
Queue Groups node for dispatch methods associated with individual queue groups:
Errors Per Interval
Queues Metrics
The following dispatch-related metrics are available under the Queues node for the
dispatch methods associated with individual queues:
Errors Per Interval
Enable or Disable Metrics for Rendezvous
Monitoring for Rendezvous is on by default when you use typical or full instrumentation
with a default polling interval of 30 seconds. If you want to disable monitoring for
Rendezvous, comment out the following lines in either the tibcobw-toggles-typical.pbd
or tibcobw-toggles-full.pbd file:
TurnOn: TibrvTransport
TurnOn: TibrvDispatchable
TurnOn: TibcoRVMessageProcessorTracing
TurnOn: TibcoRVMessageListenerTracing
For example, if you are using typical instrumentation, open the
tibcobw-toggles-typical.pbd file in a text editor and disable tracing by modifying the
lines as follows:
#TurnOn: TibrvTransport
#TurnOn: TibrvDispatchable
#TurnOn: TibcoRVMessageProcessorTracing
#TurnOn: TibcoRVMessageListenerTracing


Metrics for WebServices
All of the standard CA Introscope metrics are available for client and server web
service endpoints under the WebServices node. In addition, the SOAP Faults Per Interval
is a standard metric for all extensions that monitor web services on SOA platforms. For
information about the difference between Errors Per Interval and SOAP Faults Per
Interval, see Viewing SOAP fault and error metrics on the Errors tab.
You can also collect dependency and deviation metrics for TIBCO BusinessWorks web
service operations. For information about the standard dependency and deviation
metrics, see Using Investigator to view SOA performance metrics (see page 52).
To view and navigate WebServices metrics in the Investigator:
1. Expand the agent node, then expand WebServices to display the Client and Server
nodes for web service endpoints.
2. Expand the Client or Server node to display individual web service endpoints for
which you want to view metrics.
3. Expand a specific web service endpoint <namespace> or <servicename> to display
operations or select metrics for that web service.
4. Expand a specific operation within a web service to display metrics for that
operation.
About Average Response Time for server endpoints
For server-side operations, the Average Response Time metric represents the time it
takes TIBCO BusinessWorks to receive and parse an incoming SOAP message. In most
cases, that processing is only part of a more complex transaction. For example, a typical
BusinessWorks transaction includes the following stages on the server-side of a web
service:
the time spent receiving and parsing the incoming SOAP message
the time the BusinessWorks engine spends executing the process definition which is
exposed by the web service and preparing to send the reply
the time it takes to send the reply
Because each stage of the transaction can run on a different thread, the Average
Response Time metric can only measure the first part of the transaction for each
operation, then aggregates the data for web service endpoints. Because the metric
cannot account for the processing time that takes place on the additional threads, the
metric does not represent the total response time of a complete web service
transaction.
View Default TIBCO BusinessWorks Metric Groupings


About client and server SOAP fault metrics
For server-side operations (WebServices > Server > namespace), the SOAP Faults Per
Interval metric represents the number of SOAP faults send by BusinessWorks to the web
service client in response to a request.
For client-side operations (WebServices > Client > namespace), the SOAP Faults Per
Interval metric represents the number of SOAP faults received by the
SOAPSendReceiveActivity on the client.
The SOA extension for TIBCO BusinessWorks includes default metric groupings that are
used to define the default dashboards and alerts. You can also use these default metric
TIBCO BusinessWorks as part of the SOA Extension for TIBCO BusinessWorks
Management Module (TibcoBWManagementModule.jar).
Follow these steps:
2. Expand *SuperDomain* > Management Modules > Introscope SOA Extension for
TibcoBW <version> (*Super Domain*).
the TIBCO management module.
You can modify the default settings for any metric grouping or create your own
custom metric groupings.
Note: For more information about creating or modifying metric groupings, see the
CA APM Workstation User Guide.
Viewing default TIBCO BusinessWorks alerts
The SOA extension for TIBCO BusinessWorks includes default alert definitions that are
used in the preconfigured dashboards. You can also use these default alerts in custom
severity increases.
Viewing TIBCO BusinessWorks dependencies


TIBCO BusinessWorks as part of the SOA Extension for TIBCO BusinessWorks
Management Module (TibcoBWManagementModule.jar).
To view the default alert definitions for TIBCO BusinessWorks agents:
2. Expand *SuperDomain* > Management Modules >
Introscope SOA Extension for TibcoBW <version> (*Super Domain*).
3. Expand the Alerts node to view all of the alerts defined for the TIBCO
BusinessWorks management module.
and adjust the values, if necessary, and add notifications or corrective actions.
You can view dependencies for TIBCO BusinessWorks web services, service operations,
and process definitions by selecting TIBCO BusinessWorks Processes or WebServices
nodes in the Investigator tree and clicking the SOA Dependency Map tab.
viewing.


For example, for a high level view of the dependencies in all business processes on an
agent, you can select the Processes node in the Investigator, then click the SOA
Dependency Map tab:

For a high level view of the dependencies in a specific business processes on an agent,
you can select the business process name in the Investigator, then click the SOA
Dependency Map tab. Keep in mind that as you change the content type or Investigator
tree node, you change the context for the dependency map. For example, if you change
the content type from Services to Operations, the map displayed changes but the details
included in the map may be the same or different depending on the node selected in
the Investigator tree and the process definition.
Tracing transactions for TIBCO BusinessWorks


The following example illustrates a business process for submitting a purchase order
request selected in the Investigator tree and expanded to show additional
dependencies.

detailed information about navigating the dependency map, including showing and
hiding dependency levels, see Using the SOA Dependency Map (see page 65).
Transaction tracing provides a detailed or summary view of the specific steps involved in
completing a business transaction. For TIBCO BusinessWorks business processes or web
services, you can trace transactions that include operations routed through the
following protocols:
Simple Object Access Protocol (SOAP)
Hypertext Transport Protocol (HTTP)
Hypertext Transport Protocol Secure (HTTPS)
Java Message Service (JMS)


Transactions that involve TIBCO BusinessWorks business processes or web services can
include synchronous and asynchronous calls and activities running in parallel using
different threads. To enable transaction tracing for transactions that span multiple
threads or processes, correlation identifiers are inserted and consumed as a transaction
steps through each component and operation. You can then view detailed information
about the specific operations performed and the time each operation took to complete.
You can also track a business transaction across any combination of platforms as long as
CA APM for SOA and CA APM for TIBCO BusinessWorks are enabled at every node being
traced. This enables you to view details about the transaction even if the transaction
spans multiple JVMs or CLRs.
If a call from TIBCO BusinessWorks is executed by a process on an unmonitored server,
the transaction trace provides the execution time of the business process that calls the
unmonitored process so you can determine the time it took to receive a reply even
though the execution time for the unmonitored process itself is not recorded. The
transaction trace also records whether any errors took place.
How to Use the Transaction Trace Data in Tibco
When a very high average response time occurs, for example, x, in Tibco business
processes, you cannot use the time filter to filter a transaction greater than x. Business
Processes are generally composed of more than one transaction, therefore, perform the
following steps to diagnose the problem area.
1. Go to the TT window and enable the filter for that particular business process.
2. Invoke the application.
Numerous transaction traces for that business process occur. The traces are the
executing units of the business process.
3. Find out if any executing unit is lengthy. Drill down on that particular trace for more
information.
A time difference between the executing traces displays. This time indicates when
the business process was suspended. Using this information, find out how
frequently and for how long the business process was suspended.
A time-out for an HTTP request causes the corresponding activity to display an
error.


how business processes are routed through components.
which business processes are called and executed during a transaction.
the sequence of calls made during a transaction.
Starting and viewing a sample transaction trace
If a business process transaction includes calls to different JVMs or CLRs on a local or
remote computer and the agents on the called JVMs or CLRs report calls to the same
Enterprise Manager, you can run a transaction trace to view all of the calls executed as
part of the business process.
directly from a map node in the SOA Dependency Map.
manually from the Workstation by clicking Workstation > New Transaction Trace
Session.
You can configure filters to control which transactions are captured in the transaction
trace session and specify how long the session should last. If you start the transaction
trace from the dependency map, the map node type sets the default filter
automatically. If you manually start a new transaction trace session, you can choose one
of the following filter types for TIBCO BusinessWorks:
businessprocess
namespace
operation
For example, to filter transactions for a specific TIBCO BusinessWorks process definition,
you can select the businessprocess filter and type all or part of the process definition
name.
About frontends and backends for BusinessWorks


After you configure filters and start the transaction trace session, the Transaction Trace
Viewer is displayed. From the Transaction Trace Viewer, you can select a trace to view
additional details about the calls made in the transaction. For example, select a trace
then:
click the Summary View tab to see the components involved in the transaction
click the Trace View tab to display the calls made in the transaction and the time
spent on each call involved in the transaction
click the Sequence View to display the sequence of calls or the process workflow for
the transaction and the threads that took the most time in a transaction trace.
Note: For more information about transaction tracing, see Using transaction tracing in
SOA environments (see page 89). For information about configuring tracing, see the CA
APM Java Agent Implementation Guide or the CA APM .NET Agent Implementation
Guide. For more information about working with transaction trace views and historical
data, see the CA APM Workstation User Guide.
Transactions in a SOA often involve complex processing of synchronous and
asynchronous calls to multiple systems. For example, a single transaction may include
calls to an external web service, a TIBCO Enterprise Message Service server instance,
and to a database. For TIBCO BusinessWorks, the backend calls may all be processed
using different threads, making it more difficult to identify them as part of the same
transaction.
To enable the association of multiple backend calls with the same starting point for a
transaction, the SOA extension for TIBCO BusinessWorks includes the following
configuration property:
com.wily.soaextension.tibcobw.mbbs.enabled
By default, this property is set to true to enable the threads for backend calls that
participate in the same transaction to be included under the Backends or Called
Backends node and associated with the proper frontend.
A frontend identifies the starting point for a transaction. For TIBCO BusinessWorks, the
default frontends are process starters for business processes and the TIBCO
BusinessWorks HTTP servlet for web services.
Frontend metrics are collected and posted under the Frontends node by TIBCO
BusinessWorks application name. All of the backends calls initiated by the same
frontend for a transaction are collected under the Called Backends node for that
frontend. For example, if a process starter issues a call to a web service, a database, and
the TIBCO Enterprise Message Service, you can view the metrics for the calls under the
Frontend node associated with that process starter. Any errors generated by the
backends of the business process are propagated to the associated frontend node.


For example, to view metrics for a web service transaction that called a TIBCO
Enterprise Message Service server instance, you can expand the BusinessWorks HTTP
Server frontend in the Investigator, then expand its Called Backends node:

Understanding the limitations for spawned processes
If you have business processes that create spawned subprocesses, the originating
process typically does not wait for the spawned process to run to completion. Because
the business process that spawned the subprocess does not wait for the completion of
the spawned process, any metrics or errors produced by the spawned process may not
be included in the metrics for a called backend or in the metrics for the business
processs frontend.
If the spawned process executes and runs to completion while the main business
process is running, the metrics and errors for the spawned process can be included in
business processs frontend.
Disabling the association of multiple backends with a frontend
By default, the com.wily.soaextension.tibcobw.mbbs.enabled property is set to true to
enable calls to multiple backend systems running on different threads to be associated
with the frontend that started a transaction. If you want to disable this feature, you can
set the com.wily.soaextension.tibcobw.mbbs.enabled property to false.


If you set this property to false, only the backend calls that are executed using the same
thread as the frontend are collected under the Called Backends node. Because it is
common for TIBCO BusinessWorks to use multiple threads for processing, you should
only set this property to false if you are not interested in associating performance
metrics and errors with their corresponding frontends.
Adding a custom TIBCO BusinessWorks backend
If you want to add a custom backend and associate the custom backend with a relevant
frontend, you must mark the custom backend by defining a custom backend tracer, then
define a custom calledbackend tracer and calledbackend error tracer for the agent. For
example if you define the following backend tracer:
SetTracerClassMapping: <CustomBackendTracer>
com.wily.introscope.agent.trace.BackendTracer
com.wily.introscope.probebuilder.validate.ResourceNameValidator
SetTracerParameter: <CustomBackendTracer> nameformatter <CustomNameFormatter>

TraceOneMethodWithParametersIfFlagged: <CustomTracinFlag> <method>
<CustomBackendTracer> "Metric Path"
You can then define the CalledBackendTracer and CalledBackendErrorTracer as follows:
SetTracerClassMapping: <CustomCalledBackendTracer>
com.wily.soaextension.tibcobw.multithread.blame.CalledBackendTracer
SetTracerParameter: <CustomCalledBackendTracer> nameformatter
<CustomNameFormatter>

SetTracerClassMapping: <CustomCalledBackendErrorTracer>
com.wily.soaextension.tibcobw.multithread.blame.CalledBackendErrorTracer
com.wily.introscope.probebuilder.validate.MetricNameValidator
SetTracerParameter: <CustomCalledBackendErrorTracer> nameformatter
<CustomNameFormatter>

CustomCalledBackendTracer "Metric Path"
CustomCalledBackendErrorTracer "Metric Path:Errors Per Interval"
Note: For more information about configuring custom tracers, defining name
formatters, and marking custom frontend and backends, see the CA APM Java Agent
Implementation Guide or the CA APM .NET Agent Implementation Guide.
Customizing metric aging and removal


Customizing metric aging and removal
Metric aging periodically removes dead metrics from the agents memory cache. A dead
metric is a metric that has no new data reported in a given amount of time. This helps
the agent improve performance and avoid collecting more metrics than the system can
handle.
If you have long-running transactions or business processes, however, you may want to
avoid metric aging for some metrics. For example, if you have business processes that
run for more than 12 hours, you can avoid metric aging for Concurrent Invocations of
business processes using a configuration property similar to the following:
introscope.agent.metricAging.metricExclude.ignore.2=Tibco\|Processes\|*.*:Concurr
ent Invocations
You can also use other agent properties to customize metric aging. For example, you can
set to properties to customize how long it takes before a metric becomes a candidate
for removal or the number of metrics to check at each interval.
Note: For more information about metric aging and configuring agent properties, see
the CA APM Java Agent Implementation Guide or the CA APM .NET Agent
Implementation Guide.
To exclude a TIBCO BusinessWorks metric from metric aging
1. Navigate to <Agent_Home>/core/config directory
3. Locate the Agent Metric Aging section and uncomment the following property:
introscope.agent.metricAging.metricExclude.ignore.2=Tibco\|Processes\|*.*:Con
current Invocations
Excluding Concurrent Invocations from metric aging is recommended if you have
business processes that run for more than 12 hours.
Configuring correlated tracing for TIBCO BusinessWorks
Cross-process transaction tracing requires the agent to insert a correlation identifier
that can be passed from one process to another. The agent can insert this correlation
identifier into either a SOAP or HTTP header. By default, the SOA extension for TIBCO
BusinessWorks is configured to support the passing of correlation information in both
SOAP and HTTP headers. For more information about how correlation information is
used to enable cross-process transaction tracing, see Understanding how segments of a
transaction are linked (see page 90). For more information about configuring properties
for correlated tracing, see Configuring correlated tracing (see page 105).


Chapter 9: Monitoring TIBCO Enterprise
Message Service

TIBCO Enterprise Message Service provides a key component of the SOA infrastructure
by enabling synchronous and asynchronous communications between systems
throughout the enterprise. The SOA extension for TIBCO Enterprise Message Service
(EMS) enables you to monitor many key elements of the TIBCO EMS server, including
queues, topics, and advanced components such as bridges, multicast channels, and
routes.
This section describes the dashboards and metrics you can use to monitor and analyze
the health and operation of the TIBCO EMS environment.
About TIBCO Enterprise Message Service (see page 169)
How to Install the SOA Extension for TIBCO EMS (see page 170)
Run the Standalone Agent Installer (see page 171)
Prepare the TIBCO EMS Server for Monitoring (see page 172)
Configuring the TIBCO EMSMonitor agent (see page 173)
Configuring filters for selective monitoring (see page 176)
Defining a monitoring level (see page 178)
Creating encrypted passwords (see page 182)
Connecting to TIBCO EMS server instances using SSL (see page 183)
Starting the EMSMonitor agent (see page 185)
Enable the Enterprise Manager Extension (see page 186)
Use Dashboards to Monitor TIBCO EMS (see page 187)
Understanding and viewing TIBCO EMS metrics (see page 189)
Viewing default TIBCO EMS metric groupings (see page 212)
Viewing default TIBCO EMS alerts (see page 213)
Summary of agent configuration properties (see page 214)
About TIBCO Enterprise Message Service
TIBCO Enterprise Message Service is a standards-based messaging layer that can serve
as the backbone of the service-oriented architecture by providing JMS-compliant
communications across a wide range of platforms and application technologies.
Because the reliable and secure delivery of messages is a critical part of delivering
business services and completing business transactions, the SOA extension for TIBCO
EMS provides a separate agent for monitoring key components and performance
metrics for TIBCO Enterprise Message Service.
How to Install the SOA Extension for TIBCO EMS


The agent used to monitor TIBCO Enterprise Message Service is a standalone agent,
rather than an extension to the core Java or .NET agent. Instead of instrumenting Java
classes, the agent, EMSMonitor, uses TIBCO EMS Admin API to collect performance
information for TIBCO EMS components, then reports this information to the Enterprise
Manager.
Because the EMSMonitor agent is a standalone agent, it is distributed as a separate
software package and requires its own IntroscopeAgent.profile and unique configuration
steps. For example, you must configure connection information for the EMS servers you
want to monitor and add filters to customize the components for which you want to
collect metrics.
After you configure the appropriate agent properties, you can monitor local and remote
TIBCO EMS components using the EMSMonitor agent.
The EMSMonitor agent is not dependent on the core agent. You can install and
configure the EMSMonitor agent independent of any other CA Introscope components
on one or more computers running TIBCO Enterprise Message Service.
Adding the SOA extension for TIBCO EMS involves the following high-level steps:
1. Verify that you have a supported version of TIBCO Enterprise Message Service
installed.
2. Verify that you have the Enterprise Manager and Workstation installed in your
environment. Verify that you have connection information for the Enterprise
Manager to which the EMSMonitor agent will send data.
3. Run the Standalone agent installer (see page 171) or use a response file to add the
required agent files to your environment.
4. Prepare the EMS server for monitoring (see page 172).
5. Configure the TIBCO EMSMonitor agent (see page 173) profile to define connection
and monitoring properties.
6. Enable the Enterprise Manager extension (see page 186) for TIBCO BusinessWorks.
Run the Standalone Agent Installer


The Standalone agent installer enables you to install standalone agents that do not rely
on the core Java or .NET agent. If you want to enable monitoring for TIBCO Enterprise
Message Service, you can use the Standalone agent installer to add the agent-related
files to your environment and configure the agents connection to the Enterprise
Manager. The Standalone agent installer extracts the required files and places them in
the proper location for you to modify as needed to complete the agent configuration.
To run the Standalone agent installer for monitoring TIBCO EMS
1. Start the appropriate Standalone agent installer for your operating environment.
2. On the Introduction page, click Next.
3. Select the monitoring packages you want to install, then click Next. For example,
select the SOA Extension For TIBCO Enterprise Message Service option to enable
monitoring for TIBCO EMS.
4. For the installation directory, click Next to accept the default location, or click
Browse to specify a different location.
5. For the Enterprise Manager connection settings, specify the Enterprise Manager
host name and port number for the agent to send data to, then click Next.
6. Review the summary of your settings, then click Install to begin the installation.
7. When the installation completes, click Done to close the Standalone agent installer.
Use a Response File for Silent Installation
If you do not want to run the Standalone agent installer interactively, you can edit the
standalone sample response file to install agent files. This method lets you enable the
SOA extension for TIBCO EMS in silent mode.
Follow these steps:
1. Open the SampleResponseFile.StandaloneAgentPP.txt file, located in the same
directory as the Standalone agent installer.
2. Edit the SampleResponseFile.StandaloneAgentPP.txt file to set the
shouldInstallTibcoEMS property to true to add the SOA extension for TIBCO
Enterprise Message Service to the agent. For example:
shouldInstallTibcoEMS=true
3. Save the SampleResponseFile.StandaloneAgentPP.txt file.
Java Agent Implementation Guide or the CA APM.NET Agent Implementation Guide.
Prepare the TIBCO EMS Server for Monitoring


Manually Extract an Installation Archive
If you do not have access to the Standalone agent installer or the standalone response
file, you may be able to download a standalone installation archive for your operating
environment. You can download CA APM products from the CA APM software download
area on CA Support. After you download, you can manually extract files from the archive
using the appropriate command for your operating environment. For example, use the
tar command on UNIX computers:
tar -xvf IntroscopeStandaloneAgentPPInstaller<version>unix.tar
r
Prepare the TIBCO EMS Server for Monitoring
Before you can monitor the TIBCO Enterprise Message Service, you must prepare a user
account for the EMSMonitor agent to use and verify that the libraries required for
monitoring are available locally.
Follow these steps:
1. Log in to EMS server using an account that has change-admin-acl and change-user
privileges. For example, log on using the admin account.
2. Identify or create a user account with view-all permissions for the EMSMonitor
agent. For example, to create a new user to run the EMSMonitor agent, run the
following commands in the EMS Administration Tool:
create user wilyemsuser
grant admin wilyemsuser view-all
3. Verify the following TIBCO EMS libraries are available in the
<TIBCO_EMS_HOME>/lib directory:
jms.jar
tibjms.jar
tibjmsadmin.jar
If you want to monitor remote server instances, the computer where the
EMSMonitor agent runs should be configured as an EMS client. Typically, this means
the jms.jar, tibjms.jar, and tibjmsadmin.jar files are available and have been added
to the classpath on the same computer as the EMSMonitor agent.
Note: For information about setting up an EMS client application and adding these
files to the classpath, see the TIBCO Enterprise Message Service Users Guide.
Valid for EMS version 5.x at a minimum: If the agent must connect to the EMS
server using Secure Socket Layer (SSL) connections, the following additional
libraries must be available on the local computer for EMS, version 5.x at a
minimum:
tibcrypt.jar
slf4j-api-1.4.2.jar
slf4j-simple-1.4.2.jar
Configuring the TIBCO EMSMonitor agent


Valid for EMS server version 4.4.x: Only the tibcrypt.jar library is required.
Note: For more information about configuring SSL communication for EMS, see the
TIBCO Enterprise Message Service Users Guide.
Valid for EMS server version 4.4.x and 5.x: If you want to monitor an environment
that includes EMS 4.4.x and 5.x, verify that all of the required .jar files on the local
computer are the most recent .jar files available. For example, if the environment
includes EMS 4.4.x and 5.x, verify that the EMSMonitor agent uses the 5.x .jar files.
After running the Standalone agent installer, you should see the TibcoEMSMonitor
directory. The TibcoEMSMonitor directory provides the following files and directories
for monitoring TIBCO Enterprise Message Service:
ext directory
Contains the Supportability-Agent.jar file. The Supportability-Agent.jar file is an
extension that records system properties, configuration files, and other information
in log files that can be delivered to CA Support if you need EMSMonitor agent
support.
lib directory
Contains the required EMSMonitor agent libraries packaged as .jar files (Agent.jar
and jline-0.9.9.jar).
properties directory
Contains the IntroscopeAgent.profile, TibcoEMSMonitor.properties, and
MonitoringLevel.xml files.
You use the IntroscopeAgent.profile to configure the connection to the
Enterprise Manager.
You use the TibcoEMSMonitor.properties file to configure parameters for
connecting to local and remote TIBCO EMS server instances and customize the
monitoring level and the components you want to collect metrics for.
You use the MonitoringLevel.xml file to customize the metrics that make up the
minimum, recommended, and full monitoring level sets.
EMSMonitor.jar file
Provides the classes the agent uses to monitor EMS server instances.
emsPwdEncryptor file
Provides a password encryption script (emsPwdEncryptor.bat or
emsPwdEncryptor.sh) that enables you to encrypt the EMS user password and SSL
client certificate password for connecting to the EMS server.


EMSMonitor file
Provides the startup script (EMSMonitor.bat or EMSMonitor.sh) to run the
EMSMonitor agent when you are ready to start monitoring EMS server instances.
On UNIX platforms, you can use the EMSMonitor.sh script to start, stop, restart, or
check the status of the EMSMonitor agent. On Windows, you can use
EMSMonitor.bat or a Windows service to start the agent and stop the EMSMonitor
agent.
With the files in the TibcoEMSMonitor directory, you can configure the EMSMonitor
agent connection properties, monitoring properties, secure communication properties.
Configuring basic connection properties
The EMSMonitor agent reports data from the TIBCO EMS server to an Enterprise
Manager. To enable the collection and reporting of metrics, you must specify
connection information for the Enterprise Manager the EMSMonitor agent reports to
and identify the list of servers that the agent collects data from.
To configure the EMSMonitor agent connection properties:
1. Open the IntroscopeAgent.profile file in a text editor to specify the Enterprise
Manager connection parameters. For example:
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=mercury
introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT=5001
2. Open the TibcoEMSMonitor.properties file in a text editor and set the
ems.server.list property to the names of EMS server instances you want to monitor.
For example:
ems.server.list = tibco_ems_srv01, tibco_ems_srv02
You can use any names you choose in this list. You are not required to match the
actual names of the server instances you are monitoring. The names in the list must
match the server instance names you use to define additional properties, however.
For example, if you have two server instances named NewYork, you can use aliases
newyork1 and newyork2 in ems.server.list property, then define the rest of the
properties for these server instances using the aliases. For example:
ems.server.list = newyork1, newyork2
newyork1.host = catsmcn01
newyork1.port = 6001
The URL for each instance is then appended to the server instance name displayed
in the Investigator tree, enabling you to monitor and uniquely identify both
instances.


3. Configure the host name and port for connecting to each server instance specified
in the ems.server.list property. For example:
tibco_ems_srv01.host=localhost
tibco_ems_srv01.port=7222

tibco_ems_srv02.host=vespa
tibco_ems_srv02.port=7222
4. Run the emsPwdEncryptor utility to generate encrypted passwords for the user
accounts you want to use to connect to the EMS server.
For information about creating or selecting a user account for connecting to the
EMS server, see Preparing the EMS server for monitoring (see page 172). For
information about using the emsPwdEncryptor utility, see Creating encrypted
passwords (see page 182).
Configuring polling intervals for the server
The EMSMonitor agent polls each server instance at regular intervals to retrieve
up-to-date status and configuration information. You can control the frequency of these
queries using configuration properties.
To configure how frequently the EMSMonitor agent queries the server:
1. Configure the interval for polling each server instance to collect status-related
metrics.
The interval you specify controls how frequently the EMS server instance is queried
for status information. For example, to query the tibco_ems_srv01 instance every
60 seconds and the tibco_ems_srv02 instance every 120 seconds, you would set the
following properties:
tibco_ems_srv01.delaytime=60
tibco_ems_srv02.delaytime=120
If you dont specify an interval, metrics are refreshed every 60 seconds by default.
2. Configure the interval for refreshing static configuration-related metrics for each
server instance.
Because configuration properties do not change often, the EMSMonitor agent
collects the values once at startup, then polls for the configuration metrics after the
value set by the <ServerInstance>.report.static.freq property multiplied by the
<ServerInstance>.delaytime property. If the <ServerInstance>.delaytime property is
set to 60 seconds and the <ServerInstance>.report.static.freq property is set to 20,
static metrics are checked every 1200 seconds or 20 minutes.
For example:
tibco_ems_srv01.report.static.freq=20
tibco_ems_srv02.report.static.freq=20
If you set this property to 0, the EMSMonitor agent reports all configuration metrics
at startup but does not report any changes made to them thereafter.
Configuring filters for selective monitoring


By default, the EMSMonitor agent collects metrics for all queues and topics on the
server instances specified in the ems.server.list property. If you want to selectively
monitor queues and topics, you can configure filters to specify the queues and topics
you are interested in. You can also configure filters to enable monitoring of advanced
components, such as bridges, multicast channels, and routes, and use regular
expressions to identify the subset of those advanced components for which you want to
collect metrics.
Configuring filters for queues and topics
EMS Server supports both Static and Dynamic queues and topics. Static queues and
topics are created and managed by the EMS administrator and remain on the server
even if they are not being used. Dynamic queues and topics, including temporary
dynamic queues, are created and destroyed by EMS clients when needed, and only
remain on the server for short periods of time.
By default, the EMSMonitor agent only monitors static queues and topics to prevent
unnecessary overhead. If you want to monitor dynamic queues or dynamic topics,
however, you can define filters to include them. You can also configure filters using
regular expressions to identify specific queues and topics for which you want to collect
metrics.
To enable monitoring for dynamic queues or topics:
1. Open the TibcoEMSMonitor.properties file in a text editor.
2. Review the names of EMS server instances you are monitoring.
3. Configure the include filter for dynamic queues or dynamic topics for each server
instance where you want to monitor dynamic objects. For example, to enable
monitoring of dynamic queues and dynamic topics on the EMS server instance
tibco_ems_srv01:
tibco_ems_srv01.queue.filter.include.dynamic=true
tibco_ems_srv01.topic.filter.include.dynamic=true
To monitor specific queues or topics using regular expressions:
3. Configure queue and topic filters using regular expressions for each server instance,
if desired. For example:
tibco_ems_srv01.queue.filter.includeonly.regex=sample.*
tibco_ems_srv01.topic.filter.includeonly.regex=sample.*

tibco_ems_srv02.queue.filter.includeonly.regex=test.*
tibco_ems_srv02.topic.filter.includeonly.regex=test.*


If you dont specify a filter, metrics are collected for all queues and topics, including
dynamic and temporary queues and topics if you have configured properties to include
them. If you specify a regular expression for the queues to include, only the queues
matching that regular expression are monitored. If you specify a regular expression for
the topics to include, only the topics matching that regular expression are monitored.
Defining the advanced components to include
By default, the EMSMonitor agent does not report metrics for bridges, channels, or
routes. To enable monitoring for these advanced components, you need to specify an
include filter in the TibcoEMSMonitor.properties file. After you enable monitoring for an
advanced component you want to include, you can use a regular expression filter to
further refine the list of advanced components for which you want to collect metrics.
To enable monitoring of bridges, channels, and routes:
3. Configure an include filter for each advanced component on each server instance
that you want to monitor. For example, if you want to monitor bridges, channels
and routes on the server instance tibco_ems_srv1, add the following include filters
to the file:
tibco_ems_srv1.monitor.bridges=true
tibco_ems_srv1.monitor.channels=true
tibco_ems_srv1.monitor.routes=true
Defining regular expression filters for advanced components
If you have defined an include filter to enable monitoring of bridges, channels, or
routes, you can also configure a regular expression filter to identify the specific bridges,
channels, or routes for which you want to collect metrics.
If you define an include filter for a component but no regular expression filter, then all
components of that type are monitored. For example, if you enable monitoring for
bridges and do not add a regular expression filter for bridges, then metrics are collected
for all bridges. If you do not define an include filter for a component, any regular
expression filter for that component is ignored.
To define a regular expression filter for bridges, channels, or routes:
Defining a monitoring level


3. Configure a regular expression filter for each advanced component on each server
instance that you want to monitor. For example, if you have enabled monitoring for
bridges, channels, and routes on the server instance tibco_ems_srv1, add the
following include filters to the file:
<ServerInstance>.bridge.filter.includeonly.regex
<ServerInstance>.channel.filter.includeonly.regex
<ServerInstance>.route.filter.includeonly.regex
For each filter, use a regular expression to identify the subset of components you
want to monitor. For example:
tibco_ems_srv1.bridge.filter.includeonly.regex=new.*
tibco_ems_srv1.channel.filter.includeonly.regex=.*bulletin
tibco_ems_srv1.route.filter.includeonly.regex=.*
The regular expression filters only apply for advanced components for which you
have configured an include filter set to true.
Replacement of Special Characters in EMS Names
TIBCO Enterprise Message Service allows you to include special characters, such as the
colon (:) or pipe (|) character, in all component name. However, the colon (:) and pipe
(|) characters are reserved characters in CA Introscope and are automatically replaced
with the underscore character (_) in component names. For example, if you have a
queue named Queue:WorkInProgress, the EMS agent replaces the colon character with
an underscore and reports metrics for this queue under a node named
Queue_WorkInProgress.
If you have queues named similarly, for example, Queue:WorkInProgress and
Queue|WorkInProgress, replacing the special characters results in a duplicate name.
Because the queues have the same name after replacing the colon and pipe characters,
the Investigator displays only one set of metrics for a queue named
Queue_WorkInProgress.
This limitation for special characters applies to all EMS components. If you are defining
filters to configure monitoring, consider how the replacement of the colon or pipe
characters affects component names.
The EMSMonitor agent can collect a large number of metrics for each TIBCO EMS server
instance. To control the number of metrics collected and reported to the Enterprise
Manager, you can define a monitoring level for each TIBCO EMS server instance. For
each server instance, you can define separate monitoring levels for server, queue, and
topic metrics.


Using the default monitoring level definitions
To control the number of metrics for each EMS server and its components, the
EMSMonitor agent supports the following monitoring levels for server metrics, queue
metrics, and topic metrics:
Minimum
Collect only the metrics that are essential for monitoring the server, queue, or
topic. By default, the metrics defined for the minimum monitoring level are
required to display information in the preconfigured dashboards and Overview
tabs.
You use this monitoring level if you want to minimize the overhead for server,
queue, or topic metrics on EMS server instances.
Recommended
Collect all of the minimum level metrics plus additional metrics, such as fault
tolerance metrics for servers, inbound and outbound message statistics for queues,
or multicast-related metrics for topics.
You use this monitoring level if you can accept a small increase in overhead in
exchange for better visibility into the performance and operations for servers,
queues, or topics.
Full
Collect and report all available metrics, including the minimum and recommended
metrics, for the server, queue, or topic.
You use this monitoring level if you want deep visibility into the performance and
operations of a server, queue, or topic, or if you are not concerned about
performance overhead.
The monitoring level specifies the set of metrics you want to collect for servers, queues,
or topics on each server instance and can be set individually for each component on
each server instance.
For example to collect all server metrics, minimum queue metrics, and recommended
topic metrics on the server instance tibco_ems_server01, you can set the monitoring
levels for these components using the following properties:
tibco_ems_server01.monitoring.level = full
tibco_ems_server01.queue.monitoring.level = minimum
tibco_ems_server01.topic.monitoring.level = recommended
You can then configure these properties for the server, queue, and topic monitoring
levels on other server instances. For example:
tibco_ems_server02.monitoring.level = minimum
tibco_ems_server02.queue.monitoring.level = recommended
tibco_ems_server02.topic.monitoring.level = recommended


To set the monitoring levels for TIBCO EMS server instances:
3. Configure the monitoring level property, <ServerInstance>.monitoring.level, for
each server instance. For example, to set the monitoring level to minimum for the
EMS server instance tibco_ems_srv01 and to full for the EMS server instance
tibco_ems_srv02:
tibco_ems_srv01.monitoring.level=minimum
tibco_ems_srv02.monitoring.level=full
To set the monitoring levels for TIBCO EMS queues:
3. Configure the monitoring level property for queues,
<ServerInstance>.queue.monitoring.level, for each server instance. For example, to
set the monitoring level to minimum for queues on the EMS server instance
tibco_ems_srv01 and to recommended for queues on the EMS server instance
tibco_ems_srv02:
tibco_ems_srv01.queue.monitoring.level=minimum
tibco_ems_srv02.queue.monitoring.level=recommended
The monitoring level you set applies to all static and dynamic queues on the specified
server instance.
To set the monitoring levels for TIBCO EMS topics:
3. Configure the monitoring level property for topics,
<ServerInstance>.topic.monitoring.level, for each server instance. For example, to
set the monitoring level to full for topics on the EMS server instance
tibco_ems_srv01 and to recommended for topics on the EMS server instance
tibco_ems_srv02:
tibco_ems_srv01.topic.monitoring.level=full
tibco_ems_srv02.topic.monitoring.level=recommended
The monitoring level you set applies to all static and dynamic topics on the specified
server instance.
Modifying the default monitoring level definitions
If you want to change the metrics associated with the minimum, recommended, or full
monitoring level, you can do so by editing the MonitoringLevel.xml file.


The MonitoringLevel.xml file lists all of the metrics available for EMS server instances,
queues, and topics. The file also defines the monitoring level for each of the metrics.
You can change the monitoring level in this file to change which metrics are collected
when you set the monitoring level to minimum, recommended, or full for servers,
queues, and topics in the TibcoEMSMonitor.properties file.
You cannot use the file to configure monitoring levels for the metrics associated with
bridges, channels, or routes. You can use filters to customize monitoring for bridges,
channels, or routes. For more information about using filters to customize monitoring
for bridges, channels, and routes, see Configuring filters for selective monitoring (see
page 176).
To change the monitoring level for individual metrics:
1. Open the MonitoringLevel.xml file in a text editor.
2. Locate the <MetricGroup> section for the component for which you want to modify
metric settings. For example, if you want to change the monitoring level for Server
metrics, find the <MetricGroup name="Server"> section.
All of the metrics available for monitoring EMS server instances are listed with the
metrics monitoring level defined as an attribute for each metric name. For
example, Queue Count and Topic Count metrics are collected when you set the
monitoring level to minimum by default:
<Metric level="Minimum">Queue Count</Metric>
<Metric level="Minimum">Topic Count</Metric>
3. Locate the metric for which you want to modify the monitoring level and modify
the level attribute for that metric to the new monitoring level.
For example, to change the monitoring level for Queue Count and Topic Count from
minimum to recommended:
<Metric level="Recommended">Queue Count</Metric>
<Metric level="Recommended">Topic Count</Metric>
If you change the monitoring level for any metric from minimum to recommended
or full, the EMSMonitor agent records a warning in its log file and displays a warning
message. The agent does not issue a warning for other types of changes.
You should also keep in mind that changing the minimum set of metrics may
prevent some data from being displayed or included in graphs and dashboards.
Before changing a metric from minimum to recommended or full, you should check
whether it is used in any preconfigured or custom views or dashboards.
4. Restart the EMSMonitor agent with the startup script to have changes to the
monitoring level take effect.
After you make this change and restart the agent, the Queue Count and Topic Count
metrics are only collected for the server instances where the monitoring level is set to
recommended.
Creating encrypted passwords


The <MetricGroup name> and <Metric level> attributes are not case-sensitive. Metric
names, however, are case-sensitive in the MonitoringLevel.xml file.
The agent uses the MonitoringLevel.xml file to determine the metrics for each
monitoring level. If a metric is not listed or is deleted from this file, the agent cannot
collect or report information for that metric.
If the MonitoringLevel.xml file is corrupted or the EMSMonitor agent is unable to read
the file, the agent logs an error message and reports the metrics it discovered at
startup.
Creating encrypted passwords
For the EMSMonitor agent to connect to the EMS servers you specify, it must be able to
present valid user credentials for authentication. If you use Secure Socket Layer (SSL)
connections between clients and EMS servers and the agent connects to any EMS server
that is configured to verify the clients security certificate, the agent must also be able to
present a signed certificate for validation.
To encrypt and store a user password or client certificate path and password:
1. Open the emsPwdEncryptor script in a text editor and set the JAVA_HOME
environment variable to the appropriate directory. For example:
set JAVA_HOME=C:\Java\jdk1.5.0_10
2. Run the emsPwdEncryptor script.
For each EMS server instance you have listed for the ems.server.list property in the
TibcoEMSMonitor.properties file, you are prompted to specify a user name and
password.
To create an encrypted password for a server instance, enter y, then enter the
EMS user name and password.
To skip the creation of an encrypted password for a server instance, enter n.
When you are finished entering the user name and password to use for connecting
to each instance, the user name and an encrypted version of the password are
written to the TibcoEMSMonitor.properties file. The EMS server must be able to
authenticate the user name and password specified for the connection to succeed.
3. Enter y or n when prompted to configure Secure Socket Layer (SSL) properties.
Connecting to TIBCO EMS server instances using SSL


If you are using SSL connections and any EMS server is configured to verify the
clients security certificate, enter y. You can then specify the client certificate path
and a password for reading the client certificate.
When you are finished entering the information, the client.identity and an
encrypted version of the ssl.password properties are written to the
TibcoEMSMonitor.properties file for the EMSMonitor agent:
The client.identity property specifies the path to the certificate the EMS server
can use to verify the identity of the EMSMonitor agent. For example:
client.identity=C:/Tibco/TibcoEMSMonitor/certs/client_identity.p12
The ssl.password property specifies the encrypted password for the client
security certificate.
If TIBCO EMS is configured to use the Secure Socket Layer (SSL) protocol for network
connections, the EMSMonitor agent must be configured to connect to the TIBCO EMS
server using SSL. Configuring the EMSMonitor agent to use SSL involves setting several
properties in the TibcoEMSMonitor.properties file. Some of the properties must be set
for each EMS server instance separately. Other properties can be set once for all EMS
server instances.
To define SSL connection information for TIBCO EMS server instances:
3. Configure the <ServerInstance>.ssl.connection property to enable or disable
encrypted communication for each server instance. This property requires you to
specify the server instance name.
For example, to configure the agent to connect to the EMS server instance
tibco_ems_srv01 using SSL:
tibco_ems_srv01.ssl.connection=enable
4. Configure the <ServerInstance>.verify.host property to specify whether the
EMSMonitor agent must verify the EMS server's certificate.
This property requires you to specify the server instance name. For example, to
require verification when the agent connects to the EMS server instance
tibco_ems_srv01:
tibco_ems_srv01.verify.host=true
If you set this property to true, the agent verifies the EMS servers security
certificate against the list defined for the trusted.certificates property.


5. Configure the trusted.certificates property to specify a comma-separated list of
trusted certificates the EMSMonitor agent uses to verify the server's certificate. For
example:
trusted.certificates=C:/Tibco/wily/TibcoEMSMonitor/certs/tbx_root.cert.pem
This property is required if the verify.host property is set to true, and is applicable
for all EMS server instances that use SSL.
6. Configure the <ServerInstance>.verify.hostname property to specify whether the
agent should verify the Common Name (CN) field of the servers certificate.
tibco_ems_srv01.verify.hostname=true
If you set this property to true, the agent compares the name of the connected host
or the name specified in the <ServerInstance>.expected.name property to the value
of the Common Name (CN) field in the servers certificate. If the names do not
match, the agent rejects the connection.
If this property is set to false, the agent establishes SSL connection with the server,
but does not verify the servers name.
7. Configure the <ServerInstance>.expected.hostname property to specify the name
the EMSMonitor agent compares with the value of the Common Name (CN) field in
the servers certificate.
tibco_ems_srv01.expected.hostname=tbxserver
8. Configure the cipher.suites property to specify a comma-separated list of cipher
suites the EMSMonitor agent can use to encrypt communication with SSL-enabled
EMS servers.
The cipher.suites property optional. The EMSMonitor agent can use any encryption
package supported by the EMS servers you are monitoring. If you set this property,
it applies for all SSL-enabled EMS server instances.
You can use standard algorithm names or OpenSSL names for the cipher suites. For
example, you can set the cipher.suites property to either RC4-MD5 if you want to
use the OpenSSL name or SSL_RSA_WITH_RC4_128_MD if you want to use the
standard name to refer to the same cipher suite.
For example:
cipher.suites=RC4-MD5,RC4-SHA
9. Run the emsPwdEncryptor utility to set the path and encrypted password for the
client certificate if you have EMS servers configured to verify the clients security
certificate.
For information about using the emsPwdEncryptor utility, see Creating encrypted
passwords (see page 182).
If the EMS server is not required to verify the client certificate, you can skip this
step.
Starting the EMSMonitor agent


Starting the EMSMonitor agent
After you have configured the connection properties, you can configure additional
properties or start the agent to begin monitoring EMS server instances. If you want to
use the default monitoring properties, you can:
start the agent from the startup script
configure the agent to run as a Windows service
Start EMSMonitor With a Startup Script
On UNIX computers, you use the EMSMonitor.sh script to start and stop the
EMSMonitor agent. On Windows, you can use the EMSMonitor.bat script or you can
configure the EMSMonitor agent to run as a Windows service.
Follow these steps:
1. Open the EMSMonitor startup script in a text editor.
2. Set the TIBCO_EMS_HOME environment variable to the TIBCO Enterprise Message
Service installation directory. For example:
set TIBCO_EMS_HOME=C:\tibco\ems\5.1
3. Set the JAVA_HOME environment variable to the appropriate directory. For
example:
set JAVA_HOME=C:\Java\jdk1.5.0_10
Valid for JRE version 1.5 at a minimum: Monitoring TIBCO Enterprise Message
Service requires JRE version 1.5 at a minimum.
4. Run the EMSMonitor script. If you run EMSMonitor on a UNIX computer, the script
supports the following command line parameters:
EMSMonitor.sh [start|stop|restart|status]
To start a new instance of an agent, use the start option. For example, on UNIX
computers:
./EMSMonitor.sh start


Running the EMSMonitor agent as a Windows service
If you install the EMSMonitor agent on Windows, you have the option of running the
agent as a Windows service. Running the agent as a Windows service provides the
following advantages:
The agent service can automatically start or stop when the host computer starts up
or shuts down.
The agent can run as background process rather than in a console, making it less
vulnerable to tampering and unauthorized access.
The agent can continue running even if the user logs off the current session.
To run the EMSMonitor agent as a Windows service:
1. Install and configure the EMS Server, IntroscopeAgent.profile, and
TibcoEMSMonitor.properties file as described in the previous sections.
2. Verify the JAVA_HOME environment variable is set to a proper JVM, and is
configured as System variable not as User variable.
3. Open the TibcoEMSMonitor\Windows Service\jsw-3.2.3\conf\ wrapper.conf file in a
text editor.
4. Set the TIBCO_EMS_HOME environment variable to the TIBCO Enterprise Message
Service installation directory. For example:
set TIBCO_EMS_HOME=C:\tibco\ems\5.1
5. Save the wrapper.conf file.
6. Open a Command Window and run TibcoEMSMonitor\Windows Service\
RegisterEMSMonitorAgentService.bat file to register the EMSMonitor Agent as a
Windows service.
If you later want to remove the EMSMonitor Agent as a registered service, you can
run the DeRegisterEMSMonitorAgentService.bat file.
CA APM for TIBCO Enterprise Message Service files are installed by default in the
APM for TIBCO Enterprise Message Service, you need to copy or move the Enterprise
Manager files from the <EM_Home>/examples directory to the proper location in the
Enterprise Manager home directory.
Note: CA APM for SOA must be enabled on the Enterprise Manager before you can use
CA APM for TIBCO Enterprise Message Service. For information about enabling CA APM
for SOA Enterprise Manager extensions, see Enabling extensions on the Enterprise
Manager (see page 37).
Use Dashboards to Monitor TIBCO EMS


Follow these steps:
1. Verify the CA APM for TIBCO Enterprise Message Service directory,
SOAExtensionForTibcoEMS, is in the <EM_Home>/examples directory, then copy
the files from the <EM_Home>/examples/SOAExtensionForTibcoEMS directory to
the corresponding location in the Enterprise Manager directory structure. For
example, copy the files from the
<EM_Home>/examples/SOAExtensionForTibcoEMS/ext directory to the
2. Remove the CA APM for TIBCO Enterprise Message Service Management Module,
TibcoEMSManagementModule.jar, from the <EM_Home>/config/modules directory
if the Enterprise Manager is a Collector in a clustered environment.
to the SOA extension for TIBCO Enterprise Message Service.
The SOA extension for TIBCO Enterprise Message Service includes several preconfigured
dashboards that you can use to monitor the overall health of the EMS environment.
components of the Enterprise Message Service at-a-glance.
been crossed.
Drill-down into performance information to isolate and identify which Enterprise
Message Service components are experiencing delays or producing errors.
The preconfigured TIBCO Enterprise Message Service dashboards are packaged in the
Enterprise Manager extension for TIBCO Enterprise Message Service as part of the
TIBCO Enterprise Message Service Management Module
(TibcoEMSManagementModule.jar).


The TIBCO Enterprise Message Service Management Module provides the following
preconfigured dashboards for TIBCO Enterprise Message Service:
Tibco EMS - Overview
A top-level overview of the key activity for the Enterprise Message Service,
including alert indicators for the status of the connection between the EMS server
and the agent, the overall health of the EMS server, the maximum queue depth, the
maximum topic depth, overall health of routes and channels, and the percentage of
connections in use.
Tibco EMS - Servers
Summarized status for all EMS servers, including alert indicators for the status of
the EMS server and backup server, and the percentage of connections in use.
The dashboard also displays graphs summarizing the connection count, consumer
count, producer count, the overall inbound and outbound message rate, and the
pending message count.
Tibco EMS - Queues
Summarized status for all EMS queues, including alert indicators and graphs for the
inbound and outbound message rate for queues, an alert indicator for maximum
queue depth, and graphs for the pending message count and consumer count for
queues.
Tibco EMS - Topics
Summarized status for all EMS topics, including alerts and graphs for the inbound
and outbound message rate for topics, an alert indicator for maximum topic depth,
and graphs for the pending message count.
The dashboard also includes the total subscribers count, and the number of active
and durable subscribers.
Tibco EMS - Routes
Summarized status for all EMS routes, including alerts and graphs for the inbound
and outbound message rate for routes, an alert indicator for route status, and
graphs for the backlog count and backlog size (if applicable).
Tibco EMS - Channels
Summarized status for all EMS channels, including alert indicators for the overall
channel status, the channel message rate, and the backlog count, and graphs for
the message rate, byte rate, backlog count, and backlog size.
Follow these steps:
extension for TIBCO EMS is installed.
Understanding and viewing TIBCO EMS metrics


4. Select one of the TIBCO Enterprise Message Service dashboards from the
Dashboard drop-down list.
For example, select the Tibco EMS - Overview dashboard to see information about
the overall health of the overview of the TIBCO Enterprise Message Service
environment, including the connection status, the percentage of connections used,
and the maximum queue and topic depth.
5. Double-click a component tab to open that component's dashboard and see more
details about servers, queues, topics, routes, or channels. For example, double-click
the Servers tab to display the Tibco EMS - Servers dashboard.
The EMSMonitor agent can monitor local and remote EMS server instances and provide
data about their overall health under the Tibco EMS Servers > <host_name> >
<EMS_server_instance_name> node.
You can monitor the performance and health of TIBCO EMS components with metrics
for the following metric categories:
Bridges
Bridges enable you to route messages between destinations so that messages sent
to one destination are also delivered to all bridged destinations. You can create a
bridge from one destination to one or more destinations of the same or different
type. For example, you can create a bridge from a topic to a queue or from a queue
to a topic, or a bridge between one destination and multiple destinations.
Under the Bridges node, you can find metrics for individual target destinations
associated with each bridge you have defined.
Channels
Multicast messaging broadcasts messages to many consumers at once, rather than
sending copies of a message to each subscribing consumer individually.With
multicast messaging, the server sends messages over a multicast channel to
multicast-enabled topics. The channel determines the multicast port and multicast
group address to which the server sends messages.
Under the Channels node, you can find metrics for individual multicast channels.
Last Check
Under the Last Check node, you can find metrics about the connection between the
EMS server instance and the agent.


Queues
Queues are temporary storage objects that store messages waiting to be forwarded
to clients or to other queues in the Enterprise Message Service network.
Under the Queues node, you can find metrics for individual queues, such as the
number of messages delivered or in transit and the inbound or outbound rate for
each queue.
Routes
Routes are used to connect two TIBCO Enterprise Message Service servers as a
server pair. Each server in the pair forwards messages along the route to a
corresponding destination on the other server. Routes only forward the messages
for global topics that have the same name on both servers or for routed queues
with the same queue owner.
Under the Routes node, you can find metrics for individual routes defined between
servers, such as the number of messages in the route backlog or the inbound and
outbound rate for each route.
Server
The Server category provides metrics for the main runtime process of the
Enterprise Message Service. The EMS server process creates and manages the other
components that make up a messaging transaction.
Under the Server node, you can find metrics for the server process, such as the
number of connections, available memory, and the number of queues and topics
the server is managing.
Topics
Topics represent logical subjects on which a publisher can write messages and
subscribers can receive published messages. Unlike Queues, where only one copy of
message is stored and only one receiver can receive it, Topics are maintained by the
EMS server to publish a single copy of a message to multiple interested subscribers.
Under the Topics node, you can find metrics for individual topics, such as the
number of inbound, outbound, and pending messages for each topic.
To view and navigate TIBCO EMS metric summaries in the Investigator:
1. Expand the agent node and the Tibco Enterprise Message Service node, then click
Tibco EMS Servers to display the Overview tab, which lists all of the monitored
server instances with their current status.
2. Select a server instance to display the most critical status metrics for that server
instance in a graphical format on the Overview tab.
3. Click the Configuration tab to display configuration metrics for the selected server
instance.


4. Expand the server instance and click any sub-node to display summary or
configuration information about that metric category on tabs in the Viewer pane.
For example, select the Queues node then click the Temporary Queues tab to
display a summary of metrics for all temporary queues or the Dynamic Queues tab
to display a summary of metrics for all dynamic queues.
5. Expand any sub-node or select individual components, such as specific queues or
topics, to see more detailed information about those individual components and
the metrics associated with each.
To view and navigate TIBCO EMS metric nodes in the Investigator:
1. Expand the agent, then expand the Tibco EMS Servers node to display the host
names for the TIBCO EMS server instances you are monitoring.
2. Expand the individual server_name node corresponding to a hostname you defined
in TibcoEMSMonitor.properties file.
3. Expand the individual TIBCO EMS server instance_name node for a server instance
you specified in TibcoEMSMonitor.properties file to display sub-nodes for the
top-level TIBCO EMS metric categories. For example:



4. Expand a sub-node to display information about that metric category. For example,
click Queues > Static Queues > <queue_name> to view the Configuration or Status
metrics for the selected queue.
5. Expand sub-nodes further to see Configuration or Status metrics for the selected
queue. For example, expand the Undelivered Message Queue > <queue_name> >
Status node to view status metrics for the selected queue.
Metrics for Last Check
In addition to metrics about the performance and operation of the TIBCO EMS server
and its components, the EMSMonitor agent collects metrics about the connection
between each EMS server and the agent. The metrics under the Last Check node are
collected every 30 seconds. The frequency for these metrics is not controlled by the
delay time or static frequency configuration properties, and the metrics are collected for
all monitoring levels.
The following metrics are available to evaluate the status of the connection between
each EMS server and the EMSMonitor agent:
Agent - EMS Connection Status
Text string that indicates whether the EMSMonitor agent is currently connected to
the TIBCO EMS server.
A metric value of Connected indicates the connection exists. A value of Not
Connected indicates that the agent and the EMS server are disconnected.
Agent - EMS Connection Status Value
Numerical value that indicates whether the EMSMonitor agent is currently
connected to the TIBCO EMS server.
A metric value of zero (0) indicates the agent is connected to the EMS server. A
metric value of one (1) indicates the agent is not connected to the EMS server.
EMS Server Name
Name of EMS server being monitored.
Timestamp
Date and time at which the Last Check metrics were most recently collected. The
format for this metric is:
yyyy-MM-dd HH:mm:ss


Metrics for Queues
The following Configuration metrics are available for dynamic and static queues in
TIBCO EMS:
Bridged Queue
Indicates in a text string whether there are any bridged destinations for the queue:
A metric value of true indicates that bridged destinations exist for the queue.
A value of false indicates that no bridged destinations exist for the queue.
By default, this metric is only collected when you set the monitoring level to full.
Exclusive
Indicates in a text string whether the exclusive property is set for the queue:
A metric value of true indicates that the queue is configured as an exclusive
queue.
A value of false indicates that the queue is not configured as an exclusive
queue.
By default, this metric is collected when you set the monitoring level to minimum.
Expiration (Sec)
Indicates the maximum length of time before messages expire on the selected
queue. If the value of this metric is zero (0), messages do not expire.
If the server expiration property is set for a queue, the value of this property
overrides the JMSExpiration value that the message producer sets.
Failsafe
Indicates in a text string whether the queue is configured as a fail-safe destination:
A metric value of true indicates that the queue is configured as a fail-safe
destination.
A value of false indicates that the queue is not configured as a fail-safe
destination.
Note: This metric is only valid for EMS version 4.4.


Global
Indicates in a text string whether the queue is configured as a global queue for
routing messages from one server to another:
A metric value of true indicates that the queue is a global queue.
A value of false indicates that the queue is not a global queue.
By default, this metric is collected when you set the monitoring level to
recommended.
Is Route Connected
Indicates whether the route for the selected queue is currently connected. This
metric only appears if the selected queue is a routed queue.
recommended.
Maximum Flow Control Bytes
Indicates the maximum number of bytes used to enable flow control for this queue.
Maximum Messages
Indicates the maximum number of messages that the server can store as pending
messages for this queue.
By default, this metric is only collected when you set the monitoring level to
minimum.
Maximum Redelivery
Indicates the maximum number of times the server can attempt delivering a given
message from the selected queue to the queue receivers.
Overflow Policy
Indicates the overflow policy to use for the queue when it exceeds the maximum
message size or message number. The following overflow policy values are valid:
0Indicates the default overflow policy. If the maximum bytes or number of
messages is exceeded, the server rejects new messages and returns an error to
the message producer.
1Indicates the discardOld overflow policy. If the messages on the queue
exceed the maximum bytes or number of messages, the oldest messages are
discarded from the queue and an error is returned to the message producer.
2Indicates the rejectIncoming overflow policy. If the maximum bytes or
number of messages is exceeded, the server rejects new messages and returns
an error to the message producer.


Prefetch Count
Indicates the maximum number of messages a message consumer can fetch from
the EMS server.
recommended.
Route Name
Identifies the route name that is associated with the queue. This metric is only
displayed if the selected queue is a routed queue.
recommended.
Routed Queue
Indicates in a text string whether the selected queue is a routed queue:
A metric value of true indicates the queue that is a routed queue.
A value of false indicates that the queue is not a routed queue.
recommended.
Secure
Indicates in a text string whether the queue is configured to authenticate incoming
connections:
A metric value of true indicates that incoming connections are authenticated.
A value of false indicates that incoming connections are not authenticated.
Sender Name
Indicates in a text string whether the sender_name property is configured for the
queue:
A metric value of true indicates the sender_name property is set.
A value of false indicates the sender_name property is not set.
Sender Name Enforced
Indicates in a text string whether the sender_name_enforced property is configured
for the queue:
A metric value of true indicates the sender_name property is enforced.
A value of false indicates the sender_name property is not enforced.


Store Name
Identifies the store name where persistent messages are stored.
Note: This metric is valid for EMS version 5.x at a minimum.
The following Status metrics are available for dynamic and static queues in TIBCO EMS:
Delivered Message Count
Indicates the total number of messages that have been delivered and
acknowledged.
Inbound Byte Rate
Indicates the number of inbound bytes sent per second to the selected queue by
EMS clients and routed servers.
In Transit Message Count
Indicates the total number of messages that have been delivered to the queue
owner but have not yet been acknowledged.
Inbound Message Rate
Indicates the number of inbound messages that are sent per second to the selected
queue by EMS clients or routed servers.
Outbound Byte Rate
Indicates the number of outbound bytes sent per second to consumers on the
selected queue or routed to other servers.
Outbound Message Rate
Indicates the number of outbound messages that are sent per second to consumers
of the selected queue or routed to other servers.
Pending Message Count
Indicates the total number of pending messages currently in the selected queue.
This metric is equivalent to monitoring queue depth.


Pending Message Size
Indicates the total size in KB for all pending messages in the selected queue.
Receiver Count
Indicates the number of receivers for the selected queue.
Metrics for the Server
The following Configuration metrics are available for the TIBCO EMS server process:
Authorization Enabled
Indicates whether authorization is enabled for the server.
If this metric is True, other servers that actively connect to the server must
authenticate themselves by name and password.
Backup Server Name
Indicates the name of the server instance and host name of the computer
configured as a backup server for the selected server instance.
Client Heartbeat Server Interval (sec)
Indicates the number of seconds between heartbeat messages sent from the client
to the server.
Client Timeout Server Connection (sec)
Indicates the number of seconds clients wait for a heartbeat from the server before
terminating the connection to the server.
Fault Tolerant Activation Time (sec)
Indicates the number of seconds a backup server waits for a heartbeat message
before determining the active server has failed.


Fault Tolerant Reread
Indicates whether the backup server re-reads the configuration files, with the
exception of the main file, following a failover.
A metric value of true indicates the files are reread. A value of false indicates the
files are not reread.
recommended.
Fault Tolerant Heartbeat Interval (sec)
Indicates the number of seconds between heartbeat messages sent from the active
server to the backup server.
recommended.
Fault Tolerant Reconnect Timeout (sec)
Indicates the number of seconds a newly active server waits for clients to reconnect
after a failover.
recommended.
Fault Tolerant Server URL
Indicates the URL of the backup server.
recommended.
Flow Control Enabled
Indicates whether flow control is enabled for message producers and destinations
on the server.
A metric value of true indicates flow control is enabled. A value of false indicates
flow control is not enabled.
Maximum Log File Size
Indicates the maximum log file size in KB.
recommended.
Maximum Connections
Indicates the maximum number of connections to the EMS server.
If this metric is zero (0), there is no limit on the number of connections allowed.
recommended.


Maximum Message Memory
Indicates the maximum amount of memory, in bytes, that can be used to store
messages.
If this metric is zero (0), there is no limit on the size of memory that can be used for
messages.
recommended.
Maximum Statistics Memory
Indicates the maximum amount of memory, in bytes, that can be allocated to
collect detailed statistics.
Minimum Size Asynchronous Store file
Indicates the minimum size of the servers asynchronous store file.
The value of this metric may be in MB or GB, depending on the configuration of the
store file.
Minimum Size Store file
Indicates the minimum size of servers store file.
store file.
Minimum Size Synchronous Store file
Indicates the minimum size of the servers synchronous store file.
store file.


Multicast Enabled
Indicates whether the server has been enabled for multicast messaging.
A metric value of true indicates multicasting is enabled. A value of false indicates
multicasting is not enabled.
Because multicast messaging is not supported for EMS, version 4.4.x, this metric is
always false for EMS 4.4.x server instances.
Reserve Memory
Indicates the size of the reserve memory in KB.
recommended.
Routing Enabled
Indicates whether routing is enabled for the server.
A metric value of true indicates routing is enabled. A value of false indicates routing
is not enabled.
Server Heartbeat Client Interval (sec)
Indicates the number of seconds between heartbeats sent from the server to the
client to confirm the connection.
Server Heartbeat Server Interval (sec)
Indicates the number of seconds between heartbeats this server sends to another
server. The two servers can be connected by a route or as a fault tolerant pair.
Server Timeout for Client Connection (sec)
Indicates the number of seconds a server waits for a client heartbeat before
terminating the client connection.
Server Timeout for Server Connection (sec)
Indicates the number of seconds a server waits for a heartbeat from another server
before terminating the connection to that server.
Server Start Time
Indicates the server startup time in the form of yyyy MM-dd HH:mm:ss.


Statistics Cleanup Interval (sec)
Indicates the statistics cleanup interval in seconds.
Statistics Enabled
Indicates whether or not statistics collection is enabled.
A metric value of true indicates statistics are collected. A value of false indicates
statistics are not collected.
Store Truncation Enabled
Indicates whether the server should attempt to truncate store files when needed.
A metric value of true indicates store truncation is enabled. A value of false
indicates truncation is not enabled.
recommended.
Swapping Enabled
Indicates whether the message swapping is enabled to allow the server to swap
messages from process memory to disk.
A metric value of true indicates swapping is enabled. A value of false indicates
swapping is not enabled.
recommended.
Tibco RV Transport Enabled
Indicates whether TIBCO Rendezvous messaging is enabled for the server.
A metric value of true indicates bridging to and from tibrv and tibrvcm transports is
enabled. A value of false indicates Rendezvous transports are not enabled.
Tibco SmartSockets Transport Enabled
Indicates whether the TIBCO SmartSockets transport protocol is enabled for the
server.
A metric value of true indicates bridging to and from SmartSockets transports is
enabled. A value of false indicates SmartSockets transports are not enabled.


URL
Indicates the server instance URL.
Version
Indicates the version number of the EMS server instance.
The following Status metrics are available for the TIBCO EMS server process:
Asynchronous DB Size
Indicates the current size in KB of the asynchronous store file.
recommended.
Backup Server State
Indicates the text string indicating the current state of the server as Running or
Stopped.
Backup Server State Value
Indicates the numerical value indicating the current state of the server.
A value of zero (0) indicates a running backup server. A value of one (1) indicates a
stopped backup server.
Connection Count
Indicates the number of active connections to the server.
Consumers Count
Indicates the total number of message consumers on the server. This metric
includes all subscribers and queue receivers.
Durable Subscriber Count
Indicates the number of durable subscribers on the server.
Inbound Byte Rate
Indicates the rate at which inbound messages are received by the server in bytes
per second (Bps).


Indicates the number of inbound messages per second received by the server.
Log File Size
Indicates the current size of the log file in KB.
Message Memory Used
Indicates the memory currently used to store messages on the server in bytes.
recommended.
Outbound Byte Rate
Indicates the rate at which outbound messages are sent by the server in bytes per
second (Bps).
Indicates the number of outbound messages per second for the server.
Indicates the total number of pending messages for the server.
Indicates the total size, in KB, of the pending messages for the server.
Producers Count
Indicates the total number of message producers on the server.
This metric includes all topic publishers and queue senders.
Queue Count
Indicates the total number of queues, including static, dynamic, and temporary
queues, on the server.


Route Recover Count
Indicates the total number of Route Recover messages that can be stored on the
server.
Route Recover Interval (sec)
Indicates the interval in seconds for checking for Route Recover messages on the
server.
Sessions Count
Indicates the total number of sessions created by client applications on the server.
Server State
Indicates the text string indicating the current state of the server as Active or in
Standby. If the agent cannot connect to the EMS server, the server state is
displayed as Unknown.
Server State Value
Indicates the numerical value indicating the current state of the server.
A value of zero (0) indicates the server is Active. A value of one (1) indicates the
server is on Standby. A value of two (2) indicates an Unknown state.
Synchronous DB Size
Indicates the current size in KB of the synchronous store file.
recommended.
Topic Count
Indicates the total number of topics including static, dynamic, and temporary
topics, on the server.
More information:
About monitoring primary and backup servers (see page 205)



About monitoring primary and backup servers
If you want to monitor a primary and backup server pair, both the primary server and
the backup server must be configured to use the same user name and password setting.
The same user name and password are required to allow the EMSMonitor agent to
connect to the backup server when the primary server is offline.
If the primary server goes offline and is configured with a backup server, Server State
and Backup Server State metrics continue to report the status of both the primary and
backup server. However, the Backup Server Name metric is only reported only for the
primary server. Whereas, the server status metrics can switch from Active to Standby
depending upon the state of the paired servers, the Backup Server Name can only be
reported for one server at a time.
Metrics for Topics
The following Configuration metrics are available for TIBCO EMS dynamic and static
topics:
Bridged Topic
Indicates in a text string whether any bridged destinations exist for the topic:
A metric value of true indicates that the bridged destinations exist for the topic.
A value of false indicates that no bridged destinations exist for the topic.
Expiration (Sec)
Indicates the maximum length of time before messages expire on the selected
topic. If the value of this metric is zero (0), messages do not expire.
If the server expiration property is set for a queue, the value of the property
overrides the JMSExpiration value that the message producer sets.
Failsafe
Indicates in a text string whether the topic is configured as a fail-safe destination:
A metric value of true indicates that the topic is configured as a fail-safe
destination.
A value of false indicates that the topic is not configured as a fail-safe
destination.


Global
Indicates in a text string whether the topic is configured as a global topic and can be
used for routing messages from one server to another:
A metric value of true indicates that the topic is a global topic.
A value of false indicates that the topic is not a global topic.
recommended.
Maximum Flow Control Bytes
Indicates the maximum number of bytes used to enable flow control for the topic.
Maximum Messages
Indicates the maximum number of messages that the server can store as pending
messages for the selected topic.
minimum.
Multicast Channel Name
Identifies the multicast channel name that is associated with the topic when the
topic is enabled for multicasting.
recommended.
Multicast Enabled
Indicates whether the topic is enabled for multicasting:
A metric value of true indicates that multicasting is enabled for the topic.
A value of false indicates that multicasting is not enabled.
Note: Because multicast messaging is not supported for EMS, version 4.4.x, this
metric is always false for topics on EMS 4.4.x server instances.
recommended.


Overflow Policy
Indicates the overflow policy to use for the topic when it exceeds the maximum
number of messages or the maximum message size in bytes. The following overflow
policy values are valid:
0Indicates the default overflow policy. If a subscriber exceeds the maximum
bytes or number of messages, that subscriber does not receive the message.
No error is returned to the message producer.
1Indicates the discardOld overflow policy. If a subscriber exceeds the
maximum bytes or number of messages, the oldest messages are discarded
before new messages are delivered to the subscriber.
2Indicates the rejectIncoming overflow policy. If a subscriber exceeds the
maximum bytes or number of messages, all new messages are rejected and an
error is returned to the producer.
Prefetch Count
Indicates the maximum number of messages a message consumer can fetch from
the topic.
recommended.
Secure
Indicates in a text string whether the topic is configured to authenticate incoming
connections:
A metric value of true indicates that incoming connections are authenticated.
A value of false indicates that incoming connections are not authenticated.
Sender Name
Indicates in a text string whether the sender_name property is configured for the
topic:
A metric value of true indicates that the sender_name property is set.
A value of false indicates that the sender_name property is not set.
Sender Name Enforced
Indicates in a text string whether the sender_name_enforced property is configured
for the topic:
A metric value of true indicates the sender_name property is enforced.
A value of false indicates the sender_name property is not enforced.


Store Name
Identifies the store name where persistent messages are stored.
Note: This metric is only valid for EMS version 5.0 at a minimum.
The following Status metrics are available for TIBCO EMS dynamic and static topics:
Active Durable Subscriber Count
Indicates the number of currently active durable subscribers for the selected topic.
Durable Subscriber Count
Indicates the total number of durable subscribers for the selected topic.

Inbound Byte Rate
Indicates the number of inbound bytes sent per second to the selected topic by the
EMS clients and routed servers.
Indicates the number of inbound messages that are sent per second to the selected
topic by the EMS clients or routed servers.
Outbound Byte Rate
Indicates the number of outbound bytes sent per second to consumers on the
selected topic or routed to other servers.
Indicates the number of outbound messages that are sent per second to consumers
of the selected topic or routed to other servers.
Indicates the number of pending messages for the selected topic.
Indicates the total size in KB for all pending messages for the selected topic.


Subscriber Count
Indicates the total number of subscribers for the selected topic.
This metric includes durable and nondurable subscribers.
Metrics for Routes
TIBCO EMS routes are not monitred by default, but you can enable monitoring for
routes by adding the <ServerInstance>.monitor.routes property to the
TibcoEMSMonitor.properties file. If you enable monitoring for routes, the following
Configuration metrics are available for TIBCO EMS routes:
Remote Server URL
URL of the remote server to which the route connects.
Route Type
Indicates whether route is an active route or passive route.
The metric value indicates whether the route is Active or Passive.
Zone Name
Name of the routing zone the selected route is part of.
Zone Type
Indicates whether the routing zone for the route is a one-hop (1hop) or multi-hop
(mhop) zone type.
If the zone type cannot be determined, the metric value is UNKNOWN.
If you enable monitoring for routes, the following Status metrics are available for
TIBCO EMS routes:
Backlog Count
Number of messages in the routes backlog.
This metric is only valid for EMS, version 5.0 or later.
Backlog Size
Size, in KB, of all messages in the routes backlog.
This metric is only valid for EMS, version 5.0 or later.
Inbound Byte Rate
Rate at which inbound messages are routed in bytes per second (Bps).
Number of inbound messages received per second.


Is Connected
Text string that indicates whether the route is currently connected.
A metric value of true indicates a connected route. A value of false indicates a
disconnected route.
Is Connected Value
Numerical value that indicates whether the route is connected.
A metric value of zero (0) indicates a connected route. Any non-zero value indicates
a disconnected route.
Outbound Byte Rate
Rate at which outbound messages are routed in bytes per second (Bps).
Number of outbound messages sent per second.
Stalled Destinations
Indicates whether the route has any stalled destinations.
A metric value of true indicates a stalled destination. A value of false indicates there
are no stalled destinations.
Metrics for Channels
TIBCO EMS multicast channels are not monitored by default, but you can enable
monitoring for channels by adding the <ServerInstance>.monitor.channels property to
the TibcoEMSMonitor.properties file. If you enable monitoring for channels, the
following Configuration metrics are available for TIBCO EMS multicast channel
operations:
Channel Interface
Multicast-capable IP address used to send multicast data.
Maximum Time
Maximum length of time, in seconds, that the server retains sent messages for
retransmission.
Maximum Rate
Maximum transmission rate in bytes per seconds (Bps) for transmitting multicast
data.
Multicast Group Address
Multicast group address and port to which messages are sent.


Multicast Time to Live
Maximum number of network hops messages can make between the server and
multicast daemon.
Priority
Priority given to this channel during bandwidth allocation.
The highest priority is -5 and the lowest priority is 5.
If you enable monitoring for channels, the following Status metrics are available for
TIBCO EMS multicast channel operations:
Backlog Count
Number of messages in the buffer waiting to be sent over the channel.
Backlog Size
Size in bytes of messages in the buffer waiting to be sent on the channel.
Byte Rate
Rate at which inbound and outbound massages are processed by the channel in
bytes per second (Bps).
Channel State
Text string that indicates whether the channel is active or defined in the server
configuration but not active.
A metric displays Active if the channel is active or Inactive if the channel is defined
in the server configuration but is not active.
Channel State Value
Numerical value that indicates whether the channel is active (0) or defined in the
server configuration but not active (any non-zero value).
Message Rate
Number of messages processed per second by the channel. This metric includes
both inbound and outbound messages.
Viewing default TIBCO EMS metric groupings


Metrics for Bridges
TIBCO EMS bridges are not monitored by default, but you can enable monitoring for
bridges by adding the <ServerInstance>.monitor.bridges property to the
TibcoEMSMonitor.properties file. If you enable monitoring for bridges, the node name
identifies the type of bridge and bridge source name and its sub-nodes identify target
destinations by destination type. The target destinations and the message selector used
to filter messages (if a selector is defined) are the only metrics reported in the
Investigator tree. For example:

Viewing default TIBCO EMS metric groupings
The SOA extension for TIBCO Enterprise Message Service includes default metric
groupings that are used to define the default dashboards and alerts. You can also use
these default metric groupings in custom dashboards and alerts.
TIBCO Enterprise Message Service as part of the TIBCO Enterprise Message Service
Management Module (TibcoEMSManagementModule.jar).
To view the default metric groupings for TIBCO Enterprise Message Service agents
TibcoEMS <version> (*Super Domain*).
Viewing default TIBCO EMS alerts


the TIBCO Enterprise Message Service management module.
metric groupings.
Viewing default TIBCO EMS alerts
The SOA extension for TIBCO Enterprise Message Service includes default alert
definitions that are used in the preconfigured dashboards. You can also use these
default alerts in custom dashboards. Most of the default alerts are preconfigured with
default Caution and Danger thresholds and to send notification to the console if a
threshold is crossed or severity increases.
TIBCO Enterprise Message Service as part of the TIBCO Enterprise Message Service
Management Module (TibcoEMSManagementModule.jar).
To view the default alert definitions for TIBCO Enterprise Message Service agents
TibcoEMS <version> (*Super Domain*).
3. Expand the Alerts node to view all of the alerts defined for the TIBCO Enterprise
Message Service management module.
for the alerts you consider most important and adjust the values, if necessary. You may
also want to add notifications or specify corrective actions for some alerts.
Summary of agent configuration properties


The EMSMonitor agent relies on numerous configuration properties in the
TibcoEMSMonitor.properties file to define the EMS server instances it connects to and
the components it monitors. The following list provides a summary of these properties
and describes the type of values each property can accept as a quick reference for
setting valid values.
Several configuration properties allow you to specify regular expressions for pattern
matching. For a summary of regular expression syntax and valid constructs, see the
information about Pattern matching in your Java documentation.
ems.server.list
Comma-separated list of EMS server instance names that you want to monitor.
The names you specify are not required to match the actual names of the server
instances you are monitoring. For example, if you have two server instances with
the same name but different ports, you can use aliases in the ems.server.list
property to distinguish them.
For example:
ems.server.list=mercury01,mercury02,jupiter03
<ServerInstance>.host
Host name or IP address of EMS server that hosts the specified server instance. The
default value is localhost.
For example:
mercury01.host=winsrvT400
<ServerInstance>.port
Port number of EMS server that hosts the specified server instance. The default
value is 7222.
For example:
mercury01.port=7200
<ServerInstance>.username
User name with administrative privileges that you want to use to establish a
connection to the EMS server. This property is typically set for you when you use
the emsPwdEncryptor utility to encrypt the password for the account.
The default value is admin.
For example:
mercury01.username=jgarcia


<ServerInstance>.password
Password for the user account specified for the <ServerInstance>.username
property. This property is typically set for you when you use the emsPwdEncryptor
utility to encrypt the password for the account.
The default value is an empty string (no password).
For example:
mercury01.password=YCLhqcwQfpc=
<ServerInstance>.delaytime
Time interval, in seconds, after which a query is made to the EMS server to refresh
the metrics for EMS server components being monitored.
At this interval, the EMSMonitor agent collects metrics about the status of the
server instance and its components.
The default value is 60 seconds.
For example:
mercury01.delaytime=90
<ServerInstance>.report.static.freq
Number of EMS server status queries to make between queries for static metrics.
For example, if this property is set to 20, static configuration-related metrics are
only renewed every 20 times the EMSMonitor agent collects metrics.
The default value is 20.
For example:
mercury01.report.static.freq=50
<ServerInstance>.queue.filter.includeonly.regex
Specify a regular expression to monitor queues with a name that matches the
expression. You can use any valid regular expression. Some special characters
require an escape sequence.
By default, the EMSMonitor agent collects metrics for all queues if you dont specify
a filter with this property.
For example:
mercury01.queue.filter.includeonly.regex=[A-H]
<ServerInstance>.topic.filter.includeonly.regex
Specify a regular expression to monitor topics with a name that matches the
By default, the EMSMonitor agent collects metrics for all topics if you dont specify
a filter with this property.
For example:
mercury01.topic.filter.includeonly.regex=[a-hA-H]


<ServerInstance>.queue.filter.include.dynamic
Specify whether you want to monitor dynamic queues for this EMS server instance.
Set this property to true if you want to include metrics for dynamic queues.
By default, only static queues are monitored by the EMSMonitor agent.
For example:
mercury01.queue.filter.include.dynamic=true
<ServerInstance>.topic.filter.include.dynamic
Specify whether you want to monitor dynamic topics for this EMS server instance.
Set this property to true if you want to include metrics for dynamic topics.
By default, only static topics are monitored by the EMSMonitor agent.
For example:
mercury01.topic.filter.include.dynamic=true
<ServerInstance>.monitor.bridges
Specify whether you want to monitor bridges for this EMS server instance. Set this
property to true if you want to include metrics for bridges.
By default, the EMSMonitor agent does not monitor bridges.
For example:
mercury01.monitor.bridges=true
<ServerInstance>.monitor.channels
Specify whether you want to monitor multicast channels for this EMS server
instance. Set this property to true if you want to include metrics for channel.
By default, the EMSMonitor agent does not monitor channels.
For example:
mercury01.monitor.channels=true
<ServerInstance>.monitor.routes
Specify whether you want to monitor routes for this EMS server instance. Set this
property to true if you want to include metrics for route.
By default, the EMSMonitor agent does not monitor routes.
For example:
mercury01.monitor.routes=true


<ServerInstance>.bridge.filter.includeonly.regex
Specify a regular expression to monitor bridges with names that match the
By default, the EMSMonitor agent collects metrics for all bridges if the
<ServerInstance>.monitor.bridges property is set to true and you dont specify a
filter with this property.
For example:
mercury01.bridge.filter.includeonly.regex=test.*
<ServerInstance>.channel.filter.includeonly.regex
Specify a regular expression to monitor channels with names that match the
By default, the EMSMonitor agent collects metrics for all channels if the
<ServerInstance>.monitor.channels property is set to true and you dont specify a
filter with this property.
For example:
mercury01.channel.filter.includeonly.regex=test.*
<ServerInstance>.route.filter.includeonly.regex
Specify a regular expression to monitor routes with names that match the
By default, the EMSMonitor agent collects metrics for all routes if the
<ServerInstance>.monitor.routes property is set to true and you dont specify a filter
with this property.
For example:
mercury01.route.filter.includeonly.regex=test.*
<ServerInstance>.monitoring.level
Define the monitoring level for the EMS server instance. The valid settings for this
property are minimum, recommended, and full.
The default server monitoring level is recommended.
For example:
mercury01.monitoring.level=minimum
<ServerInstance>.queue.monitoring.level
Define the monitoring level for queues on the EMS server instance. The valid
settings for this property are minimum, recommended, and full.
The default queue monitoring level is recommended.
For example:
mercury01.queue.monitoring.level=recommended


<ServerInstance>.topic.monitoring.level
Define the monitoring level for topics on the EMS server instance. The valid settings
for this property are minimum, recommended, and full.
The default topic monitoring level is recommended.
For example:
mercury01.topic.monitoring.level=full
client.identity
Specifies the path to the certificate the EMS server can use to verify the identity of
the EMSMonitor agent. In most cases, this property is set for you when you run the
emsPwdEncryptor program.
For example:
client.identity=C:/TibcoEMSMonitor/certs/client.p12
ssl.password
Specify the encrypted password for the client security certificate.
In most cases, this property is set for you when you run the emsPwdEncryptor
program.
<ServerInstance>.ssl.connection
Specify whether to connect to the server instance using Secure Socket Layer (SSL)
protocol.
Set this property to enable if you want to connect to the server instance using SSL.
Set this property to disable if you want to allow unsecured communication.
There are no default values for security-related properties.
<ServerInstance>.verify.host
Specify whether the EMSMonitor agent must verify the EMS server's certificate. Set
this property to true to require the agent to verify the EMS servers security
certificate against the list defined for the trusted.certificates property.
For example, to require verification when the agent connects to the EMS server
instance mercury01:
mercury01.verify.host=true
trusted.certificates
Specify a comma-separated list of trusted certificates the EMSMonitor agent uses to
verify the server's certificate. This property is required if the verify.host property is
set to true, and is applicable for all EMS server instances that use SSL.


<ServerInstance>.verify.hostname
Specify whether the agent should verify the Common Name (CN) field of the
servers certificate.
Set this property to true if you want the agent to compare the name of the
connected host or the name specified in the <ServerInstance>.expected.name
property to the Common Name (CN) field in the servers certificate. If set to true
and the names do not match, the agent rejects the connection.
<ServerInstance>.expected.hostname
Specify the name the EMSMonitor agent should expect to find in the Common
Name (CN) field in the servers certificate.
cipher.suites
Specify a comma-separated list of cipher suites the EMSMonitor agent can use to
encrypt communication with SSL-enabled EMS servers. The EMSMonitor agent can
use any encryption package supported by the EMS servers you are monitoring. If
you set this property, it applies for all SSL-enabled EMS server instances.


Chapter 10: Monitoring webMethods Broker

The Software AG webMethods Broker provides asynchronous processing and message
handling services to publish documents separately from webMethods Integration
Server. With webMethods Broker, you can publish documents with guaranteed delivery
to verify that documents reach their destination. If guaranteed delivery documents
cannot be delivered to their destination, the Broker verifies that they are never
published. The SOA extension for webMethods Broker enables you to monitor the key
webMethods Broker components, including the Broker server, individual Broker
instances, Broker clients, and document handling events.
This section describes the Broker-specific dashboards, metrics, and alerts you can use to
monitor and analyze the performance, availability, and overall health of the
webMethods Broker environment.
About webMethods Broker (see page 221)
How to Install the SOA Extension for webMethods Broker (see page 223)
Use Dashboards to Monitor webMethods Broker (see page 232)
Understanding and Viewing Metrics for the Broker (see page 234)
View Default Broker Metric Groupings (see page 244)
View Default Broker Alerts (see page 245)
About webMethods Broker
The webMethods Broker manages the routing of documents between applications, and
serves as the link between business processes, enterprise and legacy systems, databases
and other backend systems, internal and external workflows and Web services, within
and across organizations. Within the service-oriented architecture, webMethods Broker
handles message routing, queuing, storage, and filtering to accommodate high volume
messaging across a wide range of platforms and protocols.
About webMethods Broker


The webMethods Broker coordinates the exchange of documents between client
programs. It provides the following services:
Queues all document events for the documents that are published by Broker
clients.
Sends documents to the clients that have subscribed to and are ready to receive the
event.
Verifies the reliable delivery of documents it receives.
Provides filtering services that allow Broker clients to selectively filter the
documents they receive, based on content.
Maintains information about document types, client groups, publication
permissions, subscription permissions, network access control, queue
characteristics for the clients in each group, and state information for each Broker
client that has been created.
Because the reliable and secure delivery of messages is a critical part of delivering
business services and completing business transactions, the SOA extension for
webMethods Broker provides a standalone agent for monitoring the operation and
performance metrics for webMethods Broker.
The standalone agent used to monitor webMethods Broker is not an extension to the
core Java or .NET agent. Instead of instrumenting Java classes, the agent,
WilyWMBrokerMonitor, uses the WmBrokerClient API to collect performance
information for webMethods Broker components and operations, then reports this
information to the Enterprise Manager.
Because the WilyWMBrokerMonitor agent is a standalone agent, it is distributed as a
separate software package and requires its own unique configuration steps. For
example, you must configure connection information for the Broker servers you want to
monitor and add filters to customize the components for which you want to collect
metrics.
After you configure the appropriate agent properties, you can start monitoring
webMethods Broker server and client operations using the WilyWMBrokerMonitor
agent.
How to Install the SOA Extension for webMethods Broker


Because the WilyWMBrokerMonitor agent is not dependent on the core agent, you can
install and configure the WilyWMBrokerMonitor agent independent of any other CA
Introscope components.
To add the SOA extension for webMethods Broker, perform the following high-level
steps:
1. Verify that your implementation meets the prerequisites (see page 223) for adding
the SOA extension for webMethods Broker.
2. Run the Standalone agent installer (see page 223) or use a response file (see
page 224) to add the required agent files to your environment.
3. Prepare the webMethods Broker server for monitoring (see page 225).
4. Configure the WilyWMBrokerMonitor agent profile (see page 226) to define
connection and monitoring properties.
5. Enable the Enterprise Manager extension (see page 231) for webMethods Broker.
Verify Prerequisites
Before you add the SOA extension for webMethods Broker, your implementation must
meet certain requirements.
Follow these steps:
1. Verify that you have webMethods Broker installed.
Note: For webMethods Broker requirements, see the Compatibility Guide.
2. Verify that you have the Enterprise Manager and Workstation installed in your
environment.
3. Verify that you have connection information for the Enterprise Manager to which
the WilyWMBrokerMonitor agent will send data.
The Standalone agent installer enables you to install standalone agents that do not rely
on the core Java or .NET agent. The Standalone agent installer lets you enable
monitoring for webMethods Broker. The installer adds the agent-related files to your
environment and configures the agent connection to the Enterprise Manager. The
Standalone agent installer extracts the required files and places them in the proper
location for you to modify to complete the agent configuration.


Follow these steps:
1. Start the appropriate Standalone agent installer for your operating environment.
2. On the Introduction page, click Next.
3. Select the monitoring packages that you want to install, and click Next. For
example, select SOA Extension For webMethods Broker.
This option enables monitoring for webMethods Broker.
4. For the installation directory, click Next to accept the default location, or click
Browse to specify a different location.
5. For the Enterprise Manager connection settings, specify the Enterprise Manager
host name and port number for the agent to send data to, and click Next.
6. Review the summary of your settings, and click Install.
The installation starts.
7. Click Done when the installation completes.
The Standalone agent installer closes.
Use a Response File for Silent Installation
If you do not want to run the Standalone agent installer interactively, you can edit the
standalone sample response file to install agent files. This method lets you enable the
SOA extension for webMethods Broker in silent mode.
Follow these steps:
1. Open theSampleResponseFile.StandaloneAgentPP.txt file, located in the same
directory as the Standalone agent installer.
2. Edit the SampleResponseFile.StandaloneAgentPP.txt file to set the
shouldInstallWMBroker property to true to add the SOA extension for webMethods
Broker to the agent. For example:
shouldInstallWMBroker=true
3. Save the SampleResponseFile.StandaloneAgentPP.txt file.
Java Agent Implementation Guide or the CA APM .NET Agent Implementation Guide.


Manually Extract an Installation Archive
If you do not have access to the Standalone agent installer or the standalone response
file, you can download a standalone installation archive for your operating environment.
Follow these steps:
1. Go to from the CA APM software download area on CA Support.
2. Download the standalone installation archive for your operating environment.
3. Manually extract files from the archive using the appropriate command for your
operating environment. For example, use the tar command on UNIX computers:
tar -xvf IntroscopeStandaloneAgentPPInstaller<version>unix.tar

Prepare webMethods Broker for Monitoring
Before you can monitor the webMethods Broker, identify a client group with
administrative privileges and verify that the libraries required for monitoring are
available locally.
Follow these steps:
1. Verify that you have the admin client group available to create a Broker client that
the WmBrokerAgent can use.
2. Verify that the following Broker libraries are available.
For Webmethods 7.x:
wmbrokerclient.jar
g11nutils.jar
For Webmethods 8.x:
wm-brokerclient.jar
wm-g11nutils.jar
The files are typically in the following locations:
<Broker_Home>/common/lib -- valid for webMethods Broker 6.5.
<Broker_Home>/lib -- valid for other supported webMethods Broker versions.
Note: For webMethods Broker requirements, see the Compatibility Guide.


Configure the Agent for the webMethods Broker
After you run the installer to add the agent files to your environment, the
WilyWMBrokerMonitor directory exists. You use the files in this directory to configure
the agent for the webMethods Broker.
Follow these steps:
1. Copy the following Broker libraries from the <Broker_Home>/lib directory or the
<Broker_Home>/common/lib to the WilyWMBrokerMonitor/lib directory:
wm-brokerclient.jar
wm-g11nutils.jar
2. Use the files in the WilyWMBrokerMonitor directory and subdirectories to
configure the WmBrokerAgent connection and monitoring properties.
lib directory
Contains required the libraries, which are packaged as a .jar file (jline-0.9.9.jar).
config directory
Contains the WilyWMBrokerMonitor.properties file that you use to configure
parameters for connecting to webMethods Brokers clients and servers.
Windows Service directory
Contains the files that you use to register and deregister the wmBrokerAgent
process as a Windows service.
Agent.jar file
Provides the classes that the agent uses to collect and forward metrics to the
Enterprise Manager.
IntroscopeAgent.profile file
Provides the properties that enable you to configure the connection to the
Enterprise Manager.
WmBrokerAgent.jar file
Provides the classes that the agent uses to monitor webMethods Broker
servers and clients.


wmBrokerPwdEncryptor file
Provides a password encryption script (wmBrokerPwdEncryptor.bat or
wmBrokerPwdEncryptor.sh). This script lets you encrypt the user password and
SSL client certificate password for connecting to the webMethods Broker
server.
WmBrokerAgent file
Provides the startup script (WmBrokerAgent.bat or WmBrokerAgent.sh) to run
the wmBrokerAgent when you are ready to start monitoring webMethods
Broker.
Configure Basic Connection Properties
The WmBrokerAgent reports data from the webMethods Broker server to an Enterprise
Manager. You can enable the collection and reporting of metrics as follows:
1. Specify connection information for the Enterprise Manager to which the
WmBrokerAgent reports.
2. Identify the list of servers from which the agent collects data.
Follow these steps:
1. Open the IntroscopeAgent.profile file in a text editor to verify the Enterprise
Manager connection parameters. For example:
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=mercury
introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT=5001
If you installed the agent files with the Standalone agent installer, use the values
that you entered during installation. If you manually extracted the agent files, you
may need to modify the default settings to connect to the correct Enterprise
Manager.
2. Open the WmBrokerAgent startup script in a text editor.
3. Set the JAVA_HOME environment variable to the appropriate directory. For
example:
set JAVA_HOME=C:\webMethods7\jvm\win150\jre
Valid for JRE version 1.5 or later: Monitoring webMethods Broker requires JRE
version 1.5 or later.
4. Open the WilyWMBrokerMonitor.properties file in a text editor and set the host
property to identify the webMethods Broker server you want to monitor. For
example:
wily.webmethods.broker.server.host=vepsa09


5. Set the port property to specify the port number to use for connecting to the
webMethods Broker server you want to monitor. For example:
wily.webmethods.broker.server.port=6890
6. Set the client group property to specify the client group in which the
BrokerAdminClient should be created. For example:
wily.webmethods.broker.server.clientgroup=admin
Configure Polling Intervals for Collecting Metrics
The WmBrokerAgent polls each Broker server at regular intervals to retrieve up-to-date
status and configuration information. You can control the frequency of these queries
using configuration properties.
To configure how frequently the WmBrokerAgent queries the server, set the interval
property to configure the polling interval for collecting Broker metrics. For example, to
collect and report metrics every 14000 milliseconds:
wily.webmethods.broker.interval=14000
Configure the Broker Client Groups to Monitor
You can control the specific client groups that you want to monitor on a Broker using
the wily.webmethods.broker.clientstat.clientGroups configuration property.
To configure which Broker client groups to monitor, specify the list of Broker client
groups to monitor. By default, metrics are reported for all of the clients in the client
groups you specify. For example, to collect and report metrics for all of the Broker
clients in the IntegrationServer and IS-Backup client groups, you would set the property
as follows:
wily.webmethods.broker.clientstat.clientGroups=IntegrationServer,IS-Backup
Configure SSL Connections for webMethods Broker
If you use Secure Socket Layer (SSL) connections between client groups and
webMethods Broker servers, the agent must present a signed certificate for validation.
To enable support for SSL connections, create an encrypted password for the SSL
certificate and set some additional properties in the WilyWMBrokerMonitor.properties
file.
Note: Use this procedure for supported versions of webMethods Broker servers other
than 6.5. For more information about supported versions, see the Compatibility Guide.
You can use the wmBrokerPwdEncryptor script to specify the path to an appropriate
certificate file to use and create an encrypted password for SSL connections.


Follow these steps:
1. Open the wmBrokerPwdEncryptor script in a text editor and set the JAVA_HOME
set JAVA_HOME=C:\webMethods7\jvm\win150\jre
2. Run the wmBrokerPwdEncryptor script and enter y to configure SSL connection
properties.
a. When prompted for the path to the keystore file, enter the path to the PKCS12
key store certificate file for the Broker.
b. When prompted for the path to the truststore file, enter the path to the Java
Key Store (JKS) trust store certificate file for the Broker.

c. When prompted for a password to the keystore/certificate file, enter the
password to use for authenticating the file.
d. Press Enter to complete the configuration.
The wmBrokerPwdEncryptor script does the following actions:
Encrypts the SSL keystore or certificate password.
Updates the appropriate properties for the Broker in the
WilyWMBrokerMonitor.properties file.
3. Open the WilyWMBrokerMonitor.properties file in a text editor.
a. Set the wily.webmethods.broker.connection.ssl_encrypted property to true to
enable encryption for SSL connections. For example:
wily.webmethods.broker.connection.ssl_encrypted=true
b. Set the wily.webmethods.broker.ssl.distinguished_name property to the full
distinguished name to use for connecting to the Broker server. For example:
wily.webmethods.broker.ssl.distinguished_name=cn=vespa09,dc=test,dc=org
c. Save and close the file.
More information:
Configure SSL Connections for webMethods Broker 6.5 (see page 230)



Configure SSL Connections for webMethods Broker 6.5
If you use Secure Socket Layer (SSL) connections between client groups and
webMethods Broker servers, the agent must present a signed certificate for validation.
To enable support for SSL connections, create an encrypted password for the SSL
certificate and set some additional properties in the WilyWMBrokerMonitor.properties
file.
Note: The specific properties that you set depend on what version of webMethods
Broker you are using. Use the following procedure for webMethods Broker 6.5. For
supported versions of webMethods Broker, see the Compatibility Guide.
You can use the wmBrokerPwdEncryptor script to specify the path to an appropriate
certificate file to use and create an encrypted password for SSL connections.
Follow these steps:
1. Open the wmBrokerPwdEncryptor script in a text editor and set the JAVA_HOME
set JAVA_HOME=C:\webMethods<version_number>\jvm\win150\jre
2. Run the wmBrokerPwdEncryptor script and enter y to configure SSL connection
properties.
a. When prompted for the path to the keystore file, press Enter to leave this
property blank.
b. When prompted for the path to the truststore file, press Enter to leave this
property blank.
c. When prompted for the path to the certificate file, enter the path to the SSL
certificate file for the Broker.
The certificate for Broker is typically in PKCS10 format. You can use the
webMethods Broker Certificate Manager (awcert) to generate the file.
d. When prompted for a password to the keystore/certificate file, enter the
password to use for authenticating the file.
e. Press Enter to complete the configuration.
The wmBrokerPwdEncryptor script does the following actions:
Encrypts the SSL keystore or certificate password.
Updates the appropriate properties for the Broker in the
WilyWMBrokerMonitor.properties file.
3. Open the WilyWMBrokerMonitor.properties file in a text editor.
a. Set the wily.webmethods.broker.connection.ssl_encrypted property to true to
enable encryption for SSL connections. For example:
wily.webmethods.broker.connection.ssl_encrypted=true


b. Set the wily.webmethods.broker.ssl.distinguished_name property to the full
distinguished name to use for connecting to the Broker server. For example:
wily.webmethods.broker.ssl.distinguished_name=cn=vespa09,dc=test,dc=org
c. Save and close the file.
4. Do the action that corresponds to the operating environment you are using:
On Windows, copy the file awssl65jn.dll from the
<webMethods_Home>\common\lib directory to the WilyWMBrokerMonitor\lib
directory.
On UNIX, copy the file libawssl65jn.so from the
<webMethods_Home>/common/bin directory to the
WilyWMBrokerMonitor/lib directory.
More information:
Configure SSL Connections for webMethods Broker (see page 228)

Start the Agent
After you configure the connection and monitoring properties for the agent, you can
start the agent. You use the agent startup script to start the agent and begin monitoring
Broker servers and clients.
To start the agent for monitoring webMethods Broker, run the WmBrokerAgent startup
script.
Monitoring for the webMethods Broker server begins.
Enable the Enterprise Manager Extension for webMethods Broker
CA APM for webMethods Broker files are installed by default in the
APM for webMethods Broker, you copy or move files from the examples directory to
the Enterprise Manager home directory.

Use Dashboards to Monitor webMethods Broker


Follow these steps:
1. Verify that the SOAExtensionForWebMethodsBroker directory, is in the
<EM_Home>/examples directory.
2. Copy the files from the
<EM_Home>/examples/SOAExtensionForWebMethodsBroker directory to the
corresponding location in the Enterprise Manager directory structure. For example,
copy the files from the
<EM_Home>/examples/SOAExtensionForWebMethodsBroker/ext directory to the
3. Remove the webMethods Broker Management Module,
WebMethodsBrokerManagementModule.jar, from the
<EM_Home>/config/modules directory if the Enterprise Manager is a Collector in a
clustered environment.
Note: You should only copy the Management Module to the
<EM_Home>/config/modules directory on the Enterprise Manager that you are
using as the MOM computer. All other files and scripts should be installed on both
the Collector Enterprise Managers and the MOM Enterprise Manager.
to the SOA extension for webMethods Broker.
The SOA extension for webMethods Broker includes several preconfigured dashboards
components of the webMethods Broker server at-a-glance.
been crossed.
Drill-down into performance information to isolate and identify which Brokers,
client groups, clients, or document types are experiencing delivery or publication
delays or have the heaviest traffic.
The preconfigured webMethods Broker dashboards are packaged in the Enterprise
Manager extension for webMethods as part of the webMethods Broker Management
Module (WebMethodsBrokerManagementModule.jar).


The webMethods Broker Management Module provides the following preconfigured
dashboards for webMethods Broker:
WebMethods Broker - Overview
A top-level overview of the key activity and storage statistics for webMethods
Broker servers, including:
graphs and alert indicators for the documents published and the documents
queued.
graphs for the client queue length and documents retrieved.
alert indicators for the queue length, queue size, and the number of
unacknowledged documents.
WebMethods Broker - Brokers
Summarized status for all Broker instances, including lists of the Brokers with:
the most clients.
the most document types.
the most documents published.
the most documents queued.
the most current documents in the Retry queue.
the highest number of attempted delivery events in the Retry queue.
the most published documents in the Retry queue.
WebMethods Broker - Clients
Summarized status for all Broker clients groups and clients, including lists of:
client groups with the most documents delivered.
client groups with the most documents published.
clients with the most documents delivered.
clients with the most documents published.
clients with the most documents queued.
clients with the most events retrieved.
From this dashboard, you can double-click the Clients Details link to display the
WebMethods Broker - Clients Details dashboard, which lists the queue size, queue
length, number of scans, maximum queue length, and the most unacknowledged
documents for clients with the most documents queued.
WebMethods Broker - Documents
Summarized status for all Broker document types, including lists of the document
types received and sent most often, and lists of the document types most often
delivered, published, and received, and with the most client subscriptions.
Understanding and Viewing Metrics for the Broker


WebMethods Broker - Territories
Summarized status for all Broker territories, including lists of:
the territories with the most documents queued.
the territories with the most document types placed in the queue, forwarded,
and received.
the territories with the highest queue size, longest current queue length, and
the highest maximum queue length.
Follow these steps:
extension for webMethods is installed.
4. Select one of the webMethods Broker dashboards from the Dashboard drop-down
list.
For example, select the WebMethods Broker - Overview dashboard to see an
overview of webMethods Broker metrics.
5. Double-click another tab or an alert to open the related dashboard to view more
detailed information.
For example, double-click the Clients tab to see more detailed information about
the webMethods Broker client groups and clients.
6. Double-click a specific broker, client, document type, or territories metric in a
dashboard to open the Investigator for further analysis.
From the WebMethods Broker - Clients Details dashboard, for example, you can
double-click the most highly queued client to open the Investigator with that
clients Events > Queued metric selected.
The WmBrokerAgent can monitor Broker servers and clients to provide data about their
overall health under the Broker Server on <host_name> at <port_number> nodes.


You can monitor the performance and health of webMethods Broker servers and clients
with metrics for the following metric categories:
Brokers
Under the Brokers node, you can find metrics for individual Broker instances, such
as the number of clients, subscriptions, and documents published and delivered.
Client Groups
Under the Client Groups node, you can find metrics for client groups you have
identified for monitoring in the WilyWMBrokerMonitor.properties file and their
associated clients, such as the number of documents published and delivered.
Document Types
Under the Document Types node, you can find metrics for the individual document
types you have defined. A document type contains a set of fields that define the
structure and content of a document used to exchange information between
partners or programs.
Retry Queue
Under the Retry Queue node, you can find metrics for the internal retry queue.
Territory Stats
Under the Territory Stats node, you can find metrics for individual territories.
Trace
Under the Trace node, you can find metrics for the internal trace queue.
Utilization
Under the Utilization node, you can find metrics that describe Broker configuration
and data storage statistics.
Note: For information about the metrics available in each metric category, see the
appropriate section for that cateogry.


To view and navigate webMethods Broker metric summaries in the Investigator:
1. Expand the agent node and the Broker Server on <host_name> at <port_number>
node, then click Brokers to display the Overview tab, which lists all of the monitored
Broker server instances with sumary information about the number of documents
delivered, published, and queued.
2. Select a specific Broker name to display summary information about the documents
delivered and published for that instance in a graphical format on the Overview tab.
For example, when you select an individual Broker name, the Overview tab displays
graphs for:
Total Documents Delivered by Clients
Total Documents Published by Clients
Total Documents Published by Broker
Total Documents Queued for Clients
Number of Clients
Number of Document Types
3. Expand an individual Broker name, then click any sub-node to display summary
information about that metric category. For example, select the Client Groups node
to display a list of the client groups for the Broker and a summary of the documents
delivered and published for each client group on the Overview tab.
To view and navigate webMethods Broker metric nodes in the Investigator:
1. Expand the agent and the Broker Server on <host_name> at <port_number> node,
then expand the Brokers node to display the Broker server names you are
monitoring.
2. Expand the individual Broker_server_name node to display the metrics for that
Broker server instance.


3. Expand the Client Groups node to view the client groups you specified in
WilyWMBrokerMonitor.properties file that you want to monitor, then expand a
specific <client_group_name> to display the metrics for that client group. For
example:

4. Expand the Clients node, then expand an individual <client_name> sub-node to
display the metrics for that client.
5. Expand the Document Types node, then expand an individual
<document_type_name> sub-node to display the metrics for that document type
for the selected Broker.
6. Expand the Retry Queue, Territory Stats, or Trace sub-node to display the retry
queue, territory, or trace metrics for the selected Broker.
7. Expand Utilization > Storage Statics, then expand the CONFIG or DATA sub-nodes to
display information about configuration or data storage for the selected Broker
server.


Metrics for Brokers
The webMethods Broker server is a host computer that manages the flow of documents
among clients, Brokers, and various applications. Client programs publish and subscribe
to information in the form of documents, and the Broker Server automatically routes,
queues, and filters documents. Each Broker Server has one or more individual Brokers,
that reside on it.
Each individual Broker can receive client connections and store information about its
own document types, client queues, and subscriptions. When a client publishes a
document, the Broker determines which Broker clients have subscribed to receive
documents of that type and places the document in the corresponding Broker client
queues.
The following metrics are available for the Broker instances you are monitoring under
the Brokers sub-node for individual Broker instance names:
Number of Clients
Total number of clients for the selected Broker server.
Number of Document Types
Total number of document types defined for the selected Broker server.
Total documents delivered by clients
Total number of documents delivered by clients to the selected Broker server.
Total documents published by broker
Total number of documents published by the selected Broker server to its clients.
Total documents published by clients
Total number of documents published by clients to the selected Broker server.
Total documents queued for clients
Total number of documents queued by the selected Broker server for delivery to its
clients.


Metrics for Client groups
In webMethods Broker, client groups enable you to set properties for multiple Broker
clients at one time. The following metrics are available for the client groups you are
monitoring under the Client Groups sub-node for individual client group names:
Number of Events Delivered
Total number of document delivery events for all of the clients in the selected client
group.
Number of Events Published
Total number of document publication events for all of the clients in the selected
client group.
Metrics for Clients
A Broker client is a webMethods object that is created and used by client programs to
connect to a particular Broker. Client programs create one or more Broker clients and
connect to one or Brokers, as needed. For webMethods Broker clients, document
handling tasks are recorded as events. For example, if a document is successfully
delivered to a client, the action is recorded as a document delivery event.
You can monitor Broker clients using metrics in the following metric categories under
the Clients > <client_name> node:
Events
Events record document handling tasks. For example, if a document is successfully
delivered to a client, the action is recorded as a document delivery event.
Queue
Queues are used to store asynchronous events in the order received until they can
be processed.
Session
Sessions represent client connections to the Broker.
Event metrics
The following metrics are available for under the Events sub-node for the individual
clients of a selected Broker client:
Delivered
Total number of document delivery events recorded by the selected client.
Published
Total number of document publishing events recorded by the selected client.


Queued
Total number of document queued for the selected client.
Retrieved
Total number of documents retrieved from the queue by the selected client.
Unacknowledged
Total number of documents that client programs have retrieved from the client
queue but not yet acknowledged to the Broker.
Broker removes documents from the client queue after receiving an
acknowledgement.
Queue metrics
The following metrics are available for under the Queue sub-node for the individual
Byte Size
Size of the queue in bytes.
Highest Length
Highest value of the queue length recorded.
Length
Total number of documents currently in the client queue, including documents not
yet retrieved by client programs and documents retrieved but not yet
acknowledged by client programs.
Session metrics
The following metrics are available for under the Session sub-node for the individual
Last Connect
Session identifier for the most recently established client session.
Last Disconnect
Session identifier for the most recent client session that disconnected from the
Broker.
Last Retrieved
Session identifier for the client session that most recently retrieved a document
from this client queue.


Metrics for Document Types
Documents are the messages that travel over a network from a publisher to subscriber,
through the Broker. Each individual document is an instance of a document type. Each
document type has a unique name and properties associated with it, such as its
document folder name, when it was created, how many times it has been published and
retrieved by Broker clients, and the number of subscriptions.
the Document Types sub-node for individual document types:
Number of Client Subscriptions
Total number of subscriptions to this document type by clients on the selected
Broker.
Number of Events Delivered
Total number of documents of the selected document type delivered by the
selected Broker.
Number of Events Published
Total number of documents of the selected document type published to the
selected Broker.
Number of Forwards Received
Total number of documents of the selected document type that were forwarded
from another Broker in the same territory.
Number of Groups Can Publish
Total number of client groups that can publish the selected document type.
Number of Groups Can Subscribe
Total number of client groups that can subscribe to the selected document type.
Metrics for the Retry Queue
The webMethods Broker Retry Queue displays statistics for an internal queue that
Broker uses to store requests that it must retry. These statistics are typically used by
support personnel for troubleshooting purposes.
the Retry Queue sub-node:
Current Events
Number of documents to be delivered currently in the Retry Queue.
Current Publishes
Number of documents to be published currently in the Retry Queue.


Maximum Events
Maximum number of documents to be delivered that can be held in the Retry
Queue.
Maximum Publishes
Maximum number of documents to be published that can be held in the Retry
Queue.
Next Operation Sequence Number
Sequence number that identifies the next request to be retried.
Number of Attempts
Number of times the Broker has attempted to deliver a document from the Retry
Queue.
Reserved Guaranteed Events
Number of documents marked for guaranteed delivery for which space is reserved
in the Retry Queue.
Reserved Total Publishes
Total number of documents to be published for which space is reserved in the Retry
Queue.
Reserved Volatile Events
Number of volatile documents to be delivered for which space is reserved in the
Retry Queue.
Reserved Volatile Publishes
Number of volatile documents to be published for which space is reserved in the
Retry Queue.
Metrics for Territory Stats
The webMethods Broker territory statistics provide information events and queues by
territory. These statistics describe the number of events placed in the queue,
forwarded, and received and the queue size and length for each territory.


the Territory Stats > <territory_name> > Events sub-node:
Number Enqueued
Number of document delivery events placed in the queue for the territory.
Number Forwarded
Number of document delivery events forwarded for the territory.
Number Received
Number of document delivery events received for the territory.
the Territory Stats > <territory_name> > Queue sub-node:
Byte Size
Total size in bytes of the queue for the selected territory.
Highest Length
Highest value of the queue length recorded for the territory.
Length
Total number of documents currently in the queue for the territory, including
documents not yet retrieved by client programs and documents retrieved but not
yet acknowledged by client programs.
Metrics for the Trace queue
The webMethods Broker Trace queue is a temporary storage area where trace events
are stored. Trace events are raised in response to publish or acknowledgement triggers
on Integration Server. Because it is an internal queue activity events and trace events,
statistics for the Trace queue are typically used by support personnel for
troubleshooting purposes. The following metrics are available for the Broker instances
you are monitoring under the Trace sub-node:
Number of Events Queued
Total number of documents in the Trace queue for the selected Broker.
Queue Byte Size
Total size in bytes of the Trace queue for the selected Broker.
Queue Length
Number of items in the Trace queue for the selected Broker.
View Default Broker Metric Groupings


Metrics for Utilization
The following metrics are available for configuration (CONFIG) and run-time (DATA) data
storage for the Broker server under the Utilization > Storage Statistics sub-node:
Current KB Reserved
Size, in KB, that is reserved for the selected storage file.
Current KB in Use
Current size, in KB, of the selected storage file.
Maximum KB Available
Maximum size, in KB, to which the selected storage file is allowed to grow.
Maximum Transaction (KB)
Maximum transaction size, in KB, for the Broker Server.
Session URL
Location and type of storage facility configuration.
The metrics under Utilization > Storage Statistics are divided into CONFIG and DATA
storage. The CONFIG metrics describe the data storage required to define Broker
servers, territories, Brokers, document types, and statistics. The DATA metrics describe
the data storage required for client queues, documents, and logs. Similar metrics are
also available for the individual configuration and data storage file names for the Broker
server under the File Statistics > <file_name> sub-node.
View Default Broker Metric Groupings
The SOA extension for webMethods includes default metric groupings that are used to
define the default dashboards and alerts. You can also use these default metric
webMethods Broker as part of the webMethods Broker Management Module
(WebMethodsBrokerManagementModule.jar).
You can view the default metric groupings using the CA Introscope Workstation
Management Module Editor. You can also extend the webMethods Broker Management
Module to include custom metric groupings or use the default metric groupings in
custom dashboards or alerts.
View Default Broker Alerts


To view the default metric groupings for webMethods Broker agents
WebMethodsBrokerManagementModule (*Super Domain*).
the webMethods management module.
View Default Broker Alerts
The SOA extension for webMethods includes default alert definitions that are used in
the preconfigured dashboards. You can also use these default alerts in custom
severity increases.
webMethods Broker as part of the webMethods Broker Management Module
(WebMethodsBrokerManagementModule.jar).
You can view the default alert definitions using the CA Introscope Workstation
Management Module Editor. You can also extend the webMethods Broker Management
Module to include custom alert definitions and notification types or use the default alert
definitions in custom dashboards.
To view the default alert definitions for webMethods Broker agents
WebMethodsBrokerManagementModule (*Super Domain*).
3. Expand the Alerts node to view all of the alerts defined for the webMethods Broker
management module.
In particular, you should review the default settings for Caution and Danger
thresholds and adjust the values, if necessary, and add notifications or corrective
actions.


Chapter 11: Monitoring webMethods
Integration Server

The Software AG webMethods product suite is a SOA platform that consists of multiple
infrastructure components and features to enable organizations to create, orchestrate,
and integrate business processes and web services. The SOA extension for webMethods
enables you to monitor many key elements of the webMethods infrastructure.
This section describes webMethods services and the related dashboards and metrics
you can use to monitor and analyze the health and operation of the webMethods
Integration Server.
About webMethods Integration Server (see page 247)
How to Enable Monitoring for webMethods Integration Server (see page 250)
Use Dashboards to Monitor webMethods (see page 253)
Filtering the services monitored and displayed (see page 258)
View and Navigate Metrics for webMethods (see page 260)
Viewing default webMethods metric groupings (see page 274)
Viewing default webMethods alerts (see page 275)
Viewing webMethods dependencies (see page 276)
Tracing transactions for webMethods (see page 277)
About webMethods Integration Server
The webMethods Integration Server enables companies to expose and integrate new
and existing business services. It includes tools that enable you to design, test, and
deploy new services, and automate, orchestrate, and assemble loosely-coupled services
and legacy systems into improved business processes.
The webMethods Integration Server provides a centralized platform for running and
distributing services. It receives and interprets client requests, identifies and invokes the
requested services, passes data to running services in the expected format, receives the
output produced by the services, and returns output to the clients.
As an integration platform, webMethods is used primarily for coordinating operation
between application servers, databases, and custom applications and enabling
companies or trading partners to exchange electronic documents.


You can monitor the operation of webMethods Integration Server with metrics for the
following top-level components:
Adapters
Adapters enable external applications to integrate with webMethods through a
common adapter framework of service interfaces. Adapters consist of:
Adapter Connections that enable Integration Server to connect to the external
resources or systems at run-time.
Adapter Services that run on Integration Server initiate operations on the external
resource.
Adapter Notifications that monitor the external resource and notify the Integration
Server when an event not initiated by the Integration Server has occurred.
With the SOA extension for webMethods, you can monitor the performance and
overall health for all adapters you have depolyed for webMethods Integration
Server using the metrics under the Adapter Connection Pools, Adapter Services, and
Adapter Notifications nodes.
Business Processes
A business process is a series of interrelated business tasks that are performed in a
specific order, using a specific set of business rules. Most business processes also
require the interaction of multiple systems and multiple people in different roles.
For example, you may have business processes for preparing for a new employee,
handling a purchase order, or, delivering invoices. Each business process then might
include business tasks such as assigning office space for the new employee, adding
the employee to the Human Resources (HR) system, and ordering office equipment
and supplies.
overall health for the business processes your have defined using the metrics under
the WebMethods > Business Processes node.
Flow Services
Flow Services are services written in webMethods Flow language and deployed on
the webMethods Integration Server. Flow services can invoke any service running
on the webMethods server, including other flow services, user-defined services,
built-in services, and services from other providers such as webMethods Adapters
or .NET Plug-in.
overall health for all flow services or filter the flow services to exclude flow services
you are not interested in monitoring. Metrics for the individual flow steps in a flow
service as listed under the WebMethods > Flow Services node.


Java Services
Java Services are built-in and user-defined services written in Java, or written in
other languages and wrapped using a Java class, and exposed as services on the
webMethods Integration Server.
overall health for all Java services or filter the Java services to exclude the Java
services you are not interested in monitoring. Metrics for the Java methods in each
Java class are listed under the WebMethods > Java Services node.
JDBC Connection Pools
The webMethods Integration Server uses Java database connections to
communicate and transfer information over the network.
With the SOA extension for webMethods, you can monitor the availability of JDBC
connections using the metrics under the WebMethods > JDBC Connection Pools
node.
Thread Pools
The webMethods Integration Server uses threads to execute services, retrieve
documents from the webMethods Broker, and execute triggers.
With the SOA extension for webMethods, you can monitor the availability of
threads using the metrics under the WebMethods > Thread Pools node.
Trading Networks
Trading networks enable organizations to exchange documents to establish and
enrich business-to-business relationships.
With the SOA extension for webMethods, you can monitor document recognition
and processing using the metrics under the WebMethods > Trading Networks node.
Triggers
Triggers establish subscriptions to publishable document types and specify how to
process instances of those documents.
A Broker or Local trigger is a trigger that subscribes to and processes documents
published locally on the Integration Server or delivered to the Broker. Broker
Triggers are often associated with asynchronous Adapter Notifications.
A JMS trigger is a trigger that receives messages from a destination (queue or topic)
on a JMS provider and then processes those messages.
With the SOA extension for webMethods, you can monitor triggers using the
metrics under the WebMethods > Triggers node.
How to Enable Monitoring for webMethods Integration Server


WebServices
WebServices metrics represent client and server business service endpoint and
associated operations within each service.
overall health of client and server web service endpoints under the WebMethods >
WebServices node.
XSLT Services
Within webMethods, you can use XSLT stylesheets to transform XML data into
different formats and include the transformation in other services.
overall health of XSL transformations under the WebMethods > XSLT Services node.
As the administrator, you enable monitoring for webMethods Integration Server by
performing the following high-level steps:
1. Verify that you have webMethods Integration Server installed.
Note: For webMethods Integration Server requirements, see the Compatibility
Guide.
2. Verify whether you have a supported version of the webMethods WmPRT.jar file.
Open the following URL in a web browser. Verify the version level listed.
http://<Integration_Server_Hostname>:<port_number>/WmRoot/Updates.dsp
3. Verify that the agent and CA APM for SOA are installed and enabled.
4. Enable the agent to use CA APM for webMethods Integration Server by configuring
the agent profile.
Important! Skip this step if you enabled CA APM for webMethods Integration
Server in the agent using the Standalone agent installer or using a response file.
5. Enable the Enterprise Manager extension (see page 253).
More information:
Manually Enable the Agent for Monitoring webMethods Integration Server (see page
251)



Manually Enable the Agent for Monitoring webMethods Integration Server
You can enable monitoring for webMethods Integration using one of the following
methods:
Select CA APMfor webMethods Integration Server when you install the agent.
The agent profile is automatically configured with default settings. No further steps
are required.
Do not select CA APM for webMethods Integration Server when you install the
agent. Configure the agent profile manually using the following procedure.
Note: For webMethods Integration Server requirements, see the Compatibility
Guide.
Follow these steps:
1. Verify that the default agent and CA APM for SOA are installed and enabled.
2. Verify that the CA APM for webMethods Integration Server directory is in the
<Agent_Home>/examples directory.
3. Copy the files from the <Agent_Home>/examples/SOAExtensionForWebMethodsIS
directory to the corresponding <Agent_Home> directory.
For example, copy the files in
<Agent_Home>/examples/SOAExtensionForWebMethodsIS/ext to the
a. Add the webmethods.pbl, the default agent pbl, and spm pbl to the
introscope.autoprobe.directivesFile property in the IntroscopeAgent.profile
file. For example:
introscope.autoprobe.directivesFile=default-typical.pbl,hotdeploy,spm.pbl
,webmethods.pbl
Note: You can customize tracing using the ProbeBuilder directive files for
webMethods Integration Server (see page 252).
b. Set the introscope.agent.agentName property value to webMethods Agent. For
example:
introscope.agent.agentName=webMethods Agent
This step ensures that only webMethods data is displayed in dashboards.
c. Modify any additional properties in the IntroscopeAgent.profile file if you want
to change the default settings.


d. Save and close the IntroscopeAgent.profile file.
5. Only valid for webMethods Integration Server 7.x, perform the following edits in
the <Agent_Home>/core/config/webmethods-toggles.pbd file:
a. Uncomment the BProcAndStepTracing71 flag in the Business Processes section.
Turn on BProcAndStepTracing71 flag.
Turn off BProcAndStepTracing80 flag.
Turn off BProcAndStepTracing82 flag.
b. Uncomment the following options in the Web Services section:
Turn off WM8xWebServicesTracing flag.
Turn on WM7xWebServicesTracing flag.
Turn off WebMethods8xWSClientTracing flag.
Turn on WebMethods7xWSClientTracing flag.
Turn off WebMethods65WSClientTracing flag.
c. Save and close the webmethods-toggles.pbd file.
6. Restart the webMethods Integration Server process.
About the Directive Files for webMethods Integration Server
IntroscopeAgent.profile, you enable the default instrumentation for webMethods
Integration Server. You can then customize the ProbeBuilder directives in either
webmethods.pbd or webmethods-toggles.pbd if you want to modify the default
monitoring. For example, you can use the toggles file to fine-tune monitoring for specific
components by turning on or turning off tracing for specific tracer groups.
webmethods.pbd
Monitors key services on the webMethods Integration Server, including flow
services, Java services, trading networks, web services, XSLT services, and business
processes.
webmethods-toggles.pbd
Toggles for turning on or turning off the monitoring of webMethods Integration
Server components.
webmethods.pbl
Provides the default list of ProbeBuilder directive files for monitoring webMethods
Integration Server:
webmethods.pbd
webmethods-toggles.pbd
Use Dashboards to Monitor webMethods


CA APM for webMethods Integration Server files are installed by default in the
<EM_Home>/examples/SOAExtensionForWebMethodsIS directory when you install the
Enterprise Manager. To enable CA APM for webMethods Integration Server, you need
to copy or move the Enterprise Manager files for webMethods Integration Server from
the <EM_Home>/examples directory to the proper location in the Enterprise Manager
home directory.
Note: CA APM for SOA must be enabled on the Enterprise Manager (see page 37) before
you can use CA APM for webMethods Integration Server.
Follow these steps:
1. Verify the CA APM for webMethods Integration Server directory,
SOAExtensionForWebMethodsIS, is in the <EM_Home>/examples directory, then
copy the files from the <EM_Home>/examples/SOAExtensionForWebMethodsIS
directory to the corresponding location in the Enterprise Manager directory
structure. For example, copy the files from the
<EM_Home>/examples/SOAExtensionForWebMethodsIS/ext directory to the
2. Remove the webMethods Integration Server Management Module,
WebMethodsISManagementModule.jar, from the <EM_Home>/config/modules
directory if the Enterprise Manager is a Collector in a clustered environment.
to CA APM for webMethods Integration Server.
The SOA extension for webMethods Integration Server includes several preconfigured
dashboards that you can use to monitor the overall health of the application
environment. Dashboards aggregate data across deployed agents to summarize
performance information and help you rapidly diagnose and resolve problems.


components of webMethods Integration Server at-a-glance.
been crossed.
Drill-down into performance information to isolate and identify which webMethods
Integration Server business processes, services, or connection pools are
The preconfigured webMethods dashboards are packaged in the Enterprise Manager
extension for webMethods as part of the webMethods Integration Server Management
Module (WebMethodsISManagementModule.jar).
The webMethods Management Module provides the following preconfigured
dashboards for webMethods Integration Server:
WebMethods - Home
A top-level architectural overview of WebMethods Integration Server and its key
components, including alert indicators for the overall health of all services, business
processes, trading network components, and external backend systems.
WebMethods - IS Services Overview
Summarized status for flow, Java, and XSLT services, and triggers, including graphs
for Average Response Time, alert indicators for errors and stalls.
From this dashboard, you can double-click the IS Slowest Services link or any Overall
Health label to display the WebMethods - IS Slowest Services dashboard, which lists
of the slowest flow, Java, and XSLT services, and a list of the slowest triggers.
WebMethods - Business Processes
Summarized status for all business processes, including graphs of the Average
Response Time and Errors Per Interval at both the process and step level.
The dashboard includes alert indicators for cancelled, restarted, suspended, and
resumed operations at the process level; alert indicators for response time, stalls,
concurrent invocations, and errors at the step level; and a list of the slowest
business processes.


WebMethods - WebServices Overview
Summarized status for all client- and server side web services, including graphs of
the Average Response Time to highlight client-side and server-side performance,
lists of the slowest client-side and server-side services, and alert indicators for
response time, SOAP faults, errors, and stalls for client and server services.
From this dashboard, you can double-click the Web Service Operations link or any
Overall Health label or graph to display the WebMethods - Web Service Operations
dashboard, which includes graphs of the Average Response Time for client-side and
server-side operations, alert indicators for SOAP faults and stalls, and lists of the
slowest client-side and server-side web service operations.
WebMethods - Adapters
Summarized status for all webMethods adapters, including graphs of the Average
Response Time for all adapter services, adapter notifications, and external backend
systems.
For adapter services, the dashboard also displays:
graphs for Errors Per Interval and Stall Count
alert indicators for concurrent invocations, errors, and stalls
a list of the slowest adapter services
For adapter notifications and external backends, the dashboard also displays alert
indicators for errors and stalls.
WebMethods - Trading Networks
Summarized status for all document processing handled by Trading Networks,
including graphs of the Average Response Time and Errors Per Interval for all
document types and processing rules, alert indicators for errors and stalls, and a list
of the slowest documents processed.
WebMethods - Connection and Thread Pools
Summarized status for adapter connection pools, JDBC connection pools, and
thread pools, including graphs for the number of available connections and the
current pool size for adapter connections and JDBC connections, and graphs for the
number of threads in use and the maximum number of threads in the thread pool.
also extend the webMethods Integration Server Management Module to include
custom dashboards or modify the default dashboard definitions to include custom
metrics or alerts.


Follow these steps:
extension for webMethods is installed.
4. Select one of the webMethods dashboards from the Dashboard drop-down list.
For example, select the WebMethods Home dashboard to see an overview of
webMethods key components and internal workflow.



5. Double-click another tab or an alert in the dashboard to open the related
dashboard to view more detailed information.
For example, double-click a Java Services alert to see more detailed information
about the overall health of webMethods Integration Server flow, Java, and XSLT
services in the WebMethods - IS Services Overview dashboard:

Filtering the services monitored and displayed


6. From the WebMethods - IS Services Overview dashboard, you can double-click IS
Slowest Services to display lists of the slowest individual flow, Java, XSLT, and
trigger services. For example:

7. Double-click a specific service, business process, or document metric in a dashboard
to open the Investigator for further analysis.
From the WebMethods - IS Slowest Services dashboard, for example, you can
double-click the slowest flow service to open the Investigator with that services
Average Response Time selected.
For the webMethods Integration Server, you can control which flow or Java services are
monitored and included in the Investigator tree by specifying filters in a configuration
file. The default configuration file is wmExtension.config. By editing this file, you can
create filters using regular expressions that identify the flow services you want to
include or exclude from monitoring.


About the Default Configuration File
The default configuration file, wmExtension.config, is located in the
<Agent_Home>/common directory and is configured with default include and exclude
filters. For example, the following default filter is defined to exclude webMethods
built-in services:
com.wily.wm.service.filter.exclude=wm.*,pub.*
The configuration file also provides the following default filter to include matching
webMethods services:
com.wily.wm.service.include=wm.tn:receive,wm.tn.route:routeBizdoc,pub.prt.tn:hand
leBiZDoc
You can modify the default configuration file to include or exclude additional services, as
needed, or remove the default filters if you want to monitor all webMethods services,
including the built-in services. If no filters are defined in the wmExtension.config file, all
services, including built-in services, are displayed in the Investigator tree.
Including and excluding services using regular expressions
Within the wmExtension.config configuration file, you can use the
com.wily.wm.service.filter.include and com.wily.wm.service.filter.exclude properties to
identify the services you can to include or exclude. For example, you can set the
com.wily.wm.service.filter.exclude property with a regular expression that defines the
service you want to exclude from monitoring. The include and exclude properties can
have any expression applicable for the fully-qualified name of the service. For example,
to exclude all flow services that end up with the string webservice, set the exclude
property like this:
com.wily.wm.service.filter.exclude=.*webservice
To define multiple filters, use a comma to separate the regular expressions. For
example, to exclude all flow and Java services that start with wm.server and wm.tomcat,
you can set the com.wily.wm.service.filter.exclude property like this:
com.wily.wm.service.filter.exclude=wm.server.*,wm.tomcat.*
All flow and Java services matching the regular expression are excluded and only the
remaining services are displayed in the Investigator. If you specify a regular expression
that is not valid, however, no services are excluded from monitoring and all flow and
Java services, including built-in services, are displayed.
View and Navigate Metrics for webMethods


Specifying a Different Location for the Configuration File
Although the default wmExtension.config file is located in the <Agent_Home>/common
directory, you can specify another directory or a different configuration file by
specifying a different location in the start-up script for the server. For example, if an
alternate wmExtension.config file is located in the directory C:\CA-Introscope, you can
add the com.wily.wm.service.filter.fileloc property to the Java arguments in the start-up
script for the server:
set JAVA_OPTS=%JAVA_OPTS% -Dcom.wily.wm.service.filter.fileloc=C:\CA-Introscope
If a file named wmExtension.config exists in the specified path, the agent checks for the
include and exclude properties in that configuration file to determine which flow and
Java services to monitor.
If the path to the configuration file is specified in the Java arguments of the server, the
agent uses the filters specified in that file to determine the flow and Java services to
exclude. If the path to the configuration file is not specified, the agent uses the filters
defined in the <Agent_Home>/common/wmExtension.config file. If the
<Agent_Home>/common/wmExtension.config or alternate wmExtension.config file is
not found, no filtering is done and all flow and Java services, including built-in services,
are displayed.
metrics for most components of the webMethods Integration Server infrastructure.
Data for the standard metrics is collected and aggregated into webMethods-specific
metric categories displayed as nodes and sub-nodes in the Investigator tree. The specific
metric categories and node names displayed depend on the processes, services, and
resources you have deployed in your environment.
As you navigate through the Investigator tree, you can choose to view low-level metrics
for individual operations or aggregated metrics depending on the node you select,
enabling you to monitor the overall health of various services you have deployed
through the webMethods Integration Server.
To view and navigate webMethods metrics in the Investigator
1. Expand the agent node, then click the WebMethods node to display the Overview
tab, which lists summary information with the standard CA Introscope metrics for
all of the webMethods flow services and business processes you are monitoring.
2. Select a flow service or business process in the list to view all the standard metrics
for that service or process in a graphical format.
3. Expand the WebMethods node to display sub-nodes for the top-level metric
categories for webMethods Integration Server.


about that metric category. For example, click the Java Services node to display
summarized metrics for Java services on the Overview tab.
5. Expand any sub-node to see more detailed information about individual business
processes, flow services, Java services, or connection pools and the metrics
associated with each.
For example, you can expand the Flow Services node, then a specific flow service
name and subfolder to display the metrics for an individual flow service.
Metrics for Adapters
Default webMethods adapters provide seamless connectivity to information resources
and enterprise applications that help organizations achieve real-time execution of
business processes. Adapters enable organizations to use webMethods to connect to
packaged applications, such as SAP and Oracle application suites, or databases, such as
Microsoft SQL Server and Oracle RDBMS, with minimal custom programming or
time-consuming integration development. The specific adapters available for you to
deploy depend on the version of webMethods Integration Server you are using.
The metrics for adapters provide detailed information about the specific adapters you
have deployed and enable you to monitor the connections, operations, and events
associated with those adapters.
You can monitor adapters using the metrics in the following metric categories under the
WebMethods node:
Adapter Connection Pools
Adapter connections enable the Integration Server to connect to the external
application or information store at run-time.
Adapter Notifications
Adapter notifications allow you to monitor the external resource and notify the
Integration Server when an event initiated by the resource occurs. An adapter
notification publishes a document to the webMethods Broker when the event
occurs.
Adapter Services
Adapter services allow you to use the adapters connection to the external resource
to initiate an operation on the resource from the Integration Server.
For example, webMethods provides a JDBC Adapter to deliver a set of user interfaces,
services, and templates that enable you to create integrations with databases using a
JDBC driver. You can monitor the connections to the database using the metrics in the
Adapter Connection Pools category.


JDBC Adapter services enable the Integration Server to initiate and perform database
operations, such as insert, update, or delete data, on the database. Adapter
notifications enable you to monitor the database and notify the Integration Server when
an update, insert, or delete has occurred on a particular database table.
For example, an adapter service could enable a trading partner to query your inventory
database to determine whether a particular item is currently in stock. And an adapter
notification could notify the Integration Server when an update was performed on
inventory database table.
To view and navigate adapter-related metrics in the Investigator:
1. Expand the agent node, then expand webMethods to display the adapter metric
categories.
2. Expand WebMethods > Adapter Connection Pools, then expand a specific adapter
name to view connection information for that adapter.
3. Expand WebMethods > Adapter Notifications, then expand a specific adapter name
to view notification information for that adapter. If you have not configured any
notifications for adapters, this metric category is not displayed.
4. Expand WebMethods > Adapter Services, then expand a specific adapter type to
see the list of active connections.
5. Expand an active adapter connection to see the list of adapter services running on
the Integration Server.
6. Expand an individual service to see the metrics for the service.
Metrics for Adapter Connection Pools
The following metrics are available for the adapters you have configured under the
WebMethods > Adapter Connection Pools sub-nodes for individual adapter names:
Available Connections
Number of free connections available for the adapter.
The available connections is calculated by subtracting the number of busy
connections from the number of currently active connections. As the server tries to
connect to the resource multiple times, the number of available connections
decreases.
Current Size
Total number of currently active connections.
Maximum Size
Maximum number of connections allowed for the selected adapter.
Minimum Size
Minimum number of connections configured for the selected adapter.


Metrics for Adapter Notifications
If you have configured adapter notifications, a polling process or a listener process
monitors the external resources for changes, such as an insert, update, or delete
operation on a database table, so that the appropriate flow or Java services can react to
the change.
For example, if you have deployed an adapter service to enable a trading partner to
query the inventory database, you can configure an adapter notification to notify the
Integration Server anytime an update is performed on inventory database table. To
process a document associated with the notification, for example, to send an invoice
based on the adapter notification, you can configure an Integration Server trigger.
All of the standard CA Introscope metrics are available for adapter notifications under
the WebMethods > Adapter Notifications sub-nodes for individual adapter service
names.
Metrics for Adapter Services
All of the standard CA Introscope metrics are available for adapter services under the
WebMethods > Adapter Services sub-nodes for individual adapter connection service
names.
The Errors Per Interval metric only includes errors that occur when the adapter service is
executed. It does not include AccessExceptions or any other type of errors that occur
before the service is executed.
Metrics for Authorization
The webMethods Integration Server typically includes multiple user groups with specific
Access Control Lists (ACLs) that define the permissions different users are granted. For
example, there are default permissions assigned to groups such as Administrators,
Developers, Monitor Users, and Replicators. You can also create your own user groups
and permissions, as needed. If users try to execute Integration Server services they do
not have permission to access, they are denied access and an error is recorded.
You can view information about authorization failures by selecting the Errors Per
Interval metric under the WebMethods > Authorization node.
Because the service is not invoked when the user is denied access, the error is not
recorded in the services Errors Per Interval metric. However, you can also view Access
Exception errors by clicking the Errors tab in the Investigator. Select the error in the list
to display detailed information about the error in the Error Snapshot.


Metrics for Business Processes
Business processes consist of a series of steps that complete a business event, such as
placing an order or adding a new employee.
Only the following standard CA Introscope metrics are available for webMethods
business processes and business process steps under WebMethods > BusinessProcesses
> <business_process_name> nodes:
Errors Per Interval
At the business process level, these metrics track the time the process takes to
complete successfully, the number of processes that completed successfully, and the
number of processes that generated errors and failed. For distributed processes, the
Average Response Time and Responses Per Interval at the process level are displayed
only for the agent where the last step of the business process is executed.
In addition to the standard metrics, the following metrics are available for business
processes:
Cancels Per Interval
Number of processes cancelled in the interval.
Suspends Per Interval
Number of processes suspended in the interval.
Restarts Per Interval
Number of processes that restarted in the interval.
Resumes Per Interval
Number of processes that resumed in the interval.
You can also collect dependency and deviation metrics for webMethods Integration
Server business processes. For information about the standard dependency and
deviation metrics, see Using Investigator to view SOA performance metrics (see
page 52).


View Step-Level Metrics for Business Processes
By default when you are monitoring webMethods Integration Server, all the standard
CA Introscope metrics are also available for business process steps as follows:
WebMethods > BusinessProcesses > <business_process_name> > <step_identifier>
nodes
Valid for webMethods Integration Server 6.5.2 through 6.5.3: Step-level metrics are
only displayed for single-level steps. Other step-level metrics, for example, metrics for
human task steps that are executed internally as more than one step, referenced
process, subprocess, or flow service steps, are not aggregated by default.
To get full step-level metrics for business processes when you are monitoring
webMethods Integration Server versions 6.5.2 through 6.5.3, uncomment the following
lines in the webmethods-toggles.pbd file:
TurnOn: BProc<version_number>FlowStepMarkTracing
TurnOn: BProc<version_number>StepFlowTracing
Note: For webMethods Integration Server requirements, see the Compatibility Guide.
Follow these steps:
1. Expand the agent node, then expand webMethods > Business Processes.
The business process that you have defined in the webMethods Designer and
deployed as packages in your environment display.
To differentiate between the different versions of business processes running, an
underscore (_) and a version number are appended to the business process name.
2. Expand any process name.
The steps that you have defined for that process appear.
3. Expand any step identifier (StepID).
The step-level metrics and flow services metrics that represent the step on the
Integration Server appear.


About Average Response Time for completed processes
It is possible for webMethods business processes to be canceled or suspended during
execution from My WebMethods Server. Processes that are canceled or suspended
using My WebMethods Server can also, in many cases, be resumed manually from My
WebMethods Server. Because these process can be resubmitted from My WebMethods
Server and run to completion, the Average Response Time metric at the process level
only represents processes that complete successfully.
If a process fails or is suspended and is resubmitted from within My WebMethods
Server, the Average Response Time metric reflects the time between the initial
invocation of the process and its successful completion after being resubmitted. If a
process fails and is not resubmitted using My WebMethods Server, it is not included in
the Average Response Time metric. However, if the process is cancelled as part of its
process flow, for example, using a Terminate step, it is included in the Average
Response Time metric.
If more than one Integration Server is involved in the business process, the Average
Response Time metric is only reported for the Integration Server where the business
process finishes.
About Responses Per Interval for completed processes
The Responses Per Interval metric reflects the number of processes that completed
successfully. If more than one Integration Server is involved in the business process, the
Responses Per Interval metric is reported only for the Integration Server where the
business process finishes.
About Errors Per Interval for failed processes
The Errors Per Interval metric is only shown when a process fails to run to completion.
About Concurrent Invocations for steps in a process
Some types of steps, such as SubProcess, Referenced Process, and Human Task steps,
are executed internally as more than one step even though they are presented as a
single step in the webMethods Designer. For example, Human Task steps are executed
internally as two steps, PRE_StepID and POST_StepID. The Concurrent Invocations
metric counts these internal steps as individual invocations rather than aggregating
them into a single step.


Metrics for Flow Services
Flow Services are services written in webMethods Flow language. A flow service consists
of a series of flow steps, each with clearly defined input and output. Each flow step is a
basic unit of work that webMethods interprets and executes at run time. All the flow
steps in a particular service are executed using the same thread so that the output of
one step is available as input to the next step in the flow.
All of the standard CA Introscope metrics are available for individual webMethods flow
services under the WebMethods > Flow Services node. Data is collected for individual
flow steps and aggregated into metrics for a flow service and across flow services to
monitor the overall health of all flow services on the Integration Server.
The node names displayed are the fully-qualified names of the services you have chosen
to monitor that have not been excluded using filters. For information about filtering the
flow services to you are interested in monitoring, see Filtering the services monitored
and displayed (see page 258).
Flow Services That Call Other Flow Services
In most cases, all of the standard CA Introscope metrics and their corresponding
aggregated metric values apply to webMethods flow services in the same way they
apply to other application components.
If one flow service calls another flow service, metrics for both of these flow services are
displayed as separate nodes under the WebMethods > Flow Services node in the
Investigator tree. They are not nested with one node under the other.
To see all of the flow steps executed on the same webMethods Integration Server in
calling sequence, you can start a transaction trace session.
Metrics for Java Services
Java services can be any user-defined or internal, built-in webMethods services that are
implemented using the Java language, or written in other languages and wrapped using
a Java class, and exposed as services on the webMethods Integration Server. For
example, all of the built-in services that webMethods Integration Server provides are
Java services.
All of the standard CA Introscope metrics are available for the individual webMethods
Java services you have deployed under the WebMethods > Java Services node.


In webMethods, Java services that reside in the same folder are methods of the same
class. For example, a Java service with the fully-qualified name of
recording.user.accounts:createAccount consists of the Java package (recording.user),
Java class (accounts), and Java method (createAccount). The node names displayed in
the Investigator represent the fully-qualified names of the services you have chosen to
monitor and not excluded using filters.
For information about filtering the Java services to you are interested in monitoring, see
Filtering the services monitored and displayed (see page 258).
Metrics for JDBC Pools
The webMethods Integration Server collects and stores information about users,
documents, internal server functions, audit and error logs, and other information by
connecting to databases through JDBC connection points. The maximum number of
JDBC connections allowed in the JDBC pool can be configured using the Integration
Server Administrator.
The following metrics are available for monitoring JDBC usage under the
WebMethods > JDBC Pools sub-nodes for individual thread pool names:
Available Connections
Number of available connections for the JDBC pool.
The available connections is calculated by subtracting the number of busy
connections from the number of currently active connections.
Current Size
Total number of currently active JDBC connections.
Maximum Size
Maximum number of JDBC connections configured for the selected pool.
Minimum Size
Minimum number of JDBC connections configured for the selected pool.
Metrics for Thread Pools
The webMethods Integration Server uses threads to execute services, retrieve
documents from the webMethods Broker, and execute triggers. When the server starts,
the thread pool initially contains the minimum number of threads. The server adds
threads to the pool as needed until it reaches the maximum allowed. If the maximum
number of threads are in use, the server waits until processes complete, then returns
threads to the pool before beginning more processes.


The following metrics are available for monitoring thread usage under the
WebMethods > Thread Pools sub-nodes for individual pool names:
Maximum Size
Maximum number of threads configured for the selected thread pool.
Minimum Size
Minimum number of threads configured for the selected thread pool.
Used Threads
Number of threads currently in use for the selected thread pool.
Metrics for Trading Networks
Trading networks enable organizations to exchange documents to establish and enrich
business-to-business relationships. For example, you can identify buyers, suppliers,
strategic partners or other organizations as trading partners with which you exchange
documents. By exchanging documents, you can streamline business processes that cross
organizational boundaries. With webMethods Integration Server, trading networks act
as the gateway between trading partners.
The following standard metric is available for webMethods trading networks under the
WebMethods > Trading Networks node:
Errors Per Interval
You can also monitor trading networks for XML document recognition and processing
rules with the following metric categories under the WebMethods > Trading Networks
node:
Document Types
Document types identify the structure and type of data to be exchanged in different
partner relationships.
Processing Rules
Processing rules describe how a document is routed through the Integration Server
and to its destination.
Service Execution Tasks
Service execution tasks are created when a processing rule executes the service
asynchronously with a retry limit.
Service Threads
Service threads are created to handle asynchronous processing for documents
being routed without a retry limit.


For example, you can expand the WebMethods > Trading Networks > Document Types
sub-node to view metrics for specific document types, including document recognition
and acceptance metrics for individual document type. Similarly, you can expand the
WebMethods > Trading Networks > Processing Rules sub-node to view metrics for
specific processing rules, including metrics for individual pre-routing and routing
operations.

Metrics for Document Types
trading networks under the WebMethods > Trading Networks > Document Types node:


The Average Response Time and Responses Per Interval metrics for Document Types are
aggregated when documents are processed. These metrics are only reported when
processing rules are executed. If a document is submitted, but not processed by any
processing rules, the Average Response Time and Responses Per Interval metrics are not
reported.
In addition to the standard metrics, the following metric is available under the
WebMethods > Trading Networks > Document Types node when valid documents are
submitted:
Recognitions Per Interval
Number of documents recognized as valid trading partner documents at the end of
a 15-second interval.
For the individual document types recognized, all of the standard CA Introscope
metrics are available under the WebMethods > Trading Networks > Document Types >
<document_type_name> node.
Metrics for Processing Rules
trading networks under the WebMethods > Trading Networks > Processing Rules >
<processing_rule_name> sub-nodes for individual processing rules:
All of the standard CA Introscope metrics are available for webMethods individual
processing rule operations under the WebMethods > Trading Networks > Processing
Rules > <processing_rule_name> > PreRoute or Route Actions sub-nodes for the specific
operations in a processing rule.
About Average Response Time for Processing Rules
The Average Response Time metric for a processing rule aggregates the average
response time taken for routing the document synchronously. For synchronous
invocations in a processing rule, the metric is the same as the aggregated Average
Response Time for Document Types.


Metrics for Service Execution Tasks
The following metrics are available for webMethods trading networks under the
WebMethods > Trading Networks > Service Execution Tasks sub-node:
New Tasks Per Interval
Task Failures Per Interval
Tasks Completed Per Interval
In addition, the following standard CA Introscope metrics are available for individual
invocation operations under the WebMethods > Trading Networks > Service Execution
Tasks > invoke sub-node:
Metrics for Service Threads
The following standard CA Introscope metrics are available for webMethods trading
networks under the WebMethods > Trading Networks > Service Threads sub-node:
Metrics for Triggers
You can configure Integration Server triggers to use webMethods Broker or the Java
Message Service (JMS) to process documents. A webMethods Broker trigger is a trigger
that subscribes to and processes documents that are published locally or delivered to
the webMethods Broker. A JMS trigger is a trigger that receives messages from a
destination, for example, a queue or topic, on a JMS provider then processes those
messages.
All of the standard CA Introscope metrics are available for triggers under the
WebMethods > Triggers sub-nodes for individual trigger names. If you have not
configured any Broker, local, or JMS triggers, this metric category is not displayed.
Metrics for WebServices
Web services are building blocks that are packaged as a unit and published to a network
so they are available to users or software programs.


Valid for a supported version of webMethods Integration ServerThe web service
connector defines whether the Integration Server is acting as a web service
consumer (client) or as a web service provider (server). For example, you can expose
any flow service or Java-based service you deploy externally as a web service. You
use a provider web service descriptor that publishes information about the service
to a UDDI registry. The webMethods Integration Server can also invoke web
services on external application servers using a consumer web service descriptor to
request service as a client.
Valid for webMethods Integration Server 6.5.2 through 6.5.3You can generate
web service connectors from WSDL documents to invoke remote web services. A
web service connector is a flow service that has an input and output signature. The
signature corresponds to the input and output messages from the WSDL document
from which it was created. With webMethods Integration Server, you can also use
Integration Server and Developer to turn any existing service in an Integration
Server package into a web service.
Note: For webMethods Integration Server requirements, see the CA APM Compatibility
Guide.
All the standard CA Introscope metrics are available for client and server web services
and operations on the webMethods Integration Server. In addition, the SOAP Faults Per
Interval is a standard metric for all extensions that monitor web services on SOA
platforms.
More information:
Viewing SOAP Fault and Error Metrics on the Errors Tab (see page 61)

About server-side metrics
As a web service provider, webMethods has multiple SOAP processors to handle web
service requests:
the default web services SOAP processor
the SOAP RPC processor to receive and process SOAP remote procedure calls
the default SOAP message handler to process messages when a process directive is
undefined or omitted
The server-side web service metrics include information for all three SOAP processors.
Custom SOAP processors are not included in the metrics, however.
Viewing default webMethods metric groupings


About client-side metrics
Client side metrics represent the execution of a web service request running on external
application server.
When the webMethods Integration Server acts as a web service consumer, it
automatically generates a web service connector for each operation. The client then
binds directly to the endpoint of the web service through the connector. When the web
service connector executes, the request to invoke the web service goes directly to the
web service implementation. Internally, web service connectors are flow services and
can be monitored using the Flow Services metrics.
The WebServices > Client metrics represent the execution of the connector calling the
external web service and not operations the client is requesting directly.
Server side metrics represent the execution of the web service running on the
webMethods Integration Server.
Metrics for XSLT Services
The Extensible Stylesheet Language (XSL) and XSL Transformations (XSLT) provide an
XML-based language for transforming source XML documents into other documents. For
example, the original XML document can be used to create a new XML document,
converted into HTML for display as a Web page, published as plain text.
When you invoke an XSLT service, the Integration Server retrieves the instructions in an
associated document, the stylesheet, then applies those instructions to transform the
source XML document into a new document in the format defined by the stylesheet.
All of the standard CA Introscope metrics are available for monitoring individual
webMethods XSLT services under the WebMethods > XSLT Services node.
Viewing default webMethods metric groupings
The SOA extension for webMethods Integration Server includes default metric
webMethods Integration Server as part of the webMethods Integration Server
Management Module (WebMethodsISManagementModule.jar).
Viewing default webMethods alerts


To view the default metric groupings for webMethods agents
2. Expand *SuperDomain* > Management Modules > WebMethods IS (*Super
Domain*).
the webMethods management module.
You can modify the default settings for any metric grouping or create your own
custom metric groupings.
Note: For more information about creating or modifying metric groupings, see the
CA APM Workstation User Guide.
Viewing default webMethods alerts
The SOA extension for webMethods includes default alert definitions that are used in
the preconfigured dashboards. You can also use these default alerts in custom
severity increases.
webMethods Integration Server as part of the webMethods Integration Server
Management Module (WebMethodsISManagementModule.jar).
To view the default alert definitions for webMethods agents:
2. Expand *SuperDomain* > Management Modules > WebMethods IS
(*Super Domain*).
3. Expand the Alerts node to view all of the alerts defined for the webMethods
Integration Server management module.
In particular, you should review the default Caution and Danger thresholds and
predefined actions for critical alerts and tune them for your environment. For example,
you may want adjust the threshold values, if necessary, add notifications, or define
corrective actions.
You can modify any of the default settings for any alert or create your own custom
alerts.
Viewing webMethods dependencies


Viewing webMethods dependencies
You can view dependencies for webMethods flow, java, adapter, and web services and
webMethods business processes by selecting an appropriate webMethods node in the
Investigator tree and clicking the SOA Dependency Map tab.
viewing. For example, for a top-level view of dependencies for all business processes,
you can select the Business Process node in the Investigator and click the SOA
Dependency Map tab:

To see a high level view of dependencies for a specific business process, you can select
the business process name in the Investigator and continue to add dependency levels to
the map to see the entire workflow for the business process or zoom in on specific
nodes of the map, as needed. For more detailed information about navigating the
dependency map, see Using the SOA Dependency Map (see page 65).
Tracing transactions for webMethods


completing a business transaction. For webMethods Integration Server business
processes or application services, you can trace transactions that include operations
routed through the following protocols:
webMethods Broker Message Service
Transactions that involve webMethods services can include synchronous and
asynchronous calls and activities running in parallel using different threads. To enable
transaction tracing for transactions that span multiple threads or processes, correlation
identifiers are inserted and consumed as a transaction steps through each component
and operation. You can then view detailed information about the specific operations
performed and the time each operation took to complete.
CA APM for SOA and CA APM for webMethods Integration Server are enabled at every
node being traced. This enables you to view details about the transaction even if the
transaction spans multiple JVMs or CLRs.
About Configuring Cross-Process Transaction Tracing
Typically, you can configure the cross-process transaction tracing feature by enabling
correlation information to be passed from one process to another. Information is passed
using either SOAP or HTTP headers. Valid for webMethods Integration Server version
6.5.2 through 6.5.3 -- you cannot use SOAP headers for passing correlation identifiers
when you are using RPC style web service clients (Connectors).
To see transaction traces for business transactions involving webMethods Integration
Server RPC Web Service Connectors, configure agents correlated tracing (see page 105)
to use HTTP headers for passing correlation identifiers.


how business processes are routed through flow or Java services.
which services are called and executed during a transaction.
You can start a transaction trace session in the following ways:
Session.
can select one of the following filter types for webMethods:
businessprocess
namespace
operationname
Viewer is displayed. You can select a trace to view additional details about the calls
made in the transaction. These details include any triggers, flow service operations, or
business process steps executed on a webMethods Integration Server.
Using the Sequence View for webMethods processes
Because transactions involving webMethods Integration Server often include
asynchronous calls, you may find it useful to click the Sequence View to view the
transaction workflow for the processes that executed asynchronously as part of a
transaction. The Sequence View displays the order in which process execute to the
extent the sequence can be identified. For webMethods Integration Server transactions,
the sequence does not necessarily represent a traditional caller-callee relationship, but
illustrates when one process triggers the execution of another process.


You should note, however, that the processing time for webMethods Integration Server
processes is calculated using the full duration from start to completion of the process,
which includes the processing time associated with its called processes. Net duration,
which subtracts the processing time for non-blocking synchronous and asynchronous
processes from the calling processs duration, is not supported for webMethods
Integration Server processes.
For more information about transaction tracing, see Using transaction tracing in SOA
environments (see page 89).
Note: For information about configuring tracing, see the CA APM Java Agent
Implementation Guide or the CA APM .NET Agent Implementation Guide. For more
information about working with transaction trace views and historical data, see the CA


Chapter 12: Monitoring WebSphere Process
Server and WESB

WebSphere Process Server (WPS) is a comprehensive service-oriented architecture
(SOA) integration platform that provides messaging and data management services to
help you integrate existing applications and develop and deploy new applications using
the Service Component Architecture (SCA). The SOA extension for WebSphere Process
Server (WPS) enables you to monitor key components of WebSphere Process Server,
such as the WebSphere Enterprise Service Bus (WESB), business service components,
and supporting services.
This section describes the WPS- and WESB-specific dashboards, metrics, and alerts you
can use for monitoring and analyzing the performance, availability, and overall health of
the WebSphere Process Server or WebSphere Enterprise Service Bus environment.
About WebSphere Process Server and WESB (see page 281)
How To Enable Monitoring for WebSphere Process Server or WESB (see page 285)
Using dashboards to monitor WPS or WESB (see page 292)
View and Navigate Metrics for WPS/WESB (see page 296)
Viewing default WPS and WESB metric groupings (see page 303)
Viewing default WPS and WESB alerts (see page 304)
Viewing WPS or WESB dependencies (see page 305)
Tracing transactions for WPS or WESB (see page 306)
About WebSphere Process Server and WESB
WebSphere Process Server (WPS) is a comprehensive service-oriented architecture
(SOA) integration platform that lets you integrate new and legacy applications and
deploy loosely coupled services to deliver business goals.
The WebSphere Process Server architecture consists of:
Service components
Supporting services
WebSphere Enterprise Service Bus messaging


Service components for WebSphere Process Server include business processes, business
state machines, business rules, and human tasks. Supporting services for WebSphere
Process Server include mediation flows, interface maps, business object maps, Java
components, Service Integration Bus (SIB) communications, business processes,
business state machines, relationships, selectors, and adapters. The WebSphere
Enterprise Service Bus (WESB) manages the flow of messages through WebSphere
Process Server and handles any data transformation or routing that is required between
services and clients.
The SOA extension for WebSphere Process Server lets you monitor the full WebSphere
Process Server architecture including WebSphere Enterprise Service Bus. Alternatively,
you can monitor only WebSphere Enterprise Service Bus. You can install WebSphere
Enterprise Service Bus as a standalone product.
If you monitor WebSphere Process Server, dashboards and metrics display information
for both WPS and WESB. If you monitor WESB as a standalone product, dashboards and
metrics only include information about WESB.
Monitoring WebSphere Process Server Components
If you are using WebSphere Process Server, you can monitor the operation of the
WebSphere Process Server environment with metrics for:
Business Object Maps
Business object maps assign values to the target business objects service
components based on the values in the source business objects service
components. One business object becomes the source and another becomes the
target. The business object map maps the source and target.
With the SOA extension for WPS, you can monitor the performance and overall
health business object maps under the WProcServer > BOMaps node.
Business Processes
Business processes consist of individual tasks that are executed in a specific order to
achieve a particular goal. A business process is made up of at least one task that
may be involved in receiving a message in response to a request.
health of activities in business processes under the WProcServer >
BusinessProcesses node.


Business State Machines
A business state machine is an event-driven application. The application waits for
an event to occur and, based on the event, chooses an appropriate action to
execute. After the action executes, the machine can go to another state or simply
wait for another event to occur.
health of event-driven processes under the WProcServer > BusinessStateMachines
node.
Business Rules
Business rules capture and implement business policies and practices. A business
rule can enforce business policy, make a decision, or infer new data from existing
data.
health of the business rules you have defined under the WProcServer >
BusinessRules node.
Data Binding
Data bindings are used to convert business objects to a stream of data during
inbound and outbound processing.
health of data bindings under the WProcServer > DataBinding node.
Human Tasks
Human tasks represent tasks that people perform but also involve interaction with
processes or services in WPS in some way.
health of tasks requiring human interaction under the WProcServer > HumanTasks
node.
Interface Maps
Interface maps reconcile the differences between components that have different
interfaces using transformation and other rudimentary operations to enable the
components with different interfaces to communicate.
health of interface maps under the WProcServer > InterfaceMaps node.
J2CA (Adapters)
Adapters are applications that enable a WebSphere Process Server to communicate
with the external Enterprise Information System (EIS). Outbound communication
occurs when a WebSphere Process Server calls an EIS-specific operation. Inbound
communication occurs when the application listens for a specific EIS event.
health of adapters under the WProcServer > J2CA node.


Java Components
Java components enable you to customize Java implementations in WPS or WESB.
health of Java components under the WProcServer > JavaComponents node.
Mediation Flows
Mediation flows consist of request flows for handling requests, response flows for
handling responses, event flows for handling events, and fault flows for handling
faults. A request flow begins for each source operation and response flow begins
for each target operation.
health of mediation flows under the WProcServer >WESB > MediationFlows node.
Mediation Primitives
Mediation primitives are building blocks that implement the capabilities of a
mediation flow component. Each mediation flow contains mediation primitives that
let you transform data.
health of mediation primitives under the WProcServer >WESB >
MediationPrimitives node.
Relationships
Relationships establish an association between data from two or more data types.
For example, a relationship can be used to define the correlation between a
Customer and a Customer ID.
health of relationship definitions under the WProcServer > Relationships node.
Selectors
Selectors provide flexibility in the processing of service components during runtime.
A selector accepts one invocation from the client application and allows different
targets to be called at runtime based on the selection criteria.
health of the selectors you have defined under the WProcServer > Selectors node.
SIB-Communication
Displays Service Integration Bus (SIB) metrics from the Process Server Controller
component, which controls the execution of business processes and business state
machines. You can monitor these metrics under the WProcServer >
SIB-Communication node.
How To Enable Monitoring for WebSphere Process Server or WESB


Monitoring WebSphere Enterprise Service Bus standalone
If you are using WebSphere Enterprise Service Bus as a standalone product, you can
monitor the operation of the WebSphere Enterprise Service Bus environment with
metrics for:
Business Object Maps
For a standalone WESB environment, you can monitor the performance and overall
health business object maps under the WESB > BOMaps node.
Data Binding
health of data bindings under the WESB > DataBinding node.
J2CA (Adapters)
health of adapters under the WESB > J2CA node.
Java Components
health of Java components under the WESB > JavaComponents node.
Mediation Flows
health of mediation flows under the WESB > MediationFlows node.
Mediation Primitives
health of mediation primitives under the WESB > MediationPrimitives node.
Relationships
health of relationship definitions under the WESB > Relationships node.
How To Enable Monitoring for WebSphere Process Server or
WESB
You enable monitoring for WebSphere Process Server or WebSphere Enterprise Service
Bus by performing the following steps:
1. Verify that you have a supported version of WebSphere Process Server or
WebSphere Enterprise Service Bus installed.
2. Verify that the agent and CA APM for SOA are installed and enabled.


3. Enable the agent to use CA APM for WebSphere Process Server or WebSphere
Enterprise Service Bus by configuring the agent profile (see page 299). You include
the appropriate ProbeBuilder directive file for monitoring WebSphere Process
Server or WebSphere Enterprise Service Bus.
4. Enable the Enterprise Manager extension (see page 289) for WebSphere Process
Server or WebSphere Enterprise Service Bus. You move files from the
<EM_Home>/examples/SOAExtensionForWPSandWESB directory to the
appropriate Enterprise Manager directory.
Enabling the agent for monitoring WPS or WESB
You can enable monitoring for WebSphere Process Server, which includes monitoring
capability for WebSphere Enterprise Service Bus, when you install the agent and select
WebSphere as the application server or manually after installing the agent.
If you selected CA APM for WebSphere Process Server and WESB when you installed the
agent, the files for monitoring both WebSphere Process Server and WebSphere
Enterprise Service Bus are available in the <Agent_Home> directory.
After installing the agent, you must manually enable CA APM for either WebSphere
Process Server or WebSphere Enterprise Service Bus by configuring the agent profile.
To enable CA APM for WPS or WESB manually:
2. Verify the CA APM for WebSphere Process Server directory,
SOAExtensionForWPSandWESB, is in the <Agent_Home>/examples directory and
copy the files from the
<Agent_Home>/examples/SOAExtensionForWPSandWESB/ext directory to the
4. Add the appropriate directives file to the introscope.autoprobe.directivesFile
property in the IntroscopeAgent.profile file.
Add wps.pbd to monitor all WebSphere Process Server components, including
Add wesb.pbd to monitor only WebSphere Enterprise Service Bus components
in a standalone WESB environment.
You can customize the ProbeBuilder directives in either the wps.pbd or wesb.pbd
file if you want to modify the default monitoring. For example, you can then
fine-tune monitoring for specific components by turning on or turning off tracing
for specific tracer groups.
5. Save and close the IntroscopeAgent.profile file.


Required Configuration for Business Process Manager 8.0 and 8.1
For Business Process Manager 8.0 and 8.1, configure wps.pbd to enable tracing.
Follow these steps:
1. Stop the Business Process Manager if it is running.
2. Go to the <Agent_Home>/core/config directory and open the wps.pbd file.
Note: If you are using legacy mode, modify the file wps-legacy.pbd using this
same procedure.
3. Comment out the following Tracer Mapping and Tracer directive statements from
the pbd file:
#SetTracerClassMapping: ThreadCreationTracer
com.wily.powerpack.websphereprocserver.tracer.hc2.ThreadCreationTracer
#TraceOneMethodWithParametersOfClass:
com.ibm.bpe.framework.navigation.NavigationWorker doWork ThreadCreationTracer
"Navigation-Work"
4. Uncomment the following Tracer Mapping and Tracer directive from the pbd file:
SetTracerClassMapping: ThreadCreationTracer80
com.wily.powerpack.websphereprocserver.tracer.hc2.ThreadCreationTracer80
TraceOneMethodWithParametersOfClass:
com.ibm.bpe.framework.navigation.NavigationWorker doWork
ThreadCreationTracer80 "Navigation-Work"
5. Save and close wps.pbd.
When you are finished modifying the default configuration, restart the Business Process
Manager.
Collect Metrics for Multiple Versions of a Business Process and Business State Machines
You can configure wps.pbd to provide separate metrics for different versions of a
business process and business state machines. If you only maintain one version of each
business process and business state machine, you can skip these configuration steps.
Follow these steps:
1. Go to the <Agent_Home>/core/config directory and open the wps.pbd file.


2. Comment out the ProcessCustomTracer and ProcessFaultTracer parameters. For
example:
##SetTracerParameter: ProcessCustomTracer nameformatter
com.wily.powerpack.websphereprocserver.nameformatter.ProcessContextFormatter
#SetTracerParameter: ProcessFaultTracer nameformatter
#SetTracerParameter: BPMapTracer nameformatter
#SetTracerParameter: BusinessProcessTracer nameformatter
com.wily.powerpack.websphereprocserver.nameformatter.BusinessProcessNameAndTi
meFormatter
#SetTracerParameter: BusinessProcessFaultTracer nameformatter
meFormatter
#SetTracerParameter: BPMap7Tracer nameformatter
meFormatter
3. Uncomment the ProcessCustomTracer and ProcessFaultTracer parameters to get
the time attribute. For example:
SetTracerParameter: ProcessCustomTracer nameformatter
com.wily.powerpack.websphereprocserver.nameformatter.ProcessAndTimeNameFormat
ter
SetTracerParameter: ProcessFaultTracer nameformatter
ter
SetTracerParameter: BPMapTracer nameformatter
ter
SetTracerParameter: BusinessProcessTracer nameformatter
com.wily.powerpack.websphereprocserver.nameformatter.BusinessProcessNameForma
tter
SetTracerParameter: BusinessProcessFaultTracer nameformatter
tter
SetTracerParameter: BPMap7Tracer nameformatter
tter
Note: If you skip this step, the Business Process and Business State Machine nodes
are appended with the time format used when developing the file.
When you are finished modifying the default configuration, you can restart the
WebSphere Process Server or WESB server.


Collect Performance Monitoring Infrastructure (PMI) Metrics
If you are monitoring the WebSphere Application Server in a distributed environment,
you have the option to collect WebSphere Performance Monitoring Infrastructure (PMI)
metrics and view those metrics for WebSphere Process Server components in the
Investigator.
To do so, you first must configure monitoring as described in the CA APM for IBM
WebSphere Distributed Environments Guide. You can then modify additional agent
properties on the application server to enable monitoring for WebSphere Process Server
components.
Follow these steps:
1. Open the IntroscopeAgent.profile file in <Agent_Home>/core/config.
2. Search for the following properties:
introscope.agent.pmi.enable.WBIStats.RootGroup
introscope.agent.pmi.enable.SCAStats.RootGroup
3. Set both of these properties to true to enable PMI metrics reporting. For example:
introscope.agent.pmi.enable.WBIStats.RootGroup=true
introscope.agent.pmi.enable.SCAStats.RootGroup=true
If these properties are not currently defined, manually add the properties to
IntroscopeAgent.profile, then set them to true.
If you are finished modifying the default configuration, you can restart the
WebSphere Process Server or WESB server.
5. Use the WebSphere Admin console to enable the Performance Monitoring
Infrastructure for WebSphere Process Server and WebSphere Enterprise Service Bus
modules.
Note: For information about enabling modules using the WebSphere Admin
Console, see the IBM WebSphere documentation.
Enable the Enterprise Manager Extension for WPS or WESB
CA APM for WebSphere Process Server and WebSphere Enterprise Service Bus files are
installed by default in the <EM_Home>/examples directory when you install the
Enterprise Manager. To enable CA APM for WebSphere Process Server or WebSphere
Enterprise Service Bus, you copy or move the Enterprise Manager files from the
<EM_Home>/examples directory to the proper location in the Enterprise Manager home
directory.
Note: CA APM for SOA must be enabled on the Enterprise Manager (see page 37) before
you can use CA APM for WebSphere Process Server or WebSphere Enterprise Service
Bus.


To enable the Enterprise Manager extension for WebSphere Process Server
1. Verify that the CA APM for WebSphere Process Server directory,
SOAExtensionForWPSandWESB, is in the <EM_Home>/examples directory. Copy the
files from the <EM_Home>/examples/SOAExtensionForWPSandWESB directory to
<EM_Home>/examples/SOAExtensionForWPSandWESB/ext directory to the
2. Copy the WPS_Management_Module.jar file from the
<EM_HOME>/examples/SOAExtensionForWPSandWESB/config/modules directory
and paste it into the <EM_Home>/config/modules directory.
The <EM_HOME>/examples/SOAExtensionForWPSandWESB/config/modules
directory contains the Management Modules for both WebSphere Process Server
and WebSphere Enterprise Service Bus standalone. You copy the
WPS_Management_Module.jar file only if you are monitoring WebSphere Process
Server with WebSphere Enterprise Service Bus.
If you have multiple Enterprise Managers in a clustered environment, copy only this
file to the <EM_Home>/config/modules directory on the Enterprise Manager you
are using as the MOM computer. All other files and scripts should be installed on
both the Collector Enterprise Managers and the MOM Enterprise Manager.
3. Remove old versions of Enterprise Manager files if you are upgrading from a
previous version of CA APM for WebSphere Process Server.
If you have a previous release installed on the Enterprise Manager, manually delete
the old version of the Enterprise Manager files before you begin using the new
version of CA APM for WebSphere Process Server.
If you upgraded from a previous release, delete the following files from the
Enterprise Manager home directory:
<EM_home>/config/modules/WPS_Management_ModuleV<version>.jar
com.wily.powerpack.websphereprocserver.em.ext_<version>.jar
For example, if you are upgrading from version 8.1, delete the following files:
WPS_Management_ModuleV8.1.0.0.jar
com.wily.powerpack.websphereprocserver.em.ext_8.1.0.jar
The dashboards and Overview tabs that are specific to the SOA extension for
WebSphere Process Server or WebSphere Enterprise Service Bus are loaded.


To enable the Enterprise Manager extension for WESB standalone
1. Verify that the CA APM for WebSphere Process Server directory,
SOAExtensionForWPSandWESB, is in the <EM_Home>/examples directory. Copy the
files from the <EM_Home>/examples/SOAExtensionForWPSandWESB directory to
<EM_Home>/examples/SOAExtensionForWPSandWESB/ext directory to the
2. Copy the WESB_Management_Module.jar file from the
<EM_HOME>/examples/SOAExtensionForWPSandWESB/config/modules directory
and paste it into the <EM_Home>/config/modules directory.
The <EM_HOME>/examples/SOAExtensionForWPSandWESB/config/modules
directory contains the Management Modules for both WebSphere Process Server
and WebSphere Enterprise Service Bus standalone. You only copy the
WESB_Management_Module.jar file if you are monitoring WebSphere Enterprise
Service Bus standalone.
If you have multiple Enterprise Managers in a clustered environment, copy only this
file to the <EM_Home>/config/modules directory on the Enterprise Manager you
are using as the MOM computer. All other files and scripts should be installed on
both the Collector Enterprise Managers and the MOM Enterprise Manager.
3. Remove old versions of Enterprise Manager files if you are upgrading from a
previous version of CA APM for WebSphere Enterprise Service Bus.
If you have a previous release installed on the Enterprise Manager, manually delete
the old version of the Enterprise Manager files before you begin using the new
version of CA APM for WESB. If you upgraded from a previous release, delete the
following files from the Enterprise Manager home directory:
<EM_home>/config/modules/WESB_Management_ModuleV<version>.jar
com.wily.powerpack.websphereprocserver.em.ext_<version>.jar
For example, if you are upgrading from version 8.1, delete the following files:
WESB_Management_ModuleV8.1.0.0.jar
com.wily.powerpack.websphereprocserver.em.ext_8.1.0.jar
The dashboards and Overview tabs that are specific to CA APM for WebSphere
Process Server or WebSphere Enterprise Service Bus are loaded.
Using dashboards to monitor WPS or WESB


The SOA extension for WebSphere Process Server includes several preconfigured
dashboards that you can use to monitor the overall health of the application
environment. Dashboards aggregate data across deployed agents to summarize
performance information and help you rapidly diagnose and resolve problems.
because they allow you to:
monitor the overall health, performance, availability, and current status of key
components of WebSphere Process Server at-a-glance;
get early notification of potential problems in the production application
been crossed;
drill-down into performance information to isolate and identify which WebSphere
business processes, business rules, mediation flows, or other components are
The preconfigured WebSphere Process Server and WebSphere Enterprise Service Bus
dashboards are packaged in the Enterprise Manager extension for WebSphere as part of
the SOA Extension for WebSphere Process Server Management Module
(WPS_Management_Module.jar) or the SOA Extension for WebSphere Enterprise
Service Bus Management Module (WESB_Management_Module.jar).
About WebSphere Process Server dashboards
The WebSphere Process Server Management Module provides the following
preconfigured dashboards for WebSphere Process Server:
WPS - Overview
A top-level overview of the health of the WebSphere Process Server, including alert
indicators for the overall response time, errors, and stalls for all major components
of the WebSphere Process Server architecture.
WPS - Business Processes & State Machines
Summarized status for all business processes and business state machines,
including graphs of the Average Response Times for all business processes and state
machines, alert indicators for errors and stalls, and lists of the slowest business
processes and state machines.
WPS - Business Rules & Human Tasks
Summarized status for all business rules and human tasks, including graphs of the
Average Response Times for all business rules human tasks, alert indicators for
errors and stalls, and lists of the slowest business rules and human tasks.


WPS - Interface Maps, BO Maps, & Relationships
Summarized status for all interface maps, business object maps, and relationships,
including graphs of the Average Response Times for interface maps, business object
maps, and relationships, alert indicators for errors and stalls, and lists of the slowest
interface maps, business object maps, and relationships.
WPS - Selectors & Java Components
Summarized status for all selectors and Java components, including graphs of the
Average Response Times for all selectors and Java components, alert indicators for
errors and stalls, lists of the slowest selectors and Java components.
WPS - Data Bindings
Summarized status for all data bindings, including graphs and alert indicators for
Average Response Time, Errors Per Interval, and Stall Counts, a list of the slowest
data bindings.
WPS - Adapters
Summarized status for all inbound and outbound adapters, including graphs of the
Average Response Times for all inbound and outbound adapters, alert indicators for
errors and stalls, and lists of the slowest inbound and outbound adapters.
WESB - Mediation Flows
Summarized status for the overall health of mediation flows, and separate graphs
and alert indicators for request flows, response flows, and fault flows.
Because mediation flows consist of request, response, and fault flows, this
dashboard displays graphs of the Average Response Time for mediation flows,
request flows, response flows, and fault flows; alert indicators for errors and stalls
for mediation flows, request flows, response flows, and fault flows; and a list of the
slowest mediation flows.
WESB - Mediation Primitives
Summarized status for the overall health of mediation primitives, including alert
indicators for response time and errors for all mediation primitives, and separate
alert indicators for response time, errors, and stalls for request flows, response
flows, and fault flows.


About WESB dashboards
If you are monitoring WebSphere Enterprise Service Bus as a standalone product, only
the following dashboards are available:
WESB - Overview
A top-level overview of the health of the WebSphere Enterprise Service Bus,
including alert indicators for the overall response time, errors, and stalls for all
major components of the WebSphere Enterprise Service Bus tier of the WebSphere
architecture.
WESB - Mediation Flows
Summarized status for the overall health of mediation flows, and separate graphs
and alert indicators for request flows, response flows, and fault flows for
WESB - Mediation Primitives
Summarized status for the overall health of mediation primitives, including alert
indicators for response time and errors for all mediation primitives, and separate
alert indicators for response time, errors, and stalls for request flows, response
flows, and fault flows for WebSphere Enterprise Service Bus.
WESB - Adapters
Summarized status for all inbound and outbound adapters, including graphs of the
Average Response Times for all inbound and outbound adapters, alert indicators for
errors and stalls, and lists of the slowest inbound and outbound adapters for
WESB - BO Maps & Relationships
Summarized status for all business object maps and relationships, including graphs
of the Average Response Times for all business object maps and relationships, alert
indicators for errors and stalls, and lists of the slowest business object maps and
relationships for WebSphere Enterprise Service Bus.
WESB - Data Bindings
Summarized status for all data bindings, including graphs and alert indicators for
Average Response Time, Errors Per Interval, and Stall Counts, a list of the slowest
data bindings for WebSphere Enterprise Service Bus.
WESB - Java Components
Summarized status for all Java components, including graphs and alert indicators
for the Average Response Time, Errors Per Interval, and Stall Counts for all Java
components, and a list of the slowest Java components for WebSphere Enterprise
Service Bus.
The dashboards for WebSphere Enterprise Service Bus are similar to the ones provided
for WebSphere Process Server, but only provide alert indicators and metrics specifically
for WebSphere Enterprise Service Bus components.


View WebSphere Process Server or WESB Dashboards
The dashboards for WebSphere Process Server or WebSphere Enterprise Service Bus
provide alert indicators and metrics to help you assess system health at a glance.
Follow these steps:
extension for WebSphere Process Server or WESB is installed.
4. Select one of the WPS or WESB dashboards from the Dashboard drop-down list.
For example, select WPS - Overview dashboard to see an overview of WebSphere
Process Server health, including alert indicators for all of the service components
and supporting services.
From the WPS - Overview or WESB - Overview dashboard, you can navigate to the
other dashboards by double-clicking the tab with the name of the dashboard you
want to view.
5. Double-click another tab or an alert in the dashboard to open a related dashboard
to view more detailed information.
For example, double-click the Response Time alert for Business Processes to see
more detailed information about the specific business processes that are taking the
most time on the WPS - Business Processes & State Machines dashboard.
The WPS - Business Processes & State Machines dashboard displays lists of the
slowest business processes and state machines along with graphs for average
response time and alert indicators for errors, and stall counts.
6. From the WPS - Business Processes & State Machines dashboard, you can
double-click a specific business process name in the list of Slowest Business
Processes to open the Investigator with the response time for that business process
selected for further analysis.
Note: For more information about starting and using the Workstation, accessing
dashboards, or opening and navigating Investigator, see the CA APM Workstation User
Guide.
View and Navigate Metrics for WPS/WESB


metrics for most components of the WebSphere Process Server or WebSphere
Enterprise Service Bus infrastructure. Data for the standard metrics is collected and
aggregated into WebSphere Process Server or WESB-specific metric categories displayed
as nodes and sub-nodes in the Investigator tree. The specific metric categories and node
names displayed depend on the components, services, and resources you have
deployed and accessed in your environment.
As you navigate through the Investigator tree, you can view low-level metrics for
individual operations or aggregated metrics depending on the node you select, enabling
you to monitor the overall health of various Process Server or WESB components. If a
component is not used at all, for example, if no human tasks are defined for any
process, then the metric categories for that component is not displayed in the
Investigator tree.
To view and navigate metric summaries in the Investigator
1. Expand the agent node, then click the WProcServer or WESB node to display the
Overview tab for summary information.
For example, if you select the WProcServer node, the Overview lists summary
information for all of the business processes, business state machines, and
mediation flows that WebSphere Process Server is using.
2. Double-click a business process, business state machine, or mediation flow to view
all the associated metrics in a graphical format.
3. Expand the WProcServer or WESB node to display sub-nodes for the top-level
WebSphere Process Server or WebSphere Enterprise Service Bus metric categories.
about that metric category. For example, click the BusinessRules node to display the
list of business rules on the Overview tab.
5. Expand any sub-node to see more detailed information about individual
components. For example, select a specific business process name to view the
metrics in graphical form for that business process.
6. Expand any individual object to view the metrics for that object. For example,
expand any individual Java component name, then expand an operation to view
metrics for that operation.


Metrics for Business Objects Maps
Business object maps assign values to the target business objects service components
based on the values in the source business objects service components.
All of the standard CA Introscope metrics are available for target namespaces and
individual business object maps under either the WProcServer > BOMaps or WESB >
BOMaps node.
Metrics for Business Processes
Business processes consist of individual tasks that are executed in a specific order to
achieve a particular business objective. This metric category is only applicable for
WebSphere Process Server. It is not applicable if you are monitoring WebSphere
All of the standard CA Introscope metrics are available for individual WebSphere
business processes and business process steps under the
WProcServer > BusinessProcesses > <business_process_name> nodes.
If you configured tracing to display separate metrics for different versions of the same
Business Process as described in Collecting metrics for multiple versions of a business
process (see page 287), the business process name under the BusinessProcesses node is
appended with an underscore [_] and a time stamp to identify different versions of the
same process.
Metrics for Business Rules
Business rules capture and implement business policies and practices. This metric
category is only applicable for WebSphere Process Server. It is not applicable if you are
monitoring WebSphere Enterprise Service Bus as a standalone product.
All of the standard CA Introscope metrics are available for the individual business rules
you have deployed under the WProcServer > BusinessRules > <rule_name> node.


Metrics for Business State Machines
Business state machines are event-driven applications that execute an action in
response to an event. This metric category is only applicable for WebSphere Process
Server. This category is not applicable if you are monitoring WebSphere Enterprise
Service Bus as a standalone product.
All the standard CA Introscope metrics are available for individual business state
machines under the WProcServer > BusinessStateMachines >
<business_state_machine_name> node.
If you configured tracing (see page 287) to display separate metrics for versions of the
same BusinessStateMachines, the name under the BusinessStateMachines node
appears as follows:
The name is appended with an underscore [_].
A time stamp identifies different versions of the same process.
Metrics for Data Bindings
Data bindings are used to convert business objects to a stream of data during inbound
and outbound processing.
All of the standard CA Introscope metrics are available for individual data bindings
under either the WProcServer > DataBindings > <data_binding_name> or
WESB > DataBindings > <data_binding_name> node.
Metrics for Human Tasks
Human tasks represent tasks that are performed by people but also involve interaction
with processes or services in WebSphere Process Server. This metric category is only
applicable for WebSphere Process Server. It is not applicable if you are monitoring
WebSphere Enterprise Service Bus as a standalone product.
All of the standard CA Introscope metrics are available for individual human tasks
under the WProcServer > HumansTasks node.
Metrics for Interface Maps
Interface maps reconcile the differences between components to enable components
with different interfaces to communicate. This metric category is only applicable for
WebSphere Process Server. It is not applicable if you are monitoring WebSphere


All of the standard CA Introscope metrics are available for the interface maps that have
been defined under the WProcServer > InterfaceMaps node.
For synchronous invocations, the metrics for individual interface maps represent the
total time taken by the interface map component. For asynchronous invocations, the
metrics represent input and output transformations separately.
Metrics for J2CA Adapters
Adapters are applications that enable a WebSphere Process Server to communicate
with the external Enterprise Information System. Outbound communication occurs
when the WebSphere Process Server calls an EIS-specific operation. Inbound
communication occurs when the application listens for a specific EIS event.
All of the standard CA Introscope metrics are available for inbound and outbound
interactions between the WebSphere server and the external system under either the
WProcServer > J2CA or WESB > J2CA node.
Metrics for Java Components
Java components let you customize Java implementations in WPS or WESB.
All of the standard CA Introscope metrics are available for individual Java components
and operations under either the WProcServer > JavaComponents or WESB >
JavaComponents node.
Metrics for Mediation flows and primitives
Mediation flows consist of request flows for handling requests, response flows for
handling responses, event flows for handling events, and fault flows for handling faults.
A request flow begins for each source operation and response flow begins for each
target operation. Mediation primitives are the building blocks that implement the
capabilities of a mediation flow. Each mediation flow contains mediation primitives that
let you transform data, if required.


All of the standard CA Introscope metrics are available for mediation flows and
mediation primitives under either the WProcServer > WESB > MediationFlows or WESB
> MediationFlows node. The MediationFlow node lists the modules that have mediation
flow components. You can then expand a mediation flow component to view the
aggregated metrics for that mediation flow and its operations, flows, and mediation
primitives. For example:

If a response, event, or fault flow has been invoked as an asynchronous call, the node
name is displayed in the Investigator as <flow_type>_Asynch where <flow_type>
identifies the flow as a ResponseFlow, EventFlow, or FaultFlow. For example, if a
response flow is invoked asynchronously with a call back, the node name displayed in
the Investigator is ResponseFlow_Asynch.
In the context of the mediation flow metrics, an asynchronous call is an operation
invoked asynchronously using a call back function.


About synchronous and asynchronous response time metrics
The metrics for mediation flow components are aggregated from the all of the Average
Response Time metrics for the operations under the flow name. The metrics for
mediation flow operations are aggregated differently depending on whether the
operation uses synchronous or asynchronous calls:
If an operation makes synchronous calls, operation-level metrics are aggregated
from the request flow of the operation because the request flow indirectly includes
the response flow duration for synchronous calls.
If an operation makes asynchronous calls, operation-level metrics are aggregated
from the existing request flow (RequestFlow) and the asynchronous response
(ResponseFlow_Asynch), fault (FaultFlow_Asynch), and event flows
(EventFlow_Asynch) under the operation name.
For example, if the Average Response Time for an interval is 10 ms for the request flow,
12 ms for the asynchronous response flow, 8 ms for the asynchronous fault flow, and 10
ms for the asynchronous event flow and the count value is 1 for the request flow, 1 for
the response flow, 2 for the fault flow, and 3 for the event flow, the calculation for the
operations Average Response Time would be:
((10 x 1) + (12 x 1) + (8 x 2) + (10 x 3))/3
About synchronous and asynchronous concurrent invocations
The metrics for mediation flow components are aggregated from all of the Concurrent
Invocation metrics for the operations under the flow name. The metrics for mediation
flow operations are aggregated differently depending on whether the operation uses
synchronous or asynchronous calls:
If an operation makes synchronous calls, the Concurrent Invocation metric at
operation-level represents the Concurrent Invocations of the request flows for the
operation because the request flow indirectly includes the response flow durations
for synchronous calls.
from the Concurrent Invocations of the existing request flow (RequestFlow) and the
asynchronous response (ResponseFlow_Asynch), fault (FaultFlow_Asynch), and
event flows (EventFlow_Asynch) under the operation name.


About synchronous and asynchronous error metrics
The metrics for mediation flow components are aggregated from all of the Errors Per
Interval metrics for the operations under the flow name. The Errors Per Interval metric
for mediation flow operations are calculated differently depending on whether the
If an operation makes synchronous calls, operation-level metrics are aggregated by
adding the Errors Per interval metric of the request flow.
by adding the existing Errors Per interval metric of the existing request flow
(RequestFlow), and the asynchronous response (ResponseFlow_Asynch) and event
(EventFlow_Asynch) flows to the Responses Per interval metric of the asynchronous
fault (FaultFlow_Asynch) flow under the operation name.
Because fault flows are expected to occur when a fault occurs, the Responses Per
Interval metric value for the asynchronous fault flow is added to the Errors Per Interval
metric value at the operation level to represent that an error has occurred during that
operations invocation.
About synchronous and asynchronous response metrics
The metrics for mediation flow components are aggregated from all of the Responses
Per Interval metrics for the operations under the flow name. The Responses Per Interval
metric for mediation flow operations is calculated differently depending on whether the
If an operation makes synchronous calls, operation-level metrics are aggregated by
adding the Responses Per Interval of the request flow.
If an operation makes asynchronous calls, the Responses Per Interval metric is
determined by the maximum Responses Per Interval of the request flow
(RequestFlow) and the asynchronous response (ResponseFlow_Asynch), fault
(FaultFlow_Asynch), and event flows (EventFlow_Asynch) under the operation
name.
About synchronous and asynchronous stall count metrics
The metrics for mediation flow components are aggregated from all of the Stall Count
metrics for the operations under the flow name. The Stall Count metric for mediation
flow operations is calculated differently depending on whether the operation uses
synchronous or asynchronous calls:
If an operation makes synchronous calls, the Stall Count is calculated by adding
together the number of stalls recorded for the request flow.
If an operation makes asynchronous calls, the Stall Count is calculated by adding
together the number of stalls recorded for the request flow and the asynchronous
response (ResponseFlow_Asynch), fault (FaultFlow_Asynch), and event flows
(EventFlow_Asynch) under the operation name.
Viewing default WPS and WESB metric groupings


Metrics for Relationships
Relationships identify semantically equivalent business objects.
All of the standard CA Introscope metrics are available for individual relationship under
either the WProcServer > Relationships or WESB > Relationships node.
Metrics for Selectors
Selectors provide flexibility in the processing of service components during run-time.
This metric category is only applicable for WebSphere Process Server. It is not applicable
if you are monitoring WebSphere Enterprise Service Bus as a standalone product.
All of the standard CA Introscope metrics are available under the
WProcServer > Selectors node.
Metrics for Service Integration Bus Communication
A Service Integration Bus (SIB) supports applications using message-based and
service-oriented architectures. You can view SIB communication metrics under the
WProcServer > SIB-Communication node.
Metrics for WebSphere Process Server Faults
When a fault occurs in the WPS tier, an exception is thrown if the fault is not handled.
The WPS Faults Per Interval metric shows the number of exceptions that have occurred
in a 15-second time slice. This metric is only applicable for WebSphere Process Server. It
is not applicable if you are monitoring WebSphere Enterprise Service Bus as a
standalone product.
The SOA extension for WebSphere Process Server and WESB includes default metric
WebSphere as part of the SOA Extension for WebSphere Process Server Management
Module (WPS_Management_Module.jar) or the SOA Extension for WebSphere
Enterprise Service Bus Management Module (WESB_Management_Module.jar).
Viewing default WPS and WESB alerts


To view the default WebSphere Process Server or WESB metric groupings
2. Expand *Super Domain* > Management Modules > WPS_ManagementModule
(*Super Domain*) if you are monitoring all WebSphere Process Server components,
or WESB_ManagementModule (*Super Domain*) if you are monitoring a
standalone WESB server.
3. Expand the MetricGroupings node to view all of the default metric groupings for
WebSphere Process Server if you are monitoring all WebSphere Process Server
components, or the default metric groupings for WebSphere Enterprise Service Bus
if you are monitoring a standalone WESB server.
You can modify the any of the default settings for any metric grouping or create
your own custom metric groupings.
Viewing default WPS and WESB alerts
The SOA extension for WebSphere Process Server and WESB includes default alert
definitions that are used in the preconfigured dashboards. You can also use these
default alerts in custom dashboards. Most of the default alerts are preconfigured with
default Caution and Danger thresholds and to send notification to the console if a
threshold is crossed or severity increases.
WebSphere as part of the SOA Extension for WebSphere Process Server Management
Module (WPS_Management_Module.jar) or the SOA Extension for WebSphere
Enterprise Service Bus Management Module (WESB_Management_Module.jar).
To view default alert definitions for WebSphere Process Server or WESB agents:
WPS_ManagementModule (*SuperDomain*) if you are monitoring all WebSphere
Process Server components, or WESB_ManagementModule (*SuperDomain*) if you
are monitoring a standalone WESB server.
Viewing WPS or WESB dependencies


3. Expand the Alerts node to view all of the alerts defined for the WebSphere Process
Server management module.
In particular, you should review the default Caution and Danger thresholds and
predefined actions for critical alerts and tune them for your environment. For example,
you may want adjust the threshold values, if necessary, add notifications, or define
corrective actions.
Viewing WPS or WESB dependencies
You can view dependencies for business processes, business state machines, mediation
flows, and adapter outBound components by selecting BusinessProcesses,
BusinessStateMachines, or MediationFlows in WebSphere Process Server or
MediationFlows in WebSphere Enterprise Service Bus using nodes in the Investigator
tree, then clicking the SOA Dependency Map tab. You can also view adapter outbound
dependencies in the dependency map if you select a component that calls an EIS
operation. For example, if a mediation flow retrieves a row from a JDBC table using an
adapter, you can display the dependency between that mediation flow and the
outbound adapter in the dependency map by selecting the mediation flow and showing
its dependencies.
viewing. For example, for a high level view of dependencies in a business process, you
can select the business process name in the Investigator, then click the SOA Dependency
Map tab.
The following example illustrates a mediation flow for a stock quote business service
selected in the Investigator tree and the dependency map expanded to show additional
dependencies:

detailed information about navigating the dependency map, see Using the SOA
Dependency Map (see page 65).
Tracing transactions for WPS or WESB


completing a business transaction. For transactions that include WebSphere Process
Server or WebSphere Enterprise Service Bus components or web services, you can trace
transactions that include operations routed through the following protocols:
Transactions initiated outside of WebSphere Process Server or WebSphere Enterprise
Service Bus components can include asynchronous calls initiated in the WebSphere
Process Server or WebSphere Enterprise Service Bus environment. To enable these
transactions to be traced across all of the components that participate in the
transaction, correlation identifiers are inserted and consumed as a transaction steps
through each component and operation. You can then drill down into the details of a
transaction to understand the WebSphere Process Server or WebSphere Enterprise
Service Bus components involved in the transaction, including the operations performed
and the time each operation took to complete.
CA APM for SOA and CA APM for WebSphere Process Server are enabled at every node
being traced. This enables you to view details about the transaction even if the
transaction spans multiple JVMs or CLRs.
how messages are routed through WebSphere Enterprise Service Bus components.
which components and activities are called and executed during a transaction.


directly from a map node in the SOA Dependency Map.
manually from the Workstation by clicking Workstation > New Transaction Trace
Session.
can choose one of the following filter types for WebSphere Process Server:
adapternode
businessprocess
businessstatemachine
mediationflow
mediationflowoperation
For example, to filter transactions for a specific mediation flow, you can select the
mediationflow filter and type all or part of the mediation flow name.
Viewer is displayed. You can select a trace to view additional details about the calls
made in the transaction, including any business process, state changes, or Java
components executed using WebSphere Process Server.
Using the Sequence View for WebSphere processes
Because transactions involving WebSphere Process Server often include asynchronous
calls, you may find it useful to click the Sequence View to view the transaction workflow
for the processes that executed asynchronously as part of a transaction. The Sequence
View displays the order in which process execute to the extent the sequence can be
identified. For WebSphere Process Server transactions, the sequence does not
necessarily represent a traditional caller-callee relationship, but illustrates when one
process triggers the execution of another process.


You should note, however, that the processing time for WebSphere Process Server and
WESB processes is calculated using the full duration from start to completion of the
process, which includes the processing time associated with its called processes. Net
duration, which subtracts the processing time for non-blocking synchronous and
asynchronous processes from the calling processs duration, is not supported for
WebSphere Process Server and WESB processes.
For more information about transaction tracing, see Using transaction tracing in SOA
environments (see page 89).
Note: For information about configuring tracing, see the CA APM Java Agent
Implementation Guide or the CA APM .NET Agent Implementation Guide. For more
information about working with transaction trace views and historical data, see the CA
Configure Tracing to Include Business Process/Business State Machine Activities
By default, transaction traces for WebSphere Process Server business
processes/business state machines include performance information to the activity
level. These traces do not include additional detail about the execution of the activities
themselves. Because a significant performance overhead exists for retrieving activity
names, the additional activity-level tracing is off by default.
You can manually turn on activity tracing to see detailed information about the activities
executed in a business process/business state machine. However, turn on activity
tracing for a limited time only.
Follow these steps:
1. Stop the WebSphere Process Server or WESB application server.
2. Change to the <Agent_Home> directory, and then open the wps.pbd file in a text
editor.
3. Uncomment the ActivityTracing and ActivityResponseTracing flags:
TurnOn: ActivityTracing
TurnOn: ActivityResponseTracing
Additional activity-level tracing is enabled.
Note:If you have enabled parameters (see page 287) to get the time attribute,
uncomment the ActivityTracer as follows. Then, the Activities node appears under
the same business process/business state machines node instead of in a separate
business process/business state machines node.
#SetTracerParameter: ActivityTracer nameformatter
com.wily.powerpack.websphereprocserver.nameformatter.ActivityTimeNameformatte
r


5. Start the WebSphere Process Server or WESB server.
The agent restarts with the new configuration.


Appendix A: SOA-Specific Agent
Configuration Properties

This section describes the agent properties that are specifically for configuring CA APM
for SOA.
Understanding where agent properties are located (see page 311)
Configure Agent Properties (see page 311)
About SOA-Specific Agent Properties (see page 312)
Understanding where agent properties are located
CA APM for SOA agent properties are stored in the agent profile,
IntroscopeAgent.profile. The profile is a text file of property names and values. The
agent searches for the agent profile as follows:
In the location specified by the com.wily.introscope.agentProfile system property.
If the com.wily.introscope.agentProfile property is not set, the agent uses the
IntroscopeAgent.profile file.
In most cases, the application server the agent monitors must be restarted before
changes to agent properties take effect.
Configure Agent Properties
Agent properties enable you to control the behavior and operation of the agent and
customize settings to suit your environment. CA APM for SOA includes several
SOA-specific agent properties with default settings. Before you can use any of these
properties, you add the property name to the IntroscopeAgent.profile file and set a valid
value for the property.
Follow these steps:
2. Identify the property you want to add to the IntroscopeAgent.profile file from the
list of SOA-specific agent properties (see page 312).
About SOA-Specific Agent Properties


3. Type the full name of the property, including the com.wily.introscope prefix, in a
SOA-specific section of the IntroscopeAgent.profile file. For example:
###########################################
# SOA Performance Management Agent Settings
# =========================================
com.wily.introscope.agent.httpheaderread.enabled
4. Set the property value, as needed. For example:
com.wicom.wily.introscope.agent.httpheaderread.enabled=true
After you add a property to the IntroscopeAgent.profile file, you can change the
property value as necessary.
You can set the following SOA-specific properties in the IntroscopeAgent.profile. All of
the properties start with the com.wily.introscope prefix, but are listed without the prefix
for readability.
Note: For information about other agent properties, see the CA APM Java Agent
Implementation Guide or the CA APM .NET Agent Implementation Guide.
agent.httpheaderinsertion.enabled (see page 313)
Enables or disables the insertion of client-side correlation information in HTTP
headers.
agent.httpheaderread.enabled (see page 314)
Enables or disables the server-side retrieval of correlation information from HTTP
headers.
agent.soapheaderinsertion.enabled (see page 315)
Enables or disables the insertion of client-side correlation information in SOAP
headers.
agent.soapheaderread.enabled (see page 316)
Enables or disables the server-side retrieval of correlation information from SOAP
headers.
agent.soa.metricNameFormatting (see page 316)
Modifies CA APM for SOA metric names to replace any specified character or
characters with an underscore [_].
agent.transactiontrace.boundaryTracing.cacheFlushFrequency (see page 317)
Specifies the number of days to hold dependency data in the agent memory before
flushing the cache.


agent.transactiontrace.boundaryTracing.enable (see page 318)
Enables or disables boundary tracing for transactions.
soa.client.prependhandler (see page 318)
Controls the insertion point of the SOAP header on the client-side.
soa.server.appendhandler (see page 319)
Controls the retrieval and removal of the SOAP header on the server-side.
In most cases, changing an agent property requires that you restart the application
server for the property change to take effect.
agent.httpheaderinsertion.enabled
Enables or disables the insertion of client-side correlation identifiers in HTTP headers.
This property is not supported for SAP NetWeaver.
Property settings
The property can be set to true or false:
True - Adds client-side correlation and dependency information to the HTTP header.
False - Disallows changes to the HTTP header for client-side correlation and
dependency information.
Default
False for CA APM for SOA, CA APM for WebSphere Process Server, and CA APM for
True for CA APM for Oracle Service Bus, CA APM for TIBCO BusinessWorks, and CA APM
for webMethods Integration Server.
Example
com.wily.introscope.agent.httpheaderinsertion.enabled=true
Notes
You must restart the managed application before changes to this property take effect.


agent.httpheaderread.enabled
Enables or disables the server-side retrieval of correlation identifiers from HTTP
headers.
This property is not supported for SAP NetWeaver.
Property settings
True - Reads server-side correlation and dependency information from the HTTP
header.
False - Does not check the HTTP header for correlation and dependency
information.
Default
False for CA APM for SOA, CA APM for WebSphere Process Server, and CA APM for
True for CA APM for Oracle Service Bus, CA APM for TIBCO BusinessWorks, and CA APM
for webMethods Integration Server.
Example
com.wily.introscope.agent.httpheaderread.enabled=true
Notes


agent.soapheaderinsertion.enabled
Enables or disables the insertion of client-side correlation identifiers in SOAP headers.
The SOA Dependency Map and cross-process transaction tracing require correlation
identifiers to be passed from one process to another. The agent can insert this
correlation identifier into either a SOAP or HTTP header.
You should set the property to false if your SOAP-based applications do not work
properly due to unexpected header entries. If you set this property to false and do not
enable the insertion of correlation identifiers in the HTTP header, you cannot display
related information in the SOA Dependency Map or cross-process transaction traces.
Property settings
True - Adds client-side correlation and dependency information to the SOAP
header.
False - Disallows changes to the SOAP header for client-side correlation and
dependency information.
Default
True
Example
com.wily.introscope.agent.soapheaderinsertion.enabled=true
Notes


agent.soapheaderread.enabled
Enables or disables the server-side retrieval of correlation identifiers from SOAP
headers.
Property settings
True - Reads server-side correlation and dependency information from the SOAP
header.
False - Does not check the SOAP header for correlation and dependency
information.
Default
True
Example
com.wily.introscope.agent.soapheaderread.enabled=true
Notes
agent.soa.metricNameFormatting
Replaces any denoted character or characters in CA APM for SOA metric names with the
underscore character [_].
For example, setting the property
com.wily.introscope.agent.soa.metricNameFormatting to replace the forward slash (/)
causes the URL http://CheckingAccount/demobank.ca.com to be displayed as:
http_CheckingAccount_demobank.ca.com
Set this property if you want to substitute specified characters with an underscore (_) in
the metric name.
You may want to make this substitution to display metric names in the format used in
some Web Services Manager. In this case, you must also replace namespace with
servicename in the webservices.pbd file. These changes result in CA APM for SOA metric
names displaying in the Investigator tree and SOA Dependency Map using service name
rather than namespace.
Property settings
The property can be set to one or more characters you want to be replaced with the
underscore (_) character in metric names.
If property is not defined or has no value, no character substitution takes place.


Default
None
Example
com.wily.introscope.agent.soa.metricNameFormatting=/:
Notes
agent.transactiontrace.boundaryTracing.cacheFlushFrequency
Specifies the number of days to hold dependency data in the agent memory before
flushing the cache. You can set this property to periodically flush idle threads and clear
the agent cache. At the end of the period specified, a cache flush results in the SOA
Dependency Map dependency data being removed in the agent. The agent then
rediscovers the dependency data and forward the data to the Enterprise Manager to
refresh the information displayed on the SOA Dependency Map.
By default, previously discovered dependencies are held in the agent cache for 30 days
to prevent the agent from sending information about known dependencies to the
Enterprise Manager unnecessarily. In most cases, 30 days is an acceptable period
because dependency data is fairly static and storing the previously discovered
dependencies in the agent cache reduces the data the agent must transmits to the
Enterprise Manager at regular intervals.
If a running agent loses the connection to a standalone Enterprise Manager or fails over
to a new Enterprise Manager in a non-clustered (no MOM) environment, you can set
this property to 1 to flush the agent cache in one day. Setting the property to 1 removes
the known dependencies from the cache and forces the agent to rediscover those
dependencies so it can send the data to the new Enterprise Manager.
Property settings
The property can be set to any whole integer greater than zero.
Default
30 days
Example
com.wily.introscope.agent.transactiontrace.boundaryTracing.cacheFlushFrequency=1
Notes
Changes to this property take effect immediately and do not require the managed
application server to be restarted.


agent.transactiontrace.boundaryTracing.enable
Enables or disables transaction trace boundary traces. Boundary traces must be enabled
if you want to display information in the SOA Dependency Map. If you are not using the
SOA Dependency map, you can disable this property to reduce overhead.
Boundary traces are sent from the agent cache at a specific size to avoid overhead
issues.
Property settings
True - Collects Transaction Trace boundary trace information required for the SOA
Dependency Map and sends it to the Enterprise Manager.
False - Does not collect Transaction Trace boundary trace information required for
the SOA Dependency Map.
Default
True
Example
com.wily.introscope.agent.transactiontrace.boundaryTracing.enable=true
Notes
soa.client.prependhandler
Controls the insertion point of the CA APM for SOA SOAP header on the client-side. By
default, the first handler in the SOAP handler chain inserts the CA APM for SOA SOAP
header. Depending on how applications process SOAP messages, you can use this
property to have the SOAP header inserted first or last in the SOAP handler chain.
This property is only applicable for application servers that use SOAP handlers and
depends on the SOAP engine and API being used. For example, this property can be
used when the application server runs older versions of WebLogic or WebSphere, or the
application server runs SAP NetWeaver. The property is not applicable if you are using
Apache Axis, Apache CXF, native JBoss, WebLogic 10.x (JAX-WS), WebSphere 7.0
(JAX-WS), or .NET or Spring web service.
Property settings
You can set the property to true or false:
TrueInserts the SOAP header using the first handler in the SOAP handler chain.
FalseAppends the SOAP header using the last handler in the SOAP handler chain.


Default
True
Example
com.wily.introscope.soa.client.prependhandler=true
Notes
soa.server.appendhandler
Controls the retrieval and removal of the CA APM for SOA SOAP header on the
server-side. By default, the last handler in the SOAP handler chain reads the CA APM for
SOA SOAP header. Depending on how applications process SOAP messages, you can use
this property to have the SOAP header read and removed first or last in the SOAP
handler chain.
This property is only applicable for application servers that use SOAP handlers and
depends on the SOAP engine and API being used. For example, this property can be
used when the application server runs older versions of WebLogic or WebSphere, or the
application server runs SAP NetWeaver. The property is not applicable if you are using
Apache Axis, Apache CXF, native JBoss, WebLogic 10.x (JAX-WS), WebSphere 7.0
(JAX-WS), or .NET or Spring web service.
Property settings
TrueReads the CA APM for SOA SOAP header using the last handler in the SOAP
handler chain, and then removes it.
FalseReads the CA APM for SOA SOAP header using the first handler in the SOAP
handler chain, and then removes it.
Default
True
Example
com.wily.introscope.soa.server.appendhandler=false
Notes


Appendix B: SOA-Specific Enterprise
Manager Configuration Properties

This section describes the Enterprise Manager properties that are specifically for
configuring CA APM for SOA.
Configuring Enterprise Manager properties (see page 321)
About SOA-specific Enterprise Manager properties (see page 322)
Configuring Enterprise Manager properties
Enterprise Manager configuration properties enable you to control the behavior and
operation of the Enterprise Manager and customize settings to suit your environment.
CA APM for SOA includes many SOA-specific Enterprise Manager properties with default
settings. Before you can use any of these properties, however, you must add the
property name to the IntroscopeEnterpriseManager.properties file and update its value.
To add a configuration property to IntroscopeEnterpriseManager.properties:
1. Open the <EM_Home>/IntroscopeEnterpriseManager.properties file in a text editor.
2. Identify the property you want to add to the
IntroscopeEnterpriseManager.properties file from the list of properties in About
SOA-specific Enterprise Manager properties.
3. Type the full name of the property, including the com.wily.introscope prefix, in a
SOA-specific section in the IntroscopeEnterpriseManager.properties file. For
example:
###########################################
# SOA Performance Management EM Settings
# ==============================
com.wily.introscope.soa.dashboard.typeviewer.mostcritical.count
4. Set the property value, as needed. For example, to use the default setting for this
property:
com.wily.introscope.soa.dashboard.typeviewer.mostcritical.count=10
5. Save and close the IntroscopeEnterpriseManager.properties file.
After an Enterprise Manager extension property has been added to the
IntroscopeEnterpriseManager.properties file, you can change the property value as
necessary.
About SOA-specific Enterprise Manager properties


To change an Enterprise Manager configuration property value:
1. Open the <EM_Home>/IntroscopeEnterpriseManager.properties file in a text editor.
2. Find the property that you want to change and set the new value as appropriate for
your environment. For example:
The example above is an explanation only and not a CA APM for SOA setting
recommendation.
You can set the following SOA-specific properties in the
IntroscopeEnterpriseManager.properties file. All of the properties start with the
com.wily.introscope prefix, but are listed without the prefix for readability.
Note: For information about setting otherEnterprise Manager properties, see the CA
APM Configuration and Administration Guide.
soa.dependencymap.aging.refresh.interval (see page 325)
Specifies the interval for checking the age of previously discovered dependencies.
soa.dependencymap.aging.expire.interval (see page 326)
Specifies the maximum number of days a dependency can remain in the SOA
Dependency Map before expiring.
soa.dependencymap.heuristics.clientside.enable (see page 326)
Enables or disables the client-side logical equivalence heuristics rule.
soa.dependencymap.heuristics.namematch.enable (see page 327)
Enables or disables the logical equivalence heuristics name matching rule.
soa.dependencymap.heuristics.serverside.enable (see page 328)
Enables or disables the server-side logical equivalence heuristics rule.
soa.dependencymap.log.suppress (see page 330)
Specifies the maximum number of times the same error or warning message can be
written to the log file.
soa.dependencymap.max.edge.ratio (see page 331)
Specifies the maximum ratio of dependencies to nodes in the map.


soa.dependencymap.max.vertices (see page 332)
Specifies the maximum number of nodes that can be stored for the dependency
map on a standalone or Collector Enterprise Manager.
soa.deviation.enable (see page 333)
Enables or disables the calculations required to produce deviation metrics.
soa.deviation.art.enable (see page 334)
Enables or disables the Average Response Time deviation metrics.
soa.deviation.dependencymetric.enable (see page 334)
Enables or disables the calculations required to produce dependency metrics.
soa.deviation.count.per.metric (see page 335)
Specifies the maximum number of operations per deviation metric.
soa.deviation.dependency.refreshrate (see page 336)
Specifies how frequently, in hours, cached SOA Dependency Map dependency
relationship data is refreshed.
soa.deviation.errors.enable (see page 337)
Enables or disables Errors Per Interval deviation metrics.
soa.deviation.max.metric.count (see page 337)
Specifies the maximum number of deviation metrics to report.
soa.deviation.metric.expressionlist (see page 338)
Defines a list of names for deviation metric expressions.
soa.deviation.metric.calledbackends (see page 339)
Uses the names defined in the deviation.metric.expressionlist property to form a
new property for creating deviation metrics.
soa.deviation.usage.enable (see page 340)
Enables or disables the Responses Per Interval Deviation metrics.
soa.dashboard.typeviewer.average.enable (see page 341)
Enables or disables the display of the Average Response Time Deviation graph for a
selected operation.
soa.dashboard.typeviewer.response.enable (see page 343)
Enables or disables the display of the Responses Per Interval Deviation graph for a
selected operation.
soa.dashboard.typeviewer.errors.enable (see page 342)
Enables or disables the display of the Errors Per Interval Deviation graph for a
selected operation.


soa.dashboard.typeviewer.mostcritical.enable (see page 344)
Enables or disables the display of the Most Critical Operations dashboard and Most
Critical tab.
soa.dashboard.typeviewer.mostcritical.count (see page 345)
Specifies the maximum number of critical operations reported.
soa.dashboard.typeviewer.mostdependent.enable (see page 346)
Enables or disables the display of the Most Dependent Operations dashboard and
Most Dependent tab.
soa.dashboard.typeviewer.mostdependent.count (see page 347)
Specifies the maximum number of dependent operations reported.
In most cases, you must restart the Enterprise Manager for property changes to take
effect.


soa.dependencymap.aging.refresh.interval
Specifies the number of hours that will pass before the Enterprise Manager performs
the next SOA Dependency Map dependency aging check.
The Enterprise Manager tracks the age of each discovered dependency, and periodically
rediscovers dependencies to make sure they still exist. The age of a dependency is based
in its most recent discovery.
During the SOA Dependency Map dependency aging check, the Enterprise Manager
determines the age of each dependency across the SOA Dependency Map.
A SOA Dependency Map refresh interval is defined as 1 hour by default. Therefore, six
SOA Dependency Map refresh intervals would last 6 hours.
Property settings
Default
6 hours
Example
com.wily.introscope.soa.dependencymap.aging.refresh.interval=6
Notes
This property works in conjunction with the
com.wily.introscope.soa.dependencymap.aging.expire.interval property to
determine whether a dependency should be removed.
Changes to this property take effect immediately and do not require the Enterprise
Manager to be restarted.


soa.dependencymap.aging.expire.interval
The maximum age, in days, of a dependency in the SOA Dependency Map. During the
dependency aging check, the Enterprise Manager removes from the SOA Dependency
Map all dependencies older than the specified value.
For example, if com.wily.introscope.soa.dependencymap.aging.expire.interval has a
value of 60 days, then an expired dependency is one that has not been re-discovered
during the previous 60 days. If a dependency has not been re-discovered during that
period, it is removed from the dependency map.
Property settings
Default
60 days
Example
com.wily.introscope.soa.dependencymap.aging.expire.interval=90
Notes
This property works in conjunction with the
com.wily.introscope.soa.dependencymap.aging.refresh.interval property.
This property determines the criteria for removing a dependency which is then
applied during the SOA Dependency Map dependency aging check.
Changes to this property take effect immediately and do not require the Enterprise
Manager to be restarted.
soa.dependencymap.heuristics.clientside.enable
Enables or disables the CA APM for SOA client-side logical equivalence heuristics rule.
The client-side logical equivalence heuristics rule states the following:
Two physical service operations of type client are considered logically equivalent when
both operations depend on the same physical service operation of type server.
This setup can occur when two different applications make the same client-side service
operation call. This rule detects this logical equivalence when the two operations both
do and do not have the same metric path (not including the agent specifier).


Property settings
TrueApplies the CA APM for SOA client-side logical equivalence heuristics rule.
FalseDisables the CA APM for SOA client-side logical equivalence heuristics rule.
Default
True
Example
com.wily.introscope.soa.dependencymap.heuristics.clientside.enable=true
Notes
If this rule is changed, the change is not applied to previously discovered dependencies.
Therefore, changing the rule value can have unpredictable results unless you stop the
Enterprise Manager and delete both the previously saved SOA Dependency Map file
types.
Changes to this property take effect immediately and do not require a restart of the
Enterprise Manager.
More information:
Ignoring or removing saved dependency data (see page 69)

soa.dependencymap.heuristics.namematch.enable
Enables or disables the CA APM for SOA logical equivalence heuristics name match rule.
The logical equivalence heuristics name match rule detects logical equivalence when the
two operations have the same metric path (not including the agent specifier).
The CA APM for SOA logical equivalence heuristics name match rule states that two
physical web service operations with the same metric path after deletion of the agent
specifier are considered as logically equivalent.
Property settings
TrueEnables the logical equivalence heuristics name match rule.
FalseDisables the logical equivalence heuristics name match rule.


Default
False
Example
com.wily.introscope.soa.dependencymap.heuristics.namematch.enable=true
Notes
Therefore, changing the rule value may have unpredictable results unless the Enterprise
Manager is stopped and both the previously saved SOA Dependency Map file types are
deleted.
If you create a Virtual Agent in CA APM for SOA, enable this property.
Changes to this property take effect immediately and do not require a restart of the
Enterprise Manager.
More information:

soa.dependencymap.heuristics.serverside.enable
Enables or disables the CA APM for SOA server-side logical equivalence heuristics rule.
The server-side logical equivalence heuristics rule states that two physical service
operations of type server are considered logically equivalent, if and only if, there exists
some physical service operation of type client that depends on both operations.
Typically this only happens when the SOA incorporates some kind of load-balancing
mechanism such that a client-side web service operation call is dispatched to one of
several available server-side web service operation implementations
Property settings
TrueEnables the CA APM for SOA server-side logical equivalence heuristics rule.
FalseDisables the CA APM for SOA server-side logical equivalence heuristics rule.


Default
True
Example
com.wily.introscope.soa.dependencymap.heuristics.serverside.enable=true
Notes
Therefore, changing the rule value may have unpredictable results unless the Enterprise
Manager is stopped and both the previously saved SOA Dependency Map file types are
deleted.Changes to this property take effect immediately and do not require a restart of
the Enterprise Manager to be restarted.
More information:



soa.dependencymap.log.suppress
Specifies the maximum number of times the same error or warning message can be
written to the log file before the duplicate message is suppressed.
You can use this property to prevent a repeated error or warning message from being
sent to the Enterprise Manager log file at every occurrence. For example, if you have a
dependency map that exceeds the maximum number of nodes or the maximum number
of dependencies allowed, a warning message is recorded in the log file each time the
maximum is reached. With this property, after the error or warning has been posted to
the log file the specified number of times, a text string indicating the message is now
suppressed is appended to the last occurrence and no further copies of the error or
warning are recorded in the log file until the Enterprise Manager is restarted or this
property is modified.
Property settings
Default
5 log entries
Example
com.wily.introscope.soa.dependencymap.log.suppress=5
Notes
This property does not require you to restart the Enterprise Manager.
If you change the property value, however, the count for suppressing error and warning
messages starts over. For example, if a specific error message occurs 5 times, it is
suppressed by default. If you then change the property value to 6, the error message is
no longer suppressed and the error must occur 6 more times before it is suppressed.


soa.dependencymap.max.edge.ratio
Specifies the maximum ratio of dependencies to nodes in the map. You can use this
property to control the overall complexity of the dependency map stored on the
Enterprise Manager in large or complex SOA environments.
itself. You can use this property to specify a ratio between nodes and dependencies to
control the level of complexity allowed. When this limit is reached, no additional
dependencies are saved and a warning is written to the Enterprise Manager log file.
You can also use this property in combination with the
com.wily.introscope.soa.dependencymap.max.vertices property to limit the total
number of nodes stored in the dependency map.
In a clustered environment, this property only applies to the Collector Enterprise
Managers. You can use the MOM to store the full representation of the combined SOA
environment across Collectors.
Property settings
Default
5 dependencies per node
Example
com.wily.introscope.soa.dependencymap.max.edge.ratio=5
Notes
With the default values for the com.wily.introscope.soa.dependencymap.max.vertices
and com.wily.introscope.soa.dependencymap.max.edge.ratio properties, the
dependency map is limited to 5000 nodes and a maximum of 25000 dependencies (5 x
5000).
Most SOA networks have fewer than 5000 components with a dependency ratio of 1 or
2 dependencies per component. The default settings, therefore, allow for greater
complexity than most organizations need. You can use these properties to intentionally
restrict the size and complexity of the dependency map, but doing so may cause the
SOA dependency map model to be unnecessarily incomplete.


soa.dependencymap.max.vertices
Specifies the maximum number of nodes that can be stored for the dependency map on
a standalone or Collector Enterprise Manager. You can use this property to control the
maximum size of the dependency map stored on the Enterprise Manager in large or
complex SOA environments.
itself. You can use this property to limit the size of the SOA model by specifying the
maximum number of nodes to include. When this limit is reached, no additional
information is saved and a warning is written to the Enterprise Manager log file.
You can also use this property in combination with the
com.wily.introscope.soa.dependencymap.max.edge.ratio property to limit the total
number of dependency relationships stored in the dependency map.
In a clustered environment, this property only applies to the Collector Enterprise
Managers. You can use the MOM to store the full representation of the combined SOA
environment across Collectors.
Property settings
Default
5000 nodes
Example
com.wily.introscope.soa.dependencymap.max.vertices=5000


soa.deviation.enable
Enables or disables the calculations required to produce the following deviation metrics:
If you set this property to true, deviation metrics are collected and can be reported. You
can then selectively enable or disable each of the deviation metrics individually.
Property settings
True - Performs calculations to provide deviation metric data.
False - Does not report any deviation metrics.
Default
True
Example
com.wily.introscope.soa.deviation.enable=true
Notes
You must restart the Enterprise Manager before changes to this property take effect.


soa.deviation.art.enable
Enables or disables the Average Response Time deviation metrics. This property
determines whether the average response time deviation metrics are reported if you
are calculating deviation metrics.
Property settings
True - Performs calculations and reports the Average Response Time Deviation
metric data.
False - Does not report the Average Response Time Deviation metric.
Default
True
Example
com.wily.introscope.soa.deviation.art.enable=true
Notes
soa.deviation.dependencymetric.enable
This property enables or disables the calculations required to produce the following
dependency metrics:
Critical Direct
Critical Indirect
Dependency Direct
Dependency Indirect
This property determines whether any of the CA APM for SOA dependency metrics are
reported.
Property settings
TruePerforms calculations to provide dependency metric data.
FalseDoes not perform the dependency metric calculations.


Default
True
Example
com.wily.introscope.soa.deviation.dependencymetric.enable=true
Notes
soa.deviation.count.per.metric
This property specifies the maximum number of operations under the WebServices
node for which deviation metrics are calculated. When the number of operations that
are reported exceeds this number, the most critical operations under every Server and
Client node namespace are used.
Property Settings
Default
25 operations per dependency metric
Example
com.wily.introscope.soa.deviation.count.per.metric=25
Notes
For this property to take effect, restart the Enterprise Manager.


soa.deviation.dependency.refreshrate
Specifies how frequently, in hours, cached SOA Dependency Map dependency
relationship data is refreshed.
The SOA Dependency Map data is cached by the deviation metric service. Critical,
dependent, and deviation metrics are reported for these service and operations every
15 seconds.
The cached SOA Dependency Map data is periodically refreshed based on this property.
This map rarely changes and usually does so only if the deployment is changed.
Property settings
Default
1 hour
Example
com.wily.introscope.soa.deviation.dependency.refreshrate=1
Notes


soa.deviation.errors.enable
Enables or disables the errors deviation metrics. This property determines whether the
error count deviation metrics are reported if you are calculating deviation metrics.
Property settings
True - Performs calculations and reports the Errors Per Interval Deviation metric
data.
False - Does not report the Errors Per Interval Deviation metric.
Default
True
Example
com.wily.introscope.soa.deviation.errors.enable=true
Notes
soa.deviation.max.metric.count
Specifies the maximum number of deviation metrics to report.
CA Technologies does not recommend changing the default value of this property. The
default value reports enough metrics to provide useful information without affecting
Enterprise Manager performance. If you change the default value, the Enterprise
Manager may experience performance issues.
Property settings
Default
1000 total deviation metrics
Example
com.wily.introscope.soa.deviation.metric.count=1000
Notes


soa.deviation.mean.days
This property specifies the number of days to accumulate operations to calculate a
mean value. The mean value is automatically calculated after the specified number of
days.
Property Settings
Default
7 days.
Example
com.wily.introscope.soa.deviation.mean.days=3
Notes
For this property to take effect, restart the Enterprise Manager.
soa.deviation.metric.expressionlist
This property defines a list of names for deviation metric expressions. Set this property
to a comma-separated list of names you want to use for creating deviation metrics. Each
name is used as a separate metric expression.
The deviation.metric.calledbackends property references this property to create
user-defined deviation metrics.
Property settings
The property can be set to any user-defined list of names.
Default
calledbackends
Example
deviation.metric.expressionlist=alpha1, beta2, gama3


Calculating Additional Deviations
By default, deviation metrics are computed for individual operations only. For deviations
to be available at the WebService, client, or server namespace level, add the following
statements to the IntroscopeEnterpriseManager.properties file.
com.wily.introscope.soa.deviation.metric.expressionlist=test,test1
com.wily.introscope.soa.deviation.metric.test=WebServices\\|Client\\|.*
com.wily.introscope.soa.deviation.metric.test1=WebServices\\|Server\\|.*
Important! Extra processing overhead is required when deviations are calculated at
multiple levels in this manner.
Notes
For the changes to this property to take effect, restart the Enterprise Manager.
soa.deviation.metric.calledbackends
Uses the names defined in the deviation.metric.expressionlist property to form a new
property for creating deviation metrics.
The new property name has the following format:
com.wily.introscope.soa.deviation.metric.<user-defined_name> = <user-defined
regular expression>
The value assigned to the deviation.metric.calledbackends property is the metric
expression. For example:
com.wily.introscope.soa.deviation.metric.alpha1=Frontends|Called Backends
com.wily.introscope.soa.deviation.metric.beta2=Frontends|Called Backends
Default
calledbackends
Example
com.wily.introscope.soa.deviation.metric.calledbackends=Frontends|Frontends|FBApp
$Frontend|Called Backends|FBApp$Backend
Notes


soa.deviation.usage.enable
Enables or disables the Responses Per Interval Deviation metrics. This property
determines whether the response count deviation metrics are reported if you are
calculating deviation metrics.
Property settings
True - Performs calculations and reports the Responses Per Interval Deviation
metric data.
False - Does not report the Responses Per Interval Deviation metric.
Default
True
Example
com.wily.introscope.soa.deviation.usage.enable=true
Notes


soa.dashboard.typeviewer.average.enable
Enables the deviation data collected for a selected operation to display in the Average
Response Time Deviation graph in the following locations:
SOA Performance - Most Critical Operations dashboard
SOA Performance - Most Dependent Operations dashboard
Most Critical tab
Most Dependent tab
Deviation data is available for dashboards and tabs only if it is if reported by the agent
to the Enterprise Manager, and allowed to be displayed in the Workstation. For more
information about reporting deviation data, see Viewing deviation metrics on the
Deviations tab (see page 59).
Property settings
True - Enables data for the selected operation to display in the Average Response
Time Deviation graph.
False - Disables the display of data for the selected operation in the Average
Response Time Deviation graph.
Default
True
Example
com.wily.introscope.soa.dashboard.typeviewer.average.enable=true
Notes
This property can be defined in the IntroscopeEnterpriseManager.properties file or the
IntroscopeWorkstation.properties file. If the property is defined in both the
IntroscopeWorkstation.properties file and the IntroscopeEnterpriseManager.properties
file, the IntroscopeWorkstation.properties property setting is used.


soa.dashboard.typeviewer.errors.enable
Enables the deviation data collected for a selected operation to display in the Errors Per
Interval Deviation graph in the following locations:
Most Critical tab
Most Dependent tab
Property settings
True - Enables data for the selected operation to display in the Error Per Interval
Deviation graph.
False - Disables the display of data for the selected operation in the Errors Per
Interval graph.
Default
True
Example
com.wily.introscope.soa.dashboard.typeviewer.response.enable=true
Notes
IntroscopeWorkstation.properties file. If this property is defined in both the


soa.dashboard.typeviewer.response.enable
Enables the deviation data collected for a selected operation to display in the Responses
Per Interval Deviation graph in the following locations:
Most Critical tab
Most Dependent tab
Property settings
True - Enables data for the selected operation to display in the Responses Per
Interval Deviation graph.
False - Disables the display of data for the selected operation in the Responses Per
Default
True
Example
Notes


soa.dashboard.typeviewer.mostcritical.enable
Enables the display of the Most Critical Operations dashboard in the Console and the
Most Critical tab in the Investigator.
Property settings
True - Enables the SOA Performance - Most Critical Operations dashboard option to
be displayed in the Console dashboard menu and the Most Critical tab to be
displayed in the Investigator.
False - Disables access to the SOA Performance - Most Critical Operations
dashboard and the Most Critical tab.
If this property is set to false, the Most Critical tab is not displayed for any node in the
Investigator. The Most Critical Operations dashboard remains listed in the Console
dashboard drop-down list, but the dashboard is not displayed if selected. Instead of the
Most Critical Operations dashboard, an error message indicates that the dashboard is
not available.
Default
True
Example
com.wily.introscope.soa.dashboard.typeviewer.mostcritical.enable=true
Notes
You must restart the Enterprise Manager and Workstation before changes to this
property take effect.


soa.dashboard.typeviewer.mostcritical.count
Determines the total number of critical operations reported by all agents in the SOA
Performance - Most Critical Operations dashboard and the Most Critical tab.
Property settings
The minimum value is 0.
The maximum value should be less than or equal to the value of the
com.wily.introscope.soa.deviation.count.per.metric property, which has a default value
of 25.
Default
10 operations
Example
Notes
IntroscopeEnterpriseManager.properties file and the IntroscopeWorkstation.properties


soa.dashboard.typeviewer.mostdependent.enable
Enables the display of the Most Dependent Operations dashboard in the Console and
the Most Dependent tab in the Investigator.
Property settings
True - Enables the SOA Performance - Most Dependent Operations dashboard
option to be displayed in the Console dashboard menu and the Most Dependent
tab to be displayed in the Investigator.
False - Disables access to the SOA Performance - Most Dependent Operations
dashboard and the Most Dependent tab.
If this property is set to false, the Most Dependent tab is not displayed in the
Investigator. The Most Dependent Operations dashboard remains listed in the Console
Most Dependent Operations dashboard, an error message indicates that the dashboard
is not available.
Default
True
Example
com.wily.introscope.soa.dashboard.typeviewer.mostdependent.enable=true
Notes


soa.dashboard.typeviewer.mostdependent.count
Determines the total number of most dependent operations reported by the agents in
the SOA Performance - Most Dependent Operations dashboard and the Most
Dependent tab.
Property settings
of 25.
Default
10 operations
Example
com.wily.introscope.soa.dashboard.typeviewer.mostdependent.count=5
Notes


Appendix C: SOA-Specific Workstation

Workstation configuration properties enable you to control the behavior and operation
of the Workstation. These properties also allow you to customize the Workstation to
best suit your environment. Workstation properties let you specifically configure CA
APM for SOA.
Configuring Workstation properties (see page 350)
About SOA-Specific Workstation Properties (see page 351)
Configuring Workstation properties


Configuring Workstation properties
CA APM for SOA includes several SOA-specific Workstation properties with default
settings. Before you can configure any of these properties, however, you must first add
the property name to the IntroscopeWorkstation.properties file.
To add a Workstation property to IntroscopeWorkstation.properties:
1. Open the IntroscopeWorkstation.properties file in the <EM_Home>/config
directory.
2. Find the property listed in About SOA-specific Workstation properties (see
page 351) that you want to add to the IntroscopeWorkstation.properties file.
3. Add the full name of the property including the com.wily.introscope prefix to the
IntroscopeWorkstation.properties file. For example:
com.wily.introscope.soa.dashboard.typeviewer.mostcritical.count
property:
After the Workstation property has been added to the IntroscopeWorkstation.properties
file, you can configure the property value as necessary.
To change a Workstation configuration property value:
1. Open the IntroscopeWorkstation.properties file in the <EM_Home>/config
directory.
This setting is only intended as an example and is not a CA APM for SOA
recommended setting.
3. Save and close the IntroscopeWorkstation.properties file.
4. Restart the Workstation for the property change to take effect.
About SOA-Specific Workstation Properties


You can set the following SOA-specific properties in the
IntroscopeWorkstation.properties file. All of the properties start with
com.wily.introscope, but are listed without this prefix for readability.
Note: For information about setting other Workstation properties, see the CA APM
soa.dependencymap.ui.view.nodecount (see page 352)
Specifies the maximum number of map nodes to display on the SOA Dependency
Map.
com.wily.introscope.soa.dependencymap.ui.view.edgecount (see page 353)
Specifies the maximum number of map edges to display on the SOA Dependency
Map.
soa.dashboard.typeviewer.average.enable (see page 341)
Enables or disables the display of the Average Response Time Deviation graph for a
selected operation.
soa.dashboard.typeviewer.response.enable (see page 343)
Enables or disables the display of the Responses Per Interval Deviation graph for a
selected operation.
soa.dashboard.typeviewer.errors.enable (see page 342)
Enables or disables the display of the Errors Per Interval Deviation graph for a
selected operation.
soa.dashboard.typeviewer.mostcritical.enable (see page 344)
Enables or disables the display of the Most Critical Operations dashboard and Most
Critical tab.
soa.dashboard.typeviewer.mostcritical.count (see page 345)
Specifies the maximum number of critical operations reported.
soa.dashboard.typeviewer.mostdependent.enable (see page 346)
Enables or disables the display of the Most Dependent Operations dashboard and
Most Dependent tab.
soa.dashboard.typeviewer.mostdependent.count (see page 347)
Specifies the maximum number of dependent operations reported.
workstation.soa.dependencymap.fetchmetrics (see page 361)
Controls the display of the metrics in the SOA Dependency Map.
workstation.traceview.crossprocess.duration.full (see page 362)
Determines whether the full duration time is used for transaction traces.


workstation.traceview.crossprocess.duration.net (see page 363)
Determines whether the net duration time is used for transaction traces.
In most cases, you must restart the Workstation for property changes to take effect. If a
property is defined in the IntroscopeWorkstation.properties file and the
IntroscopeEnterpriseManager.properties file, the IntroscopeWorkstation.properties
property setting is used.
soa.dependencymap.ui.view.nodecount
This property specifies the maximum number of map nodes that display on the
Workstation, SOA Dependency Map.
If you select an Investigator node, and the number of SOA Dependency Map nodes
exceeds the com.wily.introscope.soa.dependencymap.ui.view.nodecount value, an error
message displays. No SOA Dependency Map displays.
If you select a new context and the number of SOA Dependency Map nodes exceeds the
com.wily.introscope.soa.dependencymap.ui.view.nodecount value, an error message
displays, and the SOA Dependency Map reverts back to the previous view. For example,
if you change from the Physical view for Agents to the Physical view for Services view
and the node count limit is exceeded, the SOA Dependency Map displays an error
message and reverts back to the Physical view for Agents.
If you expand the information displayed using ShowAllOperations or ShowAllServices
and the node count value is exceeded, the SOA Dependency Map displays the error
message and displays any recently-added SOA Dependency Map nodes.
Property settings
You can set the property to any whole integer greater than zero.
Default
200 map nodes
Example
com.wily.introscope.soa.dependencymap.ui.view.nodecount=200
Notes
You must restart the Workstation before changes to this property take effect.


com.wily.introscope.soa.dependencymap.ui.view.edgecount
This property specifies the maximum number of map edges that display on the
Workstation, SOA Dependency Map.
If you select an Investigator node, and the number of SOA Dependency Map edges
exceeds the com.wily.introscope.soa.dependencymap.ui.view.edgecount property
value, an error message displays. No SOA Dependency Map displays.
If you select a new context and the number of SOA Dependency Map edges exceeds the
com.wily.introscope.soa.dependencymap.ui.view.edgecount property value, an error
message displays, and the SOA Dependency Map reverts back to the previous view no
SOA Dependency Map displays. For example, if you change from the Physical view for
Agents to the Physical view for Services view and the node edge count limit is exceeded,
the SOA Dependency Map displays an error message and reverts back to the Physical
view for Agents, and no map displays.
and the edge count value is exceeded, the SOA Dependency Map displays the error
message and displays any recently-added SOA Dependency Map edges.
To prevent the SOA dependency map from affecting application performance, you can
limit the size and complexity of the map by reducing the default value from 1000 to 400.
Property settings
Default
1000
Recommended value
400
Example
com.wily.introscope.soa.dependencymap.ui.view.edgecount=250
Notes
You must restart the Workstation application before changes to this property take
effect.


soa.dashboard.typeviewer.average.enable
Enables the deviation data collected for a selected operation to display in the Average
Response Time Deviation graph in the following locations:
Most Critical tab
Most Dependent tab
Property settings
True - Enables data for the selected operation to display in the Average Response
Time Deviation graph.
False - Disables the display of data for the selected operation in the Average
Response Time Deviation graph.
Default
True
Example
com.wily.introscope.soa.dashboard.typeviewer.average.enable=true
Notes
IntroscopeWorkstation.properties file. If the property is defined in both the


soa.dashboard.typeviewer.errors.enable
Enables the deviation data collected for a selected operation to display in the Errors Per
Interval Deviation graph in the following locations:
Most Critical tab
Most Dependent tab
Property settings
True - Enables data for the selected operation to display in the Error Per Interval
Deviation graph.
False - Disables the display of data for the selected operation in the Errors Per
Interval graph.
Default
True
Example
Notes


soa.dashboard.typeviewer.response.enable
Enables the deviation data collected for a selected operation to display in the Responses
Per Interval Deviation graph in the following locations:
Most Critical tab
Most Dependent tab
Property settings
True - Enables data for the selected operation to display in the Responses Per
False - Disables the display of data for the selected operation in the Responses Per
Default
True
Example
Notes


soa.dashboard.typeviewer.mostcritical.enable
Enables the display of the Most Critical Operations dashboard in the Console and the
Most Critical tab in the Investigator.
Property settings
True - Enables the SOA Performance - Most Critical Operations dashboard option to
be displayed in the Console dashboard menu and the Most Critical tab to be
displayed in the Investigator.
False - Disables access to the SOA Performance - Most Critical Operations
dashboard and the Most Critical tab.
If this property is set to false, the Most Critical tab is not displayed for any node in the
Investigator. The Most Critical Operations dashboard remains listed in the Console
Most Critical Operations dashboard, an error message indicates that the dashboard is
not available.
Default
True
Example
com.wily.introscope.soa.dashboard.typeviewer.mostcritical.enable=true
Notes


soa.dashboard.typeviewer.mostcritical.count
Determines the total number of critical operations reported by all agents in the SOA
Performance - Most Critical Operations dashboard and the Most Critical tab.
Property settings
of 25.
Default
10 operations
Example
Notes


Enables the display of the Most Dependent Operations dashboard in the Console and
the Most Dependent tab in the Investigator.
Property settings
True - Enables the SOA Performance - Most Dependent Operations dashboard
option to be displayed in the Console dashboard menu and the Most Dependent
tab to be displayed in the Investigator.
False - Disables access to the SOA Performance - Most Dependent Operations
dashboard and the Most Dependent tab.
If this property is set to false, the Most Dependent tab is not displayed in the
Investigator. The Most Dependent Operations dashboard remains listed in the Console
Most Dependent Operations dashboard, an error message indicates that the dashboard
is not available.
Default
True
Example
com.wily.introscope.soa.dashboard.typeviewer.mostdependent.enable=true
Notes


Determines the total number of most dependent operations reported by the agents in
the SOA Performance - Most Dependent Operations dashboard and the Most
Dependent tab.
Property settings
of 25.
Default
10 operations
Example
com.wily.introscope.soa.dashboard.typeviewer.mostdependent.count=5
Notes


workstation.soa.dependencymap.fetchmetrics
Controls the display of the metrics in the SOA Dependency Map.
Property settings
True - Requests the primary metric and the Tooltip metrics you selected from the
Enterprise Manager. If you set the property to true, the SOA Dependency Map
displays the primary metric on every map node. The additional metrics are
displayed in a Tooltip when you hover over a map node.
False - Does not display the primary metric on the SOA Dependency map nodes or
additional metrics in the Tooltip window.
Default
True
Example
com.wily.introscope.workstation.soa.dependencymap.fetchmetrics=true
Notes


workstation.traceview.crossprocess.duration.full
Determines whether the full duration time for transaction traces is displayed and used
as the default for traces on the Sequence View tab in the Transaction Trace Viewer.
Full duration time is calculated using the start-to-end time for a process, which can
include the time the process spends waiting for another process to execute. With this
approach, the root trace is always the slowest in synchronous transactions. Net duration
is calculated by subtracting duration times of a traces asynchronous children from the
full duration time.
If you make no changes to the Workstation properties file, the Sequence View tab
allows you to select either full duration or net duration time with full duration displayed
by default.
Property settings
If you add only the introscope.workstation.traceview.crossprocess.duration.full property
to the Workstation properties file, only full duration is displayed on the Sequence View
tab.
If you add introscope.workstation.traceview.crossprocess.duration.full and
introscope.workstation.traceview.crossprocess.duration.net to the Workstation
properties file, both full duration and net duration can be displayed on the Sequence
View tab and the default is determined by the property with the lowest value.
For example, if you want allow the selection of full or net duration but want net
duration time displayed by default, you can set the properties as follows in the
Workstation properties file:
com.wily.introscope.workstation.traceview.crossprocess.duration.full=2
com.wily.introscope.workstation.traceview.crossprocess.duration.net=1
Default
1 (Full duration displayed)
Example
Notes


workstation.traceview.crossprocess.duration.net
Determines whether the net duration time for transaction traces is displayed and used
as the default for traces on the Sequence View tab in the Transaction Trace Viewer.
Net duration is calculated by subtracting duration times of a traces asynchronous
children from the full duration time. The primary advantage of this approach is that the
slowest thread is readily apparent for synchronous transactions.
If you make no changes to the Workstation properties file, the Sequence View tab
allows you to select either full duration or net duration time with full duration displayed
by default.
Property settings
If you add only the introscope.workstation.traceview.crossprocess.duration.net property
to the Workstation properties file, only net duration is displayed on the Sequence View
tab.
If you add introscope.workstation.traceview.crossprocess.duration.full and
introscope.workstation.traceview.crossprocess.duration.net to the Workstation
properties file, both full duration and net duration can be displayed on the Sequence
View tab and the default is determined by the property with the lowest value.
For example, if you want allow the selection of full or net duration but want net
duration time displayed by default, you can set the properties as follows in the
Workstation properties file:
Default
2 (Net duration not displayed as the default)
Example
Notes


Appendix D: SOA-Specific WebView

WebView configuration properties enable you to control the behavior and operation of
the WebView application. These properties also allow you to customize the WebView to
best suit your environment. The WebView properties let you specifically configure CA
APM for SOA.
Configure WebView Properties (see page 365)
About SOA-Specific WebView Properties (see page 366)
Configure WebView Properties
CA APM for SOA includes SOA-specific WebView properties with default settings. Before
you start the configuration, add the property name to the
IntroscopeWebView.properties file.
To add a WebView property to IntroscopeWebView.properties:
1. Open the IntroscopeWebView.properties file in the <EM_Home>/config directory.
2. Find the SOA-specific WebView property (see page 366) that you want to add to the
IntroscopeWebView.properties file.
3. Add the full name of the property including the com.wily.introscope prefix to the
IntroscopeWebView.properties file. For example:
property:
5. Save and close the IntroscopeWebView.properties file.
After the WebView property has been added to the IntroscopeWebView.properties file,
you can configure the property value as necessary.
To change a WebView configuration property value:
1. Open the IntroscopeWebView.properties file in the <EM_Home>/config directory.
About SOA-Specific WebView Properties


This setting is only intended as an example and is not a CA APM for SOA
recommended setting.
3. Save and close the IntroscopeWebView.properties file.
4. Restart the WebView application for the property change to take effect.
You can set the following SOA-specific properties in the IntroscopeWebView.properties
file. All of the properties start with com.wily.introscope, but are listed without this prefix
for readability.
Note: For information about setting other WebView properties, see the CA APM
soa.dependencymap.ui.view.nodecount (see page 366)
Specifies the maximum number of map nodes that display on the WebView, SOA
Dependency Map.
com.wily.introscope.soa.dependencymap.ui.view.edgecount (see page 367)
Specifies the maximum number of map edges that display on the WebView, SOA
Dependency Map.
soa.dependencymap.ui.view.nodecount
This property specifies the maximum number of map nodes that display on the
WebView, SOA Dependency Map.
If you select an Investigator node, and the number of SOA Dependency Map nodes
exceeds the com.wily.introscope.soa.dependencymap.ui.view.nodecount property
value, an error message displays. No SOA Dependency Map displays.
If you select a new context and the number of SOA Dependency Map nodes exceeds the
com.wily.introscope.soa.dependencymap.ui.view.nodecount property value, an error
message displays, and no SOA Dependency Map displays. For example, if you change
from the Physical view for Agents to the Physical view for Services view and the node
count limit is exceeded, the SOA Dependency Map displays an error message and no
map displays.
and the node count value is exceeded, the SOA Dependency Map displays the error
message and displays any recently-added SOA Dependency Map nodes.
limit the size and complexity of the map by reducing the default property value from
200 to a lower value.


Property settings
Default
200 map nodes
Recommended value
200 map nodes
Example
com.wily.introscope.soa.dependencymap.ui.view.nodecount=200
Notes
You must restart the WebView application before changes to this property take effect.
This property specifies the maximum number of map edges that display on the
WebView, SOA Dependency Map.
If you select an Investigator node, and the number of SOA Dependency Map edges
exceeds the com.wily.introscope.soa.dependencymap.ui.view.edgecount value, an error
message displays. No SOA Dependency Map displays.
If you select a new context and the number of SOA Dependency Map edges exceeds the
com.wily.introscope.soa.dependencymap.ui.view.edgecount value, an error message
displays, and no SOA Dependency Map displays. For example, if you change from the
Physical view for Agents to the Physical view for Services view and the edge count limit
is exceeded, the SOA Dependency Map displays an error message and no map displays.
and the edge count value is exceeded, the SOA Dependency Map displays the error
message and displays any recently-added SOA Dependency Map edges.
limit the size and complexity of the map by reducing the default value from 1000 to 250.


Property settings
Default
1000 map edges
Recommended value
250 map edges
Example
Notes
You must restart the WebView application before changes to this property take effect.

Index 369

Index

A
A closer look at critical and dependency metrics 57
About Average Response Time for completed
processes 266
About Average Response Time for Processing Rules
271
About Average Response Time for server endpoints
157
About CA Application Performance Management for
SOA 17
About client and server SOAP fault metrics 158
About Client and Server Web Services and
Operations 44
About client-side metrics 274
About complete and active execution for business
processes 153
About Concurrent Invocations for steps in a process
266
About Configuring Cross-Process Transaction Tracing
277
About critical operations and metrics 56
About cross-process transaction tracing 89
About dependent operations and metrics 56
About direct and indirect operation dependencies
55
About Errors Per Interval for failed processes 266
About errors per interval in subprocesses 154
164
About Investigator tree nodes and map nodes 75
About logical equivalence rules 72
About map nodes for operations 76
About monitoring primary and backup servers 205
About Oracle Service Bus (OSB) 111
About Persisted Data for the SOA Dependency Map
68
About Responses Per Interval for completed
processes 266
About server-side metrics 273
About service namespaces and operation names
44
About SOA-Specific Agent Properties 312
322
About SOA-Specific WebView Properties 366
About SOA-Specific Workstation Properties 351
About standalone and dependent map nodes 75
About synchronous and asynchronous concurrent
invocations 301
About synchronous and asynchronous error metrics
302
About synchronous and asynchronous response
metrics 302
About synchronous and asynchronous response time
metrics 301
About synchronous and asynchronous stall count
metrics 302
About the Default Configuration File 259
About the directive files for Oracle Service Bus 115
About the Directive Files for TIBCO BusinessWorks
134
About the Directive Files for webMethods
Integration Server 252
About the stall count for business processes 154
About TIBCO BusinessWorks 129
About TIBCO Enterprise Message Service 169
About typical and full instrumentation 132
About Unidentified Services and Operations 45
About virtual agents 45
About webMethods Broker 221
About webMethods Integration Server 247
About WebSphere Process Server and WESB 281
About WebSphere Process Server dashboards 292
About WESB dashboards 294
Add SOA-Related Extensions Using the Silent
Installation Response File 36
Adding a custom TIBCO BusinessWorks backend
166
Adding and saving filters 100
Adding CA APM for SOA Manually to an Agent 33
Adding SOA-Related Extensions Interactively 36
Adding SOA-Related Extensions Manually After
Installing the Agent 37
Additional SOA Platform Support 25
Agent Properties Configuration After Installation
35
agent.httpheaderinsertion.enabled 313
agent.httpheaderread.enabled 314
agent.soa.metricNameFormatting 316


agent.soapheaderinsertion.enabled 315
agent.soapheaderread.enabled 316
agent.transactiontrace.boundaryTracing.cacheFlushF
requency 317
agent.transactiontrace.boundaryTracing.enable
318
Aging and removal for obsolete map nodes 71
Applying content type changes to all objects in the
map 74
B
Backing Up Before Upgrading From a Previous
Version 30
Basic system requirements for agents 28
C
CA Introscope Components and Versions 28
CA Technologies Product References 3
Changing the content type without changing the
selected node 73
Changing the Default Order for SOAP Handlers 108
Changing the dependency levels displayed 79
Checking for additional dependencies for a map
node 80
Checking for additional dependencies for all items in
the map 81
Choosing a physical or logical view 76
Client and Server Properties for Inserting the SOAP
Handler 107
Collect Metrics for Multiple Versions of a Business
Process and Business State Machines 287
Collect Performance Monitoring Infrastructure (PMI)
Metrics 289
com.wily.introscope.soa.dependencymap.ui.view.ed
gecount 353, 367
Common components of the SOA infrastructure 18
Configure Agent Properties 311
Configure Basic Connection Properties 227
Configure Polling Intervals for Collecting Metrics
228
228
6.5 230
Configure the Agent for the webMethods Broker
226
Configure the Broker Client Groups to Monitor 228
Configure TIBCO BusinessWorks to Use the Agent
135
Configure Tracing to Include Business
Process/Business State Machine Activities 308
Configure WebView Properties 365
Configuring automatic agent naming 136
Configuring basic connection properties 174
Configuring correlated tracing 105
Configuring correlated tracing for TIBCO
BusinessWorks 167
Configuring Enterprise Manager properties 321
Configuring filters for queues and topics 176
Configuring filters for selective monitoring 176
108
Configuring polling intervals for the server 175
Configuring properties for clients and servers 106
Configuring SOA-Specific Properties 103
107
103
Configuring the TIBCO EMSMonitor agent 173
Configuring Workstation properties 350
183
Contact CA Technologies 5
Creating encrypted passwords 182
Customizing metric aging and removal 167
D
Defining a monitoring level 178
Defining regular expression filters for advanced
components 177
Defining the advanced components to include 177
Deviation Metrics Calculations 59
Disabling correlated tracing 106
Disabling the association of multiple backends with a
frontend 165
Disconnecting and remounting agents 70
Displaying the SOA Dependency Map 74
E
Enable Extensions on the Enterprise Manager 37
Enable Hawk Metrics 149
Enable or Disable Metrics for Rendezvous 156
Enable the Enterprise Manager Extension 137, 186,
253

Index 371

Enable the Enterprise Manager Extension for
webMethods Broker 231
Enable the Enterprise Manager Extension for WPS or
WESB 289
Enable the Oracle Service Bus Enterprise Manager
Extension 116
Enabling or disabling metrics for jobs and job pools
151
Enabling the agent for monitoring Oracle Service Bus
114
Enabling the agent for monitoring TIBCO
BusinessWorks 131
Enabling the agent for monitoring WPS or WESB
286
Event metrics 239
Execution metrics 143
F
Filtering the services monitored and displayed 258
Flow Services That Call Other Flow Services 267
Forcing the Enterprise Manager to rediscover
dependencies 69
H
Hiding dependencies for a map node 80
Hiding dependencies for all items in the map 81
How the SOA Dependency Map Gets Data 68
How to Add CA APM for SOA to an Agent 31
114
131
How to Enable Monitoring for webMethods
Integration Server 250
How To Enable Monitoring for WebSphere Process
Server or WESB 285
How to Enable SOA Platform Extensions 35
170
How to Install the SOA Extension for webMethods
Broker 223
How to Monitor SOA Performance Using CA
Introscope 19
How to Use the Transaction Trace Data in Tibco
162
I
Ignoring or removing saved dependency data 69
Including and excluding services using regular
expressions 259
Installation and Configuration 27
Installing and Configuring CA APM for SOA 27
J
Jumping from a map node to the associated
Investigator tree node 83
M
Manually Enable the Agent for Monitoring
webMethods Integration Server 251
Manually Extract an Installation Archive 172, 225
Memory usage metrics 144
Message Listeners, Message Processors, and
Transport Metrics 156
Metrics for Activities 142
Metrics for Adapter Connection Pools 262
Metrics for Adapter Notifications 263
Metrics for Adapter Services 263
Metrics for Adapters 261
Metrics for Authorization 263
Metrics for Bridges 212
Metrics for Brokers 238
Metrics for Business Objects Maps 297
Metrics for Business Processes 264, 297
Metrics for Business Rules 297
Metrics for Business State Machines 298
Metrics for BusinessServices 121
Metrics for Channels 210
Metrics for Client groups 239
Metrics for Clients 239
Metrics for Data Bindings 298
Metrics for Document Types 241, 270
Metrics for Flow Services 267
Metrics for Group Actions 142
Metrics for Hawk 142
Metrics for Human Tasks 298
Metrics for Interface Maps 298
Metrics for J2CA Adapters 299
Metrics for Java Components 299
Metrics for Java Services 267
Metrics for JDBC Pools 268
Metrics for jobs and job pools 150
Metrics for Last Check 192
Metrics for Mediation flows and primitives 299
Metrics for Pipelines 122
Metrics for Processes 152


Metrics for Processing Rules 271
Metrics for ProxyServices 122
Metrics for Queues 193
Metrics for Relationships 303
Metrics for Rendezvous (RV) 155
Metrics for Routes 209
Metrics for Selectors 303
Metrics for Service Execution Tasks 272
Metrics for Service Integration Bus Communication
303
Metrics for Service Threads 272
Metrics for Territory Stats 242
Metrics for the Retry Queue 241
Metrics for the Server 197
Metrics for the Trace queue 243
Metrics for Thread Pools 268
Metrics for Topics 205
Metrics for Trading Networks 269
Metrics for Transports 123, 154
Metrics for Triggers 272
Metrics for UDDI 124
Metrics for Utilization 244
Metrics for WebServices 157, 272
Metrics for WebSphere Process Server Faults 303
Metrics for XQueries 124
Metrics for XSLT Services 274
Modifying the default monitoring level definitions
180
Monitoring a Service-Oriented Architecture 43
Monitoring Across Multiple Platforms and
Transports 22
Monitoring Oracle Service Bus 111
Monitoring TIBCO BusinessWorks 129
Monitoring TIBCO Enterprise Message Service 169
Monitoring Web Service Clients and Servers 20
Monitoring webMethods Broker 221
Monitoring webMethods Integration Server 247
Monitoring WebSphere Enterprise Service Bus
standalone 285
Monitoring WebSphere Process Server and WESB
281
Monitoring WebSphere Process Server Components
282
N
Native SOAP Engine Support for .NET Agents 29
Native SOAP Engine Support for Java Agents 29
Navigating between Sequence View and Trace View
96
Navigating within the SOA Dependency Map 82
P
Panning, zooming, and fitting the SOA Dependency
Map 82
Prepare the TIBCO EMS Server for Monitoring 172
Prepare webMethods Broker for Monitoring 225
Process definition and activity metrics 144
Processes metrics 147
Q
Querying the event database for SOA services 101
Queue Groups Metrics 156
Queue metrics 240
Queues Metrics 156
R
Remove CA APM for SOA 41
Removing filters 100
Replacement of Special Characters in EMS Names
178
Required Configuration for Business Process
Manager 8.0 and 8.1 287
Run the Standalone Agent Installer 171, 223
Running the EMSMonitor agent as a Windows
service 186
S
Saving SOA Dependency Map images 84
Saving the SOA Dependency Map as a snapshot 85
Select a Content Type 77
Selecting a method for calculating duration 96
Selecting a method for labeling the process nodes
95
Selecting CA APM for SOA in the Standalone Agent
Installer 31
Selecting ToolTip metrics for dependency map nodes
78
Services metrics 148
Session metrics 240
78
Set Filters for Transaction Traces 98
Showing all operations for a service 83
Showing all services for an agent 84
SOA Dependency Map for a Cluster 87

Index 373

SOA Dependency Map Sharing 84
SOA Performance Busiest Operations Dashboard
52
SOA Performance Client Health Dashboard 50
SOA Performance Most Critical Operations
Dashboard 51
SOA Performance Most Dependent Operations
Dashboard 51
SOA Performance Overview Dashboard 49
SOA Performance Server Health Dashboard 50
soa.client.prependhandler 318
soa.dashboard.typeviewer.average.enable 341,
354
soa.dashboard.typeviewer.errors.enable 342, 355
soa.dashboard.typeviewer.mostcritical.count 345,
358
soa.dashboard.typeviewer.mostcritical.enable 344,
357
347, 360
346, 359
soa.dashboard.typeviewer.response.enable 343,
356
soa.dependencymap.aging.expire.interval 326
soa.dependencymap.aging.refresh.interval 325
soa.dependencymap.heuristics.clientside.enable
326
soa.dependencymap.heuristics.namematch.enable
327
soa.dependencymap.heuristics.serverside.enable
328
soa.dependencymap.log.suppress 330
soa.dependencymap.max.edge.ratio 331
soa.dependencymap.max.vertices 332
soa.dependencymap.ui.view.nodecount 352, 366
soa.deviation.art.enable 334
soa.deviation.count.per.metric 335
soa.deviation.dependency.refreshrate 336
soa.deviation.dependencymetric.enable 334
soa.deviation.enable 333
soa.deviation.errors.enable 337
soa.deviation.max.metric.count 337
soa.deviation.mean.days 338
soa.deviation.metric.calledbackends 339
soa.deviation.metric.expressionlist 338
soa.deviation.usage.enable 340
soa.server.appendhandler 319
SOAP and Application Server Requirements for
Agents 28
SOA-Specific Agent Configuration Properties 311
SOA-Specific Enterprise Manager Configuration
Properties 321
SOA-Specific WebView Configuration Properties
365
SOA-Specific Workstation Configuration Properties
349
Specifying a Different Location for the Configuration
File 260
Start and View Transaction Traces 92
Start EMSMonitor With a Startup Script 185
Start the Agent 231
Starting a Transaction Trace from a map node 86
163, 278, 307
Starting and Viewing a Sample Transaction Trace
127
Starting the EMSMonitor agent 185
Status metrics 149
Summary of agent configuration properties 214
T
The Available Metrics 52
Tracing transactions for Oracle Service Bus 127
Tracing transactions for TIBCO BusinessWorks 161
Tracing transactions for webMethods 277
Tracing transactions for WPS or WESB 306
Tracing transactions that involve SOA components
21
U
Understanding and viewing metrics for Oracle
Service Bus 120
234
Understanding and viewing metrics for TIBCO
BusinessWorks 140
Understanding and viewing TIBCO EMS metrics 189
Understanding context for a cross-process
transaction trace 91
73
Understanding dependencies and SOA terminology
66
Understanding Directory and File Naming
Conventions 29


Understanding how segments of a transaction are
linked 90
Understanding how the content type affects what
you see 73
Understanding how the Investigator node affects
what you see 74
23
Understanding the challenge of the SOA
environment 65
Understanding the limitations for spawned
processes 165
65
Understanding the value of cross-process
transaction tracing 127, 163, 278, 306
Understanding what the SOA Dependency Map
provides 66
Understanding what you can do with the SOA
Dependency Map 67
Understanding where agent properties are located
311
Update the .NET Agent Manually to Use CA APM for
SOA 34
Update the Java Agent Manually to Use CA APM for
SOA 33
Updating the dependency map with new services
and operations 70
Use a Response File for Silent Installation 171, 224
Use Dashboards to Monitor Oracle Service Bus 118
138
Use Dashboards to Monitor TIBCO EMS 187
Use Dashboards to Monitor webMethods 253
232
Use Silent Mode to Enable CA APM for SOA for the
Agent 32
Use the SOA Performance Dashboards 46
Use the Trace View 94
Use the Tree View 94
Using complex filters 101
Using dashboards to monitor WPS or WESB 292
52
Using SOA-Specific Dashboards for Proactive
Management 21
Using the default monitoring level definitions 179
Using the Sequence View 95
Using the Sequence View for webMethods processes
278
Using the Sequence View for WebSphere processes
307
Using the SOA Dependency Map 65
Using the Summary View 93
Using Transaction Tracing in SOA Environments 89
Using transaction tracing to solve problems 91
V
Verify Prerequisites 223
Verify the CA APM for SOA Deployment 40
View and Navigate Metrics for webMethods 260
View and Navigate Metrics for WPS/WESB 296
View Critical Operation Metrics on the Most Critical
Tab 60
View Default Broker Alerts 245
View Default Broker Metric Groupings 244
View Default Oracle Service Bus Alerts 125
124
158
View Dependency Metrics on the Dependencies Tab
55
View Dependent Operations on the Most Dependent
Tab 60
View Step-Level Metrics for Business Processes 265
View Summarized Metrics on Overview Tabs 53
View the Default CA APM for SOA Alerts 63
View the Default SOA-Specific Metric Groupings 62
View WebSphere Process Server or WESB
Dashboards 295
Viewing boundary blame in the Investigator 62
Viewing correlated event information 102
Viewing default TIBCO BusinessWorks alerts 158
Viewing default TIBCO EMS alerts 213
Viewing default TIBCO EMS metric groupings 212
Viewing default webMethods alerts 275
Viewing default webMethods metric groupings 274
Viewing default WPS and WESB alerts 304
303
Viewing Dependencies and Using Metrics for Triage
and Diagnosis 21
Viewing details about processes in a transaction 97
Viewing Deviation Metrics on the Deviations Tab
59

Index 375

Viewing error event information 102
Viewing Oracle Service Bus dependencies 126
Viewing SOAP Fault and Error Metrics on the Errors
Tab 61
43
Viewing TIBCO BusinessWorks dependencies 159
Viewing webMethods dependencies 276
Viewing WPS or WESB dependencies 305
W
What is a Service-Oriented Architecture? 17
What to do if the dependency map displays
incomplete data 71
workstation.soa.dependencymap.fetchmetrics 361
workstation.traceview.crossprocess.duration.full
362
workstation.traceview.crossprocess.duration.net
363

APM - 9.5 - APM For SOA Implementation Guide

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

APM - 9.5 - APM For SOA Implementation Guide

Uploaded by

Copyright:

Available Formats

for SOA Implementation Guide

You might also like