BTrace Modules

This entry is used for gathering ideas about the built-in BTrace extensibility

Purpose

Currently, BTrace is pretty conservative about the features one can use from inside the BTrace scripts. In short, all the available functionality must be implemented as static methods of the com.sun.btrace.BTraceUtils class to make it easier for the BTrace script compiler and the runtime verifier to make sure only the harmless code is being injected in the target application. On the other hand it requires all the unrelated methods being clumped together in one giant monolithic class. This complicates locating the desired functionality as well as ties the release cycles of the extra functionality to the BTrace core.

As such, it is desirable to decouple the functionality currently provided by BTraceUtils from the BTrace core itself. In the process of making this happen an extensions plugging system will be created which will allow easier incorporation of the 3rd party value addons to BTrace.

Architecture

Packaging

An extension must be packaged in the form of JAR. A single JAR may contain more extensions. No exploded archives will be supported.

Extensions path

An extensions path (the path to search for extension jars) will be defined for BTrace. It will default to <BTRACE_HOME>/lib/ext and will be possible to append custom paths to this default by the means of a system property and and agent argument. All the jars from the effective extensions path will be added to the bootstrap classpath of the traced application.

Extension recognition

An extension will be uniquely determined by a specific annotation attached to the extension class (eg. @BTraceExtension). Only classes marked with such annotation will be processed by the BTrace extension mechanism.

Also, in order to avoid loading all the classes from the extension jars the standard ServiceLoader mechanism will be used - all extension classes will have to be explicitly mentioned in META-INF/services/<extension annotation FQN> entry.

Security

TBD

Implementation

API

@BTraceExtension

This annotation marks a class as a BTrace extension. Its fully qualified name is used for extension registration in META-INF/services.

Annotation parameters can carry info about requested permissions, detailed extension description etc.

BTraceExtensionRuntime

Used by extensions to access BTrace internal functions like sending commands or reading the agent arguments.

MBeanDecorator

When an extension needs to publish custom data via the BTrace MBean it needs to provide its own conversion between custom type and OpenType by registering an MBeanDecorator implementation in the META-INF/services registry.

CommandReceiver

An extension can opt to process the commands received by BTrace agent. The implementation needs to be registered in META-INF/services registry.

Engine Modifications

Compiler

Compiler will append the extensions combined classpath (= all jars in the default extension location + all jars in all parts of the user specified exension paths) to the compilation classpath to enable seamless inclusion of the extension classes from within a BTrace script.

Postprocessor

Postprocessor must be aware of enabled extensions in order to process the shortened BTrace script syntax correctly.

Verifier

Verifier will make sure only the declared extensions' methods are used in BTrace scripts. It will report a compiler error for any attempt to invoke a non-extension method.