CA Application Performance Management

.NET Agent Implementation Guide

Release 9.1.0.1

Before You Install the .NET Agent

If you are new to Introscope or the .NET agent, review the deployment process. If you are familiar with the basic implementation process, do the following before installing the .NET agent: 1. Verify that you have a supported version of the .NET framework:

.NET 2.0 Framework, v2.0.50727 .NET 3.0 Framework, v3.0.4506 .NET 3.5 Framework, v3.5.21022 .NET 4.0 Framework, v4.0

Note: By default, the agent only monitors one Framework. If you are using the .NET Framework 4 and In-Process Side-by-Side Execution, you can configure agent properties to control what is monitored. 2. Verify that you have a supported version of the Windows operating system and IIS:

Windows XP Professional 2002 SP2 / IIS Version 5.1 Windows Server 2003, Enterprise Edition SP1 / IIS Version 6.0 Windows Server 2003, Enterprise Edition SP2 / IIS Version 6.0 Windows Server 2008, Enterprise Edition SP1 32-bit / IIS Version 7.0.6000.16386 Windows Server 2008, Enterprise Edition SP1 64-bit / IIS Version 7.0 Windows Server 2008, Enterprise Edition R2 / IIS Version 7.0 or 7.5

3.

Verify that you have a supported version of Microsoft SQL Server or Oracle database:

SQL Server 2005 Version 9.00.1399.06 SQL Server 2008 32-bit or 64-bit SQL Server 2008 R2 32-bit or 64-bit Oracle 10g Oracle 11g

4.

You have a supported ODP.NET driver:

ODP.NET 10.2.0.1x ODP.NET 10.2.0.2x ODP.NET 10.2.0.3 ODP.NET 11.1.0.6.20

2 .NET Agent Implementation Guide

5.

Verify that the applications that you want to monitor run using the IIS worker process. To verify that a web application is using a worker process, load a page from the application, then open the Task Manager and look for:

aspnet_wp.exe on IIS 5.0, 5.1 or 6.0 running in 5.0 compatibility mode w3wp.exe on IIS 6.0 or later

If you do not see the worker process, enable IIS to handle managed components. Navigate to the .NET Framework directory for the version of .NET you are using and run the following command:
aspnet_regiis.exe i

For example:
C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\aspnet_regiis.exe -i

6.

Verify that you have sufficient disk space available to install the agent files. CA Technologies recommends disk space equal to three times the size of the installer executable. Verify that any previous version of the .NET agent has been removed from the computer where you intend to install a new .NET agent. You can verify whether the .NET agent is present by opening a Command window and typing "set" to list the environment variables currently defined. If com.wily.introscope.agentProfile=<path> is listed, remove the agent before proceeding.

7.

8. 9.

Verify that the computer where you intend to install the .NET agent does not have another monitoring agent or CLR profiler installed. Verify that you have installed the Introscope Enterprise Manager and Workstation. Note the host name and port number for onfiguring the Enterprise Manager connection. You can use ping or telnet to verify connectivity between the agent and the Enterprise Manager.

Chapter 2: Installing the .NET Agent 31

Select the Method for Installing the .NET Agent

Install .NET Agent Interactively

You can install the .NET agent interactively by starting the .NET agent installer program and responding to the prompts displayed. Follow these steps: 1. Double-click the agent installer executable for 32-bit or 64-bit operating system. For example, double-click the introscope<version>windowsAgent_dotNET_32.exe file. The Welcome page appears. Click Next to start the installation. Note: You can install using either the .exe or .msi executable. The .msi executable is provided to enable software delivery by group policy or other automated delivery, such as a scheduled task. The .exe executable provides additional functionality. For example, if you use the .exe executable, you can right-click to run the installer as an Administrator when you are not logged on as an administrator. 2. Click Next to accept the default installation directory or click Change to select another directory, then click Next. The default installation directory for the .NET agent is C:\Program Files\CA APM\Introscope<version>. Within the root installation directory, the installer creates the wily directory that is the <Agent_Home> directory. 3. Type the host name and port number for the Enterprise Manager to which the agent should report metrics, then click Next. Note: The default Enterprise Manager for the agent is localhost, which is appropriate in a lab environment where the Enterprise Manager and agent are installed on the same computer. In a typical production environment, configure the connection to a remote Enterprise Manager. The default Enterprise Manager port is 5001. 4. Select the monitoring options you want to enable, then click Next.

ChangeDetector tracks changes in the application environment and reports them in the Workstation. If you enable ChangeDetector, type the ID for the ChangeDetector agent. For more information on enabling and working with ChangeDetector, see the CA APM ChangeDetector User Guide. CA APM for SOA provides extended monitoring for client- and server-side web services. This option is selected by default. Note: The .NET agent provides web service monitoring by default. Selecting CA APM for SOA provides additional capabilities, such as enhanced transaction tracing, monitoring for WCF services, and additional dependency metrics. After installation, the content of the .pbd files depends on whether you enable CA APM for SOA. For more information, see the CA APM for SOA Implementation Guide.

4 .NET Agent Implementation Guide

Select the Method for Installing the .NET Agent

CA APM for Microsoft SharePoint and CA APM Standalone Agent for Microsoft SharePoint (SPMonitor) enable monitoring for Microsoft SharePoint web applications and services. The option is only applicable on Windows Server 2003 or 2008. For more information, see the CA APM for Microsoft SharePoint Guide.

If you do not enable any monitoring options, you can manually enable monitoring options later. 5. Select whether additional agent services should be started automatically or manually. If you selected the CA APM Standalone Agent for Microsoft SharePoint (SPMonitor), specify a SharePoint domain user account and password for the service to run. Example: <domain>\<username> 6. Click Install. The installer creates the .NET agent root installation directory and installs the files the agent uses. 7. 8. When the installation is complete, click Finish. To verify the agent has been installed successfully, do one of the following:

.exe installer: verify that the IntroscopeDotNetAgentInstall*.exe.log file is in the same directory as the installer executable. .msi installer: verify that the MSI*.LOG file is created under the %temp% folder. The log file is only available for Windows Installer 4.0 or later.

9.

Restart IIS Admin Service to complete the installation. Note: Installing the .NET agent adds the following system environment variables to the operating system: com.wily.introscope.agentProfile, Cor_Enable_Profiling, COR_PROFILER. Restarting IIS or rebooting the local computer is required to inform IIS that system environment variables have changed.

Chapter 2: Installing the .NET Agent 33

Select the Method for Installing the .NET Agent

Install .NET Agent Manually Using Installation Archives

You can include the agent files on a system without running the installer interactively or configuring a response file. Application server-specific archives let you install the agent. Installation archives contain the same files used by the agent installer. After you copy an archive to a computer, extract the contents and configure the agent. Use these files to deploy multiple agents in a batch job, or keep the files as an archive of the default set of agent files. Follow these steps: 1. Download one of the following installation archives for your operating system from the CA APM software download site.

DotNetAgentFiles-NoInstaller.x64.9.1.0.0.zip DotNetAgentFiles-NoInstaller.x86.9.1.0.0.zip

2. 3.

Extract the installation archive contents into a directory of your selection. Set up the <Agent_Home>\wily directory for the .NET agent. Note: When you run the .NET agent installer program, the default root installation directory is C:\Program Files\CA APM\Introscope<version>. Within the root installation directory, the installer creates the wily directory that is the <Agent_Home> directory.

4.

Register the wily.Agent file to the Global Assembly Cache as follows: a. b. c. d. Open a command prompt as the administrator. Navigate to the wily\bin directory. For example:
explorer <Agent_Home>\wily\bin

Navigate to the assembly directory. For example:

explorer C:\WINDOWS\assembly

Copy wily.Agent from the <Agent_Home>wily\bin directory to the assembly directory.

5.

Register the wily.NativeProfiler file as follows: a. From a command line, navigate to the wily\bin directory and invoke the following executable:
C:\WINDOWS\SysWOW64\regsvr32.exe <Agent_Home>\wily\bin\x84\wily.NativeProfiler.dll

6.

Open the IntroscopeAgent.profile file in a text editor and configure the Enterprise Manager connection as follows: a. Locate the line: introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT , and specify the host name of the Enterprise Manager for the agent. For example:
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=sfcollect01

b.

Set other properties for communication with the Enterprise Manager as appropriate.

34 .NET Agent Implementation Guide

Select the Method for Installing the .NET Agent

7.

Start the PerfMon Collector Service from a command line as follows:

PerfMonCollectorAgent binPath= "<Agent_home>\bin\PerfMonCollectorAgent.exe start= auto DisplayName= "CA APM PerfMon Collector Service"

8.

Run the wilypermissions utility from a command line to verify that users have permission to access the <Agent_Home> directory. For example:
wilypermissions.exe c:\WilyAgent9065\wily w3wp.exe

9.

Configure the .NET agent environment variables as follows:

com.wily.introscope.agentProfile=<Agent_Home>\wily\IntroscopeAgent.profile Cor_Enable_Profiling=0x1 COR_PROFILER={5F048FC6-251C-4684-8CCA-76047B02AC98}

10. Restart IIS Admin Service to complete the installation.

Install .NET Agent in Chinese or Japanese

You can specify a language value when you run the .msi installer executable. Note: This information applies to 32- and 64-bit Windows only. Follow these steps: 1. 2. Open a Command Prompt window. Invoke the .msi installer executable with the language value as follows:

Japanese:
IntroscopeDotNetAgentInstall64_9.1.0.0.msi TRANSFORMS=1041.mst ProductLanguage=1041

Chinese:
IntroscopeDotNetAgentInstall64_9.1.0.0.msi TRANSFORMS=2052.mst ProductLanguage=2052

3.

Restart the application server to complete the installation. The installer creates the .NET agent root installation directory and installs the files the agent uses. The .MSI*.LOG file is created in the %temp% folder.

Chapter 2: Installing the .NET Agent 35

Understanding the .NET Agent Directory Structure

Understanding the .NET Agent Directory Structure

After you install the .NET agent, the following <Agent_Home> directory structure is created in the root installation directory: wily Contains the IntroscopeAgent.profile, ProbeBuilder Directive files (.pbd), and ProbeBuilder List files (.pbl) files that control agent operations, metric data collection, and the instrumentation process. The specific properties defined in the IntroscopeAgent.profile that are deployed and referenced in the agent depend on choices you made during installation. Within the <Agent_Home> directory, additional subdirectories provide the libraries and extension files that enable various features of the .NET agent. bin Contains the core .NET agent libraries. dynamic This directory contains the PBD files for dynamic instrumentation. examples Contains folders and files for optional agent extensions, such as CA APM for SOA. If you did not enable an extension at installation, use the files in this directory to configure and enable the extension at a later time. ext Contains the files for enabled agent extensions or features. For example, the directory contains files for the application triage map and LeakHunter. hotdeploy This directory is empty by default. You can place PBD files in this directory to deploy new directives without editing the IntroscopeAgent.profile or restarting applications. However, use caution before placing files in this directory. If custom PBDs contain invalid syntax or are configured to collect too many metrics, instrumentation can fail or application performance can suffer. logs Stores .NET agent log files. readme This directory is only created if you enabled extensions during the installation. If the directory exists, it contains readme information for the extensions enabled. tools Contains the Network Interface integration utility.

36 .NET Agent Implementation Guide

Understanding the .NET Agent Directory Structure

version Contains version information for optional agent extensions, whether you enable them or not.

User Permissions to Agent Directory

By default, the installer program grants read access to Everyone on the <Agent_Home> directory as follows:

Read permission to <Agent_Home>\wily Read and execute permissions to <Agent_Home>\bin and <Agent_Home>\ext Read and write permissions to <Agent_Home>\logs and <Agent_Home>\dynamic

If you want to restrict access to this directory, you can modify the default permissions to only allow the user accounts that run the IIS worker process to access the <Agent_Home> directory.

Modify Default User Permissions to Agent Directory

You can modify the default user permissions to the <Agent_Home> directory by running the wilypermissions utility from a command line. If no user is specified, the utility detects the default IIS user for the application and grant permissions to that user. Follow these steps: 1. 2. Navigate to the <Agent_Home> directory. Run wilypermissions.exe from a command line as follows:
wilypermissions.exe <Agent_Home> [process name]

The utility executes, granting permission to the <Agent_Home> directory to the user, and giving access to Performance Monitor counters. Note: The process name must include the file extension. If the process name is not specified, the IIS worker process name is the default.

Chapter 2: Installing the .NET Agent 41

Check the User Permissions for the IIS Worker Process

Configure the Connection to the Enterprise Manager

If you used the default settings when you installed the agent, the agent is configured to connect to an Enterprise Manager on the local host. However, the agent and the Enterprise Manager do not typically reside on the same system. If deploying on a production system, the agent should report metrics to a remote Enterprise Manager. You can configure the communication properties for connecting to the Enterprise Manager in the IntroscopeAgent.profile. Follow these steps: 1. 2. Open the IntroscopeAgent.profile file in a text editor. Locate the introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT property and specify the host name of the Enterprise Manager the agent should connect to by default. For example:
introscope.agent.enterprisemanager.transport.tcp.host.DEFAULT=sfcollect01

3.

Set the introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT property to the Enterprise Manager listening port. For example:
introscope.agent.enterprisemanager.transport.tcp.port.DEFAULT=5001

4.

Set the introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT property to the socket factory used for connections to the Enterprise Manager. For example:
introscope.agent.enterprisemanager.transport.tcp.socketfactory.DEFAULT=com.wi ly.isengard.postofficehub.link.net.DefaultSocketFactory

Note: In most cases, you can use the default setting for this property. If you want to use a different socket factory, modify this property. 5. 6. Save and close the IntroscopeAgent.profile file. Restart IIS Admin Service to complete the configuration.

Check the User Permissions for the IIS Worker Process

Typically, .NET web applications run in an IIS worker process. By default, the IIS worker process name is w3wp.exe or aspnet_wp.exe. The default account that runs the worker process is NETWORK SERVICE. When you install the .NET agent, the installer creates the root installation directory with the appropriate permissions that allow access to the .NET <Agent_Home>, or wily, directory and the bin, ext, and log subdirectories and to Performance Monitor counters.

40 .NET Agent Implementation Guide

Check the User Permissions for the IIS Worker Process

You can, however, configure other accounts to run the worker process at the application pool level. If you configured other user accounts to run the IIS worker process, do the following:

Determine which user account run applications Verify that all of the accounts used to run applications have permission to access the <Agent_Home> directory Set user permissions for the account that runs the Performance Monitor Collection Agent to allow access to Performance Monitor counters

Determine the User Running the Application

In some organizations, accounts other than the NETWORK SERVICE run the IIS worker process. To ensure you can monitor applications that run under other accounts, you should determine the user name associated with the IIS worker process across all of the applications you want to monitor. For each user name you identify, you should verify that the user has permission to access the <Agent_Home> directory and Performance Monitor counters. Follow these steps: 1. 2. 3. 4. 5. Verify the application is running. Right-click in the Task Bar and select Task Manager to open the Windows Task Manager. Click the Processes tab. Scroll to locate the entry for the w3wp.exe or aspnet_wp.exe process in the Image Name column. Check the User Name column to determine the user account running the process. For example, the default user for the w3wp.exe worker process is NETWORK SERVICE. If you use another user account to run the IIS worker process, you should note the account name so that you can verify it has appropriate permissions.

Verify User Permissions on the Agent Directory

The user account that runs the IIS worker process must have the correct user permissions for the files in the <Agent_Home> directory and access to Performance Monitor counters for the .NET agent to function properly. By default, the installer grants read access to Everyone on the <Agent_Home> folder. Therefore, if you want to restrict access to this directory, you should modify the default permissions to only allow the user accounts that run the IIS worker process to access the <Agent_Home> directory.

42 .NET Agent Implementation Guide

Configuring application idle time

Follow these steps: 1. In Windows Explorer, right-click on the root .NET agent folder and select Properties. The Properties window for the folder is displayed. 2. 3. Click the Security tab. Click Add. The Select Users or Groups dialog box is displayed. 4. 5. 6. Type all or part of the user name in Enter the object names to select. Click Check Names to search for one or more matching user names. Select the appropriate user account, then click OK. The Permission Entry dialog box is displayed. 7. Under Full Control, verify that the user has Allow checked. Enabling Full Control provides the user with permissions to Modify, Read & Execute, List Folder Contents, Read, and Write. 8. Click Advanced. The Advanced Security Settings dialog box is displayed. 9. Select Replace permission entries on all child objects with entries shown here that apply to child Objects to propagate permissions to the child directories, and click OK.

Set user permissions for Performance Monitor metrics

To view Performance Monitor metrics in the Introscope Investigator, the user account that runs the IIS worker process must have the correct permissions. These permissions are defined automatically if you used the wilypermissions utility. If you did not use the wilypermissions utility, you must manually set the permissions for the user account that runs the IIS worker process. Follow these steps: 1. 2. 3. 4. 5. 6. 7. From the Start menu, navigate to Settings, Control Panel, Administrative Tools, Local Security Policy, Local Policies, User Rights Assignment. Right-click Profile Single Process, and select Properties. Click Add User or Group. Add the user account that runs the IIS worker process to the list of users, then click OK. Right-click Profile System Performance, and select Properties. Click Add User or Group. Add the user account that runs the IIS worker process to the list of users, then click OK. Chapter 2: Installing the .NET Agent 43

Removing the .NET agent

Removing the .NET agent

Remove .NET Agent Interactively
The .NET agent is active whenever an instrumented application is running. Before you can delete or modify any agent DLL files, you must ensure all instrumented applications are stopped. You can then remove agent files locally using the Add or Remove Programs Control Panel or silently using the uninstall program. To remove the .NET agent interactively 1. 2. 3. Stop the IIS service to stop all instrumented applications. Navigate to Start, Settings, Control Panel, Add or Remove Programs. Select one of the following from the list of currently installed programs:

CA APM .NET Agent9.1.0.0 (32 bit) CA APM .NET Agent9.1.0.0 (64 bit)

4.

Click Remove. You are prompted to confirm that you want to remove the agent.

5.

Click Yes to remove the agent. The .NET agent DLLs are unregistered, related environment variables are removed, and agent files that have not been modified since installation are removed.

6. 7. 8.

Close Add or Remove Programs. Restart the IIS Admin Service or reboot the computer. Select the root installation directory for the agent, right-click, and then select Delete. The .NET agent is removed.

44 .NET Agent Implementation Guide

Configuring application idle time

Remove .NET Agent Manually

You can remove the .NET agent and associated files manually. Note: The .NET agent is active whenever an instrumented application is running. Before you can delete or modify any agent DLL files, you must ensure all instrumented applications are stopped. Follow these steps: 1. 2. Navigate to the C:\WINDOWS\assembly directory. Right-click wily.Agent and select Uninstall from the menu. The agent files are removed. 3. Open a command prompt as the administrator. a. Remove the NativeProfiler file as follows:

C:\WINDOWS\system32\regsvr32.exe /u <Agent_Home>\bin \wily.NativeProfiler.dll C:\WINDOWS\SysWOW64\regsvr32.exe /u <Agent_Home>\bin\x86 \wily.NativeProfiler.dll

b. c.

Remove the PerfMon Collector Service by running the following command:

sc delete PerfMonCollectorAgent

Set the following .NET agent environment variables as follows:

com.wily.introscope.agentProfile=<Agent_Home>\IntroscopeAgent.profile Cor_Enable_Profiling=0x1 COR_PROFILER={5F048FC6-251C-4684-8CCA-76047B02AC98}

4.

Restart IIS to complete the uninstall process.

Index 51