Starting the monitoring agent

You start the monitoring agent from the command line, but the method depends on your runtime environment. You usually start the agent at the same time as you start your application. From Health Center Version 2, you can also start the agent when the Java™ application is already running. If you are using IBM® Bluemix®, you do not need to start the agent. If you are using WebSphere® Application Server, WebSphere Integration Developer or Rational® Application Developer, you must configure those products to start the Health Center agent.

Before you begin

The monitoring agent must be installed. See Installing a Health Center monitoring agent for more information. You can optionally configure the monitoring agent, see Configuring the monitoring agent, either before starting the agent or, for Java applications only, when you start it as part of this task.

If you have a firewall between the Health Center client and agent, ensure that the relevant ports are open. For more information about the Health Center properties that specify a port, see Health Center configuration properties.

If you are using a WebSphere or Rational product, see Configuring WebSphere or Rational product environments (Java applications only) for information about configuring those products to start the Health Center agent.

About this task

For information on how to start the agent with a Node.js application, see the documentation for the Node Application Metrics module. The rest of this topic applies to Java applications only.


  • To start the Health Center agent at the same time as a Java application, add one of the following options to the Java command that you use to start the application. The option that you use depends on your version of IBM SDK, Java Technology Edition:
    Version 7 and later, Version 6 service refresh 5 and later, and Version 5 service refresh 10 and later
    • If you are using the agent that is provided in the Java SDK installation directory, or an updated agent that you installed to that location:
      -Xhealthcenter[: property(=|:)value, property(=|:)value]
    • If you are using an updated agent that you installed outside the Java SDK installation directory:
      -Xbootclasspath/p:agent_install_path/internal_file_path/healthcenter.jar -agentpath:agent_install_dir/internal_file_path/
      The paths are as follows:
      • agent_install_path: The directory in which you installed the agent.
      • internal_file_path: The location of the associated Health Center file within the agent installation directory. This path might vary depending on your operating system. Look in your agent installation directory to determine the correct values.
      For example, on z/OS® the command might be as follows:
      -Xbootclasspath/p:/home/hclatest/lib/ext/healthcenter.jar -agentpath:/home/hclatest/lib/s390x/
      In this example, agent_install_path is /home/hclatest, and within that directory, the path to healthcenter.jar is lib/ext/, and the path to is lib/s390x/.
    Version 6 service refreshes 1 through 4, and Version 5 service refreshes 8 and 9
    -agentlib:healthcenter -Xtrace:output=perfmon.out
    You can optionally set agent configuration properties as part of the command. For more information, see Configuring the monitoring agent and Health Center configuration properties.
    Note: As with other Java applications, you can use the IBM_JAVA_OPTIONS environment variable to store the Health Center command-line option and configuration properties, so that you do not have to specify them when you start your application. For example: set IBM_JAVA_OPTIONS="-Xhealthcenter:port=1999". For more information about this variable, see the documentation for your version of IBM SDK, Java Technology Edition.
    Command examples:
    java -agentlib:healthcenter -Xtrace:output=perfmon.out HelloWorld
    java -Xhealthcenter -classpath tmp/myproject/myarchive.jar MyMainClass
    java -Xhealthcenter:port=1965,level=headless HelloWorld
    java -Xhealthcenter -agentpath:"C:\agent\jre\bin\healthcenter.dll" -cp C:\agent\jre\lib\ext\healthcenter.jar"C:\agent\jre\lib\" -Djava.ext.dirs="C:\agent\jre\lib\ext"
    If the agent starts successfully, a series of messages is displayed which lists the port for the Health Center agent. For example:
    Feb 11, 2015 11:17:42 AM <init>
    INFO: Agent version ""
    Feb 11, 2015 11:17:43 AM createJMXConnector
    INFO: IIOP will be listening on the next available system assigned port.
    Use to specify a port
    Feb 11, 2015 11:17:43 AM startAgent
    INFO: Health Center agent started on port 1978.

    The port number is also stored in the healthcenter. pid.log file in your temporary directory, where pid is the process ID of the agent that is listening on that port.

  • To start the Health Center agent after a Java application is already started, run a program to attach the agent to the JVM that is running the application. Follow the instructions in Starting the Health Center agent after starting an application (Java applications only).
  • To start the Health Center agent in the WebSphere or Rational products listed previously, see Configuring WebSphere or Rational product environments (Java applications only).

What to do next

After you start the agent, you can use the Health Center client or API to connect to and monitor the application on the port number displayed in the result message. See Connecting an application to the Health Center client and Using the Health Center API for more information. If you specified headless mode, the port number is not used, and the agent saves the collected data to a file. If you specified inprocess mode, you must use the Health Center API to connect to the agent. See Monitoring a running application and Configuring the monitoring agent for more information.

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