JETM: Five minute tutorial

This tutorial demonstrates some advanced features of JETM. It assumes you have already taken a look at advanced concepts. If you are new to JETM better start with one minute tutorial.

In this tutorial we will enhance a Java™ application such that we are able to gain performance statistics without touching source code at all. Out of convenience we use the Springframework as runtime and performance monitoring infrastructure (and there are further options to do so).

Attention: If you never heard about the Springframework before this tutorial might take longer than five minutes. In this case we recommend reading the introductional material at springframework.org.

Step 1: Prerequisites

The JETM samples archive includes all required sources and dependencies for this tutorial. Download the archive and expand it.

There are two options to execute the tutorial application: If you want to run the tutorial from within your favourite IDE just create a new project from the content of tutorial/five-minute and ensure that

• lib/jetm-{VERSION}.jar,
• lib/jetm-optional-{VERSION}.jar and
• all libraries in tutorial/five-minute/lib

are in your project classpath. Alternatively you can just use ant and run this tutorial from the command line. Therefore a valid ant installation (>= 1.6.x) is required.

Step 2: Examine tutorial source code

Our five minute tutorial application is a simple console grocery store, where you can buy apples, oranges and such. It is made of the Store itself that is using a Dao Mockup for persistence. The class OrderClient acts as a client to our store and is executed with the help of Main.

Starting in Main you will see that the application loads its configuration from five-minute-tutorial.xml, a spring configuration file. This file contains all bean (class) definitions that are wired automatically using constructor injection.

The lines

 OrderClient client = (OrderClient) context.getBean("orderClient");
 client.execute(); 

retrieve a fully configured instance of the class OrderClient and execute the demo. The surrounding thread is used to avoid blocking when executed within ant.

Step 3: Run the tutorial application

We are now ready to run the tutorial application. Depending on whether you run the demo from your IDE or from command line the process is slightly different.

You should now see at your console the JETM Grocery Store output:

Welcome to the JETM Grocery Store!

We currently have in stock:
 ------------------------------
 | ID | Qty | Item    | Price |
 ------------------------------
 |  1 |  15 |  apples | $2.99 |
 |  2 |   5 | oranges | $1.49 |
 |  3 |  20 | bananas | $1.99 |
 |  4 |  11 |  grapes | $2.49 |
 ------------------------------

Enter item id to order (or 0 exit): 

Not that pretty - but works for now;)

Step 4: Enable performance monitoring

If you examine the tutorial classes you will notice that there isn't a single etm.* import. This is because we will monitor execution performance purely by configuration.

Eventually you have noticed in five-minute-tutorial.xml the tag <jetm:runtime>. This Spring 2.0 bean definition attaches a single JETM runtime to the Spring lifecycle. Nevertheless performance monitoring has to be enabled manually on a per-bean basis.

The tag <jetm:monitoring> will be used for this purpose: As you can see in five-minute-tutorial.xml past section <!-- Step 4: ... --> you can register beans using wildcards (*Dao) and complete names (groceryStore). Uncomment the section and restart the application.

<!-- Step 4: Enable performance monitoring -->
<jetm:monitoring>
  <jetm:bean-pattern>*Dao</jetm:bean-pattern>
  <jetm:bean-pattern>groceryStore</jetm:bean-pattern>
</jetm:monitoring>

Interestingly the application is running just like before - and there aren't any performance details. That's because we enabled performance monitoring but did not add means to access the collected details.

Step 5: Access aggregated results

One option to access those details is the build-in HTTP console.

Therefore uncomment the bean definition past <!-- Step 5: ... > and restart the application.

<!-- Step 5: Access aggregated results -->
<jetm:console expanded="true"/>

Now point your browser to http://localhost:40000 and you will see aggregated performance statistics.

The attribute expanded in the bean definition decides whether all performance results should be rendered (including the nested ones) or just the top level results only. To see the difference set this property to false (or remove it) and restart the tutorial application.

Step 6: Alter aggregation chain

By default all collected performance data will be buffered and aggregated as soon as a certain threshold was reached. The default threshold is 1000 measurements. However there is one negative side effect: The thread that collected the last result will be used to calculate the aggregated performance statistics.

This negative effect can be minimized by using interval based buffering that buffers collected results for a certain period of time and aggregates them asynchronously. In the example below we enable interval based buffering as JETM runtime feature. Simply uncomment the interval definition past <!-- Step 6: ... > and restart the demo.

<!-- Step 6: Alter aggregation chain -->
<jetm:runtime>
  <jetm:features>

    <jetm:interval-buffer interval="1000"/>

    ...
  </jetm:features>
</jetm:runtime>

Step 7: Log raw performance results

While being able to access aggregated performance statistics it still may be useful to have access to raw performance data for post processing. This can be achieved by enabling the JETM runtime feature raw data logging.

<!-- Step 7: Log raw performance results -->
<jetm:runtime>
  <jetm:features>
     ...

    <jetm:raw-data-log type="commons"/>

  </jetm:features>
</jetm:runtime>

After restarting the tutorial application raw performance data will be logged to a file called performance.log in the directory tutorial/five-minute. The example above uses Jakarta commons-logging to log the raw performance data.

That's it!

Next...

Now proceed to the remaining JETM documentation.