APM_9.5 ChangeDetector User Guide

ChangeDetector User 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 [email protected].

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: CA Application Performance Management ChangeDetector Overview 11

About this Guide ........................................................................................................................................................ 11

Directory Naming Conventions Used in this Guide ............................................................................................. 12

About CA APM ChangeDetector ................................................................................................................................. 13

CA APM ChangeDetector and Your CA Introscope Environment ............................................................................... 14

CA APM ChangeDetector Usage Scenarios ................................................................................................................ 14

Triaging change as the cause of problems: Monday morning blues ................................................................... 14

Detecting a change before it becomes a problem: caught in the act ................................................................. 15

Chapter 2: Installing and Configuring CA APM ChangeDetector 17

Installing and Enabling CA APM ChangeDetector ...................................................................................................... 17

Before You Configure CA APM ChangeDetector ........................................................................................................ 18

Using Multiple CA APM ChangeDetector Configuration Files ............................................................................. 19

Understanding Datasources ................................................................................................................................ 19

Using the ChangeDetector Configuration Wizard ...................................................................................................... 20

Run the Configuration Wizard ............................................................................................................................. 20

Add Datasources with the Configuration Wizard ................................................................................................ 21

Modify Datasources with the Configuration Wizard ........................................................................................... 22

Remove Datasources with the Configuration Wizard ......................................................................................... 22

Configuring Datasources using the Wizard ......................................................................................................... 23

Modifying the CA APM ChangeDetector Configuration File ...................................................................................... 30

About the ChangeDetector-config.xml file ......................................................................................................... 30

Using System or Agent Properties in the Configuration File ............................................................................... 31

Manually Configure the Database Monitor Properties ....................................................................................... 31

Manually Configure the File System Monitor Properties .................................................................................... 34

The property Element ......................................................................................................................................... 36

Manually Configure the Java Class Monitor Properties ...................................................................................... 40

Manually Configure the Java System Property Monitor ..................................................................................... 42

Manually Configure the Assembly Monitor Properties ...................................................................................... 42

Manually Configure the .NET Environment Variable Monitor Properties .......................................................... 45

Upgrading an Existing ChangeDetector-config.xml file ....................................................................................... 46

Modifying the Agent Configuration File ..................................................................................................................... 47

Configuring CA APM ChangeDetector in a Load Balanced Environment ............................................................ 48

Configuring CA APM ChangeDetector for the Agent Failover Mechanism ......................................................... 49

Running Multiple Applications with Individual Config Files in .NET .................................................................... 50

8 ChangeDetector User Guide

Disabling CA APM ChangeDetector ..................................................................................................................... 50

ChangeDetector Agent ID Naming Options ........................................................................................................ 50

Optional Configuration properties ............................................................................................................................. 52

Optional Agent Properties .................................................................................................................................. 53

Optional Workstation Properties ........................................................................................................................ 53

Configuring an EPAgent Plugin to Send CA APM ChangeDetector Data ............................................................. 54

Optional Enterprise Manager Properties ............................................................................................................ 55

Chapter 3: Viewing CA APM ChangeDetector Data 57

Viewing Change Data in CA Introscope ...................................................................................................................... 57

Viewing Change Data in the CA APM ChangeDetector Dashboard..................................................................... 58

Opening CA APM ChangeDetector ...................................................................................................................... 59

Viewing Change Data in the Tree View ............................................................................................................... 59

Viewing Change Data in the Table View ............................................................................................................. 65

Viewing Change Data in Charts and Reports .............................................................................................................. 68

Integrated CA APM ChangeDetector Charts ....................................................................................................... 68

Running the Built-in CA APM ChangeDetector Report ....................................................................................... 70

Adding a CA APM ChangeDetector Element to an CA Introscope Report .......................................................... 71

Chapter 4: CA APM ChangeDetector Metrics 75

CA APM ChangeDetector Supportability Metrics for the Enterprise Manager .......................................................... 75

Avg Time For Insertion (ms) ................................................................................................................................ 75

Datastore Used (%) ............................................................................................................................................. 75

Number of Insertions .......................................................................................................................................... 76

Number of known agents .................................................................................................................................... 76

Number of Changes (database) .......................................................................................................................... 76

Size of Datastore ................................................................................................................................................. 76

Number of Changes (CA Introscope) ................................................................................................................... 76

CA APM ChangeDetector Supportability Metrics for CA Introscope .......................................................................... 76

Changes Sent Per Interval ................................................................................................................................... 77

Total Addition Changes ....................................................................................................................................... 77

Total Completed Scans ........................................................................................................................................ 77

Total Changes ...................................................................................................................................................... 77

Total Deletion Changes ....................................................................................................................................... 77

Total Modification Changes ................................................................................................................................ 77

Appendix A: Sample Configuration Files 79

Sample Java ChangeDetector-config.xml file ............................................................................................................. 80

Sample .NET ChangeDetectorDotnet-config.xml file ................................................................................................. 86

Contents 9

Appendix B: Frequently Asked Questions 93


Chapter 1: CA Application Performance Management ChangeDetector Overview

CA Application Performance Management ChangeDetector enables CA Introscope to monitor and report changes in application files and configuration. CA APM ChangeDetector can detect production Web application changes to help you identify change as the root cause of Web application performance problems. After identifying change as the cause of a problem, you can use CA APM ChangeDetector to diagnose the problemCA APM ChangeDetector gives you visibility into changes in code, application server configuration, and the configuration of connected systems that might be responsible for performance issues.

Because change occurs in many different parts of an application, CA APM ChangeDetector is also supported on the Environment Performance Agent (EPAgent). EPAgent enables you to gather application performance information from almost any source and thus monitor change data that is particular to your environment. See the CA APM Environment Performance Agent Implementation Guide for detailed information on the EPAgent.

This chapter describes CA APM ChangeDetector and how it fits into your CA Introscope environment, and provides typical usage scenarios.

This section contains the following topics:

About this Guide (see page 11) About CA APM ChangeDetector (see page 13) CA APM ChangeDetector and Your CA Introscope Environment (see page 14) CA APM ChangeDetector Usage Scenarios (see page 14)

About this Guide

This guide contains information about installing, configuring, deploying, and using the CA APM ChangeDetector graphical user interface components.

It is assumed that the information is suitable for all platforms unless noted. For example, if a section is intended only for the .NET platform, it will contain a note such as in the example below:

Note: This section is applicable only to the .NET platform.

About this Guide


Directory Naming Conventions Used in this Guide

This guide uses the following naming conventions for installation directories.

Convention:

Refers to:

The directory where the Enterprise Manager is installed. This is typically under the Program Files directory.

Convention:

Refers to:

The directory where the Workstation is installed. This is typically under the Program Files directory.

Convention:

Refers to:

The directory where the CA Introscope Agent is installed. This is typically the CA APM Agent directory.

Convention:

Refers to:

The installation directory of a third party product or type of application. For example, is the installation directory of the application server if you are using WebLogic.

About CA APM ChangeDetector


Convention:

FileName.FileType

Refers to:

A file name that includes specific identifying information.

For example, if you are extracting files from a tar package for CA APM ChangeDetector 8.1 on a Unix operating system, you would download this file:

ChangeDetector8.1.0.0.unix.tar

But, would view it as this in the guide:

ChangeDetector.unix.tar

About CA APM ChangeDetector

CA APM ChangeDetector is a set of extensions to CA Introscope that you can use to monitor change in your application environment. CA APM ChangeDetector is directly integrated with CA Introscope to provide real-time change detection, with low overhead. When a production problem occurs, CA APM ChangeDetector can help CA Introscope users to correlate application changes with changes in the applications performance, and thus isolate change as the cause of the problem.

CA APM ChangeDetector can report on differences in application code, configuration, and environment in an agent, over multiple time periods, so that you can see how an instance of your application differs between time periodsfor example, between today and yesterday, or today and last week.

With CA APM ChangeDetector installed, you can view:

Graphical views of change events including files (text and binary), archives, system properties, application code, database tables, and certain database query result sets.

Change-event details including the time a change was detected, the nature of the change, and the difference between versions for text files.

The CA APM ChangeDetector dashboard, to see a high-level view of change data.

Hierarchical and historical views of changes (today, yesterday, last week).

Change Reports to summarize changes in an application.

CA APM ChangeDetector and Your CA Introscope Environment


CA APM ChangeDetector and Your CA Introscope Environment

This illustration shows how the CA APM ChangeDetector components interact with CA Introscope:

CA APM ChangeDetector Usage Scenarios

These scenarios illustrate using CA APM ChangeDetector to detect changes, correlate them to a problem, determine what changed, and decide how to correct the problem.

Triaging change as the cause of problems: Monday morning blues

Monday morning at 9:00, a banks online banking application starts experiencing performance problems. CA Introscope alerts the IT team that login and other critical transaction response times are degrading and breaching SLA levels. Irate users begin calling the customer service desk complaining that they cant access their bank accounts. The call-center manager escalates the issue to the application support group, which immediately initiates an investigation.

"What changed? The application was working fine through the last week."

The application support team looks over their CA Introscope dashboards to review the decline in performance. They look at the performance graphswith CA APM ChangeDetector installed, they see the change data integrated directly into the CA APM ChangeDetector chart. The team reviews the change annotations and detailed information provided on the chart and notices that a cluster of changes over the previous weekend preceded the current performance problems. Zooming in closer they realize that the changes occurred over Saturday night during the applications maintenance window. The team clicks through the CA Introscope Investigators tree view and inspects performance graphs of the various application instances; its clear from the similar graphs that each instance experienced a similar set of changes around the same time.

CA APM ChangeDetector Usage Scenarios


With change as a suspected cause of the problem, the application support team looks deeper. As they click on each component of their application within the CA Introscope Investigator, the CA APM ChangeDetector view shows the changes that occurred for each component. Locking in on the application files, they notice that 37 files have changed, including 3 configuration files. CA APM ChangeDetector helps the team verify that each of the changes is a modification, and each was detected during the maintenance window. Selecting one of the application server configuration files, they compare the current version on the server and the earlier version of the file from before the change.

The cause is now clear. A database connection pool parameter that was set to 100 appears to have been changed to 10. With this information, a call by the application support manager to the development manager confirms a typing error, and that the slowdown was due to an unexpected change in the database connections.

Detecting a change before it becomes a problem: caught in the act

A CA Introscope alert goes off. The application support team is informed that a change has occurred in their Java application. Because no changes were expected (this is not within the scheduled maintenance window) the application support manager starts investigating their performance graphs. The application is behaving normally for now, but the graph shows that a small number of changes had occurred a couple of minutes ago. Placing the cursor on the changes, displays the change details. They appear to be modifications to system variables.

The application support manager begins by browsing the CA Introscope Investigator, looking for changes to the various application components. CA APM ChangeDetector provides a tree view of the changes in the application. While inspecting the changes, the application support manager notices that no changes have occurred in the application and configuration files, or in the APM database configuration. However, confirming the earlier CA Introscope alert, the support manager notices that four system properties of the JVM and application server have changed.

By clicking on each of the detected variable changes, the application support manager views the specific variable name, when the change was detected, and the changed value. It appears that the Java heap size variables were lowered, which could cause trouble if the application experienced increased load. A check with the UNIX system administrator confirms that housekeeping was done and the potential effect of the changes was not realized. With the changes returned to their original values, a potential performance problem is averted.


Chapter 2: Installing and Configuring CA APM ChangeDetector

This chapter describes how to install and configure CA APM ChangeDetector datasources with the Configuration Wizard or manually by editing the XML configuration file.

This section contains the following topics:

Installing and Enabling CA APM ChangeDetector (see page 17) Before You Configure CA APM ChangeDetector (see page 18) Using the ChangeDetector Configuration Wizard (see page 20) Modifying the CA APM ChangeDetector Configuration File (see page 30) Modifying the Agent Configuration File (see page 47) Optional Configuration properties (see page 52)

Installing and Enabling CA APM ChangeDetector

CA APM ChangeDetector is installed and enabled during agent installation. CA APM ChangeDetector can be installed using the Standalone agent installer or using the silent mode installation option. After CA APM ChangeDetector is installed, you have to configure it.

Follow these steps:

1. Install the agent.

For more information about installing the agent, see the CA APM .Net Agent Implementation Guide or the CA APM Java Implementation Guide. By default CA APM ChangeDetector is enabled.

Before You Configure CA APM ChangeDetector


a. You can enable CA APM ChangeDetector by opening the IntroscopeEnterpriseManager.properties file in the /config directory and setting the following property to false and restarting the Enterprise Manager:

introscope.changeDetector.disable=false

Important! If you are running CA APM ChangeDetector against a WebSphere 6.1 or 7.0 application and Oracle DB on AIX environments may receive an unexpected exception similar to the following:

java.security.AccessControlException: Access denied (java.net.SocketPermission hostname:port connect,resolve) at java.security.AccessController.checkPermission(AccessController.java:104)

Modify /properties/server.policy to allow Java Security permissions or clear the Enable application security check box in the WebSphere Admin console to prevent this exception.

2. Configure CA APM ChangeDetector.

Before you configure CA APM ChangeDetector familiarize yourself with the various configuration options, see Before You Configure CA APM ChangeDetector (see page 18).

Note: CA APM ChangeDetector installs a native library that reports file owner data along with the data that has been changed for Windows (cdnativefile.dll) and Linux (libcdnativefile.so) operating systems. For a list of supported platform versions, see the CA APM Compatibility Guide.


Before you configure CA APM ChangeDetector, familiarize yourself with the various configuration options and choose the method that best suits your environment:

Using the CA APM ChangeDetector Configuration Wizard (see page 20)this allows you to configure CA APM ChangeDetector by entering information on a series of pages that guide you when configuring settings.

Modifying the CA APM ChangeDetector Configuration File (see page 30)this method can be used for all platforms. It allows you to configure CA APM ChangeDetector by manually editing the XML file. CA APM ChangeDetector is packaged with a sample XML file that can assist if you choose this method.

Additionally, familiarize yourself with these concepts:

Using multiple CA APM ChangeDetector configuration files (see page 19)

Understanding Datasources (see page 19)



More information:

Sample Configuration Files (see page 79)

Using Multiple CA APM ChangeDetector Configuration Files

You can specify a directory that contains multiple CA APM ChangeDetector configuration files instead of specifying a single file. When you specify a directory CA APM ChangeDetector reads all the valid configuration files in this directory at startup.

To specify a CA APM ChangeDetector configuration directory:

Edit IntroscopeAgent.profile to set the following property:

introscope.changeDetector.profileDir=

The default value for this property is:

/changeDetector_profiles.

If you also specify a single file for the following property:

introscope.changeDetector.profile

CA APM ChangeDetector will read that file and all the files in the configuration directory specified.

Understanding Datasources

A datasource is a group of resources whose type is defined by the datasource typefor example, files, database table column values, or runtime class instances. A resource is identified by its name, for example C:\Introscope\Introscope Enterprise Manager.exe, the buffer_pool column name in a database, or java.lang.System. A datasource can have many resources; resources can have many values, but only one value at a time.

Note: Resource names within a datasource must be unique.

Datasources are defined using one of two methods:

Using the CA APM ChangeDetector Configuration Wizard (see page 20)

Modifying the CA APM ChangeDetector Configuration File (see page 30)

The datasources you specify in the configuration file appear in the Changes tab in the Investigator for CA APM ChangeDetector-enabled agents. See Viewing CA APM ChangeDetector data (see page 57) for information about viewing change data.

Using the ChangeDetector Configuration Wizard


Each datasource definition must be enclosed within the datasource-type tags and contain the attributes name and class. The name can be anything, and is referenced later in the configuration file. The class attribute defines which class is used to parse any datasource-instance definitions for this type of datasource. The class must implement the following interface:

com.wily.cd.agent.config.IDataSourceConfig

The datasource-type elements tell the agent what types of datasources are available to use. To take full advantage of the datasource-type elements, you also define datasource-instance elements. Each of the elements corresponds to a physical datasource that the agent monitors.

Note: A datasource instance cannot contain multiple resources with the same namefor example, a duplicate file with the same full path and name in the same datasource instance is invalid, as is a javaenv property with the same name. All data in CA APM ChangeDetector is organized by datasource instance.


Use the Configuration Wizard to configure CA APM ChangeDetector. However, you can also update ChangeDetector-config.xml to do sosee Sample Configuration Files (see page 79).

The following can be done with the Configuration Wizard:

Run the Configuration Wizard (see page 20)

Add datasources with the Configuration Wizard (see page 21)

Modify datasources with the Configuration Wizard (see page 22)

Remove datasources with the Configuration Wizard (see page 22)

Note: You can use multiple CA APM ChangeDetector configuration files. See Using multiple CA APM ChangeDetector configuration files (see page 19) for details.

Run the Configuration Wizard

You can use the Configuration Wizard to set datasource properties using a graphical user interface, instead of manually editing XML.



To run the Configuration Wizard:

1. After CA APM ChangeDetector has been installed, go to /tools and run configwizard.bat from command prompt to start the Configuration Wizard.

Note: If JAVA_HOME is not set, run configwizard.bat from a command prompt with the path to the JRE as an argument. For example: configwizard.bat s:\sw\sun\jre.

2. From here you can do the following:

Add datasources with the Configuration Wizard (see page 21)

Modify datasources with the Configuration Wizard (see page 22)

Remove datasources with the Configuration Wizard (see page 22)

Add Datasources with the Configuration Wizard

You can use the Configuration Wizard to add the following datasources:

Configure Assembly Monitor with the Wizard (see page 23)

Note: This is applicable only for the .NET platform.

Configure Java Class Monitor with the Wizard (see page 24)

Note: This is applicable only for the Java platform.

Configure Database Monitor with the Wizard (see page 25)

Configure File System Monitor with the Wizard (see page 26)

Configure .NET Environment Variable Monitor with the Wizard (see page 28)


Configure Java System Property Monitor with the Wizard (see page 29)


To add a datasource:

1. Run the Configuration Wizard (see page 20).

2. Select the platform of choice and click Next.

3. Select Create new CA APM ChangeDetector configuration file and click Next.

From this page of the Wizard you can create a new configuration file or modify an existing one.

4. Select an option and click Next.

As you create datasources, they appear in the Current datasources section of the Wizard window. Thereafter, you can edit and delete them at any time.

After you add datasources, they appear in the current datasources. You can further edit different fields and elements or remove the datasource if desired.



5. Choose the type of datasource you want to add, and click Next.

6. Enter a name for the datasource you are adding, and click Next. These options vary depending on the platform specified in a previous step.

Continue configuring all applicable datasources (see Configuring Datasources using the Wizard (see page 23)) and if necessary, define optional CA APM ChangeDetector workstation and Enterprise Manager properties (see Optional Configuration properties (see page 52)).

7. When you have completed adding all datasources, click Save As to save the XML file.

Modify Datasources with the Configuration Wizard

After you have added datasources, you can modify them.

Note: If you are upgrading from a previous version, you can save a backup of the original file or overwrite the existing file while upgrading.

To modify a datasource:


2. Select a platform and click Next.

3. Select Modify existing ChangeDetector, and click Next.

4. Choose the configuration file you want to modify.

5. Modify a datasource by selecting it in the left pane of the wizard.

Each datasource has different fields and elements you can modify. You can do so by changing the fields or selecting the element then modifying it.

6. After making changes, click Save, then Exit.

Remove Datasources with the Configuration Wizard

After you have added datasources, you can remove them.

To remove a datasource:


2. Select the platform of choice and click Next.

3. Select Remove selected datasource and click Next.

4. Choose the configuration file from which you want to remove the datasource.

5. Remove a datasource by selecting it in the left pane of the wizard.

6. After making all your changes, click Save, then Exit.



Configuring Datasources using the Wizard

The following datasources can be configured using the Configuration Wizard. After adding datasources to your new configuration file, click Save As to name and save the XML file:

Configure Assembly Monitor with the Wizard (see page 23)

Note: Assembly Monitor is applicable only for the .NET platform.

Configure Java Class Monitor with the Wizard (see page 24)

Note: Java Class Monitor is applicable only for the Java platform.

Configure Database Monitor with the Wizard (see page 25)

Configure .NET Environment Variable Monitor with the Wizard (see page 28)

Note: .NET Environment Variable Monitor is applicable only for the .NET platform.

Configure Java System Property Monitor with the Wizard (see page 29)

Note: Java System property is applicable only for the Java platform.

Configure Assembly Monitor with the Wizard

For the .NET platform, you can add or modify an Assembly Monitor datasource.

To configure the assembly monitor datasource with the Wizard:

1. Enter a datasource name using alphanumeric characters and click Next.

The next page of the Wizard appears.

2. Enter the following property configuration information and click Next:

Classes per iterationThe number of classes loaded per iteration defined. Lower values lessen CPU usage, but increase the time required to scan.

Delay between iterationsThe time in seconds, minutes, or hours lapsed in between iterations when classes are not monitored. Higher values lessen CPU usage, but increase the time required to scan.

Initial Wait TimeThe initial time in seconds, minutes, or hours before classes are monitored.




3. Perform the following steps to add an exclude element for both assemblies and classes:

a. Select Add New Exclude Element.

b. Click Next.

c. Type the exclude pattern in the field provided.

d. To add include patterns, click Add and type the pattern in the field provided. Repeat this step as needed.

e. Click Next.

f. Add more exclude patterns by repeating the above steps, or click Done.

Note: The first exclude element excludes assemblies matching regex from being monitored and the second exclude element, excludes the classes matching regex from being monitored. Use exclude patterns to narrow your scan, and add include patterns for any exceptions to the exclude pattern. For example, your exclude pattern could be .* and your include pattern could be java\.* Use regular expressions for your exclude or include patterns. Here are some examples: foo .*bar. .* com\.wily\.(.*)

More information:

Add Datasources with the Configuration Wizard (see page 21) Modify Datasources with the Configuration Wizard (see page 22)

Configure Java Class Monitor with the Wizard

For the Java platform, you can add or modify a Java Class Monitor datasource.

To configure the java class monitor datasource with the Wizard:

1. Using alphanumeric characters, enter a datasource name and click Next.


2. Enter the following property configuration information and click Next:

Classes per iteration - lower values lessen CPU usage, but increase the time required to scan.

Delay between iterations - higher values lessen CPU usage, but increase the time required to scan.




3. Select Add New Exclude Element and click Next.

4. Enter the exclude pattern in the field provided.

5. To add include patterns, click Add and enter the pattern in the field provided. Repeat this step as needed and click Next.

6. Add more exclude patterns by repeating the above steps, or click Done.

Note: Use exclude patterns to narrow your scan, and add include patterns for any exceptions to the exclude pattern. For example, your exclude pattern could be .* and your include pattern could be java\.* Use regular expressions for your exclude or include patterns. Here are some examples: foo .*bar. .* com\.wily\.(.*)

More information:


Configure Database Monitor with the Wizard

You can add or modify a Database Monitor datasource using the Wizard.

To configure the database monitor datasource with the Wizard:



2. Enter the following database information for the Java platform and click Next:

JDBC driver - the driver for this database. for example: oracle.jdbc.driver.OracleDriver

JDBC driver classpath - the path to your database driver (you can also browse for this).

JDBC URL - enter the JDBC URL to your database.

Username - enter the username for the person using the database.

Password - enter the password for your database. These will automatically be obfuscated in the configuration file.



Confirm Password - re-enter the password for verification purposes.

Schedule type - Repetitive or Post-startup. Choose post-startup for databases that have infrequent changes, or are only checked by applications at startup.

Repetition interval - If your schedule is repetitive, choose the interval. Higher values lessen CPU usage, but increase the time required to scan.

Delay between iterations - higher values lessen CPU usage, but increase the time required to scan.


3. Enter the following database information for the .NET platform and click Next:

URL - enter the URL to your database.

Username - enter the username for the person using the database.

Password - enter the password for your database. These will automatically be obfuscated in the configuration file.

Confirm Password - re-enter the password for verification purposes.

Note: The user name and password may be specified within the URL property on the .NET platform or they may have no value. The Wizard does not check the URL for these values.

Schedule type - Repetitive or Post-startup. Choose post-startup for databases that have infrequent changes, or are only checked by applications at startup.

Repetition interval - If your schedule is repetitive, choose the interval. Higher values lessen CPU usage, but increase the time required to scan.


4. To add a SQL statement, select Add new SQL statement and click Next.

You can add more SQL statements by repeating these steps, or click Done. For example:

SELECT name, value FROM v$parameter

Note: The Wizard does not validate the SQL statements. Be sure to use a valid SQL statement for you database.

More information:


Configure File System Monitor with the Wizard

You can add or modify a File System Monitor datasource using the Wizard.



To configure the file system monitor datasource with the Wizard:



2. Select Add new scan-directory element and click Next.

3. Enter the directory name and the required fields: Directory Name, Recursive, Fileset, and Enabled:

Directory Name - Enter the path to the directory you want CA APM ChangeDetector to scan. For example: C:\\WebLogic\\myApplicationHome

Recursive - A True value lets CA APM ChangeDetector look in any subfolders under the specified directory.

Fileset - Select the fileset associated with this scan-directory.

Enabled - You may want to disable a scan directory for testing or other purposes. However, if you disable this after it has been enabled, the files included by this scan directory element will be reported by CA APM ChangeDetector as deleted.

4. To add an exclude pattern, click Add New and enter a pattern. Repeat this step as needed.

5. Click Create or Modify Filesets to add or edit an existing fileset.

Select Add new fileset, and click Next.

Enter the fileset name, and click Next.

6. Click Next to add more scan-directory elements by repeating these steps and click Done.

7. Enter include/exclude elements to help narrow down your scan, and add include patterns for any exceptions to the exclude pattern:

Select Add new exclude element, and click Next.

Type the exclude pattern in the field provided.

To enter an include pattern, click Add, and type the include pattern in the field provided. Repeat this step as needed.

8. Enter the following information and click Next:

Files per iteration - lower values lessen CPU usage, but increase the time required to scan.

Delay between file iterations - higher values lessen CPU usage but increase the time required to scan.

Max file size to upload - maximum ASCII file size uploaded to the server. Uploaded ASCII files can be seen in the Diff View in CA APM ChangeDetector.

Note: The following archive properties are applicable only on the Java platform.



Use Digest - Choose Always, Never, or Needed. A digest is a form of message digest, such as MD5. It lets CA APM ChangeDetector ignore touch changes to files by performing a hash comparison. This can affect performance if you choose Always. If you choose Needed, a digest is used only if the timestamp and file size have changed.

Explode archives - Choose True if you want to scan individual files in an archive, such as .zip or .jar.

Archives per iteration - Specify this value if you choose to explode archives. Lower values increase the time required to scan. Since archive files are scanned as a whole, you should limit this number if your archives have a large number of files.

Delay between archive iterations - Higher values lessen CPU usage, but increase time required to scan.

9. Add fileset(s), select Done with this section, and click Next.

Note: Monitored file systems must have read permissions, and if they are on a network, the network must be functioning in order for CA APM ChangeDetector to detect the files.

More information:


Configure .NET Environment Variable Monitor with the Wizard

For the .NET platform, you can add or modify an Environment Variable datasource.

To configure the file system monitor datasource with the Wizard:


2. Add an exclude element, by selecting Add new exclude element, and clicking Next.

The field provided lets you enter the exclude pattern. Use exclude patterns to narrow down your scan, and add include patterns for any exceptions to the exclude pattern. For example, your exclude pattern could be .* and your include pattern could be java\.*

Use regular expressions for your exclude or include patterns. Here are some examples:

foo

.*bar.

(.*)

java\.*



3. Add an include pattern, by selecting Add New, and clicking Next.

The field provided lets you enter the include pattern.

4. Continue adding as many include/exclude patterns as needed by repeating the steps necessary and click Done.

More information:


Configure Java System Property Monitor with the Wizard

For the Java platform, you can add or modify a Java System Property Monitor datasource.

To configure the Java system monitor datasource with the Wizard:


2. Add an exclude element, by selecting Add new exclude element, and clicking Next.

The field provided lets you enter the exclude pattern. Use exclude patterns to narrow down your scan, and add include patterns for any exceptions to the exclude pattern. For example, your exclude pattern could be .* and your include pattern could be java\.*

Use regular expressions for your exclude or include patterns. Here are some examples:

foo

.*bar.

(.*)

java\.*

3. Add an include pattern, by selecting Add New, and clicking Next.

The field provided lets you enter the include pattern.

More information:


Modifying the CA APM ChangeDetector Configuration File



You manually modify the configuration settings by editing the XML configuration file. This method can be used for all platforms. CA APM ChangeDetector is packaged with a sample XML file that can assist if you choose this method.

More information:


About the ChangeDetector-config.xml file

You can create a custom configuration file based on ChangeDetector-config.xml, which specifies the types of changes you want CA APM ChangeDetector to monitor. CA APM ChangeDetector groups changes by datasource. Using this file you can change the following configurations:

Manually Configure the Database Monitor Properties (see page 31)The database datasource defines how to collect change data from a compliant database.

Manually Configure the File System Monitor Properties (see page 34)The file datasource defines which files to monitor for changes.

Manually Configure the Java Class Monitor Properties (see page 40)The classmonitor datasource defines which Java classes to monitor.


Manually Configure the Java System Property Monitor (see page 42)The javaenv datasource defines which Java process system properties to monitor.


Manually Configure the Assembly Monitor Properties (see page 42)The classmonitor datasource that represents the Assembly Monitor for the .NET environment tells CA APM ChangeDetector which assemblies to monitor.




Manually Configure the .NET Environment Variable Monitor Properties (see page 45)The javaenv datasource that represents the System Monitor Properties for the .NET environment tells CA APM ChangeDetector which system properties to monitor.


Important! Searching for a file using the full file path may cause a spike in CPU utilitzation. To avoid this, search by using the full path file name only. To search using the full path file name only, edit the ChangeDetector-config.xml file by adding fullpath="true" property as follows:

Using System or Agent Properties in the Configuration File

You can use system properties or agent profile properties as values in any XML attribute in the configuration files. This lets you use properties that are resolved at runtime in the CA APM ChangeDetector configuration file. If both system and agent profile properties are provided for a value, the system properties take precedence.

Here is an example:

In this example, ${APPLICATION_HOME} is replaced with its current value at runtime.

Note: Values for these properties must map to valid system or agent profile properties at runtime.

More information:


Manually Configure the Database Monitor Properties

The database datasource instance tells CA APM ChangeDetector how to collect change data from a compliant database. Be sure you have the supported JDBC or OLEDB driver for your database.

Note: The configuration properties vary slightly depending on the platform in use. Attributes applicable only to certain platforms are noted as such in this section.



Note: This element is defined in the example of the custom configuration file shown in the Sample Java ChangeDetector-config.xml file (see page 80). This example provides sample data that may or may not reflect the content of your data. If you are using a different version of CA APM ChangeDetector, substitute with the appropriate content where applicable:

SQL Server

SELECT name, value FROM v$parameter

You can supply multiple classpaths to your database driver by using either of these classpath separators: ; or :

You can supply the username and password for your database if there are any. However, you cannot supply a value for only one of these.

Note: For security, the values you enter for username and password will be replaced automatically with obfuscated values. To change these values, first set the property isClearText="true" then make your changes. The next time the agent runs, the isClearText property will be automatically reset to false.

When using the Database Monitor, you must set these attributes in the datasource-instance element, in addition to the name and type attributes that all datasource-instance elements must define:

driverThe class name of the JDBC-compliant driver to be used. This example connects to an Oracle database, so the driver supplied in this custom configuration file is:

oracle.jdbc.driver.OracleDriver

Note: This attribute is applicable only to the Java platform.



driverClasspathThe path to the archive containing the driver that was referenced in the driver attribute. You can point to multiple drivers by using the classpath separator for your platform.

Note: This attribute is applicable only to the Java platform.

urlThe JDBC URL to be used to connect to the database.

usernameThe username to be used to connect to the database. This value is obfuscated even if the cleartext property is set to true when the agent is restarted.

passwordThe password to be used to connect to the database. This value is obfuscated even if the cleartext property is set to true when the agent is restarted.

isClearTextDefines whether or not the username and password are obfuscated. If the value is true, the username and password will be obfuscated and the config file will be overwritten with the obfuscated values.

This property is set to false by default for security reasons. If you set the property true, then restart the agent, the property will be set back to false.

You can define two top-level elements within a datasource-instance element of type database: sql and schedule.

The sql element is the SQL statement used collect information from the table that you plan to monitor. There can be any number of SQL elements within this type of datasource-instance element.

Note: The SQL statement must only result in two columns, and the values in the first column must be unique (Primary Key), regardless of how many SQL elements are defined. NULL values are not allowed in the first column of the resultset. A NULL value in the second column is treated as if the row were not there (that is, the absence of this row from the resultset).

The schedule element defines how often the Database Monitor scans for changes. The type attribute must be defined for this element. The valid values for this attribute are:

repetitiveif the value for the type attribute is repetitive, the interval and unit attributes must be defined. The interval attribute must be an integer value. The unit attribute must be one of these values: minute, hour, sec. These two attributes tell CA APM ChangeDetector how often to scan the database for changes. In the example, CA APM ChangeDetector scans every minute. If you want to scan once every 10 seconds, supply 10 for the value for interval and sec for the unit value.

post-startupno other attributes need to be defined if the value for the type attribute is post-startup. Using this value for the type attribute tells CA APM ChangeDetector to scan the supplied SQL statements once, after the agent starts.



Manually Configure the File System Monitor Properties

The CA APM ChangeDetector file monitoring system gives you control over monitoring for file changes in organizations that have different needs and different tolerances for I/O overhead. This enables you to balance processing and I/O costs and time, from the time a change takes place to the time it is detected.

Note: File monitoring properties are case-sensitive. For example, if a directory you want to monitor is named i18n and the scan-directory name property is set to I18N, CA APM ChangeDetector will be unable to locate the directory.




Defining Elements in a File Datasource Instance Type

You can define three top-level elements within a datasource-instance of type file:

property (see page 36)

fileset (see page 39)

scan-directory (see page 40)

Datasource-instance type file is defined to be the File System Monitor in the beginning of the configuration file.

The file-change monitoring system sequentially scans all files specified by the file data source instance configuration. CPU is granted to the collection for a unit of work, after which it is released back to other tasks.

The property Element

Each property element must have a name attribute and a value attribute. Some of the properties defined here might include the units attribute as well.

Note: The .NET platform does not support archiving, thus all archive-related properties can be defined only for Java.



These properties are allowed for this type of datasource-instance:

explodeArchiveFiles

This property is applicable only if you are using a Java agent. It is not compatible for environments running a .NET agent.

Allows either true or false for its value attribute.

If the value is set to true, CA APM ChangeDetector reports the contents of the archive files. If something changes in an archive file that CA APM ChangeDetector is monitoring, at least two change events are sentone for the modification of the archive file, and another for the modification of the content file within the archive file. If the modified content file is also an archive file, CA APM ChangeDetector opens that archive as well, and sends a change event for the content file of the nested archive, and so on.

Only ZIP and GZIP file formats are supported as archives (for example zip, gzip, jar, ear, war, rar, sar). CA APM ChangeDetector does not support tar files.

If the explodeArchiveFiles value is set to false, CA APM ChangeDetector does not look inside the archive. Any changes made to the archive appear as a modification/addition/deletion to the archive itself.

The default value is false.

delayBetweenIterations

Allows an integer for its value, with the units of sec, min, or hour.

This property defines the sleep time between each iteration for the file queue, and is associated with the filesPerIteration property.

The default value is 3 seconds.

filesPerIteration

Allows an integer for its value, to define the number of files for the unit of work as described for the delayBetweenIterations property.

This property specifies how many files are scanned before relinquishing the CPU. If there are 10 files per iteration, CA APM ChangeDetector scans 10 files for changes, and then sleeps as defined in the delayBetweenIterations property. After the sleep time it scans another 10 files and returns to sleep, and so on.

The default value is 5.



delayBetweenArchiveIterations


This property controls the sleep time on the Archive Queue. When CA APM ChangeDetector scans a file and recognizes it as an archive, CA APM ChangeDetector puts it in the Archive Queue so that its contents can be inspected.

This property is only relevant if the explodeArchiveFiles is set to true; otherwise, archive files are treated as regular files.


archiveFilesPerIteration

Allows the same attributes as the filesPerIteration property. As with the filesPerIteration property, archiveFilesPerIteration is an aspect of the Archive Queue, controlling the number of archives scanned for its contents per iteration. This property is only relevant if the explodeArchiveFiles is set to true; otherwise archive files are treated as regular files.


Note: The full content of the archive is uploaded at oncethe value of filesPerIteration does not apply here. If an archive is found within the archive being scanned, however, the nested archive is added to the Archive Queue.

maxFileSizeToUpload

Allows an integer for its value attribute and B, KB, or MB as the units. This property defines the maximum size of a file whose contents will be sent to the server. Currently only ASCII files that are below the file size defined by this property are sent.

The default value is 50KB.

useDigest

This property defines how a message digest (such as MD5) is to be used to detect changes. Using a digest lets CA APM ChangeDetector ignore touch changes to files by performing a hash comparison. Values for this property are:

never - digest is not used

always - always do a digest comparison

needed - use a digest only if the timestamp and file size have changed (default)



The fileset Element

Here are examples of fileset elements:

A fileset defines the pattern(s) of files that are included or excluded in a scan. The sub-elements allowed for the fileset element are:

exclude

include-fileset

The exclude element must have the attribute pattern defined. The exclude element may have 0 or more include elements as sub-nodes. The include element must have the attribute pattern defined. The purpose of an include element is to override the exclude element. In the example above, for the fileset NoCode we want to exclude all file names that end with .jar except those which have wily in the name.

The include-fileset element must have the attribute name defined. When using the include-fileset element, the fileset that is being included must be defined previously. In the example above, the fileset NoCode includes the fileset default. If we were to switch the order of the two filesets such that default was the second fileset defined, the configuration would be invalid. When a fileset uses the include-fileset element, all include and exclude patterns of the referenced fileset become a part of the master element. In the example above, the fileset "NoCode" contains the exclude pattern of *.jar, *.zip, *.err, *.log, *.lok, etc.

The order of the exclude and include-fileset elements within a fileset element does not matter. If a file does not match a defined exclude pattern, it is included in the scan. If a file matches a defined exclude pattern, then it is checked to see if it matches any include patterns that are defined within it. If it matches one, the file is included in the scan. If it does not match one, the file is excluded from the scan.



The scan-directory Element

A scan-directory element defines a directory to be scanned. The attributes for the scan-directory element are name, recursive, fileset, and enabled:

The name attribute defines the directory that is to be scanned. Required. For example, c:\\test or C:/test.

The recursive attribute takes a true/false value and defines whether or not the File System Monitor will recurse through any directories it finds. The default value is true.

The fileset attribute defines which fileset to use with this datasource instance. The fileset supplied must be defined earlier in the config file. This is a required attribute.

The enabled attribute takes a true/false value and enables or disables the scan-directory element.

The scan-directory element can have exclude child elements. The exclude element requires a name attribute. The name attribute must map to a directory.

Note: The value given for the name attribute cannot be a regular expression. It must be a literal string that maps to an actual directory. To exclude things based on a pattern, modify the fileset element that you are using.

The following is an example of this element defined in the Sample Java ChangeDetector-config.xml file (see page 80):

Manually Configure the Java Class Monitor Properties


The classmonitor datasource instance tells CA APM ChangeDetector which Java classes to monitor. Class names and their classloaders are used as resource names, and the byte array that corresponds to the class definition is used as the resource value.

Only one datasource instance of this type is allowed per CA APM ChangeDetector instance.

Note: Because Java operates by load-on-demand, CA APM ChangeDetector cannot determine whether a class is no longer part of the binary executing, or whether it has not yet been loaded; classmonitor datasources thus do not generate deletion changes.




The syntax for the exclude element is the same as in the Java system property monitor.

More information:

Manually Configure the Java System Property Monitor (see page 42)

Defining Elements in a Classmonitor Datasource Instance Type


You can define two property elements for the datasource instance of type classmonitor. Each of these property elements must have a name attribute and a value attribute:



This property defines the sleep time between each iteration for the classes queue, and is associated with the classesPerIteration property.


classesPerIteration

Allows an integer for its value, to define the number of classes for the unit of work as described for the delayBetweenIterations property.

This property specifies how many classes are scanned before relinquishing the CPU. If there are 10 classes per iteration, CA APM ChangeDetector scans 10 classes for changes, and then sleeps as defined in the delayBetweenIterations property. After the sleep time it scans another 10 classes and returns to sleep, and so on.




Manually Configure the Java System Property Monitor


The javaenv datasource instance tells CA APM ChangeDetector which Java system properties to monitor. CA APM ChangeDetector monitors Java system property changes between process restarts only, and not runtime changes provoked by the Java program runningcollections of this type only run once, at startup. Property names are used as resource names, and property values constitute these resources' values.


Only the exclude element can be defined as the top-level element within a javaenv datasource. The exclude element can have a sub-child.

Use the exclude element to exclude properties you do not want CA Introscope to display. The exclude element must have the pattern attribute defined. For example, if you did not want CA Introscope to display the foo property, use the exclude element shown in the example.

The exclude element can have any number of include sub-nodes defined. Like the exclude element, the include element must have the pattern attribute defined. The include sub-nodes are used to override the behavior of the exclude element. As the example shows, you can exclude all properties that match .*bar.* except for the ones that match hello or .*world.*.

Manually Configure the Assembly Monitor Properties


The classmonitor datasource represents the Assembly Monitor for the .NET environment. It tells CA APM ChangeDetector which assemblies to monitor.



Assembly Monitor loads methods one at a time. The metadata contained in the method is as follows:

Assembly name

Version

Classes

Methods

Method signatures

The changes in metadata can be monitored between versions of assemblies with the same name. For example, classes within cd_sample.dll 1.0.0 and cd_sample.dll version 1.0.1 will be treated as different versions of the same metadata. Changes to the data will be monitored and displayed in the Workstation Investigator. If, however, the name of the assembly changes then it will be treated as new resources and classes within it will be new resources that will be treated as additional events.

Note: This element is defined in the example of the custom configuration file shown in the Sample .NET ChangeDetectorDotnet-config.xml file (see page 86). This example provides sample data that may or may not reflect the content of your data. If you are using a different version of CA APM ChangeDetector, substitute with the appropriate content where applicable:



The syntax for these elements are as follows:

excludeassembly

exclude

include



You can define the property elements for the datasource instance of type classmonitor. Each of these property elements must have a name attribute and a value attribute:

initialWaitTime


This property defines the time that the agent waits after the last assembly has loaded, before it scans for any classes.



This property defines the sleep time between each iteration for the classes queue, and is associated with the classesPerIteration property.


classesPerIteration

Allows an integer for its value, to define the number of classes for the unit of work as described for the delayBetweenIterations property.

This property specifies how many classes are scanned before relinquishing the CPU. If there are 10 classes per iteration, CA APM ChangeDetector scans 10 classes for changes, and then sleeps as defined in the delayBetweenIterations property. After the sleep time it scans another 10 classes and returns to sleep, and so on.


Manually Configure the .NET Environment Variable Monitor Properties


The .NET Environment Variable Monitor datasource (javaenv) instance tells CA APM ChangeDetector which environment variables to monitor. CA APM ChangeDetector monitors environment variable changes between process restarts only, and not runtime changes provoked by the application running - collections of this type only run once, at startup. Variable names are used as resource names, and variable values constitute these resources' values.



Note: This element is defined in the example of the custom configuration file shown in the Sample .NET ChangeDetectorDotnet-config.xml file (see page 86). This example provides sample data that may or may not reflect the content of your data. If you are using a different version of CA APM ChangeDetector, substitute with the appropriate content where applicable:

Only the exclude element can be defined as the top-level element within a javaenv datasource. The exclude element can have a sub-child.

Use the exclude element to exclude properties you do not want CA Introscope to display. The exclude element must have the pattern attribute defined. For example, if you did not want CA Introscope to display the foo property, use the exclude element shown in the example.

The exclude element can have any number of include sub-nodes defined. Like the exclude element, the include element must have the pattern attribute defined. The include sub-nodes are used to override the behavior of the exclude element. As the example shows, you can exclude all properties that match .*bar.* except for the ones that match hello or .*world.*.

Upgrading an Existing ChangeDetector-config.xml file

When you upgrade your CA APM ChangeDetector configuration file is automatically upgraded to the new format.

Note: You must have write access to the configuration file and its current directory in order for your existing configuration file to be upgraded to the original name .bak.

CA APM ChangeDetector renames your existing configuration file and replaces it with an upgraded file. If the existing file cannot be renamed, or its directory cannot be written to, the new upgrade configuration file is saved in a temporary directory, and you are instructed to overwrite your existing file with the new one.

Modifying the Agent Configuration File



Modify IntroscopeAgent.profile to specify the CA APM ChangeDetector Agent Extension ID, the path to the CA APM ChangeDetector configuration file, and the failover mechanism. These modifications may not always be necessary and instead you may choose to use automatic ID assignment.

Setting ChangeDetector Agent ID and path to configuration file (optional):

1. Back up the IntroscopeAgent.profile in each ChangeDetector-extended agent instance to a separate directory, using an easy-to-remember new namefor example, IntroscopeAgentBackup.profile.

2. Edit IntroscopeAgent.profile to set this property:

introscope.changeDetector.agentID=

The agentID property must contain only alphanumeric characters, and can include the special characters underscore (_) and hyphen (-).

This ID corresponds to the Global ID of the CA APM ChangeDetector agent, and must be unique across all agents that are connecting to your Enterprise Manager or to your Enterprise Manager cluster.

3. Edit introscopeAgent.profile on each ChangeDetector-extended agent instance to include the path to the configuration file, including the file name:

introscope.changeDetector.profile=

If you used the sample configuration file without changing the name, the file name is ChangeDetector-config.xml. If you changed the name, specify that name.

When entering a path name, use the absolute path name and two back slashes. For example, if you are referencing a WebLogic application server, the path entered in the property value would look something like this: \\.

Note: Be sure to specify the path to the configuration file for each agent. If more than one agent runs from an IntroscopeAgent.profile, define the properties on the command line (for example, in the startup script of your application server). This enables CA Introscope to differentiate between CA APM ChangeDetector Agent Extension configurations. For information about how to create a new IntroscopeAgent profile, see the CA APM Java Agent Implementation Guide.

More information:

ChangeDetector Agent ID Naming Options (see page 50)



Configuring CA APM ChangeDetector in a Load Balanced Environment

You can configure the CA APM ChangeDetector Agent Extension to work in a load balanced agent environment. Do this by configuring the agent with the CA APM ChangeDetector Agent extension to connect to the Manager of Managers (MOM). The MOM then distributes the agent load to the appropriate Collector, depending on the configuration of the weight property (introscope.enterprisemanager.clustering.login.em1.weight).

To configure your CD for load balancing:

Configure the ChangeDetector Agent to connect to the MOM by setting the following properties:

introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=

introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT=5001

introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT=com.wi

ly.isengard.postofficehub.link.net.DefaultSocketFactory

Configure load balancing for the MOM by setting the following properties:

(Collector 1)

introscope.enterprisemanager.clustering.login.em1.host=sqw32vserv12

introscope.enterprisemanager.clustering.login.em1.port=5001

introscope.enterprisemanager.clustering.login.em1.publickey=internal/server/E

M.public

introscope.enterprisemanager.clustering.login.em1.weight=50

(Collector 2)

introscope.enterprisemanager.clustering.login.em2.host=sqw32vserv10

introscope.enterprisemanager.clustering.login.em2.port=5002

introscope.enterprisemanager.clustering.login.em2.publickey=internal/server/E

M.public

introscope.enterprisemanager.clustering.login.em2.weight=50

See the CA APM Java Agent Implementation Guide or CA APM .NET Agent Implementation Guide for more information about agent properties. See the CA APM Configuration and Administration Guide for more information about Enterprise Manager properties.



Configuring CA APM ChangeDetector for the Agent Failover Mechanism

If the CA APM ChangeDetector Agent Extension is installed to work with the Agent Failover mechanism, configure primary and fallback Enterprise Managers Collectors using the following procedure.

In a failover situation, the CA APM ChangeDetector Agent Extension starts sending change data to the Enterprise Manager designated as the fallback Enterprise Manager. However, since the changes database (changes.db) on the fallback Enterprise Manager will not be in sync with the primary Enterprise Manager, CA APM ChangeDetector will shut down. However, the CA Introscope agent will continue to run, and CA APM ChangeDetector retries the primary (default) Enterprise Manager until it is back up.

Note: Changes will not be reported if an CA Introscope agent connects directly to the MOM.

To configure CD for the Agent Failover mechanism:

Configure the following properties in the IntroscopeAgent.profile:

Designate a primary Enterprise Manager Collector (not the MOM) for the agent to be CA APM ChangeDetector-enabled. Set the following properties:

introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=

introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT=

introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT=com.wi

ly.isengard.postofficehub.link.net.DefaultSocketFactory

Designate the MOM Enterprise Manager as the fallback Enterprise Manager. Set the following properties:

introscope.agent.enterprisemanager.transport.tcp.host.FALLBACK =

introscope.agent.enterprisemanager.transport.tcp.port.FALLBACK =

introscope.agent.enterprisemanager.transport.tcp.socketfactory.FALLBACK=

com.wily.isengard.postofficehub.link.net.DefaultSocketFactory

Provide the connection order and retry interval by setting the following properties:

introscope.agent.enterprisemanager.connectionorder=DEFAULT, FALLBACK

introscope.agent.enterprisemanager.failbackRetryIntervalInSeconds=

See the CA APM Java Agent Implementation Guide or CA APM .NET Agent Implementation Guide for more information about agent properties.



Running Multiple Applications with Individual Config Files in .NET

Users who are running multiple applications under IIS in .NET and want each application to report its changes separately must identify the config folders for each application in a comma-separated list. Each application must have its own ChangeDetector config folder. This folder has the ChangeDetector config XML for each application. The name of the final folder in the path should match part of the application name (AppDomain Friendly name).

For example, if you are monitoring changes for BalloonShop and Petshop, each with its own config folder, the introscope.changeDetector.profileDir should be configured as in this example:

introscope.changeDetector.profileDir=S:\sw\CA_Wily\wily_dotnet\Introscope\wily\CD-config\balloonshop,S:\sw\CA_Wily\wily_dotnet\Introscope\wily\CD-config\petshop

Disabling CA APM ChangeDetector

To disable CA APM ChangeDetector:

Set the following property to false:

introscope.changeDetector.enable=false

ChangeDetector Agent ID Naming Options

The ChangeDetector Agent ID must be unique for each CA APM ChangeDetector Agent Extension you install. In a simple environment where you only have one CA Introscope agent, you can let CA APM ChangeDetector automatically assign an ID for you.

In a more complex environment, you may want to use another method to obtain unique ChangeDetector Agent IDs. Your options depend on:

Whether you have multiple CA APM ChangeDetector-enabled agents

Whether your agents each have a unique profile file (IntroscopeAgent.profile) or if all of them use the sam

Documents

APM_9.5 ChangeDetector User Guide