2010/12/15 - Apache Excalibur has been retired.

For more information, please explore the Attic.

Introduction

Instruments allow a user to connect and externally monitor what is happening within an application as it is running. It is designed to be used in coordination with a logging system.

While logging systems are great at displaying the order in which events take place, there are poor at making clear the rates, volumes and interactions between such events in a temporal fashion.

Audiences

Instrumentation is used in different ways depending on how you will be using it.

Perspective Description
Application User

Out of the Box, Instrumentation provides an HTTP based connector which allows the user to connect to an application using their favorite web browser. This interface is capable of communicating with the client using either HTML or XML depending on the needs of the client.

In addition to connecting directly using a Web Browser, a standalone Java client is also provided which allows the user to make use of the Instrument features using an optimum GUI environment. Behind the scenes, this client uses XML on top of the HTTP connector to communicate with the application.

Application Administrator

An application administrator is interested in how to configure the Instrumentation features within an application to best meet the needs of its users.

Component Developer

A component developer will be interested in how to write their components so that they can be monitored and easily analyzed by users and system administrators when the components are deployed as part of an application. The Instrument package provides a very light weight and simple API which makes it possible to very quickly instrument most components. The API has been specifically designed in such a way as to allow components to be used even in contexts which do not support the Instrumentation features.

Note that while the Instrument APIs have been designed to work well with the Avalon Framework APIs, there is nothing about the API which requires them.

Container Developer

Container developers will be interested in what is involved to make their containers take advantage of the Instrumentation provided by components. An API has been provided to make implementing instrumentation quite painless by treating it like any other life-cycle.

Note that while the Instrument APIs have been designed to work well with the Avalon Framework APIs, there is nothing about the API which requires them.

Connector Developer

In cases where the provided HTTP connector does not meet the needs of a specific application, the Instrument Manager API provides a number of additional ways for an application to take advantage of the Instrumentation provided by the application.