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.

• 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/libhealthcenter.so=path=agent_install_dir

    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/libhealthcenter.so=path=/home/hclatest

    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 libhealthcenter.so 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 -Dcom.ibm.java.diagnostics.healthcenter.agent.port=1997 HelloWorld

  java -Xhealthcenter -classpath tmp/myproject/myarchive.jar MyMainClass

  java -Xhealthcenter:port=1965,level=headless -Dcom.ibm.java.diagnostics.healthcenter.headless.delay.start=2 -Dcom.ibm.java.diagnostics.healthcenter.headless.output.directory=/tmp HelloWorld

  java -Xhealthcenter -agentpath:"C:\agent\jre\bin\healthcenter.dll" -cp C:\agent\jre\lib\ext\healthcenter.jar -Dcom.ibm.java.diagnostics.healthcenter.agent.properties.file="C:\agent\jre\lib\healthcenter.properties" -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 com.ibm.java.diagnostics.healthcenter.agent.mbean.HCLaunchMBean <init>
  INFO: Agent version "3.0.2.20150210"
  Feb 11, 2015 11:17:43 AM com.ibm.java.diagnostics.healthcenter.agent.mbean.HCLaunchMBean createJMXConnector
  INFO: IIOP will be listening on the next available system assigned port.
  Use com.ibm.java.diagnostics.healthcenter.agent.iiop.port to specify a port
  Feb 11, 2015 11:17:43 AM com.ibm.java.diagnostics.healthcenter.agent.mbean.HCLaunchMBean 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).