SOA-Specific Agent Configuration Properties

SOA agent properties are stored in the agent profile, IntroscopeAgent.profile. The profile is a text file of property names and values. The agent searches for the agent profile as follows:
apmdevops106
Understanding where agent properties are located
SOA agent properties are stored in the agent profile,
IntroscopeAgent.profile
. The profile is a text file of property names and values. The agent searches for the agent profile as follows:
  • In the location specified by the
    com.wily.introscope.agentProfile
    system property.
  • If the
    com.wily.introscope.agentProfile
    property is not set, the agent uses the
    IntroscopeAgent.profile
    file.
In most cases, the application server the agent monitors must be restarted before changes to agent properties take effect.
You can configure the following agent properties that are specific to SOA Performance Management (SPM):
2
Configure Agent Properties
Agent properties enable you to control the behavior and operation of the agent and customize settings to suit your environment. SOA Performance Management includes several SOA-specific agent properties with default settings. Before you can use any of these properties, you add the property name to the
IntroscopeAgent.profile
file and set a valid value for the property.
Follow these steps:
  1. Open the IntroscopeAgent.profile file in a text editor.
  2. Identify the property you want to add to the
    IntroscopeAgent.profile
    file from the list of SOA-specific agent properties.
  3. Type the full name of the property, including the
    com.wily.introscope
    prefix, in a SOA-specific section of the
    IntroscopeAgent.profile
    file. For example:
    ########################################### # SOA Performance Management Agent Settings # ========================================= com.wily.introscope.agent.httpheaderread.enabled
  4. Set the property value, as needed. For example:
    com.wily.introscope.agent.httpheaderread.enabled=true
  5. Save and close the
    IntroscopeAgent.profile
    file.
    After you add a property to the
    IntroscopeAgent.profile
    file, you can change the property value as necessary.
About SOA-Specific Agent Properties
You can set the following SOA-specific properties in the IntroscopeAgent.profile. All of the properties start with the com.wily.introscope prefix, but are listed without the prefix for readability.
For information about other agent properties, see the
Java Agent
or the
NET Agent
.
In most cases, changing an agent property requires that you restart the application server for the property change to take effect.
agent.httpheaderinsertion.enabled
Enables or disables the insertion of client-side correlation identifiers in HTTP headers.
This property is not supported for SAP NetWeaver.
Property settings
The property can be set to true or false:
  • True - Adds client-side correlation and dependency information to the HTTP header.
  • False - Disallows changes to the HTTP header for client-side correlation and dependency information.
Default
False
If you enable CA APM for Oracle Service Bus, CA APM for TIBCO BusinessWorks, or CA APM for webMethods Integration Server, the default value is True.
Example
com.wily.introscope.agent.httpheaderinsertion.enabled=true
Notes
You must restart the managed application before changes to this property take effect.
agent.httpheaderread.enabled
Enables or disables the server-side retrieval of correlation identifiers from HTTP headers.
This property is not supported for SAP NetWeaver.
Property settings
The property can be set to true or false:
  • True - Reads server-side correlation and dependency information from the HTTP header.
  • False - Does not check the HTTP header for correlation and dependency information.
Default
False
If you enable CA APM for Oracle Service Bus, CA APM for TIBCO BusinessWorks, or CA APM for webMethods Integration Server, the default value is True.
Example
com.wily.introscope.agent.httpheaderread.enabled=true
Notes
You must restart the managed application before changes to this property take effect.
agent.soapheaderinsertion.enabled
Enables or disables the insertion of client-side correlation identifiers in SOAP headers.
The SOA Dependency Map and cross-process transaction tracing require correlation identifiers to be passed from one process to another. The agent can insert this correlation identifier into either a SOAP or HTTP header.
You should set the property to false if your SOAP-based applications do not work properly due to unexpected header entries. If you set this property to false and do not enable the insertion of correlation identifiers in the HTTP header, you cannot display related information in the SOA Dependency Map or cross-process transaction traces.
Property settings
The property can be set to true or false:
  • True - Adds client-side correlation and dependency information to the SOAP header.
  • False - Disallows changes to the SOAP header for client-side correlation and dependency information.
Default
True
Example
com.wily.introscope.agent.soapheaderinsertion.enabled=true
Notes
You must restart the managed application before changes to this property take effect.
agent.soapheaderread.enabled
Enables or disables the server-side retrieval of correlation identifiers from SOAP headers.
Property settings
The property can be set to true or false:
  • True - Reads server-side correlation and dependency information from the SOAP header.
  • False - Does not check the SOAP header for correlation and dependency information.
Default
True
Example
com.wily.introscope.agent.soapheaderread.enabled=true
Notes
You must restart the managed application before changes to this property take effect.
agent.soa.metricNameFormatting
Replaces any denoted character or characters in SPM metric names with the underscore character [_].
For example, setting the property com.wily.introscope.agent.soa.metricNameFormatting to replace the forward slash (/) causes the URL http://CheckingAccount/demobank.ca.com to be displayed as:
http_CheckingAccount_demobank.ca.com
Set this property if you want to substitute specified characters with an underscore (_) in the metric name.
You may want to make this substitution to display metric names in the format used in some Web Services Manager. In this case, you must also replace namespace with servicename in the webservices.pbd file. These changes result in SPM metric names displaying in the Investigator tree and SOA Dependency Map using service name rather than namespace.
Property settings
The property can be set to one or more characters you want to be replaced with the underscore (_) character in metric names.
If property is not defined or has no value, no character substitution takes place.
Default
None
Example
com.wily.introscope.agent.soa.metricNameFormatting=/:
Notes
You must restart the managed application before changes to this property take effect.
agent.transactiontrace.boundaryTracing.cacheFlushFrequency
Specifies the number of days to hold dependency data in the agent memory before flushing the cache. You can set this property to periodically flush idle threads and clear the agent cache. At the end of the period specified, a cache flush results in the SOA Dependency Map dependency data being removed in the agent. The agent then rediscovers the dependency data and forward the data to the Enterprise Manager to refresh the information displayed on the SOA Dependency Map.
By default, previously discovered dependencies are held in the agent cache for 30 days to prevent the agent from sending information about known dependencies to the Enterprise Manager unnecessarily. In most cases, 30 days is an acceptable period because dependency data is fairly static and storing the previously discovered dependencies in the agent cache reduces the data the agent must transmits to the Enterprise Manager at regular intervals.
If a running agent loses the connection to a standalone Enterprise Manager or fails over to a new Enterprise Manager in a non-clustered (no MOM) environment, you can set this property to 1 to flush the agent cache in one day. Setting the property to 1 removes the known dependencies from the cache and forces the agent to rediscover those dependencies so it can send the data to the new Enterprise Manager.
Property settings
The property can be set to any whole integer greater than zero.
Default
30 days
Example
com.wily.introscope.agent.transactiontrace.boundaryTracing.cacheFlushFrequency=1
Notes
Changes to this property take effect immediately and do not require the managed application server to be restarted.
agent.transactiontrace.boundaryTracing.enable
Enables or disables transaction trace boundary traces. Boundary traces must be enabled if you want to display information in the SOA Dependency Map. If you are not using the SOA Dependency map, you can disable this property to reduce overhead.
Boundary traces are sent from the agent cache at a specific size to avoid overhead issues.
Property settings
The property can be set to true or false:
  • True - Collects Transaction Trace boundary trace information required for the SOA Dependency Map and sends it to the Enterprise Manager.
  • False - Does not collect Transaction Trace boundary trace information required for the SOA Dependency Map.
Default
True
Example
com.wily.introscope.agent.transactiontrace.boundaryTracing.enable=true
Notes
You must restart the managed application before changes to this property take effect.
soa.client.prependhandler
Controls the insertion point of the SPM SOAP header on the client-side. By default, the first handler in the SOAP handler chain inserts the SPM SOAP header. Depending on how applications process SOAP messages, you can use this property to have the SOAP header inserted first or last in the SOAP handler chain.
This property is only applicable for application servers that use SOAP handlers and depends on the SOAP engine and API being used. For example, this property can be used when the application server runs older versions of WebLogic or WebSphere, or the application server runs SAP NetWeaver. The property is not applicable if you are using Apache Axis, Apache CXF, native JBoss, WebLogic 10.x (JAX-WS), WebSphere 7.0 (JAX-WS), or .NET or Spring web service.
Property settings
You can set the property to true or false:
  • True -- Inserts the SOAP header using the first handler in the SOAP handler chain.
  • False -- Appends the SOAP header using the last handler in the SOAP handler chain.
Default
True
Example
com.wily.introscope.soa.client.prependhandler=true
Notes
You must restart the managed application before changes to this property take effect.
soa.server.appendhandler
Controls the retrieval and removal of the SPM SOAP header on the server-side. By default, the last handler in the SOAP handler chain reads the SPM SOAP header. Depending on how applications process SOAP messages, you can use this property to have the SOAP header read and removed first or last in the SOAP handler chain.
This property is only applicable for application servers that use SOAP handlers and depends on the SOAP engine and API being used. For example, this property can be used when the application server runs older versions of WebLogic or WebSphere, or the application server runs SAP NetWeaver. The property is not applicable if you are using Apache Axis, Apache CXF, native JBoss, WebLogic 10.x (JAX-WS), WebSphere 7.0 (JAX-WS), or .NET or Spring web service.
Property settings
You can set the property to true or false:
  • True -- Reads the SPM SOAP header using the last handler in the SOAP handler chain, and then removes it.
  • False -- Reads the SPM SOAP header using the first handler in the SOAP handler chain, and then removes it.
Default
True
Example
com.wily.introscope.soa.server.appendhandler=false
Notes
You must restart the managed application before changes to this property take effect.
com.wily.soa.dependencyarray.maxsize
Clamps the SOA Dependency Map edges collected on the Agent side to avoid unexpected memory overhead.
Property settings
You can set the property to the default value or specify a value greater than the default value.
Default
1000
Recommended value
Default value or greater
Example
com.wily.soa.dependencyarray.maxsize=1000