An agent can be used standalone or it can be extended by means of Flopsar Extensions. Flopsar Agent is a powerful engine, which is extensible by plugins. The extensions are some extra jar files, which consist of user-defined POJO classes. The jars can be then included in the agent deployment. The plugins enable to extend
Agent capabilities. We provide a mechanism that you can use to extend your application diagnosis and trace your data flow. It makes Flopsar an open tool, that can be extended. The plugin allows for processing data inside instrumented methods.
There are two types of formatters, which can be used:
standard formatter is embedded in
Agent. This formatter will execute the following method on each argument it gets:
and return a result in a form of concatenated pairs of parameter identifiers and the corresponding
valueOf function result. The following parameters are returned (in order of appearance):
THIS: If the instrumented method is static, this parameter is
null, otherwise a class instance the method is executed on.
ARGS: List of all arguments of the instrumented method.
RET: Only if the instrumented method does not return void and the instrumentation is performed at the method exit.
If you are not satisfied with standard formatters and you want to extract some additional information (or make some preprocessing) you must implement your own,
custom formatter. In order to take advantage of this feature, all you have to do is set up a configuration, create a simple POJO class and implement a single method (called formatter):
You can give any name to the above method but the signature of the method must be preserved. Otherwise, it will not work.
args argument of the formatter is an array of the instrumented method arguments delivered to your formatter. These are your original application objects, not clones. When you set up the configuration correctly, the agent will inject your formatter code into the instrumented methods during the instrumentation. It can be injected in one of the two places, i.e. at the beginning or the end of the method. Note, your formatter code is executed inside your instrumented method, so make sure your formatter code generates minimal overhead. The argument
args is an array of the following objects (in order of appearance):
argsIf the instrumented method is static this element is
null, otherwise it is a reference to a class instance the instrumented method is executed on.
args[1..N]List of all arguments of the instrumented method in the same order as they appear in the method signature. These are the references to your original application objects, not some clones.
args[N+1]If the instrumented method returns void this element is
null, otherwise it is a reference to the object instance this method returns. Please note, this argument is passed to the formatter if and only if the instrumentation is performed at the end of the method.
N is the number of the instrumented method arguments.
When you set up the configuration correctly, the agent will inject your formatter code into the instrumented methods during the instrumentation. It can be injected in one of the two places, i.e. at the beginning or the end of the method. Note, your formatter code is executed inside your instrumented method, so make sure your formatter code generates minimal overhead.
If you crash your application because of badly written formatters, do not blame us. Formatters code can be written by anyone, that is why they are not supported by Flopsar Technology.
In fact, it is up to you what extra features the agent will have. You can even extend your agent installation to cover a distributed transaction tracing.
U+001E as a separator in your formatters. Otherwise, the result will not be formatted properly in
Your result should always consist of pairs of keys and values.
U+001E separates each entry in the result, which means you should always have an odd number of separators. The resulting string size cannot be greater than
8192 B, otherwise it will be truncated.
There are some tips, you should take into account when writing formatters:
- Design and implement formatters with performance in mind. If your formatters code performs poorly, obviously the instrumented methods will perform poorly as well.
try-catchblock to protect your application from any errors you can make in your formatter implementation. Otherwise, any errors inside the formatter can interfere with your application processing.
- Do not modify arguments delivered to your formatter since they are your genuine application objects. Make sure that whatever you do with them will not cause any problem to your application flow.
- Try not to use reflections, unless there is no other way.
- Try not to create too many new objects, otherwise you risk increased GC overhead.
- Deploy your formatter classes into separate jar files. This can save you a lot of trouble when dealing with class loading issues.
Suppose, you have some method:
and you are interested in some additional information extracted from the first and second arguments. Your formatter implementation can look like the one below:
No formatter implementation is supported by Flopsar Technology.
Please refer to our GitHub repository for a sample implementation of plugins.