5 Adding Monitoring Capabilities

Defining an Event Provider

An event provider defines the types of events for the operations that generate statistics for an add-on component.

GlassFish Server enables you to define an event provider in the following ways:

• By writing a Java Class. Define an event provider this way if you have access to the source code of the component for which you are defining an event provider.

• By writing an XML fragment. Define an event provider this way if you do not have access to the source code of the component for which you are defining and event provider.

import org.glassfish.external.probe.provider.annotations.Probe;
import org.glassfish.external.probe.provider.annotations.ProbeParam;
import org.glassfish.external.probe.provider.annotations.ProbeProvider;
@ProbeProvider(moduleProviderName="examplecomponent", 
moduleName="transaction", probeProviderName="manager")
public class TxManager {
    
    @Probe("begin")
    public void onTxBegin(
        @ProbeParam("{txId}") String txId
    ){}

    @Probe ("end")
    public void onCompletion(
        @ProbeParam("{outcome}") boolean outcome
    ){}
 }

void jspLoaded (String jsp, String hostName)

<probe-provider moduleProviderName="glassfish" moduleName="web" probeProviderName="jsp">
    <probe name="jspLoadedEvent">
       <class>com.sun.enterprise.web.jsp.JspProbeEmitterImpl</class>
       <method>jspLoaded</method>
       <signature>void (String,String)</signature>
       <probe-param type="String" name="jsp"/>
       <probe-param type="String" name="hostName"/>
       <return-param type="void" />
    </probe>
</probe-provider>

probe-provider-class-names : org.glassfish.pluggability.monitoring.ModuleProbeProvider

Sending an Event

At runtime, your add-on component might perform an operation that generates statistics. To provide statistics about the operation to GlassFish Server, your component must send an event of the correct type when performing the operation.

To send an event, instantiate your event provider class and invoke the method of the event provider class for the type of the event. Instantiate the class and invoke the method in the class that represents your add-on component. Ensure that the method is invoked when your component performs the operation for which the event was defined. One way to meet this requirement is to invoke the method for sending the event in the body of the method for performing the operation.

...
public class TransactionManagerImpl {
...
     public TransactionManagerImpl() {
         TxManager txProvider = new TxManager();
         ...
     }
    ...
    public void begin() {
        String txId = createTransactionId();
        ....
        txProvider.onTxBegin(txId); //emit
      }
...
}

Creating Event Listeners

An event listener gathers statistics from events that an event provider sends. To enable an add-on component to gather statistics from events, create listeners to receive events from the event provider. The listener can receive events from the add-on component in which the listener is created and from other components.

To create an event listener, write a Java class to represent the listener. The listener can be any Java object.

An event listener also represents a component's statistics. To enable the Application Server Management Extensions (AMX) to expose the statistics to client applications, annotate the declaration of the class with the org.glassfish.gmbal.ManagedObject annotation.

Ensure that the class that you write meets these requirements:

• The return value of all callback methods in the listener must be void.

• Because the methods of your event provider class may be entered by multiple threads, the listener must be thread safe.

• The listener must have the same restrictions as a Java Platform, Enterprise Edition (Java EE) application. For example, the listener cannot open server sockets, or create threads.

A listener is called in the same thread as the event method. As a result, the listener can use thread locals. If the monitored system allows access to thread locals, the listener can access thread locals of the monitored system.

Representing a Component's Statistics in an Event Listener Class

Represent each statistic as the property of a JavaBeans specification getter method of your listener class. Methods in the listener class for processing events can then access the property through the getter method. For more information, see Subscribing to Events From Event Provider Classes.

To enable AMX to expose the statistic to client applications, annotate the declaration of the getter method with the org.glassfish.gmbal.ManagedAttribute annotation. Set the id element of the @ManagedAttribute annotation to the property name all in lowercase.

The data type of the property that represents a statistic must be a class that provides methods for computing the statistic from event data.

The org.glassfish.external.statistics.impl package provides the following classes to gather and compute statistics data:

AverageRangeStatisticImpl

Provides standard measurements of the lowest and highest values that an attribute has held and the current value of the attribute.

BoundaryStatisticImpl

Provides standard measurements of the upper and lower limits of the value of an attribute.

BoundedRangeStatisticImpl

Aggregates the attributes of RangeStatisticImpl and BoundaryStatisticImpl and provides standard measurements of a range that has fixed limits.

CountStatisticImpl

Provides standard count measurements.

RangeStatisticImpl

Provides standard measurements of the lowest and highest values that an attribute has held and the current value of the attribute.

StatisticImpl

Provides performance data.

StringStatisticImpl

Provides a string equivalent of a counter statistic.

TimeStatisticImpl

Provides standard timing measurements.

...
import org.glassfish.external.statistics.CountStatistic;
import org.glassfish.external.statistics.impl.CountStatisticImpl;
...
import org.glassfish.gmbal.ManagedAttribute;
import org.glassfish.gmbal.ManagedObject;

...
@ManagedObject
public class TxListener {

    private CountStatisticImpl txCount = new CountStatisticImpl("TxCount", 
        "count", "Number of completed transactions");
...
    @ManagedAttribute(id="txcount")
    public CountStatistic  getTxCount(){
         return txCount;
    }
}

Subscribing to Events From Event Provider Classes

To receive events from event provider classes, a listener must subscribe to the events. Subscribing to events also specifies the provider and the type of events that the listener will receive.

To subscribe to events from event provider classes, write one method in your listener class to process each type of event. To specify the provider and the type of event, annotate the method with the org.glassfish.external.probe.provider.annotations.ProbeListener annotation. In the @ProbeListener annotation, specify the provider and the type as follows:

"module-providername:module-name:probe-provider-name:event-type"

module-providername

The application to which the event provider belongs. This parameter must be the value of the moduleProviderName element or attribute in the definition of the event provider. See Defining an Event Provider by Writing a Java Class and Defining an Event Provider by Writing an XML Fragment.

module-name

The module for which the event provider is defined. This parameter must match be the value of the moduleName element or attribute in the definition of the event provider. See Defining an Event Provider by Writing a Java Class and Defining an Event Provider by Writing an XML Fragment.

probe-provider-name

The name of the event provider. This parameter must match be the value of the probeProviderName element or attribute in the definition of the event provider. See Defining an Event Provider by Writing a Java Class and Defining an Event Provider by Writing an XML Fragment.

event-type

The type of the event. This type is defined in the event provider class. For more information, see Defining Event Types in an Event Provider Class.

Annotate each parameter in the method signature with the @ProbeParam annotation. Set the value element of the @ProbeParam annotation to the name of the parameter.

In the method body, provide the code to update monitoring statistics in response to the event.

...
import org.glassfish.external.probe.provider.annotations.ProbeListener;
import org.glassfish.external.probe.provider.annotations.ProbeParam;
import org.glassfish.gmbal.ManagedObject;
...
@ManagedObject
public class TxListener {
    ...;    @ProbeListner("examplecomponent:transaction:manager:begin")
    public void begin(
    @ProbeParam("{txId}")
    String txId) {
      txCount.increment();
    }
  }

Registering an Event Listener

Registering an event listener enables the listener to receive callbacks from the GlassFish Server event infrastructure. The listener can then collect data from events and update monitorable objects in the object tree. These monitorable objects form the basis for monitoring statistics.

Registering an event listener also makes a component and its statistics monitorable objects by adding statistics for the component to the monitorable object tree.

At runtime, the GlassFish Server event infrastructure registers listeners for an event provider when the event provider is started and unregisters them when the event provider is shut down. As a result, listeners have no dependencies on other components.

To register a listener, invoke the static org.glassfish.external.probe.provider.StatsProviderManager.register method in the class that represents your add-on component. In the method invocation, pass the following information as parameters:

• The name of the configuration element with which all statistics in the event listener are to be associated. System administrators use this element for enabling or disabling monitoring for the event listener.

• The node in the monitorable object tree under which the event listener is to be registered. To specify the node, pass one of the following constants of the org.glassfish.external.probe.provider.PluginPointPluginPoint enumeration:

  • To register the listener under the server/applications node, pass the APPLICATIONS constant.

  • To register the listener under the server node, pass the SERVER constant.

• The path through the monitorable object tree from the node under which the event listener is registered down to the statistics in the event listener. The nodes in this path are separated by the slash (/) character.

• The listener object that you are registering.

...
import org.glassfish.external.probe.provider.StatsProviderManager;
import org.glassfish.external.probe.provider.PluginPoint
...
public class TransactionManagerImpl {
...
    StatsProviderManager.register("web-container", PluginPoint.APPLICATIONS, 
        "tx/txapp", new TxListener());
...
}