Starting a Java application with the Health Center agent enabled

There are two ways to activate the Health Center agent when your Java™ application is started. There are additional considerations for specific WebSphere® or Rational® products.

Prerequisite

The Health Center agent must be installed. See Installing the Health Center agent for more information.

Procedure

To monitor an application, the Health Center agent must be enabled when the JVM is started. There are two ways to do this:
  1. Start Java from the command line using the appropriate Health Center option, which is described in full in the Platform requirements section.
    For example, with Java 5 SR9 and earlier, or Java 6 SR4 and earlier, use:
    java -agentlib:healthcenter -Xtrace:output=perfmon.out -classpath my/class/path.jar MyMainClass
    For Java 5 SR10 and later, or Java 6 SR5 and later, use:
    java -Xhealthcenter -classpath my/class/path.jar MyMainClass
  2. Use the IBM_JAVA_OPTIONS environment variable to set the Health Center agent option before running your Java command. For example, on Microsoft® Windows®, with Java 5 SR9 and earlier, or Java 6 SR4 and earlier, enter the following command:
    set IBM_JAVA_OPTIONS="-agentlib:healthcenter -Xtrace:output=perfmon.out"
    For Java 5 SR10 and later, or Java 6 SR5 and later, type:
    set IBM_JAVA_OPTIONS="-Xhealthcenter"
    When the option is set you can start Java.
After the JVM is started with the agent enabled, you see a message detailing the port for the Health Center agent. For example:
05-Mar-2009 09:49:57 com.ibm.java.diagnostics.healthcenter.agent.mbean.HCLaunchMBean startAgent
INFO: Health Center agent started on port 1972.

The port number is also written to the healthcenter.<pid>.log file in the users temporary directory. The <pid> is the process ID for the agent that is listening on that port.

To enable the Health Center agent when a JVM is started in a WebSphere or Rational product environment, see Configuring WebSphere or Rational product environments.

Changing the listening port

By default, the Health Center agent uses port 1972 for its communications. If it cannot use port 1972, it increments the port number and tries again, for up to 100 attempts. You can override the first port number that the agent tries to use.

If you are using a JVM level that provides the -Xhealthcenter option (described in the Platform requirements section), you can specify the port as a command-line option. For example:
java -Xhealthcenter:port=<port_number> HelloWorld
Otherwise, use the com.ibm.java.diagnostics.healthcenter.agent.port command-line option. For example:
java -agentlib:healthcenter -Xtrace:output=perfmon.out -Dcom.ibm.java.diagnostics.healthcenter.agent.port=<port_number> HelloWorld
To change the port permanently, edit the following line in the healthcenter.properties file.
com.ibm.java.diagnostics.healthcenter.agent.port
This file is in the jre/lib directory of the JVM containing the agent.

Starting the Health Center agent without a client connection

From Health Center V1.2, you can start the agent without a client connection in place. The agent waits for a client connection with no impact on the application that is running. When the client connects to the agent, data collection starts. To configure an agent to start in this mode, edit the following line in the healthcenter.properties file, and change the value to off.
com.ibm.java.diagnostics.healthcenter.data.collection.level
This file is in the jre/lib directory of the JVM containing the agent.

For more information about troubleshooting problems with the Health Center agent, see Cannot connect to an application.



© Copyright IBM Corporation 2005, 2010. All Rights Reserved.
© Copyright Sun Microsystems, Inc. 1997, 2007, 901 San Antonio Rd., Palo Alto, CA 94303 USA. All rights reserved.
US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
This information center is powered by Eclipse technology. (http://www.eclipse.org/)