The EJB Monitoring Interceptor
As of version 1.1, the Epsilon method level annotation @MonitoredByEpsilon can be used to annotate EJB 3.0 methods to indicate that they should be monitored by the Epsilon runtime.
In this section, we provide a simple EJB variation of the 'Hello World'-style example, to demonstrate how to enable monitoring of EJBs. The example source can be downloaded from this repository link, however please bear in mind that you will need an obix account to view the source code as we do not encourage anonymous SVN access. When setup in the Eclipse IDE, the application should be laid out as follows:
Note that, in order to enable the functionality of an EJB container, we have bundled the sample with Open EJB 3.1. The Open EJB specific dependencies are placed in a separate folder under the lib directory so as to avoid confusion with the Epsilon specific jars and dependencies.
As can be inferred from the above picture, the application consists of the following source files:
- EJBMonitorDemo.java: Application entry point which initialises Open EJB container and invokes the monitored bean.
- HelloWorldEJBBean.java: The actual implementation of the EJB being monitored. As will be shown, this is the class that is annotated for monitoring by the Epsilon runtime.
- HelloWorldEJBLocal.java and HelloWorldEJBRemote.java : The local and remote interfaces of the monitored EJB, as specified in the EJB standard.
- ejb-jar.xml: EJB deployment descriptor.
- epsilon-cfg.xml: The configuration-file for the Epsilon runtime. When monitoring J2EE components, such as EJBs, we recommend using the default naming convention for the Epsilon configuration.
If you execute EJBMonitorDemo.java its tail-output should look similar to the following trace:
[main] INFO com.obixlabs.epsilon.configuration.EpsilonConfigurationReader - Reading Epsilon configuration file from: CLASSPATH:/epsilon-cfg.xml
[main] INFO obixlabs.epsilonsamples.ejb.HelloWorldEJBBean - Hello World (0)
[main] INFO obixlabs.epsilonsamples.ejb.HelloWorldEJBBean - Hello World (1)
[main] INFO obixlabs.epsilonsamples.ejb.HelloWorldEJBBean - Hello World (2)
[main] INFO obixlabs.epsilonsamples.ejb.HelloWorldEJBBean - Hello World (3)
[main] INFO obixlabs.epsilonsamples.ejb.HelloWorldEJBBean - Hello World (4)
[main] INFO obixlabs.epsilonsamples.ejb.HelloWorldEJBBean - Hello World (5)
[main] INFO obixlabs.epsilonsamples.ejb.HelloWorldEJBBean - Hello World (6)
[main] INFO obixlabs.epsilonsamples.ejb.HelloWorldEJBBean - Hello World (7)
[main] INFO obixlabs.epsilonsamples.ejb.HelloWorldEJBBean - Hello World (8)
[main] INFO obixlabs.epsilonsamples.ejb.HelloWorldEJBBean - Hello World (9)
[main] INFO obixlabs.epsilonsamples.ejb.HelloWorldEJBBean - Hello World (10)
[Thread-4] INFO Epsilon-EJBMonitorDemo-Logger - main: WorkCategory 'helloCategory' exceeded specified latency 200.
[main] INFO obixlabs.epsilonsamples.ejb.HelloWorldEJBBean - Hello World (11)
[Thread-4] INFO Epsilon-EJBMonitorDemo-Logger - main: WorkCategory 'helloCategory' exceeded specified latency 200.
[main] INFO obixlabs.epsilonsamples.ejb.HelloWorldEJBBean - Hello World (12)
[Thread-4] INFO Epsilon-EJBMonitorDemo-Logger - main: WorkCategory 'helloCategory' exceeded specified latency 200.
[main] INFO obixlabs.epsilonsamples.ejb.HelloWorldEJBBean - Hello World (13)
[Thread-4] INFO Epsilon-EJBMonitorDemo-Logger - main: WorkCategory 'helloCategory' exceeded specified latency 200.
[main] INFO obixlabs.epsilonsamples.ejb.HelloWorldEJBBean - Hello World (14)
[Thread-4] INFO Epsilon-EJBMonitorDemo-Logger - main: WorkCategory 'helloCategory' exceeded specified latency 200.
To understand the above trace, let us first of all examine the latency criteria specified for the sample EJB. This can be found in the Epsilon configuration epsilon-cfg.xml, excerpts of which are shown below, and from which we can observe that a maximum latency of 200 milliseconds has been specified for category "helloCategory".
<latencyRequirements>
<cappedRequirement workCategory="helloCategory" ignoreErrors="false" expectedLatency="200">
<alertHandlerId>alertLogger</alertHandlerId>
</cappedRequirement>
</latencyRequirements>
Next, let us examine the source of the bean implementation (HelloWorldEJBBean.java) to see how monitoring is enabled. The relevant sections of this class are shown in the following listing:
@Interceptors(EpsilonEJBMonitor.class)
@Stateless
public class HelloWorldEJBBean implements HelloWorldEJBLocal, HelloWorldEJBRemote
{
public static final int INTENTIONAL_DELAY_THRESHOLD = 10;
@Override
@MonitoredByEpsilon("helloCategory")
public void sayHello(int i)
{
try
{
if (i >= INTENTIONAL_DELAY_THRESHOLD)
Thread.sleep(400L);
else Thread.sleep(i);
logger.info("Hello World (" + i +")");
}
catch (Throwable t)
{logger.error("error occured",t);}
}
}
As can be verified from the above code, the steps for enabling monitoring are as follows:
- Add the EpsilonEJBMonitor as an interceptor to the EJB.
- Annotate each monitored method with the @MonitoredByEpsilon annotation. You do not necessarily have to specify a category in the annotation; but, if you don’t, the fully qualified method-name will be used as the name of the category.
Observe that the method sayHello(...) accepts an integer as an argument; as will become clear shortly, this is the invocation index that is used to simulate the operation’s latency. From the method definition, the reader will notice that we have introduced an intentional 400 millisecond delay for all invocations after the 10th.
Finally, let us look at the execution harness for this example, which is excerpted below:
public static void main(String[] args) throws NamingException
{
Properties props = new Properties();
props.put(Context.INITIAL_CONTEXT_FACTORY,
"org.apache.openejb.client.LocalInitialContextFactory");
Context context = new InitialContext(props);
HelloWorldEJBLocal ejb =
(HelloWorldEJBLocal) context.lookup("HelloWorldEJBLocal");
for (int i=0;i<15;i++)
ejb.sayHello(i);
}
As can be seen from the above code, the harness initialises the OpenEJB context. It then obtains a reference to the local interface for the Hello World EJB, and invokes the sayHello(...) method 15 times. From the implementation of the sayHello(...) method excerpted earlier, we know that all invocations after the 10th will result in a latency requirement breach.