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
- 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:
You can specify any number of properties. For example-Xhealthcenter: option (=|:) value [, option (=|:) value ]
-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:
You can specify any number of options, and any number of option strings. For example:[option (=|:) value [, option (=|:) value]]
port:1999,transport=jrmp
For more information about starting the agent, see Starting the monitoring agent.
- As system properties that you set by using the
Order of precedence
- 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:
The JVM that runs the application becomes the target JVM.java -Dcom.ibm.java.diagnostics.healthcenter.agent.port=1985 MyMainClass
- 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
- 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).
- 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.
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.