Java Agent Naming

This section has information about agent naming, related environmental and deployment considerations, and options for automatically naming your agents.
This section has information about agent naming, related environmental and deployment considerations, and options for automatically naming your agents.
Understanding the Java Agent name
Each Java Agent running in your Introscope environment has a name, whether you assigned one explicitly, configured a method of automatically assigning a name, or simply started an instrumented application that the Java Agent monitors. The Java Agent name is central to many views in the Introscope Workstation and Investigator, and it is key to the process of associating monitoring logic with target applications.
When an agent report metrics to an Enterprise Manager, a node is created for that agent in the Investigator tree. When you configure management logic in the Workstation -- for instance, Dashboards, Alerts, and Actions -- the agent name is a component in the regular expressions that identify the applications to which the management logic applies. The Investigator tree below shows agents named
, running on host
qw32vtest01 u
nder the WebLogic process.
The Investigator tree displays the agent for each host under the SuperDomain.
How the Agent Determines its Name
The Java Agent uses the following sequence to determine a name:
  1. If the Java Agent determines a name using the first method, it accepts that name and connects to the Enterprise Manager.
  2. If the Java Agent does not determine a name using the first method, it tries the second method, and so on.
  3. If the Java Agent does not determine a name using any method, it names itself "UnnamedAgent."
Method 1 Agent Name Specified in a Java System Property Using the Full Property Name
The agent name is defined using a Java system property on the command line. Using this method will override any other agent naming method.
To specify an agent name using Java system property, on the Java command line, supply the desired name using this property:
Method 2 Agent Name Specified in a Java System Property Using a Shortcut
Instead of the full, canonical form of the property, you can use a shortcut version. We recommend this simplified method because of its ease of use. Still, the full form described under Method 1 above takes precedence over the shortcut form.
On the Java command line, supply the desired agent name using this shortcut form of the property:
Method 3 Agent Name Specified in a System Property Key in the IntroscopeAgent.profile
This method is the second the agent uses to look for its name. Use this method if you want the agent to be named from the value of an existing Java system property specified in the
Follow these steps:
  1. Open the
  2. Under the Agent Name section, specify the Java system property that will provide the agent name in this property:
    If the Java system property specified here does not exist, this property will be ignored.
  3. Restart the application server.
Method 4 Agent Name Obtained Automatically from the Application Server
If you use certain versions of WebLogic or WebSphere, the agent name can be automatically obtained from the application server using automatic agent naming functionality. This eliminates the need to configure individual agent names in a separate agent profile file. The agent can also rename itself if there are changes in the application server environment. This enables you to deploy an agent profile across a large number of environments that might consist of a mix of application server platforms.
You can configure a time delay, to give the agent as much time as necessary to determine its name before connecting to the Enterprise Manager.
Automatic agent naming is supported when you use Introscope with these supported application server versions:
  • JBoss
  • WebLogic
  • WebSphere distributed
The name of the application server displayed in the Workstation is determined by a Java J2EE API. This sometimes causes the name of the application servers to display differently in the Workstation because all application servers implement the API differently. The names of multiple application servers may be formatted differently in the Workstation, and even the same application server name may be formatted differently from release to release.
Method 5 Agent Name Specified Explicitly in the Agent Profile
The agent name is defined in the
, in the property
. This was the standard method for naming agents in early Introscope versions. Use this option if you already have an agent profile for every application.
Method 6 Agent Name Determined to be "Unknown agent"
If the agent is unable to determine a name using one of the methods listed above, then the agent names itself "UnnamedAgent".
Agent Naming Considerations for Clustered Applications
If you run multiple instances of the same application, Introscope attempts to resolve identical agent names,
custom metric agents, by appending the agent name with a character and a random number. CA Technologies recommends, however, that you tell Introscope how to resolve the naming.
The options for resolving identical agent naming are:
Automatic Agent Naming
When automatic agent naming is enabled, the agent starts and looks for name information from the application server. The agent waits until an agent name is obtained before attempting to connect to the Enterprise Manager.
When the agent locates naming information, Introscope edits the information to make the agent name compliant with agent naming rules.
When information is obtained, segments are separated by forward slashes. For example: medrec/MyCluster/MedRecServer
Any forward slashes in the segment name are converted to underscores. For example, if a Domain is named Petstore/West, it is converted to Petstore_West.
Introscope edits the information that is used to construct the agent name according to the following rules:
  • characters such as pipes, colons, or percentage signs are replaced with underscores
  • names that begin with any character other than a letter are prepended with the letter "A"
  • empty names are replaced with "UnnamedAgent" to distinguish them from the "UnknownAgent" condition
To enable automatic agent naming
  1. In the
    , set
  2. Make the following application server-specific changes:
    • For JBoss, edit the IntroscopeAgent.profile and the standalone.xml files. See JBoss for more information.
Automatic Agent Naming and Renamed Agents
Using automatic agent naming, the agent always tries to obtain the most current application-server-specific agent name. The agent periodically checks for a new name.
If a change to the application server configuration results in an agent name change, the agent automatically renames itself. In the Investigator tree, the agent appears to disconnect. The disconnected agent remains in the Investigator tree, and unmounts automatically after the unmount time period has elapsed, or can be unmounted manually.
The renamed agent reconnects to the Enterprise Manager and appears in the Investigator tree. The agent logs these changes.
Advanced Automatic Agent Naming Options
There are several properties you can change to control automatic agent naming for your environment.
Initial Enterprise Manager Connection Delay
When using the automatic agent naming feature, the agent waits up to a configurable amount of time before connecting to the Enterprise Manager while trying to find agent name information. The default delay is 120 seconds.
Follow these steps:
  1. Open the
  2. Under the Agent Name section, configure the desired delay in the property
  3. Restart the application server.
The delay value has been configured.
Agent Rename Check Interval
When using the automatic agent naming feature, the agent periodically checks to see if the naming information from the application server has changed. The default interval is ten minutes.
To change this interval
  1. Open the
  2. Under the Agent Name section, configure the desired interval in the
  3. Restart the application server.
Turning Off Agent Log File Automatic Naming
By default, when the agent name is found automatically, either by information provided by a Java system property or application server, the log files associated with that agent are named automatically using that same information. However, you can turn off this automatic log naming, and continue to use the agent log name specified in the
Follow these steps:
  1. Open the I
  2. Set the property,
    , to a value of
  3. Save the I
  4. Restart the application server.
Enabling Cloned Agent Naming in Clustered Environments
If two agents exist with the same name monitoring the same host and process and are not uniquely named by a user, the name is appended with a number. Cloned agent naming enables you to correlate an agent with a particular application instance in a clustered application.
You are running cloned agents if you:
  • are running agents that share a host, process, or Java Agent name with one or more other agents, or
  • are running two or more agents that are using the same agent profile.
Follow these steps:
  1. Stop your managed application and the Java Agent.
  2. Open the
    and set the following property to true:
  3. Save the
  4. Restart your managed application and the Java Agent.
Cloned agent naming example
With the Java Agent cloning property turned on, if you have four Java Agents, all named
, the Enterprise Manager names the agents
. If
disconnects and then reconnects, it will still use
as its name. With this naming, you will never have more Java Agent names in the database than the number of Java Agents originally cloned.
Configure Unique Names for Application Instances
If you monitor multiple instances of an application on the same machine, you can configure unique agent names explicitly.
To configure unique agent names
  1. Create a separate agent profile for each application.
  2. Uniquely name each agent in the agent profile.
  3. Specify which agent profile each application should use.
How Introscope Resolves Agent Naming Conflicts
The fully qualified agent name -- comprised of host name, process name and agent name -- is typically unique to each agent in an Introscope environment. Agents with the same agent name usually have a unique
agent name because their host name and process names are likely to be different. Multiple agents will have the same fully-qualified agent name only if they reside on the same host, monitor the same process, and have the same agent name.
If an agent tries to connect to an Enterprise Manager to which an agent with the same fully-qualified agent name is already connected, the Enterprise Manager appends a unique identifier to the name of the newly connecting agent. The identifier consists of a percent (%) character and a digit. This mechanism ensures that multiple agents that connect using the same fully-qualified name can be uniquely identified for the duration of the connection. The Enterprise Manager renames the first duplicate agent to connect by appending "%1" to its agent name.
For instance, assume that two agents with the fully qualified agent name:
connect to the Enterprise Manager, one after the other. The Enterprise Manager renames the second agent:
If other agents with the same fully qualified name connect, they are renamed, in succession,
, and so on, where the digit following the percent character is the next number in sequence.
When a renamed agent disconnects, the suffix it was assigned can be re-used. For example, if
disconnects while
remains connected, the next agent with the fully qualified name
to connect will be renamed
Reuse of the suffix identifier makes it possible that the Enterprise Manager might assign the same suffix to a particular agent’s name from connection to connection. However, on subsequent connections, a given agent could just as well be renamed differently. Having an agent’s name vary from connection to connection is problematic when querying historical data -- it is preferable to configure a naming strategy that avoids the Enterprise Manager renaming agents.
Application Triage Map and the Agent Name
Valid for CA APM 10.7 on-premise. The application triage map in the Workstation uses the agent name as part of several unique identifiers when defining the front- and backends of applications, as well as for storing information about application components in Introscope databases. If agent names change some aspects of the application triage map may also change. For example, during initial registration of an agent, the Enterprise Manager may assign a duplicated agent name a unique name by appending
%<sequence number>
to the agent name (e.g.
). If parts of the application triage map are relying on the duplicated agent name for information, aspects of the map could change.
While this does not affect the proper functioning of either the agent or the Enterprise Manager, it may reduce the overall capacity of your system; as such, CA Technologies recommends users be aware of the naming conventions employed in their Introscope environments. Users may want to designate specific agent names to sidestep this issue.
Name Abbreviation
The Agent supports abbreviated names to simplify configuration. Abbreviated names can be used for the agent profile, the agent name, the manager name and advanced properties. For example:
The agent profile is located by the agent using the following Java system property names from the JVM launch command parameters.
System property name
: introscope.agent.agentProfile
Abbreviated name
: agentProfile
The fully qualified system property name takes precedence over the abbreviated name.
java -javaagent=C:/path/to/tomcat/wily/Agent.jar -Dintroscope.agent.agentProfile=C:/path/to/IntroscopeAgent.profile
java -javaagent=C:/path/to/tomcat/wily/Agent.jar -DagentProfile=C:/path/to/IntroscopeAgent.profile