org.brutusin:instrumentation

Extensible java agent framework to instrument programs running on the JVM

License

License

GroupId

GroupId

org.brutusin
ArtifactId

ArtifactId

instrumentation
Last Version

Last Version

1.0.0
Release Date

Release Date

Type

Type

jar
Description

Description

org.brutusin:instrumentation
Extensible java agent framework to instrument programs running on the JVM
Project URL

Project URL

https://github.com/brutusin/instrumentation
Source Code Management

Source Code Management

https://github.com/brutusin/instrumentation

Download instrumentation

How to add to project

<!-- https://jarcasting.com/artifacts/org.brutusin/instrumentation/ -->
<dependency>
    <groupId>org.brutusin</groupId>
    <artifactId>instrumentation</artifactId>
    <version>1.0.0</version>
</dependency>
// https://jarcasting.com/artifacts/org.brutusin/instrumentation/
implementation 'org.brutusin:instrumentation:1.0.0'
// https://jarcasting.com/artifacts/org.brutusin/instrumentation/
implementation ("org.brutusin:instrumentation:1.0.0")
'org.brutusin:instrumentation:jar:1.0.0'
<dependency org="org.brutusin" name="instrumentation" rev="1.0.0">
  <artifact name="instrumentation" type="jar" />
</dependency>
@Grapes(
@Grab(group='org.brutusin', module='instrumentation', version='1.0.0')
)
libraryDependencies += "org.brutusin" % "instrumentation" % "1.0.0"
[org.brutusin/instrumentation "1.0.0"]

Dependencies

compile (1)

Group / Artifact Type Version
org.ow2.asm : asm-all jar 5.0.3

test (2)

Group / Artifact Type Version
junit : junit jar 4.10
org.brutusin : commons jar 1.0.0

Project Modules

There are no modules declared in this project.

Check out https://github.com/ShiftLeftSecurity/bctrace instead. A more mature and stable version of this project

org.brutusin:instrumentation Build Status Maven Central Latest Version

An extensible java agent framework that instruments programs running on the JVM (modifying the bytecode at class loading time), with the purpose of capturing method invocation events (start, finish, errors ...) and notifying custom listeners.

Table of Contents

How it works

The java instrumentation package introduced in JDK1.5, provides a simple way to transform java-class definition at loading time, consisting basically in a byte[] to byte[] transformation, by the so called "java agents".

This module provides an agent (org.brutusin.instrumentation.Agent) that creates an execution listener instance (from the name of a concrete class extending org.brutusin.instrumentation.Interceptor passed from the JVM agent arguments) and, making use of the ASM library, introduces a series of instructions in the method definitions of the classes to be loaded (classes and methods can be skipped) to notify these execution events to the listener.

From a simplified point of view, the dynamic transformation turns a method like this:

public Object foo(Object bar){
    return new Object();
}

into that:

public Object foo(Object bar){
    onStart(bar);
    try{
        Object ret = new Object();
        onFinished(ret);
        return ret;
    } catch(Throwable th){
        onThrowable(th);
        throw th; // at bytecode level this is legal
    }
}

allowing your custom listener to be notified.

Maven dependency

<dependency>
    <groupId>org.brutusin</groupId>
    <artifactId>instrumentation</artifactId>
</dependency>

Click here to see the latest available version released to the Maven Central Repository.

If you are not using maven and need help you can ask here.

Example

See logging-instrumentation for a complete working example.

Implementation

Create the following listener implementation:

package mypackage;

public class MyInterceptor extends Interceptor {

    @Override
    public void init(String arg) {
        System.out.println("Interceptor args: " + arg);
    }

    @Override
    public boolean interceptClass(String className, byte[] byteCode) {
        return true; // all classes can be intrumented
    }

    @Override
    public boolean interceptMethod(ClassNode cn, MethodNode mn) {
        return true; // all methods are instrumented
    }

    @Override
    protected void doOnStart(Method m, Object[] arg, String executionId) {
        System.out.println("doOnStart " + m + " " + executionId);
    }

    @Override
    protected void doOnThrowableThrown(Method m, Throwable throwable, String executionId) {
        System.out.println("doOnThrowableThrown " + m + " " + executionId);
    }

    @Override
    protected void doOnThrowableUncatched(Method m, Throwable throwable, String executionId) {
        System.out.println("doOnThrowableUncatched " + m + " " + executionId);
    }

    @Override
    protected void doOnFinish(Method m, Object result, String executionId) {
        System.out.println("doOnFinish " + m + " " + executionId);
    }
}

Packaging

Create a fat-jar with the previous class and its dependencies. Add the following attribute to the manifest of the agent JAR:

Premain-Class: org.brutusin.instrumentation.Agent

Suppose this jar to be named myagent.jar

JRE launching

Run (at least JRE 1.5) the desired java application with the following JVM options: (suppossing myagent.jar located in the working directory)

-javaagent:myagent.jar=mypackage.MyInterceptor;an_interceptor_optional_parameter

Main stack

This module could not be possible without:

Brutusin dependent modules

Support, bugs and requests

https://github.com/brutusin/instrumentation/issues

Authors

Contributions are always welcome and greatly appreciated!

License

Apache License, Version 2.0 http://www.apache.org/licenses/LICENSE-2.0

org.brutusin

brutusin.org

Best friendly software libraries. In loving memory of Brutus

Versions

Version
1.0.0