leif 2002/10/01 08:24:00
Modified: instrument/src/xdocs instrumentables.xml menu.xml
Added: instrument/src/xdocs abstract-instrumentable-howto.xml
instrumentable-howto.xml instruments.xml
overview.xml
Log:
Take a first pass at the Instrument documentation. Still needs more work.
Revision Changes Path
1.3 +49 -193
jakarta-avalon-excalibur/instrument/src/xdocs/instrumentables.xml
Index: instrumentables.xml
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/instrument/src/xdocs/instrumentables.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- instrumentables.xml 26 Sep 2002 06:34:54 -0000 1.2
+++ instrumentables.xml 1 Oct 2002 15:24:00 -0000 1.3
@@ -2,204 +2,60 @@
<document>
<header>
- <title>Excalibur Instrument - Enable Instrumenting</title>
+ <title>Excalibur Instrument - Instrumentables</title>
<authors>
- <person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
+ <person name="Leif Mortenson" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
- <s1 title="Coding for Instrumentation">
+ <s1 title="Instrumentables">
<p>
- There are different types of instrumentation we need to use,
depending
- on our purposes. Excalibur Instrument has two basic types:
- <code>CounterInstrument</code> and <code>ValueInstrument</code>.
The
- <code>CounterInstrument</code> allows us to take samples that
represent
- a count of events. The <code>ValueInstrument</code> allows you to
take
- samples that represent the current value.
- </p>
- <p>
- Excalibur Instrument knows how to take the raw samples, and bring
them
- in line with more useable numbers. It is not uncommon to want an
average
- value, a maximum value, or a minimum value for each sample period.
You
- do not have to do anything in your code to explicitly do that.
- </p>
- <p>
- Instrumentation has been designed from the start with performance
in mind
- you can feel comfortable instrumenting your code without worrying
about
- how it will effect performance. When your code is running in an
environment
- where it has not been registered with an InstrumentationManager,
the Instrument
- code acts as a noop. In cases where the your code is registered
with an
- InstrumentationManager, the Instrument is still a noop unless the
instrument
- output is actually been monitored. This makes it possible to place
- Instrumentation throughout your code just as would be done with
debug logging
- information. When the Instrument data is required, it can be
requested at any
- time. Even from a live running system.
- </p>
- </s1>
- <s1 title="Getting Started">
- <p>
- The first thing that you will need to do to Instrument enable your
class
- is to modify your class to implement the
<code>Instrumentable</code> interface.
- There are currently three ways of acomplishing this, each of which
are described
- in detail below. 1) Extend <code>AbstractInstrumentable</code>, 2)
Extend
- <code>AbstractLogEnabledInstrumentable</code> and 3) Implement
- <code>Instrumentable</code>.
- </p>
- <s2 title="Extending AbstractInstrumentable">
- <p>
- The first option works well in cases where your code does not
already have a
- super class. You simply extend the
<code>AbstractInstrumentable</code> class
- create and register your Instruments in your class's
constructor and then
- use the Instruments at the appropriate locations in your code.
All of the
- details of telling your class how to register itself with an
- <code>InstrumentManager</code> are taken care of for you.
- </p>
- <source>
-<![CDATA[
-]]>
- </source>
- </s2>
-
- <p>
- You will need to import the relavant classes from the
avalon-instrument.jar
- file.
- </p>
- <source>
-<![CDATA[
-import org.apache.excalibur.instrument.CounterInstrument;
-import org.apache.excalibur.instrument.Instrumentable;
-import org.apache.excalibur.instrument.Instrument;
-import org.apache.excalibur.instrument.ValueInstrument;
-]]>
- </source>
- <p>
- Once you do that, you need to implement the
<code>Instrumentable</code>
- interface or extend one of the available utility classes:
- <code>AbstractInstrumentable</code> or
- <code>AbstractLogEnabledInstrumentable</code>.
- </p>
-
- <p>
- Once you do that, you need to implement the
<code>Instrumentable</code>
- interface, and set up your instrumentation points. The
InstrumentManager,
- or the parent Instrumentable will assign the name to your
Instrumentable.
- That way we can easily determine what the heirarchy is.
- </p>
- <source>
-<![CDATA[
-public class DefaultExampleInstrumentable
- implements Instrumentable
-{
- public static final String INSTRUMENT_VALUE_NAME = "value";
- public static final String INSTRUMENT_COUNTER_NAME = "counter";
-
- /** Instrumentable Name assigned to this Instrumentable */
- private String m_instrumentableName;
-
- /** Instrument used to profile values */
- private ValueInstrument m_valueInstrument = new ValueInstrument(
INSTRUMENT_VALUE_NAME );
-
- /** Instrument used to profile a count of actions. */
- private CounterInstrument m_counterInstrument = new CounterInstrument(
INSTRUMENT_COUNTER_VALUE );
-
- /*---------------------------------------------------------------
- * Constructors
- *-------------------------------------------------------------*/
- public DefaultExampleInstrumentable()
- {}
-
- // Skip a bunch of other stuff....
-
- /*---------------------------------------------------------------
- * Instrumentable Methods
- *-------------------------------------------------------------*/
- /**
- * Sets the name for the Instrumentable. The Instrumentable Name is used
- * to uniquely identify the Instrumentable during the configuration of
- * the InstrumentManager and to gain access to an InstrumentableDescriptor
- * through the InstrumentManager. The value should be a string which does
- * not contain spaces or periods.
- * <p>
- * This value may be set by a parent Instrumentable, or by the
- * InstrumentManager using the value of the 'instrumentable' attribute in
- * the configuration of the component.
- *
- * @param name The name used to identify a Instrumentable.
- */
- public void setInstrumentableName( String name )
- {
- m_instrumentableName = name;
- }
-
- /**
- * Gets the name of the Instrumentable.
- *
- * @return The name used to identify a Instrumentable.
- */
- public String getInstrumentableName()
- {
- return m_instrumentableName;
- }
-
- /**
- * Obtain a reference to all the Instruments that the Instrumentable object
- * wishes to expose. All sampling is done directly through the
- * Instruments as opposed to the Instrumentable interface.
- *
- * @return An array of the Instruments available for profiling. Should
- * never be null. If there are no Instruments, then
- * EMPTY_INSTRUMENT_ARRAY can be returned. This should never be
- * the case though unless there are child Instrumentables with
- * Instruments.
- */
- public Instrument[] getInstruments()
- {
- return new Instrument[]
- {
- m_valueInstrument,
- m_counterInstrument
- };
- }
-
- /**
- * Any Object which implements Instrumentable can also make use of other
- * Instrumentable child objects. This method is used to tell the
- * InstrumentManager about them.
- *
- * @return An array of child Instrumentables. This method should never
- * return null. If there are no child Instrumentables, then
- * EMPTY_INSTRUMENTABLE_ARRAY can be returned.
- */
- public Instrumentable[] getChildInstrumentables()
- {
- // This instrumentable does not have any children.
- return Instrumentable.EMPTY_INSTRUMENTABLE_ARRAY;
- }
-}
-]]>
- </source>
- </s1>
- <s1 title="Using Instruments">
- <p>
- Lastly, you need to use your instrumentables. Excalibur Instrument
will
- skip the sampling and processing of values if no Manager or Client
is
- attached to them.
- </p>
- <source>
-<![CDATA[
-/**
- * Method that uses the instrumentables we have set up so far
- */
-Object lookup(String name)
-{
- // Do critical stuff
- m_valueInstrument.setValue( m_dictionary.size() );
- m_counterInstrument.increment();
-
- return m_dictionary.get( name );
-}
-]]>
- </source>
+ The Instrumentable interface is required to be able to register a
component with
+ an InstrumentManager. The interface makes it possible for the
InstrumentManager
+ to query the component about what Instruments and child
Instrumentables is making
+ available.
+ </p>
+ <p>
+ The interface provides four methods. The first two,
setInstrumentableName and
+ getInstrumentableName are used to get and set the name of the
Instrumentable.
+ This name is similar to a category name in logger frameworks. The
name is
+ required by the InstrumentManager to be able to provide clients
with a way to
+ request and access instrumentation output. The name should not
include any
+ periods as they are used as separators in a hierarchy of
Instrumentables and
+ their Instruments. The name of top level Instrumentable is usually
set by the
+ object which creates the component. Usually this is a container.
If the
+ creating object is not aware of the Instrument API then it is
possible that
+ setInstrumentableName will never be called. Components should be
able to
+ function properly under this condition. In the case of child
Instrumentables,
+ it is the responsibility of the parent to call
setInstrumentableName.
+ </p>
+ <p>
+ The third and fourth methods, getInstruments and
getChildInstrumentables, are
+ each called once by an InstrumentManager to query the
Instrumentable for a list
+ of the Instruments and child Instrumentables that is making
available.
+ </p>
+ <p>
+ Please see the <link
href="instrumentable-howto.html">Instrumentable How-To</link>
+ for an example.
+ </p>
+ <p>
+ Implementing the Instrumentable interface directly requires a
little bit of work,
+ but is necessary in cases where the parent class can not be
controlled. In most
+ situations, it is possible to extend one of the two helper classes
provided with
+ the API, AbstractInstrumentable and
AbstractLogEnabledInstrumentable. Either
+ of these classes provide methods to add Instruments and Child
Instrumentables to
+ the lists to be published. All of the above methods are handled
behind the scenes.
+ The second helper class is available for classes also wish to
extend the
+ AbstractLogEnabled class provided with Framework. (If this class
is used, then
+ Instrument requires that the avalon-framework.jar file be included
in the
+ classpath.)
+ </p>
+ <p>
+ Please see the
+ <link
href="abstract-instrumentable-howto.html">AbstractInstrumentable How-To</link>
+ for an example. An example of the AbstractLogEnabledInstrumentable
helper class is
+ not included as its usage is identical to AbstractInstrumentable.
+ </p>
</s1>
</body>
</document>
1.4 +16 -5 jakarta-avalon-excalibur/instrument/src/xdocs/menu.xml
Index: menu.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/instrument/src/xdocs/menu.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- menu.xml 26 Sep 2002 06:34:54 -0000 1.3
+++ menu.xml 1 Oct 2002 15:24:00 -0000 1.4
@@ -2,17 +2,28 @@
<project href="http://jakarta.apache.org/avalon/excalibur/instrument/";
name="Excalibur Instrument">
<title>Excalibur Instrument</title>
<body>
+ <menu name="About">
+ <item name="About Instrument" href="index.html"/>
+ <item name="Excalibur Home"
href="http://jakarta.apache.org/avalon/excalibur/index.html"/>
+ <item name="Download"
href="http://jakarta.apache.org/builds/jakarta-avalon-excalibur/release"/>
+ <item name="API Docs" href="api/"/>
+ </menu>
+ <menu name="Essentials">
+ <item name="Overview" href="overview.html"/>
+ <item name="Instrumentables" href="instrumentables.html"/>
+ <item name="Instruments" href="instruments.html"/>
+ </menu>
<menu name="Related">
+ <item name="Instrument Manager" href="../instrument-manager/"/>
+ <item name="Instrument Client" href="../instrument-client/"/>
<menu name="Containers">
<item href="../component/" name="Excalibur Component Manager"/>
<item href="../fortress/" name="Excalibur Fortress"/>
</menu>
</menu>
- <menu name="About">
- <item name="Overview" href="index.html"/>
- <item name="Enabling Instrumentation" href="instrumentables.html"/>
- <item name="Download"
href="http://jakarta.apache.org/builds/jakarta-avalon-excalibur/release/???"/>
- <item name="API Docs" href="api/"/>
+ <menu name="How To">
+ <item name="Implement Instrumentable" href="instrumentable-howto.html"/>
+ <item name="Extend AbstractInstrumentable"
href="abstract-instrumentable-howto.html"/>
</menu>
</body>
</project>
1.1
jakarta-avalon-excalibur/instrument/src/xdocs/abstract-instrumentable-howto.xml
Index: abstract-instrumentable-howto.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>Excalibur Instrument - AbstractInstrumentable How-To</title>
<authors>
<person name="Leif Mortenson" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="AbstractInstrumentable How-Tos">
<p>
To do.
</p>
</s1>
</body>
</document>
1.1
jakarta-avalon-excalibur/instrument/src/xdocs/instrumentable-howto.xml
Index: instrumentable-howto.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>Excalibur Instrument - Instrumentable How-To</title>
<authors>
<person name="Leif Mortenson" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Instrumentable How-Tos">
<p>
To do.
</p>
</s1>
</body>
</document>
1.1 jakarta-avalon-excalibur/instrument/src/xdocs/instruments.xml
Index: instruments.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>Excalibur Instrument - Instruments</title>
<authors>
<person name="Leif Mortenson" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Instruments">
<p>
Instruments are the actual hooks used by a component to make
profiling or
instrumentation information available to the outside world.
Instruments are
created by a component during their initialization phase and then
referenced
throughout the life of the component. The Instruments should be
created whether
the component is registered with an InstrumentManager or not. This
removes the
necessity for the component to do anything special if not registered.
</p>
<p>
The Instruments themselves are designed to be extremely lightweight.
In cases
where an InstrumentManager is not present, or where it is present
but output is
not currently being collected, the Instrument effectively becomes a
noop.
</p>
<p>
There are currently two types of Instruments available for use by
components.
So far they have proven to be enough to profile any type of
quantitative
information.
</p>
<p>
The first is the CounterInstrument. Counters are used to, well,
count the number
of times that something happens. They can be used to keep track of
the number of
times a method is called, a resource is accessed, etc. The
CounterInstrument
provides two methods. The first, increment(), which ups the counter
by 1. And
the second, instrument( count ), which accepts any positive integer.
The later
method can be used in cases where increment would normally have to
be called a
large number of times. For example, the number of iterations in a
sort algorithm.
</p>
<p>
The second type of Instrument is the ValueInstrument.
ValueInstruments are used
to track quantities over time. Examples are the size of a pool, the
current
memory usage of the JVM, etc. ValueInstruments provide a single
method,
setValue( value ).
</p>
</s1>
</body>
</document>
1.1 jakarta-avalon-excalibur/instrument/src/xdocs/overview.xml
Index: overview.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>Excalibur Instrument - Overview</title>
<authors>
<person name="Leif Mortenson" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Why Instrument Was Created">
<p>
Instrument was created out of a desire to provide a standard API for
adding
profiling or instrumentation hooks into an application or class. As
any
application grows in complexity the ability to understand the
interactions
and resource usages of its individual components becomes
increasingly difficult.
</p>
<p>
Logging tools have helped by making it possible to maintain debug
and informational
log messages throughout the code. This output can be enabled or
disabled at will
and then used to help understand the flow of an application.
</p>
<p>
However, while logging is indispensable in many areas, it is not
very useful at
tracking quantitative information over time. There was a need to be
able to
collect information over time to be able to monitor quantities like
memory usage,
pool sizes, counts, and durations over time.
</p>
</s1>
<s1 title="When To Use Instrument">
<p>
Instrument is an API for enabling the collection of qualitative
information from a
component. The API itself has no dependencies on the Avalon
framework and can thus
be used to instrument any application.
</p>
<p>
Instrumenting an application should be thought of in the same way as
adding support
for logging. Just like logging, instrumentation can be very useful
in all phases
of an applications life. During development, information collected
can be
invaluable to help track down bottlenecks, leaks, or simply in
understanding the
flow of a system. Once an application has been released, the
instrument output
can be used to monitor the resources consumed by the application as
well as the
loads that are placed on it over time.
</p>
</s1>
<s1 title="Portability">
<p>
The Instrument API has been carefully designed in such a way as to
remove any
limitations on where components making use of the API can be used.
Most logger
APIs require that a logger be configured before components making
use of their
APIs will function correctly. Failing to configure the component
with a logger
will using result in NullPointerExceptions or similar problems.
</p>
<p>
Instrumentation takes a different approach by providing an opaque
API which makes
it possible for a component providing instrumentation output to
function the same
whether the output is being collected or not. Output is provided to
the outside
world by making use of Instrument instances within the component.
The component
will work identically even if run in an environment which is
completely unaware
of the Instrument API. This should remove all portability fears.
</p>
</s1>
<s1 title="Performance">
<p>
Another concern with any tool like this is performance. Many users
ask, "How will
instrumenting my component affect its performance." The answer is
that the
Instrument API was designed from the beginning with performance in
mind. When a
component implementing the Instrumentable interface is instantiated,
it must be
registered with an InstrumentManager. Upon registration, the
component is queried
for a list of any Instruments or child Instrumentables that it would
like to
publish. If the component is never registered, or until the time
that the
registered Instument output is actually needed, the Instruments them
selves are
effectively noops in the code. For this reason, other than in the
case of an
extremely tight loop, instruments can be added to code without any
fear of a
negative impact on their performance.
</p>
<p>
When an InstrumentManager receives a request for output from a
particular
Instrument, there will be a slight performance hit caused by the
actual collection
of the output. However, the collection of data points has been
designed to avoid
affecting performance as much as possible.
</p>
</s1>
<s1 title="Core Concepts">
<p>
When working with the Instrument API, there are two main classes
that you need to
be aware of.
</p>
<p>
The first is the Instrumentable interface. This interface must be
implemented by
any class wishing to be registered with an InstrumentManager and
then publish
Instrument output. The interface provides methods used by an
InstrumentManager
to query the component for its name, Instruments, as well as any
child
Instrumentable objects. See the
<link href="instrumentables.html">Instrumentables</link> section for
more
information.
</p>
<p>
The second is the Instrument interface. It should not be necessary
to implement
this interface yourself. The Instrument API provides to two
implementations which
have so far covered all requred types of output. The first is the
CounterInstrument which is used to count the number of times an
event takes place.
The second is the ValueInstrument which is useful for tracking
changes in a value
over time. Examples of the later are memory allocation, pool sizes
and durations.
See the <link href="instruments.html">Instruments</link> section for
more
information.
</p>
<p>
The Instrument API also provides InstrumentManager and
InstrumentManageable
interfaces. The InstrumentManager interface must be implemented by
any class
which wishes to act as an InstrumentManager. In most cases the
DefaultInstrumentManager can be used. It is provided by the
<link href="../instrument-manager/">Instrument Manager</link>
project.
</p>
<p>
The InstrumentManageable interface should be implemented by any
component which
needs to be able to have access to the InstrumentManager. In most
cases, only
elements of a container need to implement this interface.
</p>
<p>
In order to make use of the Instrumentation added to components,
they must be
registered with an Instrument Manager. If an Instrument Manager
aware container
is used, this will be automatic. Currently, both the
<link href="../component/">Excalibur Component Manager</link> and
<link href="../fortress/">Excalibur Fortress</link> know how to
manage and register
Instrumentable components.
</p>
<p>
Once an application is running with an active, users can connect to
the
InstrumentManager and request instrumentation output from any
registered
Instrument in the application. The most common method of connecting
to an
InstrumentManager is to make use of the
<link href="../instrument-client/">Instrument Client</link>. The
Instrument
Client provides a Swing based GUI that makes it easy to monitor
several Instruments
at once. For other options read over the documentation of the
<link href="../instrument-manager/">Instrument Manager</link>.
</p>
</s1>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
