Simplified Trace Arguments Handling

Problem Summary

One of the weaker points of BTrace is not really clear argument handling. The arguments are identified by their position (eg. the first argument in trace method for a non static method is *this*) and their meaning may also be determined by the @Location kind.

All this means a lot of confusion for newcomers and may create an obstacle in BTrace adoption.

Solution Proposal

It would be better if arguments could be identified by annotations to clearly state their meaning. Using this approach each special argument would be easily comprehensible for anyone reading the trace code.

For this I propose following annotations:

@Self - stores the instance the probed method belongs to
@Return - stores the probed method return value
@Arguments - AnyType[] : stores the arguments of the probed method (if not Kind.ENTRY)
@TargetInstance - if tracing a call to another instance (Kind.CALL, Kind.ARRAY_SET etc.) it will store the target instance
@TargetMethod - if tracing a call to a method of another instance (Kind.CALL) it will store the target method name + signature

The unannotated arguments will be used for signature matching and they must appear in exactly the same order as required by the target call (but they can be interleaved by the annotated arguments). Also, the AnyType[] arguments will take and store all unannotated arguments in the order of their appearance.

The meaning of unannotated arguments is as follows:

Kind.ENTRY, Kind.RETURN- the probed method arguments
Kind.THROW - the thrown exception
Kind.ARRAY_SET, Kind.ARRAY_GET - the array index
Kind.CATCH - the caught exception
Kind.FIELD_SET - the field value
Kind.LINE - the line number
Kind.NEW - the class name
Kind.ERROR - the thrown exception

Disadvantages

Introducing this feature would mean breaking backward compatibility with the older scripts.