Starting the Health Center agent after starting an application (Java applications only)

If you did not start the agent at the same time as the Java™ application that you want to monitor, you can start it afterwards and attach it to the JVM that is running the application. To complete this task you use a program that is included with the agent. This program is based on the Java Attach API.

1. Ensure that the target JVM is enabled for the Java Attach API, and that you have the correct authority. Refer to your platform and JVM documentation for details.
2. At a command line on the same machine as the target JVM, enter one of the following commands:
   • 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:

     java -jar path/healthcenter.jar [ID(:|=) target_JVM_ID ] [ data_provider_properties ] [ configuration_properties ]

   • If you are using an updated agent that you installed outside the Java SDK installation directory:

     java -Xbootclasspath/p:path/healthcenter.jar -jar path/healthcenter.jar agent_path_configuration_property [ID(:|=) target_JVM_ID ] [ data_provider_properties ] [ configuration_properties ]

   • path is the path to the healthcenter.jar archive file. The healthcenter.jar file is usually in the jre/lib/ext directory of the Java runtime environment that will run the Health Center agent. If you installed an updated agent outside the runtime environment file system, to a directory of your choice, the archive file is located in your chosen directory tree. For more information, see Installing a Health Center monitoring agent.
   • agent_path_configuration_property is one of the Health Center configuration properties mentioned later in this step. Configuration properties are usually optional, but in this case this property is required; if you installed an updated agent outside the runtime environment file system, to a directory of your choice, you must use this property to specify that directory. You can specify the property either as path=agent_path or as -Dcom.ibm.java.diagnostics.healthcenter.agent.path=agent_path, where agent_path is the directory in which you installed the agent.
   • JVM_ID is, by default, the process ID of the running JVM. You can override this default by using the com.ibm.tools.attach.id system property when you start the JVM. Refer to the Java Attach API documentation for the JVM for more details. If you supply an ID argument and the command is successful, the agent starts in the specified JVM and the task is complete. If you do not use the ID argument, the program generates a list of JVMs that are running; you can then select a JVM from the list.
   • data_provider_properties specifies data providers that you want to disable. By default, all data providers are enabled, and Health Center collects all of the available data. If you do not need all the data, you can reduce the size of your stored data files by collecting only the data that you are interested in. You can specify multiple properties. The format of each property is -D property_name =(on|off). The following properties are supported:
     • com.ibm.diagnostics.healthcenter.data.classes
     • com.ibm.diagnostics.healthcenter.data.cpu
     • com.ibm.diagnostics.healthcenter.data.gc
     • com.ibm.diagnostics.healthcenter.data.io
     • com.ibm.diagnostics.healthcenter.data.jit
     • com.ibm.diagnostics.healthcenter.data.memory
     • com.ibm.diagnostics.healthcenter.data.profiling
     • com.ibm.diagnostics.healthcenter.data.threads
     For example: -Dcom.ibm.diagnostics.healthcenter.data.threads=off disables the collection of thread data.
   • configuration_properties specifies Health Center configuration options that you might want to use. For more information, see Configuring the monitoring agent. You can specify properties by using either the parameter or system property format, or both. You can specify any number of properties. For example:

     java -jar healthcenter.jar -Dcom.ibm.java.diagnostics.healthcenter.agent.port=1999

     java -jar healthcenter.jar ID:46375 port=1999

     java -jar healthcenter.jar level=headless,port=1999 -Dcom.ibm.java.diagnostics.healthcenter.headless.run.pause.duration=5 -Dcom.ibm.java.diagnostics.healthcenter.headless.run.number.of.runs=10 -Dcom.ibm.java.diagnostics.healthcenter.headless.run.duration=2

     java -Xbootclasspath/p:/home/hclatest/lib/ext/healthcenter.jar -jar /home/hclatest/lib/ext/healthcenter.jar -Dcom.ibm.java.diagnostics.healthcenter.agent.path=/home/hclatest

     Notes:

     • The -D option is used as a parameter to the attach program, and therefore must be specified after the healthcenter.jar parameter.
     • If you have a firewall between the Health Center client and agent, and the transport protocol for Health Center is set to iiop (the default), specify the IIOP port number property. This property sets the port that is used by the object request broker (ORB) on the machine that is running the Health Center agent. This port is different from the main Health Center port. You must then open both ports in the firewall, so that the Health Center agent can communicate with the client.
3. If the command generated a list of JVMs, enter the number of the JVM in which to start the agent.
   The following text shows an example of a generated list:

   Running Virtual Machines:
   
   1:
   org.eclipse.hyades.execution.remote.NodeImpl 1423070418: ID=10696
   
   2:
   HCTest.jar: ID=11940
   
   3:
   C:\Program Files\Eclipse\v37\eclipse\\plugins/org.eclipse.equinox.launcher_1.2.0
   .v20110502.jar -os win32 -ws win32 -arch x86_64 -showsplash -launcher C:\Program
   Files\Eclipse\v37\eclipse\eclipse.exe -name Eclipse --launcher.library C:\Progr
   am Files\Eclipse\v37\eclipse\\plugins/org.eclipse.equinox.launcher.win32.win32.x
   86_64_1.1.100.v20110502\eclipse_1406.dll -startup C:\Program Files\Eclipse\v37\e
   clipse\\plugins/org.eclipse.equinox.launcher_1.2.0.v20110502.jar --launcher.over
   rideVmargs -exitdata 218c_98 -vm C:\Windows\system32\javaw.exe -vmargs -Xms40m -
   Xmx384m -jar C:\Program Files\Eclipse\v37\eclipse\\plugins/org.eclipse.equinox.l
   auncher_1.2.0.v20110502.jar: ID=12184
   
   4:
   healthcenter.jar: ID=292
   
   Please select the VM (enter number between 1 and 4) in which to enable the Health Center agent, or blank line to exit.

   Note: The JVM that is running the agent attach program also appears in the list of running JVMs. For example VM number 4 in the previous sample output. You can attach the Health Center agent to this JVM, but the agent will finish shortly after a successful attach.

Successfully enabled Health Center agent in VM: HCTest.jar
Health Center properties used by agent in target VM:
com.ibm.java.diagnostics.healthcenter.agent.port=1972
com.ibm.java.diagnostics.healthcenter.data.collection.level=full