Description Paul Slauenwhite 2006-06-27 10:12:18 EDT

BtM Common Base Event instrumentation improvements.

The following recommendations are for imporving the Common Base Event instrumentaiton provided by BtM:

1) Document (e.g. http://www.eclipse.org/tptp/monitoring/documents/tutorials/tptp_btm_setup.html or TPTP product docuemtnation) the default mapping used for capturing run-time data (e.g. method invocations) as a Common Base Event.  The user should be able access this mapping to understand the generated Common Base Events and write tooling to consume these Common Base Events.

2) Use the standard Java naming conventions for referencing method names (e.g. Common Base Event's msg property and the name property of the parameter's Extended Data Element):

<package name>.<class name>#<method name>([<type of parameter 1>[, <type of parameter n>]])

3) Do not include a parameter Extended Data Element when a method inovation has no parameters.

4) Use the following mapping for method invoation parameters:

public void foo(String[] stringArray, String string){
}

foo(new String[]{"Hello","World"}, "Hello World");

<extendedDataElements name="parameters" type="noValue">
  <children name="java.lang.String[]" type="string">
    <values>Hello</values>
    <values>World</values>
  </children>
  <children name="java.lang.String" type="string">
    <values>Hello World</values>
  </children>
</extendedDataElements>

For example, there is no need specify the invoked method, order of the parameters, number of parameters or the size of array paremters since this infomatrion is implicit.  FOr more information, see EventHelpers#getClassName(Object):

http://dev.eclipse.org/viewcvs/index.cgi/platform/org.eclipse.hyades.logging.core/src.cbe101/org/eclipse/hyades/logging/events/cbe/util/EventHelpers.java?hideattic=0&cvsroot=TPTP_Project

5) For the source componet ID, use the package and class name (e.g. <package name>.<class name>) for the component property and the method name and its parameters (e.g. <method name>([<type of parameter 1>[, <type of parameter n>]])) for the subComponent property.

6) The msg of the Common Base Event should consist of the common name for the instrumenion type (e.g Before Call Method <method information>, Method Entry <method information>, Method Catch <exception package name>.<exception class name>, etc.).

7) Remove the CBE acroymn from all code and UI and replace with Common Base Event due to licensing issues.

8) The Common Base Event generated in a catch block contains the follow msg property:

Exception catched :: <exception mesage>

and should be:

Method Catch <exception package name>.<exception class name>

9) Leverage the remaining probe fragment types:

-executable unit
-static initializer

10) Provide extensibility (via the UI or an extension point) for the user to specify where to instrument applications for Common Base Event instrumentation.  For example, at the start of conditional blocks.

11) UI (e.g. wizard) to map scenario (e.g. catch block) and run-time (e.g. method/class names) properties to Common Base Event properties based on the Common Base Event V1.0.1 specification
(http://www.eclipse.org/tptp/platform/documents/resources/cbe101spec/CommonBaseEvent_SituationData_V1.0.1.pdf).  This mapping function will be extensible (e.g. code snippet) for resolving
application-specific values for Common Base Event properties.  For example, run-time specific situation and sourceComponentId properties.  Default values will be provided for required Common Base Event properties.  Finally, function will be provided to validate the mapped Common Base Event in the UI to ensure its correctness.

12) UI (e.g. wizard), preference (e.g. panel) or environment variable to specify the consumer of generated Common Base Events at run-time.  This configuration would also include filtering (e.g. logging level) and any formatting and/or conversion required to consume the Common Base Event.  TPTP will provide consumer support for the currently supported logging facilities (Apache Commons, Apache Log4J and JSR-047 Java Logging).  One approach is to provide logging instrumentation similar to the Common Base Event instrumentation.  For example, using Java Logging, the user can instrument their application with logging calls to a user configurable named logger (e.g. package, class, application, etc.) that include Common Base Event instrumentation.  This logging instrumentation should be done for the existing supported logging facilities (Apache Commons, Apache Log4J and JSR-047 Java Logging).  Finally, there is a use case for configuration and controlling the logging instrumentation (e.g. loggers and their configuration) using the new JMX instrumentation and managed resource view(s).