User's Guide: Beta 1 draft

Transcription

1 IBM Tivoli Composite Application Manager for Microsoft Applications:.NET Data Collector vnext User's Guide: Beta 1 draft SC

2

3 IBM Tivoli Composite Application Manager for Microsoft Applications:.NET Data Collector vnext User's Guide: Beta 1 draft SC

4 Note Before using this information and the product it supports, read the information in Notices on page 57. This edition applies to version vnext of IBM Tivoli Composite Application Manager for Microsoft Applications:.NET Data Collector (product number 5724-U17) and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright IBM Corporation 2012, US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents Figures v Tables vii Chapter 1. Overview of.net Data Collector New in this release Components of.net Data Collector Chapter 2. Scenarios monitored by.net Data Collector NET transactions monitored by.net Data Collector 3 Intra-domain transactions monitored by.net Data Collector Chapter 3. Installing.NET Data Collector 5 Permissions required for the.net Data Collector installation directory Prerequisites checking Chapter 4. Configuring.NET Data Collector Configuring registration Configuring connection to the Transaction Collector. 9 Enabling and disabling ADO.NET interfaces monitoring Activating the configuration Configuring.NET Data Collector by using the configuration tool Configuring logging for.net Data Collector Working with IBM Tivoli Composite Application Manager for SOA Configuring.NET Data Collector with IBM Tivoli Composite Application Manager for SOA Verifying installation of.net Data Collector ADO Event Aggregation Disabling ADO event aggregation utility Chapter 5. Uninstalling.NET Data Collector Uninstalling.NET Data Collector if it is installed with ITCAM for SOA agent Chapter 6. Selective Filtering utility.. 19 Prerequisites Running the Selective Filtering utility Removing SetApplicationPools.dll file User interface elements of Selective Filtering utility 20 Using the Selective Filtering utility Enabling the application pools filtering Disabling the application pools filtering Removing environment variables Chapter 7..NET tracking data displayed in Transaction Tracking workspaces.. 23 Interpreting topologies Chapter 8. Troubleshooting Problems and workarounds NET Data Collector configuration changes not reflected in operation No events are received from the.net Data Collector Extra events are sent to the Transaction Collector for the.net Data Collector NET Data Collector event SVC node is disconnected if SOAP is disabled.. 30 ASPX node is not seen in transaction topology 30 SOAP status is displayed as enabled even if it is not registered Static nodes might be seen in the transaction topology Async arrow that points to the WCF web service is seen Multiple play icons might be seen in transaction topology Empty folder structure of.net Data Collector remains after uninstallation NET Data Collector does not get installed if.dll files of previous versions are used configdc getconfig command displays all components in disable state Database node details might vary according to the database and connection type Support information Selective Filtering messages Event log messages NET Data Collector messages: BWMNT* Appendix A. Functions of namespaces supported by.net Data Collector Appendix B. Configuration values of.net Data Collector Notices Trademarks Index Copyright IBM Corp. 2012, 2013 iii

6 iv.net Data Collector: User's Guide : Beta 1 draft

7 Figures 1..NET Data Collector in the Component workspace NET Data Collector in the Applications workspace NET Data Collector in the Transactions workspace Copyright IBM Corp. 2012, 2013 v

8 vi.net Data Collector: User's Guide : Beta 1 draft

9 Tables 1..NET Data Collector - components required for monitoring scenarios NET Data Collector intra-domain transactions monitored Permissions required for the.net Data Collector installation directory NET Data Collector configuration commands Verification steps for registration of.net Data Collector components Graphical user interface elements and their description Transaction tracking data displayed in workspaces Selective Filtering messages Event log messages for.net Data Collector Functions of namespaces intercepted by.net Data Collector Copyright IBM Corp. 2012, 2013 vii

10 viii.net Data Collector: User's Guide : Beta 1 draft

11 Chapter 1. Overview of.net Data Collector IBM Tivoli Composite Application Manager for Microsoft Applications includes.net Data Collector that enables you to track the transactions that occur in the.net Framework application and the Internet Information Services (IIS) web applications. New in this release For the.net Data Collector, the following enhancements have been made since version 7.3.1, including the fix packs: v Support for monitoring.net transactions that are done by using the ASP.NET MVC application. The following versions of ASP.NET MVC application are supported: MVC 2 MVC 3 MVC 4 v New scenarios supported: Web requests to ASP.NET MVC application ASP.NET MVC application to WCF web service calls ASP.NET MVC application to ASP.NET web service calls ASP.NET MVC application to ADO.NET Database calls v Support for LDAP Async APIs v New methods supported: void DirectoryEntry.CommitChanges() void DirectoryEntry.MoveTo(DirectoryEntry, String) DirectoryResponse LdapConnection.SendRequest(DirectoryRequest, TimeSpan) IAsyncResult LdapConnection.BeginSendRequest(DirectoryRequest, PartialResultProcessing, AsyncCallback, Object) IAsyncResult LdapConnection.BeginSendRequest(DirectoryRequest, TimeSpan, PartialResultProcessing, AsyncCallback, Object) DirectoryResponse LdapConnection.EndSendRequest(IAsyncResult) void LdapConnection.Abort(IAsyncResult) Components of.net Data Collector The following components of.net Data Collector are registered during the installation of.net Data Collector: Profiler This component uses the.net Common Language Runtime (CLR) profiler to provide the transactions of ADO.NET database and directory service. SOAP This component provides SOAP and Windows Communication Foundation (WCF) extensions to monitor ASMX and WCF requests and responses. ISAPI This component provides authentication timings in Internet Information Services (IIS) 6, IIS 7.x classic mode and IIS 8. HttpModule This component provides ASP.NET monitoring support and ASPX linking support. It also provides authentication timings of IIS 7.x in integration mode and IIS 8. Copyright IBM Corp. 2012,

12 .NET Data Collector components required to monitor scenarios The.NET Data Collector components that are required to monitor various scenarios are determined by the systems that you want to monitor in your environment. Table 1 contains the components of.net Data Collector that are required to monitor scenarios. Table 1..NET Data Collector - components required for monitoring scenarios Domain tracking scenario.net Data Collector component required Tracking authentication timings of web applications in ISAPI and HttpModule IIS 6, IIS 7.x classic mode, and IIS 8 classic mode Tracking authentication timings of web applications in HttpModule IIS 7.x integration mode and tracking basic, digest, and Windows authentication Tracking transactions of ASP.NET web services by using ASPX Tracking SOAP transactions of.net ASMX (sync or async) web services Tracking SOAP transactions of WCF web services Tracking ADO.NET (sync or async database calls) interfaces HttpModule, SOAP, and Profiler SOAP, Profiler, and HttpModule SOAP, Profiler, and HttpModule Profiler and HttpModule (only profiler if ADO Event Aggregation utility is disabled) Tracking Active Directory services (sync only) through LDAP & ADSI Tracking HTTP request for ASPX Tracking HTTP request for ASPX by using Response.Redirect Tracking.NET > IHS > WAS linking Tracking.NET > WAS linking Tracking.NET > Websphere Message Broker (WMB) For more information about ADO Event Aggregation utility, see ADO Event Aggregation on page 16 Profile and HttpModule (only profiler if ADO Event Aggregation utility is disabled) ISAPI, HttpModule, and Profiler HttpModule Http, SOAP, and Profiler HttpModule, SOAP, Profiler HttpModule, SOAP, Profiler, and ISAPI 2.NET Data Collector: User's Guide : Beta 1 draft

13 Chapter 2. Scenarios monitored by.net Data Collector Within the.net Framework application, the.net Data Collector monitors the ASP.NET web pages, web services, calls to ADO.NET, and calls to directory services. Within the Internet Information Services web applications,.net Data Collector monitors the basic, digest, and Windows authentications..net transactions monitored by.net Data Collector The.NET Data Collector monitors the.net transactions that include relational database connections and the connections that are made by using the database drivers. Connections to the following relational databases are monitored by.net Data Collector: v DB2 v Oracle v SQL Server For ADO.NET, the database connections made by using the following drivers are monitored by.net Data Collector: v ODBC v OLE DB.NET Data Collector monitors the transactions by using the synchronous LDAP and ADSI APIs and asynchronous LDAP APIs. The following scenarios are monitored by.net Data Collector: v ASMX/WCF web services v ADO.NET (DB2, ODBC, OleDB, Oracle, Microsoft SQL Server) v Directory service interfaces (ADSI, LDAP) v IIS Server for web applications, and basic, digest, and Windows authentication The following versions of ASP.NET MVC application are supported: v MVC 2 v MVC 3 v MVC 4 The following scenarios for.net transactions that are made by using the MVC application are monitored by.net Data Collector: v Web requests to ASP.NET MVC application v ASP.NET MVC application to WCF web service calls v ASP.NET MVC application to ASP.NET web service calls v ASP.NET MVC application to ADO.NET Database calls Copyright IBM Corp. 2012,

14 Intra-domain transactions monitored by.net Data Collector The Table 2 includes the intra-domain interactions that are monitored by the.net Data Collector Table 2..NET Data Collector intra-domain transactions monitored Intra-domain transactions monitored Description.NET to IBM HTTP Server The WCF applications are linked to the IBM HTTP Server, where the IBM HTTP Server is monitored by Application Response Measurement (ARM)..NET to WebSphere Application Server, V 6.0 and V 7.0 The Service Oriented Architecture (SOA).NET applications can interact with web services that are running on WebSphere Application Server, where the web services are monitored by IBM Tivoli Composite Application Manager for Application Diagnostics, V 7.1 that is configured on ARM layer or SOAP layer..net to and from WebSphere Message Broker WCF/ASMX web services. 4.NET Data Collector: User's Guide : Beta 1 draft

15 Chapter 3. Installing.NET Data Collector Install.NET Data Collector on the computer where you installed the applications that you want to monitor..net Data Collector does not support remote and silent installations. Before you begin Make sure that your system meets the requirements for IBM Tivoli Composite Application Manager for Microsoft Applications:.NET Data Collector. For information about requirements, see the Prerequisites topic for.net Data Collector in the IBM Tivoli Composite Application Manager for Microsoft Applications Information Center ( publib.boulder.ibm.com/infocenter/tivihelp/v24r1/topic/com.ibm.itcamms.doc_6.3/ welcome_msapps63.html) Procedure 1. If you are installing.net Data Collector on an x86-32 processor or on an x86-64 processor, launch the installation wizard by double-clicking the setup.exe file in the WINDOWS subdirectory on the installation media. Use the IBM Tivoli Monitoring Base Agent DVD or a distributed agent product CD for Windows operating systems. Do not use the Data Files for z/os CD. 2. Click Next on the Welcome window. Note: If you have another IBM Tivoli Monitoring component already installed on this computer, select Modify on the Welcome window. A message displays the items that you selected. Click OK and go to Step Read and accept the software license agreement. 4. Browse to the CANDLE_HOME/TMAITM6 directory. 5. On the Select Features window, expand the Tivoli Enterprise Monitoring Agents list. 6. Select.NET Data Collector and click Next. 7. Review the installation summary details. The summary provides information about what you want to install and the location of installation. Click Next to start the installation. After the installation is complete, the Setup Type window opens that contains the following check boxes: v Configure agents default connection to Tivoli Enterprise Monitoring Server v Launch Manage Tivoli Monitoring Services for additional configuration options and to start Tivoli Monitoring services These check boxes are selected by default. You can clear the check boxes if you are installing only.net Data Collector. 8. Click Next to start configuring.net Data Collector. 9. Click Finish to complete the installation. 10. If you are updating an existing installation, on the Maintenance Complete window, click Finish. Note: The.NET Data Collector is not displayed in the Manage Tivoli Enterprise Monitoring Services window. Copyright IBM Corp. 2012,

16 What to do next You must provide permissions for the.net Data Collector installation directory. To know more about the permissions, see Permissions required for the.net Data Collector installation directory Permissions required for the.net Data Collector installation directory Before you start monitoring the applications by using.net Data Collector, you must provide appropriate permissions for the.net Data Collector installation directory. Table 3. Permissions required for the.net Data Collector installation directory Applications Built-in account Required users Required access IIS Applications ApplicationPoolIdentity User group and LocalMachine\IIS_IUSRS v v Read access to the CANDLE_HOME directory Read, Execute, and Write permissions for the K4 directory and its subdirectories LocalSystem v For IIS 7: LocalMachine\IIS_IUSRS v For IIS 6: LocalMachine\IIS_WPG Network Service v LocalMachine\Network Service v For IIS 7: LocalMachine\IIS_IUSRS v For IIS 6: LocalMachine\IIS_WPG v v v v Read access to the CANDLE_HOME directory Read, Execute, and Write permissions for the K4 directory and its subdirectories Read access to the CANDLE_HOME directory Read, Execute, and Write permissions for the K4 directory and its subdirectories Desktop applications (all.net-based applications installed and running after the.net Data Collector is installed) Local Service v LocalMachine\Local Service v For IIS 7: LocalMachine\IIS_IUSRS v For IIS 6: LocalMachine\IIS_WPG Built-in or Active Directory LocalMachine\username or custom-created user or DomainName\username v v v v Read access to the CANDLE_HOME directory Read, Execute, and Write permissions for the K4 directory and its subdirectories Read access to the CANDLE_HOME directory Read, Execute, and Write permissions for the K4 directory and its subdirectories System LocalMachine\Users v Read access to the CANDLE_HOME directory v Read, Execute, and Write permissions for the K4 directory and its subdirectories 6.NET Data Collector: User's Guide : Beta 1 draft

17 Table 3. Permissions required for the.net Data Collector installation directory (continued) Applications Built-in account Required users Required access Network Service v LocalMachine\Network Service v LocalMachine\USRS Local Service v LocalMachine\Local Service v LocalMachine\USRS Built-in or Active Directory or custom-created user LocalMachine\username or DomainName\username v v v v v v Read access to the CANDLE_HOME directory Read, Execute, and Write permissions for the K4 directory and its subdirectories Read access to the CANDLE_HOME directory Read, Execute, and Write permissions for the K4 directory and its subdirectories Read access to the CANDLE_HOME directory Read, Execute, and Write permissions for the K4 directory and its subdirectories Prerequisites checking The prerequisite checker utility verifies whether all the prerequisites that are required for the agent installation are met. The prerequisite checker creates a log file that contains a report of all the prerequisites checks when the prerequisite checker is run. For the.net Data Collector, the prerequisite checker verifies the following requirements: v Memory v Disk v Operating systems v.net Framework versions Additionally, the prerequisite checker verifies whether the user, who installs the agent, is a member of the Administrators group. For detailed information about installation prerequisites, see the Prerequisites topic for.net Data Collector in the IBM Tivoli Composite Application Manager for Microsoft Applications Information Center ( welcome_msapps63.html). You can run the prerequisite checker in stand-alone mode or remotely. For more information about the prerequisite checker, see "Prerequisite Checking for IBM Tivoli Monitoring Agents" in the IBM Tivoli Monitoring Installation and Setup Guide. Chapter 3. Installing.NET Data Collector 7

18 8.NET Data Collector: User's Guide : Beta 1 draft

19 Chapter 4. Configuring.NET Data Collector After you install.net Data Collector, you must configure the.net Data Collector to monitor the applications. To configure.net Data Collector, you must complete the following steps: 1. Configuring registration 2. Configuring connection to the Transaction Collector 3. Enabling and disabling ADO.NET interfaces monitoring on page Activating the configuration on page 11 For information about configuring.net Data Collector with IBM Tivoli Composite Application Manager for SOA, see Working with IBM Tivoli Composite Application Manager for SOA on page 13. Configuring registration After you complete the installation of.net Data Collector, you must configure the.net Data Collector to monitor.net transactions. About this task When you configure.net Data Collector, all components of.net Data Collector that are required for monitoring.net transactions are registered automatically. Procedure 1. Go to the CANDLE_HOME/TMAITM6/K4/bin directory, and register the.net Data Collector profiling DLL by running the following command: configdc registerdc [-f] where -f overrides any existing.net profiler without further prompts. If a profiler exists, and the -f option is not specified, the.net Data Collector profiler is not configured. 2. Restart all.net applications. What to do next After you configure registration, you must configure connection to the Transaction Collector. For further information, see Configuring connection to the Transaction Collector To stop.net Data Collector from monitoring.net transactions, go to the CANDLE_HOME/TMAITM6/K4/bin directory, and run the following command: configdc unregisterdc After you unregister the.net Data Collector, restart all.net applications. Configuring connection to the Transaction Collector.NET Data Collector events are sent to the Transaction Collector. Therefore, you must configure connection to the Transaction Collector after you install.net Data Collector. Copyright IBM Corp. 2012,

20 About this task The location of the Transaction Collector is automatically set in the configuration file during installation. If you are not prompted for the location of the Transaction Collector during installation of.net Data Collector, you might need to manually verify the location. Procedure From the CANDLE_HOME\TMAITM6\K4\bin directory, run the following command: configdc ttserver -name [host name/ip address] -port [port number] What to do next v If configuration is complete, activate your configuration changes. See Activating the configuration on page 11 for more information. v If you want to monitor ADO.NET interfaces to be monitored, see Enabling and disabling ADO.NET interfaces monitoring Enabling and disabling ADO.NET interfaces monitoring Choose the ADO.NET client interfaces that you want the.net Data Collector to monitor. Before you begin You might want to view the ADO.NET interfaces that are supported by.net Data Collector. For information about supported ADO.NET interfaces, see Appendix A, Functions of namespaces supported by.net Data Collector, on page 39. About this task By default, all supported ADO.NET interfaces are enabled for monitoring during installation of.net Data Collector. To select the interfaces that must be monitored by.net Data Collector, enable or disable monitoring for specific interfaces. If you disable monitoring of an interface, any associated application domain filter is retained when the interface is enabled again. Procedure 1. To enable monitoring, from the CANDLE_HOME\TMAITM6\K4\bin directory, run the configdc enablemonitor command: configdc enablemonitor all adsi db2 ldap odbc oledb oracle sql http web [-appdomain appdomain filter list] 2. To disable monitoring, from the CANDLE_HOME\TMAITM6\K4\bin directory, run the configdc disablemonitor command: configdc disablemonitor all adsi db2 ldap odbc oledb oracle sql http web For more information about using the configdc command, see Configuring.NET Data Collector by using the configuration tool on page 11. For information about default configuration values for configuring.net Data Collector, see Appendix B, Configuration values of.net Data Collector, on page 43 What to do next After you enable or disable the ADO.NET interfaces for monitoring, activate the configuration changes. See Activating the configuration on page 11 for more information. 10.NET Data Collector: User's Guide : Beta 1 draft

21 Activating the configuration Activate the updated configurations for the changes to take effect. Procedure To activate an inactive configuration: 1. From the CANDLE_HOME\TMAITM6\KD4\bin directory, run the configdc activateconfig command. 2. Restart all.net applications. What to do next If IIS transactions are monitored and the Transaction Collector connection configuration is updated, restart IIS to finish activating the configuration. If ASMX or WCF web services are monitored and the Transaction Collector connection configuration is updated, complete one of the following: v Restart the process that hosts the web service. v Register the.net Data Collector again by running the unregisterdc command, and then run the configdc registerdc command. Configuring.NET Data Collector by using the configuration tool You can use the command line configuration tool of.net Data Collector to perform the basic configuration tasks, such as registering the.net Data Collector, validating and storing the connectivity information, enabling and disabling trace logging, and so on. Run all commands that are mentioned in Table 4 from the CANDLE_HOME\TMAITM6\KD4\bin directory. Table 4..NET Data Collector configuration commands Command syntax configdc registerdc [-f] Description Registers the.net Data Collector. -f overrides any.net profiler that is already registered without any notifications. If a profiler exists and the -f option is not specified, the.net Tracking profiler is not configured. Run this command as an administrator. configdc unregisterdc configdc ttserver -name name -port port configdc logging [level ERROR DEBUG WARNING INFO] [-size ] [-files ] [-tracing on off] Stops.NET Data Collector from intercepting.net transactions. Run this command as an administrator. Validates and stores the connectivity information of the Transaction Collector to which the data collector sends the tracking data. Enables or disables trace logging. Sets tracing attributes, for example, the level of trace detail, the maximum trace log file size, and the maximum number of trace log files. Chapter 4. Configuring.NET Data Collector 11

22 Table 4..NET Data Collector configuration commands (continued) Command syntax Description configdc enablemonitor [all adsi db2 ldap odbc oledb oracle sql http web] [-appdomain app domain list] Enables transaction monitoring of an ADO.NET interface. After installation, all interfaces are enabled for monitoring by default. Use all to enable all the supported ADO.NET interfaces for transaction tracking. Use http to enable interception of supporting APIs for http monitoring. (See configdc interface and http supported APIs in Table 10 on page 39.) The -appdomain command restricts the ADO.NET interface monitoring to one or more.net application domain names. If you specify more than one application domain name, separate each name with a semicolon (;). Use an asterisk (*) to enable all application domains. All application domains are enabled by default during the installation. configdc disablemonitor [all adsi db2 ldap odbc oledb oracle sql http web] configdc getconfig [-active] configdc activateconfig When an application domain list is assigned to an ADO.NET interface, the list remains unchanged in the configuration unless it is set to another value. If an interface is enabled for monitoring without specifying an application domain, the last application domain value that you specified or that was specified by default for the interface is used. Disables transaction monitoring of an ADO.NET interface. Use all to disable all supported ADO.NET interfaces for transaction tracking. Use http to intercept GetResponse (System.Net) and use web to disable the monitoring of http requests. Displays the properties file where you can add or remove.net API calls to be intercepted by.net Data Collector. When the changes are complete, activate the edited file by using the configdc activateconfig command. Activates the updated configuration. Configuring logging for.net Data Collector In IBM Tivoli Composite Application Manager for Microsoft Applications V6.3, logging for.net Data Collector is separately configured for each component of.net Data Collector. Performance of.net Data Collector might be affected when tracing is enabled. Disable tracing after the required trace logs are gathered. For the.net profiler, configure logging by using the configdc command. For further information about using the command, see Configuring.NET Data Collector by using the configuration tool on page 11. If both.net Data Collector and IBM Tivoli Composite Application Manager for SOA agent are installed on a computer, the ASMX/WCF trace and operation logging is controlled by the IBM Tivoli Composite Application Manager for SOA agent. Use the Take Action commands of IBM Tivoli Composite Application Manager for SOA agent to modify the logging settings. If only.net Data Collector is installed on a computer, the settings for ASMX/WCF trace and operation logging are taken from the dotnetdcconfig.properties file. 12.NET Data Collector: User's Guide : Beta 1 draft

23 For information about default configuration values for configuring.net Data Collector, see Appendix B, Configuration values of.net Data Collector, on page 43 Working with IBM Tivoli Composite Application Manager for SOA You can configure.net Data Collector with IBM Tivoli Composite Application Manager for SOA. For installation and prerequisites information of IBM Tivoli Composite Application Manager for SOA, seethe user's guide for IBM Tivoli Composite Application Manager for SOA V7.1.1, Fix Pack 2, or later. Configuring.NET Data Collector with IBM Tivoli Composite Application Manager for SOA In an environment where the ITCAM for SOA agent (V7.1.1 Fix Pack 2, V7.1.1 Fix Pack 3, or V7.2) is installed, you can use the KD4configureTT.bat configuration utility to configure.net Data Collector with IBM Tivoli Composite Application Manager for SOA. Procedure 1. Open a new instance of the command prompt, and change the path to the bin directory:candle_home\ TMAITM6\KD4\bin where CANDLE_HOME is the location where IBM Tivoli Monitoring is installed. For example, on Windows systems, C:\IBM\ITM is the default value for CANDLE_HOME. 2. Run the following command: KD4configureTT -enable -server tcp:[ip address of collector:port] The default port is To enable the.net Data Collector to work with IBM Tivoli Composite Application Manager for SOA, modify the dotnetdcconfig.properties.inactive file that is located in the CANDLE_HOME\TMAITM6\K4\ config directory as follows: default.kd4.enabled=true 4. Open the command prompt, and change the path to the bin directory: cd CANDLE_HOME\TMAITM6\K4\ bin 5. Run the configdc activateconfig command. 6. Run the configdc registerdc and iisreset command. To see the transaction topology, view the SOAP component. For more information about configuring the.net Data Collector with ITCAM for SOA, see the ITCAM for SOA Information Center Verifying installation of.net Data Collector If the components of.net Data Collector that you selected while installing.net Data Collector are successfully registered, the.net Data Collector is successfully installed and is monitoring the applications. The Table 5 on page 14 provides information about the procedures to verify whether each component of.net Data Collector that you selected during the installation is successfully registered. Chapter 4. Configuring.NET Data Collector 13

24 Table 5. Verification steps for registration of.net Data Collector components Component Name Location for verification Procedures to verify HttpModule Global Assembly Cache 1. To open the Global Assembly Cache (GAC), go to Start > Run > enter assembly command. 2. Verify whether NetdcHttpModule is displayed in the GAC. machine.config file If.NET Framework 2.0 is installed, complete the following steps: 1. Go to the system_root\microsoft.net\framework\v \config directory. 2. Open the machine.config file. 3. Verify whether the <add name="netdchttpmodule" type=="ktjdotnetdc.netdchttpmodule, NetdcHttpModule, Version= , Culture=neutral, PublicKeyToken=df3a8c65f5d404b8"/> tag is displayed in the file. 4. If the 64-bit version of.net Framework 2.0 is installed, go to the system_root\microsoft.net\framework64\v \config directory and repeat steps 2 and 3. applicationhost.config file (only for IIS 7) If.NET Framework 4.0 is installed, complete the following steps: 1. Go to the system_root\microsoft.net\framework\v \config directory. 2. Open the machine.config file. 3. Verify whether the <add name="netdchttpmodule" type="ktjdotnetdc.netdchttpmodule, NetdcHttpModule, Version= , Culture=neutral, PublicKeyToken=df3a8c65f5d404b8"/> tag is displayed in the file. 4. If the 64-bit version of.net Framework 4.0 is installed, go to the system_root\microsoft.net\framework64\v \config directory and repeat steps 2 and To open the applicationhost.config file, go to the system_root\system32\inetsrv\config directory. 2. Open the applicationhost.config file. 3. Verify whether the <add name="netdchttpmodule" type="ktjdotnetdc.netdchttpmodule, NetdcHttpModule, Version= , Culture=neutral, PublicKeyToken=df3a8c65f5d404b8"/> tag is displayed in the file. 14.NET Data Collector: User's Guide : Beta 1 draft

25 Table 5. Verification steps for registration of.net Data Collector components (continued) Component Name Location for verification Procedures to verify SOAP Global Assembly Cache 1. To open the GAC, go to Start > Run > enter assembly command. machine.config file 2. Verify whether the following.dll files with version are displayed in the GAC: v KD4SoapHandler v KD4WCFExtension v KD4dcAgent If.NET Framework 2.0 is installed, complete the following steps: 1. Go to the system_root\microsoft.net\framework\v \config directory. 2. Open the machine.config file. 3. Verify whether the following tags are displayed in the file: v <add type="com.ibm.management.soa.msnet.kd4soaphandler,kd4soapagent,version=7 group="1" priority="50" /> v <add name="kd4wcfextension" type="com.ibm.management.soa.msnet.kd4wcfextension, KD4wcfagent, Version= , Culture=neutral, PublicKeyToken=10a210f b4" />(If only.net Framework 2.0 is installed, this value will not be displayed in the file.) 4. If the 64-bit version of.net Framework 2.0 is installed, go to the system_root\microsoft.net\framework64\v \config directory and repeat steps 2 and 3. If.NET Framework version 4.0 is installed, complete the following steps: 1. Go to the system_root\microsoft.net\framework\v \config directory. 2. Open the machine.config file. 3. Verify whether the following tags are displayed in the file: v <add type="com.ibm.management.soa.msnet.kd4soaphandler,kd4soapagent,version=7 PublicKeyToken=10a210f b4" group="1" priority="50"/> v <add name="kd4wcfextension" type="com.ibm.management.soa.msnet.kd4wcfextension, KD4wcfagent, Version= , Culture=neutral, PublicKeyToken=10a210f b4"/> 4. If the 64-bit version of.net Framework 4.0 is installed, go to the system_root\microsoft.net\framework64\v \config directory and repeat steps 2 and 3. Chapter 4. Configuring.NET Data Collector 15

26 Table 5. Verification steps for registration of.net Data Collector components (continued) Component Name Location for verification Procedures to verify ISAPI Metabase.xml file (only for IIS 6) applicationhost.config file (only for IIS 7) 1. To open the Metabase.xml file, go to the system_root\system32\ inetsrv\ directory. 2. Open the Metabase.xml file. 3. Verify whether a tag that includes Location ="/LM/W3SVC/1/Filters/ IISDC" string is displayed. 1. To open the applicationhost.config file, go to the system_root\system32\inetsrv\config directory. 2. Open the applicationhost.config file. 3. Verify whether the following tags are displayed in the file: v <filter name="iisdc" path="$(candle_home)\ TMAITM6\K4\bin\iisdc_32.dll" enabled="true"/> v <filter name="iisdc64" path="$(candle_home)\ TMAITM6\K4\bin64\iisdc_64.dll" enabled="true" enablecache="true" precondition="classic,bitness64/> Profiler Environment Variable 1. On Windows desktop, right-click My Computer and the click Properties. 2. Complete one of the following steps: v On Windows 2003 system, click Advanced tab and then click Environment Variables. v On Windows 2008 system, click Advanced System Settings and then click Environment Variables. 3. Verify whether the COR_ENABLE_PROFILING variable is displayed and the value of the variable is Verify whether the COR_PROFILER variable is displayed and the value of the variable is { F-9CDC-40E8-B31C-F35DB9BD1F5D}. ADO Event Aggregation ADO Event Aggregation utility enables.net Data Collector to generate only one node for all the calls that are made to a database from an ASP.NET page. Event aggregation simplifies instance topology and reduces traffic to the Transaction Collector. The ADO Event Aggregation utility is enabled by default when you configure.net Data Collector. For information about disabling the ADO Event Aggregation utility, see Disabling ADO event aggregation utility. Disabling ADO event aggregation utility When ADO Event Aggregation utility is enabled, and only Profiler component is registered, nodes for the database calls are not seen in the topology. Therefore, if only Profiler component is enabled, you must preferably disable the ADO Event Aggregation utility. Procedure 1. Go to the CANDLE_HOME\TMAITM6\K4\config\ directory. 2. Open the dotnetdcconfig.properties.inactive file. 3. Change the value of ktj_adoaggregation.enabled to false. 16.NET Data Collector: User's Guide : Beta 1 draft

27 Chapter 5. Uninstalling.NET Data Collector When you uninstall.net Data Collector, all the components of.net Data Collector are automatically unregistered. Before you begin You must disable application pools filtering. For more information, see Disabling the application pools filtering on page 21. Procedure 1. On the computer where you installed the.net Data Collector, go to Start > Settings > Control Panel. v If you are uninstalling.net Data Collector on a Windows 2003 system, go to step 2. v If you are uninstalling.net Data Collector on a Windows 2008 system, go to step Click Add/Remove Programs, and then perform the following steps: a. Click IBM Tivoli Monitoring. b. Click.NET Data Collector, and then click Modify/Remove. 3. Click Programs and Features, and then perform the following steps: a. Click IBM Tivoli Monitoring. b. Click.NET Data Collector, and then click Modify/Remove. 4. Click Next and complete the following steps: a. Expand Tivoli Enterprise Monitoring Agents list and clear the.net Data Collector check box. a. Click Next. b. On the message window, click Next. A message window is displayed for each component that is registered with.net Data Collector. c. Click Next on each message window. 5. Click Finish to complete the uninstallation. All components of.net Data Collector are unregistered. Uninstalling.NET Data Collector if it is installed with ITCAM for SOA agent When.NET Data Collector and IBM Tivoli Composite Application Manager for SOA agent are installed on the same computer, you must manually uninstall.net Data Collector after uninstalling the IBM Tivoli Composite Application Manager for SOA agent. Procedure 1. Open the CANDLE_HOME\TMAITM6\K4\bin\config\dotNetDcConfig.properties.inactive file, and edit the value of the default.kd4.enabled key as follows: default.kd4.enabled=false 2. To activate the configuration change, run the configdc activateconfig command. 3. To register the ASMX/WCF SOAP handlers, complete one of the following steps: v For.NET tracking, run the confignetdc.bat command. v For.NET Data Collector, run the configdc registerdc command. Copyright IBM Corp. 2012,

28 18.NET Data Collector: User's Guide : Beta 1 draft

29 Chapter 6. Selective Filtering utility The Selective Filtering utility lists all the application pools on the IIS Server. With this utility, you can filter the application pools that you want the.net Data Collector to monitor. Prerequisites Before running the Selective Filtering utility, make sure that your environment meets the requirements for the IBM Tivoli Composite Application Manager for Microsoft Applications:.NET Data Collector. For information about requirements, see the Prerequisites topic for the NET Data Collector in the IBM Tivoli Composite Application Manager for Microsoft Applications Information Center ( welcome_msapps63.html). You must have local administrative privileges on the computer where you want to run the Selective Filtering utility, and that none of the applications update the environment variables while installing or using the Selective Filtering utility. Running the Selective Filtering utility The selective filtering utility is bundled with.net Data Collector V You can run the Selective Filtering utility by using the executable file that is located in the.net Data Collector installation directory. Before you begin Ensure that the SetApplicationPools.dll file is present in the GAC by completing the following steps: 1. Open the command prompt. 2. Change the directory to CANDLE_HOME\TMAITM6\K4\bin\Selective_Filtering\script. 3. Run the iis_version_script install command. 4. Browse to the CANDLE_HOME\TMAITM6\K4\logs directory. 5. Open the confignetdc.log file, and search for the string that begins with Selective Filtering status. Complete one of the following steps: v If the string includes value=disabled, repeat steps 3, 4, and 5. v If the string includes value=enabled, run the Selective Filtering utility. Procedure 1. On the computer where you want to run the Selective Filtering utility, browse to the CANDLE_HOME\TMAITM6\K4\bin\Selective_Filtering directory. 2. Double-click the SelectiveFiltering.exe file. Removing SetApplicationPools.dll file When you uninstall.net Data Collector, the SetApplicationPools.dll file is automatically removed from the GAC. If the file is not removed automatically, you must manually remove it from the GAC. Procedure 1. Open the command prompt. 2. Change the directory to CANDLE_HOME\TMAITM6\K4\bin\Selective_Filtering\script. Copyright IBM Corp. 2012,

30 3. Run the iis_version_script uninstall command. User interface elements of Selective Filtering utility The user interface of the Selective Filtering utility provides check boxes and buttons that enable you to perform tasks, such as enabling or disabling application pools filtering, selecting application pools for filtering, and so on. Table 6 lists the user interface elements of Selective Filtering utility. Table 6. Graphical user interface elements and their description User interface element Description Application Pools Lists the application pools that are present on the IIS Server. Select or clear an application pool name to filter the pool name. Fetch Application Pools Refreshes the list of application pools that is displayed in the Application pools area. Select All Selects all application pools for filtering. Clear All Excludes all application pools from being filtered. Invert Selection Inverts the selection of the application pools. Enable Filtering/Disable Filtering Toggles between enabling and disabling application pools filtering. If application pools filtering is enabled, Disable Filtering is displayed on the button. If application pools filtering is disabled, Enable Filtering is displayed on the button. The filtering of the application pools is disabled by default, when the Selective Filtering utility is run for the first time. Save Selected For Filtering Saves the selection of application pools for filtering. The Save Selected for Filtering button is disabled in one of the following conditions: v If selective filtering is disabled for application pools v If no changes are made in the selection of application pools for filtering Web Applications Under Selected Application Pools Remember: If you edit the list of application pools for filtering by clicking either Select All, Clear All, orinvert Selection buttons, you must save the selection by clicking the Save Selected for Filtering button. Lists all application pools that are selected for filtering. Expand the application pool name to view the list of web applications listed under the application pool. Note: On IIS 6, the metabase location of a web application is displayed as the name of the web application and on IIS 7, the path of a web application is displayed as the name of the web application. Using the Selective Filtering utility You can use the Selective Filtering utility to enable and disable application pools filtering. Enabling the application pools filtering You can filter the application pools that you do not want to be monitored by the.net Data Collector. 20.NET Data Collector: User's Guide : Beta 1 draft

31 Procedure 1. Open the user interface of Selective Filtering utility by double-clicking the SelectiveFiltering.exe file. 2. Click Fetch Application Pools. Application pools that are available for filtering are displayed in the Application Pools area. 3. Click Enable Filtering. Note: If application pools filtering is enabled, the Disable Filtering button is displayed. 4. In the Application Pools area, select the application pools that you want to filter. Note: v If you do not select application pools for filtering, and click Save Selected for Filtering, the Selective Filtering utility automatically disables the application pools filtering. v If you want to select all the application pools for filtering, click Select All, and then click Save Selected for Filtering. 5. Click Save Selected For Filtering. 6. Required: Reset the IIS Server by running the iisreset command. Disabling the application pools filtering This section contains the procedure for disabling application pools filtering. Procedure 1. Open the user interface of the Selective Filtering utility by double-clicking the SelectiveFiltering.exe file. 2. Click Disable Filtering. 3. Required: Reset the IIS Server by running the iisreset command. Removing environment variables After you disable the Selective Filtering utility, you must preferably remove the NETDCProfilerAttachFilterEnable environment variable before you uninstall or upgrade.net Data Collector. Procedure 1. On Windows desktop, click Start > Control Panel > System. The System Properties window opens. 2. Click the Advanced tab, and click Environment Variables. 3. Under System Variables, select the NETDCProfilerAttachFilterEnable variable, and click Delete. 4. Click OK. 5. Click OK to exit the System Properties window. 6. Restart IIS Server by completing the following steps: a. Click Start > Run, and enter the iisreset command. b. Click OK. Chapter 6. Selective Filtering utility 21

32 22.NET Data Collector: User's Guide : Beta 1 draft

33 Chapter 7..NET tracking data displayed in Transaction Tracking workspaces The.NET Data Collector sends the.net tracking data to the Transaction Collector. The Transaction Collector sends the.net tracking data to Transaction Reporter through Tivoli Enterprise Monitoring Server and the data is displayed in the Transaction Tracking workspaces. The transaction tracking data that is collected by.net Data Collector from the.net domains is displayed in the IBM Tivoli Composite Application Manager for Transactions workspaces. The Table 7 provides information about the data that is included in Servers, Components, Applications, and Transactions navigator items in IBM Tivoli Composite Application Manager for Transactions workspaces: Table 7. Transaction tracking data displayed in workspaces Scenarios monitored Data displayed in workspaces For ADO.NET that is monitored by.net profiler v Workspaces in the Servers navigator item display data about each Windows server that hosts the database. v Workspaces in the Components navigator item display data about each ADO.NET call that is identified by the name Microsoft.NET. v Workspaces in the Applications navigator item display the following data: Database server name, such as Oracle, SQL, and DB2 Database name Data source Connection string v Workspaces in the Transactions navigator item display the following data: Database name Data source Connection string For ASP.NET pages that are monitored by HTTP Module v Workspaces in Servers navigator item display data about each Windows server that hosts ASP.NET pages. v Workspaces in Components navigator item display data about each ASP.NET page that is identified by the name IIS. v Workspaces in Applications navigator item display data about the name of the application pool under which the ASP.NET website is hosted. v Workspaces in Transactions navigator item display the Internet Information Services server name on which the ASP.NET website is hosted. Copyright IBM Corp. 2012,

34 Table 7. Transaction tracking data displayed in workspaces (continued) Scenarios monitored Data displayed in workspaces For web services that are monitored by ASMX handlers v Workspaces in the Servers navigator item display data about each Windows server that hosts.net clients. v Workspaces in the Components navigator item display data about each web server that is identified by the name IIS. v Workspaces in the Applications navigator item display data about each application pool name. v Workspaces in the Transactions navigator item display data about the web service and the method name in the following format: WS:WebserviceName:MethodName For web services that are monitored by WCF handlers v Workspaces in the Servers navigator item display data about each Windows server that hosts.net clients. v Workspaces in the Components navigator item display data about each web service request (WCF) that is identified by the name IIS. If ASP.NET impersonation is disabled, the data is identified by the name Microsoft.NET. v Workspaces in the Applications navigator item display data about each application pool name. If ASP.NET impersonation is disabled, the data about w3wp is displayed in the workspaces. v Workspaces in the Transactions navigator item display data about the web service and the method name in the following format: WS:WebserviceName:MethodName Interpreting topologies The Transaction Reporter uses the aggregate and instance data that is tracked by the.net Data Collector, and displays the transaction topology at various levels of information. The topology diagrams help you to understand the transaction topologies in detail. A.NET transaction is a two-way (request-response) communication and depends on the characteristics of the service. In the following diagrams, a solid arrow pointing from the requester to the responder represents a two-way communication. The topology shows the transactions between the services and operations that are used on the servers. Examples of.net Data Collector in workspaces The following topology diagrams describe how.net Data Collector functions in the Components, Applications, and Transactions workspaces: 24.NET Data Collector: User's Guide : Beta 1 draft

35 Figure 1..NET Data Collector in the Component workspace Chapter 7..NET tracking data displayed in Transaction Tracking workspaces 25

36 Figure 2..NET Data Collector in the Applications workspace 26.NET Data Collector: User's Guide : Beta 1 draft