Configuring the monitoring agent

You can run the monitoring agent with the default settings, or you can configure various aspects such as the port to use to communicate with the Health Center client, or which connection mode to use. You usually configure the agent by setting properties in a properties file. For Java™ applications, you can also set properties on the command line when you start the agent or attach the agent to a running application. If you are using IBM® Bluemix®, you cannot configure the agent that is provided as part of the Bluemix runtime environments.

The agent properties are listed and described in Health Center configuration properties.

For instructions on setting agent properties for Node.js applications, see the documentation for the Node Application Metrics module. The rest of this topic applies to Java applications only.

Setting agent properties for Java applications

You can set Health Center agent properties in the following ways:

As system properties in the Health Center properties file, healthcenter.properties. This file is in the jre/lib directory of the JVM that contains the agent.
On the command line when you start the agent:
- As system properties that you set by using the -D option of the Java command. For example -Dcom.ibm.java.diagnostics.healthcenter.agent.port=1999.
- As part of the -Xhealthcenter option of the Java command, when you start the agent and the application to be monitored at the same time. This method is available only in Java 5 SR10 and later and Java 6 SR5 and later, and only for some system properties. Use the following format:
```
 -Xhealthcenter: option (=|:) value [, option (=|:) value ] 
```
  You can specify any number of properties. For example -Xhealthcenter:port=1999 or -Xhealthcenter:port:1999,level:full.
- As parameters of the Java command that you use to attach the agent to a JVM that is already running. This method is available only for some system properties; the available set is the same as for the -Xhealthcenter method. Use the following format:
```
[option (=|:) value [, option (=|:) value]]
```
  You can specify any number of options, and any number of option strings. For example:
```
port:1999,transport=jrmp
```
For more information about starting the agent, see Starting the monitoring agent.

For more information about the available properties, see Health Center configuration properties.

Order of precedence

When you set agent properties you can use multiple methods in combination. For example, if you are attaching an agent to a JVM that is already running, you might complete the following steps:

Set the port number system property in the property file to 1998
```
com.ibm.java.diagnostics.healthcenter.agent.port=1998
```
Start the application to be monitored, and specify a port number system property of 1985:
```
java -Dcom.ibm.java.diagnostics.healthcenter.agent.port=1985 MyMainClass
```
The JVM that runs the application becomes the target JVM.

Attach the agent to the target JVM, and specify two further port numbers:

java -jar healthcenter.jar port=1999 -Dcom.ibm.java.diagnostics.healthcenter.agent.port=1992

The following list shows the decreasing order of precedence of Health Center properties when you attach an agent to a JVM that is already running. This JVM is known as the target JVM to distinguish it from the JVM that runs the attach program:

Properties that you supply as parameters to the program that attaches the agent to the target JVM (port=1999 in the previous example).
System properties that you supply as parameters to the attach program by using the -D option (com.ibm.java.diagnostics.healthcenter.agent.port=1992 in the previous example).
System properties that you set by using the -D option when you start the target VM (com.ibm.java.diagnostics.healthcenter.agent.port=1985 in the previous example).
The contents of the healthcenter.properties file of the target JVM (com.ibm.java.diagnostics.healthcenter.agent.port=1998 in the previous example).

The following list shows the decreasing order of precedence of Health Center properties when you start the agent at the same time as the Java application:

Properties that you set by using the -Xhealthcenter option (Java 5 SR10 and later, and Java 6 SR5 and later).
System properties that you set by using the -D option.
The contents of the healthcenter.properties file.

Health Center agent configuration of JVM system properties

From Health Center Version 2, the Health Center agent sets the system properties of the JVM to which it is attached, according to the options that are in use by the agent. These values overwrite any existing values. For example, the port number that the agent uses might be different from the port number that you specify by using any of the methods listed previously. By default (JMX connection), the agent uses your specified port number as the first port to try to connect to. If the connection fails, the agent tries to connect to the next port number. The agent can scan up to 100 port numbers in an attempt to connect. When a connection is made, the com.ibm.java.diagnostics.healthcenter.agent.port system property in the JVM is set to the number of the connected port.

When you attach an agent to a JVM that is already running, any Health Center properties that you specify when you attach the agent are set in the target JVM, overwriting existing properties in that JVM. For example, you might start the target JVM by starting the Java application with a Health Center system property:

java -jar -Dcom.ibm.java.diagnostics.healthcenter.data.collection.level=off MyApplication

If you specify a different value for this property when you attach the agent, the previous system property is overwritten:

java -jar healthcenter.jar -Dcom.ibm.java.diagnostics.healthcenter.data.collection.level=headless

If there are any other properties in the healthcenter.properties file, these properties are also loaded as system properties in the target JVM.