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

For more information, please explore the Attic.

Component Integration

Under Construction.


The instrument API has been designed to avoid adding any dependencies to a component other than the instrument-api.jar itself. This jar by itself is very small and light weight.

The exception is where the AbstractLogEnabledInstrumentable base class is extended. The use of this class places a dependency on avalon-framework-api.jar.

Types of Instruments

There are currently two basic types of instruments supported by the Instrument API. Counters and Value Instruments.

Counter instruments can be used to track the number of times an action takes place. Component developers simply increment the counters. The Instrument Manager will then allow the user to decide on a sample period at runtime, over which to count the number of times the instrument is incremented. It is possible to to increment a counter instrument by 1, or any positive integer.

Value instruments are used to track how quantitative values change over time. They can be used to track pool sizes, execution times, resource levels, etc. Once again, Component developers set values to the instrument as the application executes. Users will have the ability to configure how the instrument values are used from the Instrument Manager. The default implementation allows the user to select a sample interval of say 1 minute. Then track the maximum, minimum, and/or mean values of the instrument within each 1 minute interval over the last 24 hours, for example.

To date, these two simple instrument types have made it possible instrument everything that has been thrown at them. If you encounter a problem which can not be applied to either Instrument type, post a message on the user list and it will be discussed.

Instrument Use Examples

Before delving into how to Instrument a component as a whole. It will be useful to cover some individual examples of how Instruments can be used within a component.

Instrumentation Methods

Extend the AbstractInstrumentable base class

Extend the AbstractLogEnabledInstrumentable base class

Impement the Instrumentable interface