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.
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.
Procedure
-
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).
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.