Skip to content
CA Application Performance Management - 10.3
Documentation powered by DocOps

Configure SOA-Specific Properties

Last update May 25, 2017

You can customize SOA Performance Management (SPM) using the following configuration properties:

Configure the Name Displayed for Web Services

By default, web service nodes are named using the web service namespace. The web service namespace is similar to its URL. For example, if a web service uses the following URL:

http://ClearingHouse.demobank.ca.com

its node is displayed like this by default:

http_//ClearingHouse.demobank.ca.com

Optionally, you can configure the agent to use the web service endpoint as the node name. The web service endpoint includes additional information, such as the server name and port number for the service. For example, if you choose to display the web service endpoint for the ClearingHouse.demobank.ca.com web service, its node in the Investigator might look like this:

http_localhost_8383_demobank_services_ClearingHouseService

You can change the name displayed by editing the agent’s webservices.pbd file and specifying whether you want to use {namespace} or {servicename}. In most cases, the namespace is the most recognizable name to display in the Investigator and the SOA Dependency Map. You can, however, use the service endpoint if you edit the webservices.pbd file and the IntroscopeAgent.profile file.

Note: In this release, the WCF web services client-side nameformatter does not support {servicename}. In addition, the optional configuration steps for replacing {namespace} with {servicename} does not apply to the WCF web service metric configuration.

To use the service endpoint as the node name in the Investigator and Dependency Map:

  1. Open the webservices.pbd file in the <Agent_Home> directory.
  2. Search for and replace all instances of {namespace} with {servicename}.
    Because it is included in tracers as part of the fully-qualified metric name, there are many occurrences of the {namespace} string in the file.
  3. Save the webservices.pbd file.
  4. Open the appmap-soa.pbd file in the <Agent_Home> directory.
  5. Search for and replace all instances of {namespace} with {servicename}.
  6. Save the appmap-soa.pbd file.
  7. Restart the application server.
    After you restart the application server, the Investigator tree and SOA Dependency Map display the web service endpoint name rather than namespace.
    If you are using the service endpoint name instead of the namespace, you may also want to change the Namespace labels displayed on the Client and Server Overview tabs.

To change the label used in the client and server Overview tabs:

  1. Open the ws.overview.tv.xml file in the <EM_Home>/ext/xmltv/ directory.
  2. Search for and replace all instances of Namespaces with Services.
  3. Save the ws.overview.tv.xml file.
  4. Restart the Enterprise Manager.
    After you restart the Enterprise Manager, the Overview tab displays the Services label when you select the WebServices, Client, or Server node in the Investigator tree.

To use the metric naming convention from Web Services Manager 7.0.x:

  1. Open the IntroscopeAgent.profile file in the <Agent_Home> directory.
  2. Add the com.wily.introscope.agent.soa.metricNameFormatting property to the file.
  3. Set the com.wily.introscope.agent.soa.metricNameFormatting property as follows:

    com.wily.introscope.agent.soa.metricNameFormatting=/:
    

    This setting replaces the slash (/) and colon (:) characters with an underscore (_) character in metric names. With this setting, http://CheckingAccount/demobank.ca.com is displayed as http_CheckingAccount_demobank.ca.com.

  4. Save the IntroscopeAgent.profile file.
  5. Restart the application server.
    After you restart the application server, the Investigator tree and SOA Dependency Map display the web service endpoint name rather than namespace.

Configure Correlated Tracing

Cross-process transaction tracing requires the agent to insert a correlation identifier that can be passed from one process to another. The agent can insert this correlation identifier into either a SOAP or HTTP header.

Because most services use SOAP messaging, the correlation identifiers are inserted and read from SOAP headers by default. In certain situations, however, you may prefer to pass the correlation identifier using HTTP headers. For example, in rare cases, adding the correlation identifier to the SOAP header can cause the message to be rejected because the correlation ID changes the SOAP payload.

Depending on how your applications process SOAP messages and how you have implemented security, you can choose whether to pass the correlation ID in the HTTP header or the SOAP header by modifying the IntroscopeAgent.profile file.

There are four agent configuration properties that control the handling of the correlation identifier on the client and the server. With these properties, you can specify whether the identifier should be inserted into the SOAP header, the HTTP header, both header protocols, or not inserted at all. These properties start with the standard agent prefix com.wily.introscope.agent:

  • soapheaderinsertion.enabled
    Enables the client to insert the correlation identifier in the SOAP header.
    • Set the property to true to allow the client to use the SOAP header.
    • Set the property to false if you want to prevent the client from inserting correlation identifier in the SOAP header.
    By default, this property is set to true.
  • httpheaderinsertion.enabled
    Enables the client to insert the correlation identifier in the HTTP header.
    • Set this property to true to allow the client to use the HTTP header.
    • Set this property to false if you want to prevent the client from inserting correlation identifier in the HTTP header.
    By default, this property is set to false.
  • soapheaderread.enabled
    Enables the server to read the correlation identifier from the SOAP header.
    • Set this property to true to allow the server to use the SOAP header.
    • Set this property to false if you want to prevent the server from reading the SOAP header.
    By default, this property is set to true.
  • httpheaderread.enabled
    Enables the server to read the correlation identifier from the HTTP header.
    • Set this property to true to allow the server to use the HTTP header.
    • Set this property to false if you want to prevent the server from reading the HTTP header.
    By default, this property is set to false.

Configure Properties for Clients and Servers

You can set these properties to enable or disable specific behavior on an agent-by-agent basis. For example, if a server processes messages from both SOAP- and HTTP-based services, you may want to configure the agent on that server to read the correlation ID in either type of header, but prevent the agent from inserting the identifier in the SOAP header:

com.wily.introscope.agent.soapheaderread.enabled=true
com.wily.introscope.agent.httpheaderread.enabled=true
com.wily.introscope.agent.soapheaderinsertion.enabled=false
com.wily.introscope.agent.httpheaderinsertion.enabled=true

With these settings, the local computer can read the correlation identifier from a SOAP header sent to it by other agents, but it can only insert the correlation identifier in the HTTP header. To enable tracing, however, you should keep in mind that the web service client and server must insert and read correlation identifiers from the same type of header. For example, if you configure clients to insert the correlation identifier in the HTTP header, you must configure the server to read the identifier from HTTP headers.

Disable Correlated Tracing

If you want to disable the insertion of the correlation identifier for both SOAP and HTTP and turn off cross-process transaction tracing, you can set all four properties to false. For example:

com.wily.introscope.agent.soapheaderread.enabled=false
com.wily.introscope.agent.httpheaderread.enabled=false
com.wily.introscope.agent.soapheaderinsertion.enabled=false
com.wily.introscope.agent.httpheaderinsertion.enabled=false

Before modifying these properties, you should keep in mind that the SOA Dependency Map and cross-process transaction tracing require correlation identifiers to be passed from one process to another.

If you disable correlated tracing by setting these properties to false, the SOA Dependency Map cannot display dependencies properly and dependency metrics cannot be collected accurately, and transaction traces may be incomplete.

Configure the Insertion Point for SOAP Handlers

You can use configuration properties in the IntroscopeAgent.profile file to control where the SOAP handler is inserted in the SOAP handler chain. These properties provide flexibility for applications that include encryption or require signature verification against the original SOAP message, so that the insertion of the SOAP header does not interfere with the application’s validation of the SOAP message.

Client and Server Properties for Inserting the SOAP Handler

For application servers that use SOAP handlers, the following configuration properties let you control the SPM SOAP header:

  • soa.client.prependhandler
    Enables the SOAP header to be inserted first or last in the SOAP handler chain on the client.
    • Set the property to true to insert SOAP header by the first handler in the SOAP handler chain.
    • Set the property to false if you want the SOAP header appended by the last handler in the SOAP handler chain.
    By default, this property is set to true.
  • soa.server.appendhandler
    Enables the SOAP header to be read first or last in the SOAP handler chain on the server.
    • Set this property to true to have the SOAP header read by the last handler in the SOAP handler chain.
    • Set this property to false if you want the SOAP header read by the first handler in the SOAP handler chain, and then removed.
    By default, this property is set to true.

Change the Default Order for SOAP Handlers

By default, the first handler in the handler chain on the client inserts the SOAP header and the last handler in the chain on the server reads the header. For some applications, you may need to modify the default behavior to verify the proper passing of an SPM SOAP header and the original SOAP message. For example, if an application must verify the signature of a SOAP message, you may need to modify the default behavior.

To illustrate why you would change the default property settings, consider an application in which the first handler in the chain inserts the SOAP header. The SOAP message is then signed in the second handler. When the message is received on the server, the first handler attempts to verify the signature. Because the SPM SOAP header has been inserted but not yet read and removed, the signature fails and the message is rejected.

The configuration properties let you change the default behavior so that the first handler in the chain reads the SPM SOAP header, and then removes it. This setup allows the next handler in the chain to verify the signature against the original SOAP message. For example:

com.wily.introscope.agent.soa.client.prependhandler=true
com.wily.introscope.agent.soa.server.appendhandler=false

Although the default property settings are appropriate in most environments, these configuration properties give you flexibility in adapting SOA Performance Management to different application scenarios.

Configure Limits for the SOA Dependency Map

The dependency map data stored on the Enterprise Manager typically represents all of the dependencies across discovered applications, providing a complete model of the service-oriented architecture you have deployed. In a very large or complex SOA environment, however, a full representation of all SOA components and their dependencies may affect the performance and operation of the Enterprise Manager itself.

To prevent the dependency map from affecting the performance of the Enterprise Manager, there are configuration properties that limit the size and complexity of the map. By default, these configuration properties limit the dependency map to a maximum of 5000 nodes and a maximum of 25000 dependencies (a ratio of 5 dependency relationships per node).

You can set the following Enterprise Manager configuration properties in the IntroscopeEnterpriseManager.properties file to control these limits:

  • dependencymap.max.vertices
    Sets the maximum number of nodes for which dependency data can be stored on standalone or Collector Enterprise Manager.
    By default, this property is set to 5000.
  • dependencymap.max.edge.ratio
    Set the maximum ratio of dependency relationships to nodes to control the overall complexity of the dependency data that can be stored on a standalone or Collector Enterprise Manager.
    By default, this property is set to 5.

For most organizations, the SOA network requires fewer than 5000 components and a typical dependency ratio is 1 or 2 dependencies per component. The default settings, therefore, allow for greater size and complexity than most organizations need. In rare cases, however, you may want to modify the default values. For example, you may want to modify the properties:

  • to increase the size and complexity allowed for the dependency map if the default values do not accommodate your SOA environment. You should consider how the changes may affect performance of the Enterprise Manager.
  • to intentionally restrict the size and complexity of the dependency map if your SOA environment does not require as many nodes and dependencies as the default values allow. You should consider whether any changes may cause the SOA dependency map model to be unnecessarily incomplete.

For example, to modify the properties to store data for fewer nodes but more dependency relationships per node:

com.wily.introscope.soa.dependencymap.max.vertices=2000
com.wily.introscope.soa.dependencymap.max.edge.ratio=8

Configure SPM Compatibility With JAX-WS 2.2.6 or Higher

Newer versions of JAX-WS (2.2.6 or higher) expect usage of com.sun.xml.ws.transport.Headers instead of java.util.HashMap. To avoid a ClassCastException when your application makes a webservice call, uncomment the following configuration property in the IntroscopeAgent.profile file:

com.wily.introscope.agent.soa.JAXWSHeadersClassName=com.sun.xml.ws.transport.Headers

This change does not have any impact on cross-process or cross-JVM transaction tracing. It will also not break the old functionality. If the application has two JAX-WS implementations for different features of the application, both will work when this property is enabled.

Was this helpful?

Please log in to post comments.