Summary
-------

Provide infrastructure for detailed tracing of the JVM, and add tracing
to all sub-components of the JVM.


Non-Goals
---------

It is not a goal of this project to provide visualization or analysis of
trace data.


Success Metrics
---------------

  - No measurable performance overhead when not enabled.


Motivation
----------

Capturing detailed information about the inner workings of the JVM can be
useful for both performance tuning by customers as well as for debugging
and servicing.


Description
-----------

The infrastructure will be designed to allow for a low-overhead
implementation. Tracing will be done in the form of _events_ that carry
data. These events will also carry meta-data to facilitate rendering of
the information.

Examples of events are "Young Generation Collection" and "Method
Compiled". Each event has a number of fields that can contain additional
information about the event. For example, "Heap Usage Before" and "Method
Name" would be included in the previous two events. In addition, events
contain the thread they occured in as well as timing information.

### Event timing

Events are automatically time stamped. For the purpose of timing there
are two different classes of events:

  - _Instant events_: these have only a single timestamp
  - _Timed events_: these have a start and an end time

### Event Definition

All events are defined in the source code with a full description of the
event as well as all the fields in the event. The description includes
the _data types_ and _content types_ of the fields as well as a human
readable description of the event.

_Data type_ refers to the binary encoding of the data. Examples are
_string_, _int_ and _float_.

_Content type_ refers to the semantic value of the data. Examples are
_bytes_, _milliseconds_ and _percentage_.

The purpose of including lots of meta-data about events and fields is to
make it possible for clients of the data to make sense of it and display
it in an appropriate fashion.

### Event Instrumentation

The source code of the JVM is instrumented with creation of
events. Instrumentation typically looks something like:

    size_t heapSizeBefore, heapSizeAfter;

    EventYoungCollection yc_event;

    // Do the collection here and set the values
    // of heapSizeBefore and heapSizeAfter

	yc_event.set_heapBefore(heapSizeBefore);
	yc_event.set_heapAfter(heapSizeAfter);
	yc_event.commit();

If the instrumented code is performance critical, the last three
statements can be made conditional on `yc_event.should_commit()` which
will make sure these statements aren't executed unless tracing is
enabled.

Alternatives
------------

One alternative approach already present in the JVM is DTrace
probes. Some shortcomings of DTrace in terms of instrumenting the JVM:

  - Only available on Solaris and OS X (although there are efforts to
    port it to Linux).
  - Does not include detailed meta-data about the information it
    exposes.
  - Has only an implicit tie between the start- and end-point of an
    event.


Testing
-------

Apart from unit tests it it important to test that the performance
characteristics of the JVM are not impacted by the
instrumentatation. When instrumentation is turned off, the performance
impact should not be measurable.


Impact
------

  - Performance/scalability: As stated above, performance should not be
    impacted when instrumentation is turned off.