Using the Health Center API

You can use the Health Center API to write your own code for manipulating Health Center data that is collected from Java™ or Node.js applications. You cannot use the API with Bluemix® applications.

1. Optional: To use the plug-in version of the Java API, you must install Health Center into Eclipse.
   1. If you do not already have Health Center in Eclipse, follow the instructions in the Eclipse documentation for installing new software, specifying the following URL for the software site:

      http://public.dhe.ibm.com/software/websphere/runtimes/tools/healthcenter/

   2. Create a Java application in Eclipse.
      Use the Eclipse documentation if you need further information for this step.
2. Optional: To use the API with an existing Java application, complete the following steps:
   1. Obtain the API package from Health Center.
      Use the following link, but note that this link works only if you are viewing this documentation from within the product: monitoring-api.jar.
   2. Add the monitoring-api.jar file to the bootstrap class path when you run your application, by specifying the -Xbootclasspath/p command-line parameter.
      For example:

      java -Xbootclasspath/p:./monitoring-api.jar helloworld

3. Add Health Center code to your Java application, to connect to the monitoring agent:
   1. Create a ConnectionProperties object, optionally specifying the host name and port number.
      This object stores the information that is required to connect the Health Center client within your application to the monitoring agent. For more information, see Class ConnectionProperties.
   2. Pass the ConnectionProperties object into one of the HealthCenterFactory.connect(ConnectionProperties props ...) methods to return a HealthCenter object.
      This object represents the connection to the monitored application.
      For example:

      • You can use the HealthCenterFactory.connect(ConnectionProperties props, boolean autoScan) method, with the autoScan parameter set to true, to connect to the first available agent.
      • You can use the HealthCenter.connect(ConnectionProperties props java.lang.String agentName) method to connect to the agent that is specified by the agentName parameter. You can get a list of agent names by using the scanForAgents(ConnectionProperties props, int numberOfAgents) method. This option is useful when you are connecting through an MQTT broker because multiple agents can use the same broker.
      • You can also connect to a saved file instead of a running application, by using the HealthCenterFactory.connect(java.io.File filename) method.

      For more information, see Class HealthCenterFactory.

      Code example:

      ...
      
      // Create the connection object:
      ConnectionProperties conn1 = new ConnectionProperties("localhost", 1973);
      
      // Connect to the monitoring agent by using the connection object:
      HealthCenter hcObject = HealthCenterFactory.connect(conn1, true);
      
      ...
      

4. Add Health Center code to your Java application, to obtain data from the agent:
   • If you want to use event-only mode, enable the mode then create and register listeners as required. You must create a different listener implementation for each type of data, such as CPU or garbage collection. You then register the listener with an appropriate data object and get the monitored data from that data object. For example:

     ...
     
     // Switch on event-only mode:
     hcObject.setEventOnlyMode(true);
     
     // Define and create a garbage collection listener.
     // The listener receives a garbage collection event object after an event:
     class myGCEventListener implements GCEventListener {
     @Override
     public void gcEvent(GCEvent event) {
     System.out.println("GC event detected");
     System.out.println("event.gcEventTime " + event.gcEventTime);
     System.out.println("event.gcPauseTime " + event.gcPauseTime);
     System.out.println("event.heapSize " + event.heapSize);
     System.out.println("event.usedHeapAfterGC " + event.usedHeapAfterGC);
     System.out.println("event.reason " + event.reason);
     System.out.println("event.type " + event.type);
     }
     }
     
     myGCEventListener gclistener = new myGCEventListener();
     
     // Register the listener with a garbage collection data object:
     GCData gcData = hcObject.getGCData();
     gcData.addGCListener(gclistener);
     
     // Extract data from the data object:
     System.out.println("GC Mode is " + gcData.getGCMode().toString());
     
     ...

   • If you want to use non-event mode, use the HealthCenter object to obtain a data object that represents the type of data that you are interested in, then retrieve data from that data object. For example:

     ...
     
     // Get the garbage collection data and print it:
     GCData gcData = hcObject.getGCData();
     System.out.println("GC Mode is " + gcData.getGCMode().toString());
     
     ...

   You can also use the HealthCenter object to limit the amount of data that is returned from a running application. For more information about the data that you can retrieve, and the associated methods and classes, see Health Center Java API documentation.