Resolving Discovery Issues

The simplest reasons for not being able to observe a service are the following:

  • Traffic has not run long enough or diversely enough for Business Transaction Management to see a service. The solution here is to run more traffic and attempt to traverse all possible branches.

  • The probe responsible for observing the service has not been activated. To check, select Administration > Observers from the Navigator and make sure that the probe appropriate for the type of service you are trying to discover is active. If it is not, edit the observer communication policy to activate it. By default all probes are activated except for the JAVA probe. To enable it, you must configure it with the names of the specific Java classes you want to observe.

More complicated issues arise in determining whether services are replicates. In the process of discovering and representing services and endpoints appropriately, Business Transaction Management needs to figure out whether a copy of a service represents a valid replicate and, conversely, whether services whose WSDL definitions are not identical actually implement the same interface. It makes these decisions by comparing the WSDLs it discovers and by following the criteria defined by the system service versioning policy. In addition, there might be cases where you might want to separate or merge different versions of a service because of ownership or accounting issues. Business Transaction Management provides commands and tools that you can use to resolve replication and duplication problems, and to resolve cases where it cannot guess your needs or intent.

This section summarizes some of these issues and introduces the commands you use to deal with them. You can also resolve some discovery problems by using the Disambiguate endpoints tool, which you access from the management console. This section includes the following topics:

Modifying the Service Versioning Policy

By default, the service versioning policy sets guidelines for how Business Transaction Management should deal with new or changed WSDLs:

  • It treats two endpoints as part of the same service version if their qualified service names, port type names, and port definitions match.

  • When it discovers a WSDL defining a distinct version of an existing service, it creates a new service version based on the host and port of the endpoint location being registered.

  • When it re-reads a WSDL, if the qualified name of a service changes, it replaces the previous endpoints, consequently losing all measurements.

It might be possible to forestall discovery problems by editing the default service versioning policy to make these criteria more or less restrictive. If modifying the policy does not suffice, there are a number of CLI commands as well as a tool you can access from the console that you can use to correct discovery results. For additional

To edit the default service versioning policy

  1. In the Navigator, select Administration > System Policies.

  2. Double click the Service Versioning Policy item in the summary area to display the current versioning policy in the detail area.

  3. Select Edit Definition for Service Versioning Policy from the Modify menu.

  4. Make the desired changes and click Apply.

Resolving Replication Issues

If you deploy a service in multiple containers, Business Transaction Management is able to understand that the same service is referenced by all the endpoints and that all endpoints share one interface. Consequently, it is able to aggregate statistics for the replicates at the service level and it allows you to define message properties on operations shared by all endpoints in the service.

For two endpoints to be treated as replicates of the same service, the following is required:

  • The WSDLs for the two services have the same qualified name (target name space and a simple name)

  • The endpoints implement the same interface

There are cases however where this information is not sufficient to make a determination, and you might have to teach the system whether two endpoints are the same or different. In each of the following cases, you will be alerted to take some action:

  1. In a development environment, multiple versions of the same service might be created that are incompatible. If Business Transaction Management sees a version that looks different from what it has seen before, it will treat it as a different version. If these differences are not important, you can run the mergeServices command to merge two versions into one.

  2. Due to a rolling upgrade, parallel versions might need to coexist temporarily until all servers are upgraded. In this case, Business Transaction Management will not generate a new service version, but it will generate an alert and allow you to move upgraded endpoints to a new service version if needed. This might be the case if existing policies are not compatible with the upgraded version. You can use the moveEndpoints command to move upgraded endpoints to a new service version. By the time the upgrade is done, all endpoints will wind up in the new service version.

  3. Due to a failed or incomplete upgrade, a version skew arises that was not intended but results in two different versions of the services. You can choose to merge the two versions or separate them.

  4. When a side-by-side upgrade results in the deployment of a new version of the application with an updated interface at new endpoint locations, Business Transaction Management will generate a new service version by default. You can accept this or merge the new version with the older version to retain the service history.

  5. Two sets of WSDLs that identify the same service would normally be treated as replicates, but because different instances of the service are used by different departments in different ways, you might need to divide the endpoints between service versions manually (moveEndpoints). In this case Business Transaction Management will generate an alert if new replicated endpoints are discovered, to allow you to determine which service version they belong to.

  6. There are cases where deploying an updated version of a service causes Business Transaction Management to delete the older version. If you wish to keep the measurements associated with the older version, you can use the moveMeasurements command to move the measurements from the older to the newer version.

Resolving Duplication Issues

Business Transaction Management attempts to resolve issues that arise as the result of changes to a machine name or to a container's listening address, or the use of multiple aliases for the same host name, without assistance from you. If the system guesses incorrectly how to handle such conditions, the most common symptom is the discovery of duplicate services or endpoints where in reality only one exists. You can use the commands listed in the following table to help the system avoid or resolve duplication problems.

The parts to be used as WSDL, service, or endpoint identifiers are as follows (with respect to the following example):

The base address is

The node is

The path is Bookmart/Credit/CreditService?wsdl

Generally, using the removeDuplicateEndpoint (or addBaseAddressAlias) command accomplishes everything you need to do. That is, the duplicate item is removed and the appropriate alias is defined so that duplication does not recur. But note that otherwise, all alias corrections made using the commands listed below are forward looking: they do not delete duplicates that have already been mistakenly created.

Command Balancing command Description
addBaseAddressAlias removeBaseAddressAlias Teaches the system to recognize that two base addresses are the same. This prevents duplicate endpoints from being discovered.
addNodeAlias removeNodeAlias Teaches the system to recognize that two node addresses are the same.
addPathAlias removePathAlias Teaches the system to recognize that two paths are the same for a given endpoint or WSDL address.
listNodeAliases None Lists current node aliases.
removeDuplicateEndpoint None The system has discovered two endpoints with the same path but different host names. Executing this command removes the duplicate and also adds the missing alias to make sure that future discoveries do not result in recreating the duplicate endpoint.
removeNode None Removes all information about the node and its aliases. Removing a node is not something you would normally need to do unless aliases for different machines have gotten so mixed up that you face the choice of pruning nodes or reinstalling the system.

Another apparent duplication might result when two endpoints share the same URL and are given the same port name in the WSDL that describes them. By default the port name is used as the friendly name. Although the system does not require friendly names to be unique, you will have to specify the endpoint URL (and possibly other characteristics) instead of its friendly name in any command that requires you to reference a unique endpoint. You can use the renameEndpoint command (or just pick the desired endpoint and modify its friendly name in its Profile tab) to distinguish the endpoints from one another.

Using the Console to Disambiguate Endpoints

You can use the Disambiguate Endpoints tool (from the console) to do the following:

  • Merge services: merge the source service into the specified target service

  • Move an endpoint: move the source endpoint to an existing or to a new service

  • Remove a duplicate endpoint: remove the source endpoint that is a duplicate of a target endpoint

To use the Disambiguate Endpoints tool:

  1. Select the source service or endpoint and choose Admin > Disambiguate Endpoints. The Disambiguate Endpoints tool is displayed in the console. The tool consists of three main areas: an area that compares the source and target, an area that lists available actions, and an area that allows you to preview the effect of your actions before you choose to execute them.

    The source drop list includes all possible sources, based on an internal evaluation of duplication in the system. The service or endpoint shown at the top is the one you selected when you opened the tool. You can choose another if you like.

    The target drop list includes all possible targets, given the items you have chosen for source.

    Below the drop lists is shown basic information for the selected source and target. Icons (equal/does not equal) indicate whether elements of the source and target are the same. To view differences in the WSDL's listed, click on the link to display WSDL contents.

  2. Use the drop lists to select the source and target.

    If you want to create a new service as the target service, click the New Service check box and specify the name and version of the service. You might do this if you want to move the source endpoint to a service that does not yet exist.

  3. The action part of the Disambiguate Endpoints tool shows you the possible actions you can take based on the selected source and target.

    Click the enabled action. If the desired action is not enabled, you might have to change your target or select Create New Service. For detailed information about the effect of each of these actions, please look up its command line equivalent: mergeServices, removeDuplicateEndpoint, or moveEndpoints. The use cases that require these actions are described above

  4. After you select an action, the effects of your action are shown in the Preview area.If the results shown are what you intended, click the OK button to execute the chosen action.