Configure Java Agent

Most agent operations are configured using properties in the IntroscopeAgent.profile file. This section describes the most common agent properties to set and post-installation information. More properties might be appropriate for your environment.
apmdevops106
Most agent operations are configured using properties in the IntroscopeAgent.profile file. This section describes the most common agent properties to set and post-installation information. More properties might be appropriate for your environment.
 
 Different versions of the agent might have different properties available for you to set or have different default values.
Configure the Connection to the Enterprise Manager
To report metrics, the agent must connect to an Enterprise Manager. The default communication settings enable an agent to connect to a local Enterprise Manager using port 5001. However, the agent and the Enterprise Manager do not typically reside on the same system. You can modify the default settings when you install the agent, or after installing the agent by modifying the IntroscopeAgent.profile.
Depending on your requirements, you can configure the communication between the agent and Enterprise Manager to use:
  • Direct socket connections
  • HTTP tunneling connections
  • HTTP tunneling through a proxy server
  • HTTP over Secure Sockets Layer connections (HTTPS)
  • Secure Socket Layer (SSL) connections
 
More Information:
 
Connect to the Enterprise Manager Using a Direct Socket Connection
The most common way for the agent to connect to the Enterprise Manager is through a direct socket connection. We recommend using a direct socket connection to the Enterprise Manager when possible. Use the following system properties to supply the URL of the Enterprise Manager, Collector, or MOM to which the agent should connect:
 
System property name
: agentManager.url.1
Abbreviated name
: agentManager
The fully qualified system property name takes precedence over the abbreviated name. You can specify the fully qualified name on the Java command line or in the agent profile. The abbreviated name is an alias for the first connection entry 
agentManager.url.1
 (refer to “Specifying one or more managers in the agent profile”). The abbreviated form should only be used on the JVM command line. The property value is a URL.
The 
serverHostOrIP
 value can be either an IP address (IPv4 or IPv6), a host name, or a fully qualified domain name. Provide the optimal value for your environment. In all cases, the port must be specified as part of the property because no default is inferred.
 
Follow these steps:
 
  1. Open the IntroscopeAgent.profile in a text editor.
  2. Locate the 
    agentManager.url.1 property
    . Specify the host name or IP address and the Enterprise Manager default listening port to which the agent connects. For example:
    agentManager.url.1=sfcollect01:5001
    If you use a cluster with more than one Enterprise Manager, be sure to specify the MOM. The MOM then assigns the agent to a Collector.
  3. (Optional) Specify one or more backup Enterprise Managers for the agent to connect to in case the primary Enterprise Manager connection is lost.
  4. Save and close the IntroscopeAgent.profile file.
Direct TCP connection
To use a direct TCP connection, specify either of the following formats. The 
agentManager=serverHostOrIP:Port
 format assumes the 
tcp:// prefix
 for the namespace.
agentManager=serverHostOrIP:Port
agentManager=tcp://serverHostOrIP:Port
Connect to the Enterprise Manager with HTTP Tunneling
If a direct socket connection to the Enterprise Manager is not feasible, you can configure agents to connect to an Enterprise Manager over HTTP. This configuration allows communication to pass through firewalls that only permit HTTP traffic.
You can configure agents to send information using tunneling technology, enabling agents to connect to an Enterprise Manager remotely. In this case, you must configure the agent to connect to the Enterprise Manager embedded web server, where the HTTP tunneling web service is hosted.
HTTP tunneling imposes more CPU and memory overhead on the application server and Enterprise Manager than a direct socket connection.
 
Follow these steps:
 
  1. Open the IntroscopeAgent.profile in a text editor.
  2. Set the 
    agentManager.url.1
     property to the host name or the IP address of the Enterprise Manager to which the agent connects by default. Follow the host name or IP address with a colon and the HTTP listening port of the Enterprise Manager embedded web server. For example:
    agentManager.url.1=http://webhost:8081
    Ensure that the port number matches the 
    introscope.enterprisemanager.webserver.port
     property value in  the <
    EM_Hom
    e>/config/IntroscopeEnterpriseManager.properties file. The default port value is 8081.
  3. (Optional) Specify one or more backup Enterprise Managers for the agent to connect to in case the connection to the primary Enterprise Manager is lost.
  4. Save and close the IntroscopeAgent.profile file.
Configure a Proxy Server for HTTP Tunneling
You can configure the HTTP tunneled agent to connect through a proxy server to the Enterprise Manager. This configuration is necessary for a forwarding proxy server. You make this configuration when the agent is running behind a firewall that only allows outbound HTTP traffic routing through the proxy server.
The proxy server configuration properties apply only if the agent is configured to tunnel over HTTP. The proxy server configuration applies to any configured HTTP tunneled connection on the agent, not to a single connection. Consider this configuration carefully when configuring failover between multiple Enterprise Managers when the connection to each Enterprise Manager is over HTTP.
  • HTTP/1.1 is required to enable agent HTTP tunneling. In addition, the proxy server must support HTTP Post.
  • If the proxy is not reachable, the agent bypasses the proxy and the agent makes a direct connection with the Enterprise Manager. If the proxy is reachable but its authentication fails, the agent keeps retrying to connect to the Enterprise Manager through the proxy.
 
Follow these steps:
 
  1. Open the IntroscopeAgent.profile in a text editor.
  2. Set the
     
     
    agentManager.httpProxy.host
     property to the host name or IP address of the proxy server.
  3. Set the 
    agentManager.httpProxy.port
     property to the port number of the proxy server.
  4. (Optional) If the proxy server requires user credentials for authentication, carry out one of the following options.
    • To use clear text authentication, set the following properties:
      agentManager.httpProxy.username=<user_name>
      agentManager.httpProxy.password=<user_password>
    • To encrypt the password, follow these steps:
      1. Access the encryption tool from wily\tools\PropertiesUtil.jar.
      2. Run the tool using the following command
        java -jar <
        directory path
        >\wily\tools\PropertiesUtil.jar encrypt <user_password>
        The encrypted password is provided. 
      3. In the IntroscopeAgent.profile file, set the following properties:
        agentManager.httpProxy.username=<user_name>
        agentManager.httpProxy.password=<encrypted_password>
  5. Save and close the IntroscopeAgent.profile.
Connect to the Enterprise Manager with HTTPS Tunneling
The agent can connect to the Enterprise Manager using HTTP over Secure Sockets Layer (SSL) by configuring properties in the 
IntroscopeAgent.profile
 file.
 
Follow these steps:
 
  1. Open the IntroscopeAgent.profile in a text editor.
  2. Set the 
    agentManager.url.1
     property to the either of these settings: Specify the host name or the IP address of the target Enterprise Manager. Follow the host name or IP address with a colon and the Enterprise Manager embedded web server HTTPS listening port. For example: 
    agentManager.url.1=https://172.31.255.255:8444
  3. (Optional) Specify one or more backup Enterprise Managers for the agent to connect to in case the connection to the primary Enterprise Manager is lost.
  4. Save and close the IntroscopeAgent.profile.
Connect to the Enterprise Manager over SSL
If you are using direct Secure Socket Layer (SSL) connections, you can configure the agent communication with the Enterprise Manager using SSL without HTTP tunneling. Previously, you must have enabled an SSL server socket on the Enterprise Manager. See Configure Enterprise Manager Communications for more information.
 
Follow these steps:
 
  1. Open the IntroscopeAgent.profile in a text editor.
  2. Configure the agent to connect to the Enterprise Manager SSL listening port using an SSL socket factory.
  3. Set the 
    agentManager.url.1
     property to the host name or IP address of the target Enterprise Manager. Follow the host name or IP address with a colon and the Enterprise Manager SSL listening port. For example:
    agentManager.url.1=ssl://172.31.255.255:443
  4. Configure the agent to authenticate the Enterprise Manager.
    1. Uncomment the 
      agentManager.trustStore.1
       
       
      property. 
    2. Set 
      agentManager.trustStore.1
       to the trustStore location containing the Enterprise Manager certificate.
      If you do not specify a trustStore, the agent trusts all certificates. You can specify an absolute path or a path relative to the agent profile. For example:
      agentManager.trustStore.1=/certs
  5. When needed, set the 
    agentManager.trustStorePassword.1
     property to specify the trustStore password.
  6. If the Enterprise Manager requires client authentication, set the 
    agentManager.keyStore.1
     property to the location of a keyStore containing the agent certificate. You can specify an absolute path or a path relative to the agent profile. On Windows, backslashes must be escaped. For example:
    agentManager.keyStore.1=C:\\keystore
  7. Set the 
    agentManager.keyStorePassword.1
     property to the keyStore password, if needed.
  8. Set the 
    agentManager.cipherSuites.1
     property.
    You can define other allowed cipher suites by adding a property with an increased suffix number. For example, 
    agentManager.cipherSuites.2
     and so on.
    If you do not specify a value for this property, the default cipher suites are used.
  9. (Optional) Specify one or more backup Enterprise Managers for the agent to connect to, in case the connection to the primary Enterprise Manager is lost.
  10. Save and close the IntroscopeAgent.profile.
Configure the agentManager.url.1 Property as a JVM Argument
You can have a single agent configuration for all of your application servers.
Follow these steps:
 
  1. Set the agentManager.url.1 property as a JVM argument.
    You can have a single configuration instead of a custom configuration for a single server as shown in this example:
    -d agentManager.url.1=<momhostname>:5001
  2. Comment out the agentManager.url.1=localhost:5001 in the agent profile.
Configure Agent Connection Metrics
By default, metrics are reported about the connection status of agents that are connected to an Enterprise Manager. You can monitor agent connection metrics to determine the current state of the connection between an agent and the Enterprise Manager.
Agent connection metrics appear in the Investigator under the Enterprise Manager process (the custom metric host):
Custom Metric Host (Virtual)|Custom Metric Process(Virtual)|Custom Metric Agent (Virtual) (*SuperDomain*)|Agents|<HostName>|<Agent Process Name>|<Agent Name>|ConnectionStatus
Connection metrics have these values:
  • 0 -- No data about the agent is available
  • 1 -- agent is connected
  • 2 -- agent is slow to report
  • 3 -- agent is disconnected
As with other events, users can query for agent disconnects using the historical query interface. Agent disconnect events are part of the data that are used in assessing application health. The health metrics display in the WebView and Workstation Overview tabs.
After an agent disconnects from the Enterprise Manager, the agent continues to generate disconnected state metrics until the agent is timed out. When an agent times out, no additional connection metrics are generated or reported to the Enterprise Manager.
You can also configure how long the Enterprise Manager tracks an agent during a specific period. The period is from when the agent disconnects until the Enterprise Manager unmounts the agent.
 
Example 1
 
You set the agent connection time-out to one day (1440 minutes).
When an agent disconnects from Enterprise Manager, the agent connection status metric changes to 3 (disconnected). After 1440 minutes, the Enterprise Manage stops reporting status for that agent. The metric does not show any value because nothing is being reported.
 
Example 2
 
You set the agent connection time-out to one day (1440 minutes) and the agent unmount delay to a day and a half (2160 minutes).
When an agent disconnects from Enterprise Manager, the agent connection status metric changes to 3 (disconnected). After 1440 minutes, the Enterprise Manage stops reporting status for that agent. The metric does not show any value because nothing is being reported. The Enterprise Manager continues to track the agent for 12 hours (720 minutes) before unmounting the agent. After 12 hours, the Enterprise Manager also releases the resources that are associated with tracking the agent.
 
Follow these steps:
 
  1. Open the IntroscopeEnterpriseManager.properties file in the 
    <EM_Home>/
    config directory.
  2. (Optional) Configure how long the Enterprise Manager continues to track an agent after a temporary disconnection.
     Be sure the
    introscope.enterprisemanager.autoUnmountDelayInMinutes
    value is greater than or equal to the
    introscope.enterprisemanager.agentconnection.metrics.agentTimeoutInMinutes
    value.
  3. Save IntroscopeEnterpriseManager.properties.
  4. Restart the Enterprise Manager.
Configure Backup Enterprise Managers and Failover Properties
When you install the agent, you specify the Enterprise Manager host name and port number that the agent connects to by default. Optionally, you can also specify one or more backup Enterprise Managers. If the agent loses the connection to its primary Enterprise Manager, it can then attempt to connect to a backup Enterprise Manager.
To enable an agent to connect to a backup Enterprise Manager, specify the communication properties for the Enterprise Managers in the agent profile.
 
Follow these steps:
 
  1. Open the Introscope.Agent.profile file in a text editor.
  2. Specify one or more alternative Enterprise Manager communication channels by adding the following properties to the agent profile. For example, to create two backup Enterprise Managers:
    agentManager.url.2=paris:5001
    agentManager.url.3=voyager:5002
    The connection order is automatically determined by the number in the suffix. If the primary Enterprise Manager (agentManager.url.1) is not available, the agent tries to connect to the next Enterprise Manager (agentManager.url.2). If the agent does not connect with its first backup Enterprise Manager, it tries the next Enterprise Manager (agentManager.url.3).
    The process continues trying to connect to each Enterprise Manager, in order, until the connection succeeds. If the agent is unable to connect to any of its Enterprise Managers, the agent waits 10 seconds before retrying.
  3. Save the changes and close the IntroscopeAgent.profile file.
  4. Restart the application.
Enable and Use More Garbage Collection Metrics
Garbage collection (GC) and memory management can have a significant effect on an applications performance. The basic GC Heap metrics are available by default. You can enable optional metrics to provide more details about garbage collection processing and memory pool usage. These additional metrics display under the GC Monitor node in the Investigator when enabled. The GC Monitor metrics report information to help you optimize memory pool allocation and garbage collection processing. You typically enable these metrics when developing or testing applications, or when researching application performance issues. Usually, the metrics are not used for real-time application management in a production environment and are disabled by default.
When the 
introscope.agent.gcmonitor.enable
 property is set to true (default), you can view details about the Garbage Collectors and Memory Pools for the JVM you are monitoring.
 
More information
CPU Utilization Metrics 
Configure Agent Load Balancing
In clusters where the workload is primarily agent-reported metrics, you can optimize the overall cluster capacity by configuring MOM agent load balancing.
Heap Sizing
The agent uses some of the application server Java heap memory to store collected data. You can view the application server GC heap usage in the metric browser tab GC Heap overview.
The following information applies to the heap usage:
  • For a highly utilized heap, you might need to increase the heap allocation when you install the agent.
  • If you plan to collect large numbers of transaction traces, increase the JVM heap size.
 If you are operating a high-performance CA APM environment, contact CA Services for the appropriate agent JVM heap settings.