-
Notifications
You must be signed in to change notification settings - Fork 4
Direct vs Generic instrumentation
bctrace defines two different approaches to instrumentation; "generic" and "direct", each one better suited to a different scenario.
These categories are relected in the agent API as different base implementations of hooks, filters and listeners.
Generic Listeners expose a fixed general purpose interface capable of handling events coming from any method. They are suited for creating listeners able to be injected in multiple places, like it's the case in a logging or tracing agent, and handling events coming from any method.
At runtime, generic instrumentation comes at the cost of creating an additional object array to pass the arguments to the generic listener method as well as the needed boxing/unboxing of the primitive values.
Argument passing to generic listeners can be disabled (in order to reduce this overhead) by overriding requiresArguments()
The bctrace runtime passes a method-id to the generic listeners, that can be used by the listener implementation to identify the instrumented method triggering the event, with the help of MethodRegistry. This operation is lightweight and don't add significant overhead, given at runtime each instrumented method just moves an integer literal as a parameter to the listener. Listener implementations can get the method information in O(1) time if needed.
Currently only methods can be instrumented in a generic way. Call-site generic instrumentation has not been added yet.
The entry point in the API for using generic instrumentation is GenericMethodHook.
Direct listeners on the contrary, have no fixed signature. They define a listener method annotated with @DirectListener.ListenerMethod whose signature must match (plus some additional parameters) the signature of the method or call-site being instrumented.
At runtime, they are called with minimal overhead given that both the arguments and return values are passed to or from them as they are, without needed transformations.
Both methods and call-sites can be instrumented in a direct way. The entry points in the API are: