Sun GlassFish Enterprise Server v3 Add-On Component Development Guide

Defining Statistics That Are to Be Monitored

At runtime, your add-on component might perform operations that affect the behavior and performance of your system. For example, your component might start a thread of control, receive a request from a service, or request a connection from a connection pool. Monitoring the statistics that are related to these operations helps a system administrator maintain the system.

To provide statistics to Enterprise Server, your component must define events for the operations that generate these statistics. At runtime, your component must send these events when performing the operations for which the events are defined. For example, to enable the number of received requests to be monitored, a component must send a “request received” event each time that the component receives a request.

A statistic can correspond to single event or to multiple events.

Counter statistics typically correspond to a single event. For example, to calculate the number of received requests, only one event is required, for example, a “request received” event. Every time that a “request received” event is sent, the number of received requests is increased by 1.
Timer statistics typically correspond to multiple events. For example, to calculate the time to process a request, two requests, for example, a “request received” event and a “request completed” event.

Defining statistics that are to be monitored involves the following tasks:

Defining an Event Provider

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

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

By writing a Java^TM 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.

Defining an Event Provider by Writing a Java Class

To define an event provider, write a Java language class that defines the types of events for the component. Your class is not required to extend any specific class or implement any interfaces.

To identify your class as an event provider, annotate the declaration of the class with the org.glassfish.external.probe.provider.annotations.ProbeProvider annotation.

To create a name space for event providers and to uniquely identify an event provider to the monitoring infrastructure of Enterprise Server, set the elements of the @ProbeProvider annotation as follows:

moduleProviderName

Your choice of text to identify the application to which the event provider belongs. The value of the moduleProviderName element is not required to be unique.

For example, for event providers from Sun GlassFish^TM Enterprise Server, moduleProviderName is glassfish.

moduleName

Your choice of name for the module for which the event provider is defined. A module provides significant functionality of an application. The value of the moduleName element is not required to be unique.

In Enterprise Server, examples of module names are web-container, ejb-container, transaction, and webservices.

probeProviderName

Your choice of name to identify the event provider. To uniquely identify the event provider, ensure that probeProviderName is unique for all event providers in the same module.

In Enterprise Server, examples of event—provider names are jsp, servlet, and web-module.

Defining Event Types in an Event Provider Class

To define event types in an event provider class, write one method for each type of event that is related to the component. The requirements for each method are as follows:

The return value of the callback methods must be void.
The method body must be empty. You instantiate the event provider class in the class that invokes the method to send the event. For more information, see Sending an Event.
To enable the event to be used as a Solaris DTrace probe, each parameter in the method signature must be a Java language primitive, such as Integer, boolean, or String.

Annotate the declaration of each method with the org.glassfish.external.probe.provider.annotations.Probe annotation.

By default, the type of the event is the method name. If you overload a method in your class, you must uniquely identify the event type for each form of the method. To uniquely identify the event type, set the name element of the @Probe annotation to the name of the event type.

Note –

You are not required to uniquely identify the event type for methods that are not overloaded.

Specifying Event Parameters

To enable methods in an event listener to select a subset of values, annotate each parameter in the method signature with the org.glassfish.external.probe.provider.annotations.ProbeParam annotation. Set the value element of the @ProbeParam annotation to the name of the parameter.

Example of Defining an Event Provider by Writing a Java Class

Example 5–1 Defining an Event Provider by Writing a Java Class

This example shows the definition of the TxManager class. This class defines events for the start and end of transactions that are performed by a transaction manager.

The methods in this class are as follows:

onTxBegin: This method sends an event to indicate the start of a transaction. The name of the event type that is associated with this method is begin. A parameter that is named txId is passed to the method.
onCompletion: This method sends an event to indicate the end of a transaction. The name of the event type that is associated with this method is end. A parameter that is named outcome is passed to the method.

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
    ){}
 }

Defining an Event Provider by Writing an XML Fragment

To define an event provider, write an extensible markup language (XML) fragment that contains a single probe-provider element.

To create a name space for event providers and to uniquely identify an event provider to the monitoring infrastructure of Enterprise Server, set the attributes of the probe-provider element as follows:

moduleProviderName

Your choice of text to identify the application to which the event provider belongs. The value of the moduleProviderName attribute is not required to be unique.

For example, for event providers from Sun GlassFish Enterprise Server, moduleProviderName is glassfish.

moduleName

Your choice of name for the module for which the event provider is defined. A module provides significant functionality of an application. The value of the moduleName attribute is not required to be unique.

In Enterprise Server, examples of module names are web-container, ejb-container, transaction, and webservices.

probeProviderName

Your choice of name to identify the event provider. To uniquely identify the event provider, ensure that probeProviderName is unique for all event providers in the same module.

In Enterprise Server, examples of event—provider names are jsp, servlet, and web-module.

Within the probe-provider element, add one probe element for each event type that you are defining. To identify the event type, set the name attribute of the probe element to the type.

To define the characteristics of each event type, add the following elements within the probe element:

class

This element contains the fully qualified Java class name of the component that generates the statistics for which you are defining events.

method

This element contains the name of the method that is invoked to generate the statistic.

signature

This element contains the following information about the signature if the method:

return-type (paramater-type-list)

return-type: The return type of the method.
paramater-type-list: A comma-separated- list of the types of the parameters in the method signature.

probe-param

The attributes of this element identify the type and the name of a parameter in the method signature. One probe-param element is required for each parameter in the method signature. The probe-param element does not contain any data.

The attributes of the probe-param element are as follows:

type: Specifies the type of the parameter.
name: Specifies the name of the parameter.

return-param

The type attribute of this element specifies the return type of the method. The return-param element does not contain any data.

Example 5–2 Defining an Event Provider by Writing an XML Fragment

This example defines an event provider for the glassfish:web:jsp component. The Java class of this component is com.sun.enterprise.web.jsp.JspProbeEmitterImpl. The event provider defines one event of type jspLoadedEvent. The signature of the method that is associated with this event is as follows:

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>

Packaging a Component's Event Providers

Packaging a component's event providers enables the monitoring infrastructure of Enterprise Server to discover the event providers automatically.

To package a component's event providers, add an entry to the component's META-INF/MANIFEST.MF file that identifies all of the component's event providers. The format of the entry depends on how the event providers are defined:

If the event providers are defined as Java classes, the entry is a list of the event providers' class names as follows:
```
probe-provider-class-names : class-list
```
class-list

A comma-separated list of the fully qualified Java class names of the component's event providers.
If the event providers are defined as XML fragments, the entry is a list of the paths to the files that contain the XML fragments as follows:
```
probe-provider-xml-file-names : path-list
```
path-list

A comma-separated list of the paths to the XML files relative to the root of the archive in the JAR file.

Example 5–3 Manifest Entry for Event Providers That Are Defined as Java Classes

This example shows the entry in the META-INF/MANIFEST.MF file of a component whose event provider is the org.glassfish.pluggability.monitoring.ModuleProbeProvider class.

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 Enterprise 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.

Example 5–4 Sending an Event

This example shows the code for instantiating the TxManager class and invoking the onTxBegin method to send an event of type begin. This event indicates that a component is about to begin a transaction.

The TxManager class is instantiated in the constructor of the TransactionManagerImpl class. To ensure that the event is sent at the correct time, the onTxBegin method is invoked in the body of the begin method, which starts a transaction.

The declaration of the onTxBegin method in the event provider interface is shown in Example 5–1.

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