12 Installing Observer Libraries for WCF

This help topic provides instructions for installing, uninstalling, and upgrading observer libraries for monitoring WCF 3.5 services. The observer requires that you have the .NET 3.5 Framework installed on your machine. This observer monitors only IIS-hosted, WCF Services.

The Observer Distribution File

The Business Transaction Management observers are distributed by way of ZIP files. Each ZIP file contains one type of observer that is suitable for installation into a particular application server. The ZIP file containing the observer for monitoring WCF 3.5 services is BTMObserver_Iis_6-7_Wcf35_*.zip.

Note:

In the complete ZIP file name, the asterisk (*) is replaced with the observer version number.

Installing the Observer Libraries for WCF 3.5

Locate the observer distribution ZIP file for WCF (BTMObserver_Iis_6-7_Wcf35_*.zip).
Unpack the ZIP file into a temporary directory (referred to henceforth as observer_temp).

Unpacking the ZIP file creates a nanoagent directory containing two subdirectories—config and lib.
Use gacutil.exe to copy all of the DLL files from observer_temp\nanoagent\lib to the global application cache (GAC; normally located at C:\WINDOWS\assembly).
Configure the observer into your applications by editing the application configuration file as follows:

Caution:
Make a backup copy before editing your application configuration file.

To monitor all WCF applications running on the machine, edit the machine.config file (see Editing the machine.config File).

To monitor one or more specific web applications, edit the web.config file appropriate for each web application (see Editing the web.config File).

Ensure that the version numbers of the AmberPoint assemblies in the GAC match the version number in your application configuration file, for example:

Description of the illustration gac.gif

<soapExtensionTypes>
  <add type="AmberPoint.NanoAgent.DotNet.AspNet.Handlers.SoapExtensionHandler,
   AmberPoint.NanoAgentToolkit, Version=64000.64000.23409.20080,
   Culture=neutral,
   PublicKeyToken=d8685c0afbb35893" priority="1" group="0" />
</soapExtensionTypes>

The version numbers must match for the assemblies to be found.

In your application configuration file, set the value of the AmberPoint:NanoConfigURL key to the URL of the monitor to which you want the observer to forward messages.

Use the following form, replacing Host:Port with the host name and port number of the monitor:
```
<add key="AmberPoint:NanoConfigURL" value="http://Host:Port/btmmonitor/agent/agent"/>
```
This key associates the observer with the monitor whose URL you specify in the key. At startup, the observer retrieves its configuration from the specified monitor and begins sending observations to the monitor.

As an alternative to setting the monitor URL in the AmberPoint:NanoConfigURL key, you can create an environment variable named AP_NANO_CONFIG_URL and use it to set the monitor URL.
Notes:
If you are using replicated monitors, you must set the host and port portion of the URL to the host and port of your load balancer's HTTP virtual server. For example, if the HTTP virtual server's IP address is 10.147.46.152, and its port number is 5072, then you would set the URL to:
```
http://10.147.46.152:5072/btmmonitor/agent/agent/
```
For more information about the load balancer's HTTP virtual server, see Configuring Your Load Balancer.
Also in your application configuration file, set the value of the AmberPoint:NanoLogBaseDir key to the location in which you want error logs created. Specify the location as an absolute path. If you want the directory created in case it doesn't exist, set the value of the AmberPoint:NanoCreateLogBaseDir key to true. For example:
```
<add key="AmberPoint:NanoLogBaseDir" value="C:/Inetpub/AmberPoint"/>
<add key="AmberPoint:NanoCreateLogBaseDir" value="true"/>
```
The AmberPoint:NanoLogBaseDir key does not have a default value. If it is set to null, log files will not be generated.

In order for the observer to generate the log files, ensure that the user under which the observer is running has permission to write to the log directory. The observer runs as the following user:
- IIS 5.x – the observer user is ASPNET
- IIS 6.x and 7.x – the observer user is NETWORK SERVICE
For information about configuring error logging, see Chapter 14, "Logging Observer Errors and Debugging Information."
Ensure that the monitor to which your observer forwards messages has an Observer Communication policy applied to it.

For information on applying an Observer Communication policy, see Applying an Observer Communication Policy.

Editing the machine.config File

Caution:

Make a backup copy before editing your machine.config file.

To monitor all WCF applications running on the machine, edit the machine.config file. This file is typically located at C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\CONFIG.

An annotated example of a machine.config file is provided at observer_temp\nanoagent\config\Machine.config.part. Use this file as a guide in making your edits.

Editing the web.config File

Caution:

Make a backup copy before editing your web.config file.

You can monitor all web applications or only specific web applications depending on which web.config file you edit. For example, if you want to monitor all the applications installed in the web site, edit the web.config file located in the web site's home directory. If you want to monitor only specific web applications, edit the web.config file located in the directories of those specific applications.

An annotated example of a web.config file is provided at observer_temp\nanoagent\config\Web.config.part. Use this file as a guide in making your edits.

Uninstalling the Observer Libraries for WCF 3.5

Delete the apobserver.configuration file from the location specified in your application configuration file as the value of the AmberPoint:NanoConfig key.

Your application configuration file is either machine.config or web.config.
Revert your application configuration file to the state it was in before you installed the observer.

The observer distribution file (BTMObserver_Iis_6-7_Wcf35_*.zip) contains annotated examples of application configuration files that explain how to edit an application configuration file to insert the observer. You can also use these as a guide in reverting your application configuration file.

If you need to revert your machine.config file, use the config\Machine.config.part file as a guide. If you need to revert your web.config file, use the config\Web.config.part file as a guide.
Remove the observer DLLs from the GAC (unless they are being used by another observer on the machine).

The name of each observer DLL begins with the string “AmberPoint”. To remove a DLL, right-click it and choose Uninstall.

Note:
The observer for ASP.NET uses many of the same DLLs as the observer for WCF. If you have the observer for ASP.NET installed on the machine, you must not remove the DLLs that are being used by it.