Developing a JVM Agent for bytecode instrumentation with Javassist – Part 1

May 15, 2013

Hi, this is the first part of a blog post entitled “Developing a JVM Agent for bytecode instrumentation with Javassist“.

In this first part I’ll walk you through the basics of what is/what’s the purpose of a  JVM agent, bytecode instrumentation, we’ll also talk a bit about the available APIs for developing an agent and show how to use the APIs to create an agent for bytecode instrumentation

In the next parts of this post I’ll talk about what is Javassist (a library for bytecode manipulation which we’ll use), how to use it by looking at examples and it’s API, then finally by combing Javassist with JVM Agent API we’ll have a fully working agent capable of doing amazing things with bytecode instrumentation.

All source and compiled code (jars) are available on my github repository

What are JVM/Java Agents?

A JVM Agent is a program that runs in same process as the JVM.
An agent can receive events from the JVM and query it for information on JVM itself or the application running in it and control or alter the application.

Agents are commonly used by tools in order to assist the development and monitoring of applications running in the JVM.


What is bytecode instrumentation?

Bytecode instrumentation in a nutshell is altering the compiler generated bytecode for a class, with it you can all sorts of nifty cool stuff such as calculating how long does it take to a method to be executed, alter its execution flow etc – possibilities are endless when you can add/change bytecode of an application, and since we are dealing with bytecode you can do all this without the need of the applications source at all.

Bytecode instrumentation is not the only thing JVM Agents can do, in fact they can do all sorts of interesting and crazy stuff like iterating over all reachable objects in the JVM or get notified when resources needed by the JVM (like memory, threads) get exhausted and many many other things, but still Instrumentation is one of the most useful and interesting features as it can leverage a lot of flexibility and power over the application.


Available APIs when creating JVM Agents

Starting with Java 1.5 JVM TI (Java Virtual Machine Tool Interface) was introduced as the main API for monitoring tools and as a substitute for JVMPI (Java Virtual Machine Profiling Interface) and JVMDI (Java Virtual Machine Debug Interface, which were considered at the time quite complex, unstable, unreliable and poorly documented.

The JVM TI was defined by JSR-163, it’s a native interface of the JVM, hence requiring you to write the agent’s code in C/C++ and also use JNI (Java Native Interface), JSR-163 was a great success and JVMTI is commonly used by all sort of vendors for profiling and monitoring tools, but the JVM TI was not the only interface defined by the JSR-163 for the release of Java 1.5, they also defined among other things the Java programming language in-process instrumentation API (java.lang.instrument) which as the name pretty much says it allows you to instrument bytecode on the JVM by working directly with a Java API.

Not only is usually simpler to work with a Java interface than a native interface, it is much easier to work with bytecode using one of the various existing Java tools dedicated to it. (such as ASM, Javassist etc.)

One thing should be noted, this Java API is not the JVMTI ported to Java, while JVMTI also allows instrumentation the java.lang.instrument API allows only instrumentation, and it is widely used for this, but it does substitute in any way the other existing features of JVM TI.

Since our goal here is bytecode instrumentation it is much better to stick with Java API since dealing with bytecode within Java itself is much easier,  part due to the large availability of well know open source libraries (such as Javassist, ASM, BCEL) that already tackle this problem.


The basics of the java.lang.instrument API

So let’s get down to the basics of writing an instrumentation agent in a few quick steps.

Step #1 – The Agent Premain Class

The main agent class has to implement something similar to the public static void main method if we want to load the agent during the JVM start-up procedure, it’s the premain method, and it has two possible signatures:

public static premain(String agentArgs, Instrumentation inst);

public static void premain(String agentArgs);

These are executed in the above order of availability, there’s also the agentmain method that gets called if an agent is loaded after the JVM starts, but this approach won’t be tackled on this post.

In our case today, we’ll be using only the first method signature:

public static void premain(String agentArgs, Instrumentation instrumentation);

That’s because we need the Instrumentation argument that’s passed along by the JVM to the agent

The Instrumentation object passed along it’s a sort of Instrumentation Service exposed by the JVM to the agent so that he can among other things register one or more ClassFileTransformer that allows us to redefine a class bytecode.

So that’s what we have to do in our premain agent class, register our ClassFileTransformer, this would look something like this:

package my.agent;

import java.lang.instrument.Instrumentation;

public class MyAgent {

    //agent start-up hook
    public static void premain(String args, Instrumentation inst) throws Exception {
    	System.out.println("Loading Agent..");
        inst.addTransformer(new MyTransfomer());



Pretty straight-forward right?

Ok, moving on then,

Step #2 – The ClassFileTransfomer

So as I’ve mentioned ClassFileTransformer(which MyTransformer is an implementation of) allows us to transform/redefine a class bytecode before it gets defined by the JVM


ClassFileTransformer is an interface that requires us to implement the following method:


byte[] transform(ClassLoader loader, String className, Class<?> classBeingRedefined, ProtectionDomain protectionDomain, byte[] classfileBuffer);

Once we register our own ClassFileTransformer by doing:

inst.addTransformer(new MyTransfomer())

The JVM will take care of calling up the transform method of MyTransformer once a class starts its definition (or redefinition) process.

Here follows a dummy implementation of MyTransformer that will just print out the name of every class that gets loaded into the JVM.

package my.agent;

import java.lang.instrument.ClassFileTransformer;
import java.lang.instrument.IllegalClassFormatException;

 * Dummy sample ClassFileTransformer
 * @author rafael oltra

public class MyTransfomer implements ClassFileTransformer {

	public byte[] transform(ClassLoader loader, String className,
			Class<?> klass, ProtectionDomain domain, byte[] klassFileBuffer)
			throws IllegalClassFormatException {
		System.out.println(className + " is about to get loaded by the ClassLoader");

		return null;


Right now the only thing our ClassFileTransformer is doing is printing out each and every class that gets loaded by the ClassLoader, don’t fret! This is just a way to show the agent API, we’ll get this guy doing way more interesting things soon

We’ll come back to this method again once we go over on how to use Javassist to do bytecode instrumentation, but one thing you should now is that the return value of this method should be the class altered bytecode in a byte array or null in case of no instrumentation going on.


So we have a the premain class which loads the dummy implementation of an agent via the ClassFileTransformer API,

What we need now is to create a valid MANIFEST.MF file for our agent, the reason for this is because not only we need to tell the JVM the JAR that contains the agent (which we do it in the next step), we also need to tell it what is class of the agent that contains the premain method among other things, for our agent the following MANIFEST file should be enough:

Manifest-Version: 1.0
Agent-Class: my.agent.MyAgent
Can-Redefine-Classes: true
Can-Retransform-Classes: true
Premain-Class: my.agent.MyAgent

Make sure to put the MANIFEST.MF file the META-INF folder of the JAR!

Step #4 – Building the agent

Our agent in it’s current state does not have any external dependencies, you can build it any way you feel like it as long you have the MANIFEST.MF file in the META-INF folder.

If you don’t feel like building it you can download the JAR file with everything already set from my github page.

Final Step! – Running the agent within the JVM – How to and output

To make the agent actually run inside the JVM you need to pass the -javaagent argument to the JVM, the way this works is that you execute your java application usually in the same way but passing the -javaagent argument with the location of the JAR with the agent when executing the JVM binary file, for instance:

java -javaagent:PATH_TO_AGENT.jar -jar myapplication.jar

Since in this example we are printing out each and every class that gets loaded, I suggest loading the agent in a simple application so you won’t get flooded with name of classes in your console window.

If you don’t want to run this agent in your own application (or it’s just too much trouble) I’ve built a very simple demo application for this post, that does some basic use of JDK, (it simply tries to open a connection to, it is also available from my github repository here, it’s the dummy-app.jar.

Since we are printing out every class that gets loaded, this might slow your application down when starting up if a lot of classes are loaded (for example when running it within a application server, that definitely loads a lot of stuff specially on start-up), since this is just a sample agent there would not be much use of putting it up with a real application.

To run the agent with this sample application you just have to place both jars in the same folder and run it like this:

java -javaagent:sample-agent-pt1.jar -jar dummy-app.jar

then you should see printed to your console a few dozen lines like this (this output might vary slighty depending on the version and vendor of your JVM)

Loading Agent..
dummy/DummyMain is about to get loaded by the ClassLoader
Starting DummyApp
This is so we'll demonstrate our agent printing out the classes that get loaded by the ClassLoader
Trying to hit
sun/net/www/protocol/http/Handler is about to get loaded by the ClassLoader
sun/net/www/protocol/http/HttpURLConnection is about to get loaded by the ClassLoader
java/net/HttpURLConnection is about to get loaded by the ClassLoader
java/util/logging/Logger is about to get loaded by the ClassLoader
java/util/logging/Handler is about to get loaded by the ClassLoader
java/util/logging/Level is about to get loaded by the ClassLoader
java/util/logging/LogManager is about to get loaded by the ClassLoader
java/util/logging/LogManager$1 is about to get loaded by the ClassLoader
java/beans/PropertyChangeSupport is about to get loaded by the ClassLoader
java/util/logging/LogManager$LogNode is about to get loaded by the ClassLoader

One interesting thing to notice is that the main-class for this dummy-app.jar is DummyMain, and it’s the first thing that gets loaded into the JVM, the rest of the classes are the stuff that get’s loaded once we try to do this:

URL url = new URL("");

Next part!

Okay, this concludes our first part of this sort of tutorial on “Developing a JVM Agent for bytecode instrumentation with Javassist”!

As I mentioned before all source code and ready to use JARs are available at my github repository.

For the next post we’ll discuss how to use Javassist and improve the agent so that it does more interesting stuff, like deploying it on an application server (like Tomcat, JBoss, Weblogic) to gather info from Servlets and EJBs.

If you have any comments, suggestions or corrections please feel free to leave a comment or mail me, thanks!


JVM TI Documentation
java.lang.instrument Javadocs

posted in JVM Bytecode Instrumentation by Rafael Oltra

Follow comments via the RSS Feed | Leave a comment | Trackback URL

16 Comments to "Developing a JVM Agent for bytecode instrumentation with Javassist – Part 1"

  1. Alex wrote:

    with this agent and API is possibel to change class at runtime in a JVM in a application server ?

  2. Rafael Oltra wrote:

    Yes Alex, by instrumenting the class bytecode, I’m finishing the second part of this post where I’ll discuss how to do it by using Javassist

  3. Ramon wrote:

    are classes defined in agents jar visibilies to the client application?

  4. Rafael Oltra wrote:

    Hi Ramon, the classes defined by the agent are loaded by the System Classloader, if the application classloader inherits the system classloader then they are visible

  5. wrote:

    This is very interesting, You are a very skilled blogger.
    I have joined your feed and look forward to seeking more of your great post.
    Also, I’ve shared your site in my social networks!

  6. Ram wrote:

    Hi Rafael,
    Very informative and well written post.
    I am trying to learn these things and hence found your post very useful. Thank you. Looking forward to next part.

    However I do have two queries. I would be glad if me could help me with these:

    1. Is it possible to build a java agent which can inspect/control all classes running currently in the JVM?

    2. Is it possible to build a java object as a composite of objects(sub objects), so that these sub-objects can evolve dynamically updating their behavior on the fly while the main java object is still running?

  7. best facebook fan pages wrote:

    So whether it is iinternal links oor external links – it always helps.
    If you are selling lots of prroducts on your website then you must categorize it so visitor can easily navgigate andd able
    to seee every images of tthe product properly. When’s the
    first time you remember taking immediate action on something
    yourself. Business card financial commitment is value the traffic it can carry.

    Of course you have every reason to be unhappy at the moment, but make sure that you deal with it in private so that she does not see it.
    It is a common sense that if two websites promoting the
    same business idea, the one which is promoted more on social networking sites like Facebook progress
    more as compared to the other one. To buy Facebook likes may
    seem like a desperate attempt to many people at establishing a reputation, increasing
    popularity and creating a demand for your business. If your page is based
    around a service you provide, it’s best to
    have a picture of you. However, obviously, the main goal is that you
    need to get people to “like” your page–this should be obvious.
    The problem is most average social networkers do not have anything to sell.
    This may move from exclusive insights about your products or services, Facebook only discounts as well as
    flash discounts that last not many hours or extra content that only
    people who have liked your Facebook page will access.
    Of course, you’ll have to talk with your baand mates to deide whether
    thisis a good approach for you. People in many countries use Facebook and the
    larger your fanbase and more diverse it is, your prducts will be known worldwide.

    However, many entrepreneurs are daunted by tthe procss orr concerned hat they do not hafe
    the necessary skill to produce a newsletter regularly.
    When the dust settled, it suowed that the new technology wass nothing to be feared.
    Also noye how the top recommendation links to hot content, and specifically a product detail page with an.
    Youu are able too increase your client base throuugh visibility of being.
    Hence, you shuld make the page attrawctive enough that it draws attentiin and arouses intereest of the users.
    Make it a place where people can feel comforttable discussing things.
    Why Do People Cick 3 Billion Facebook Like Burtons Each Day.

  8. facebook page fan adder wrote:

    Then tell yur friends about the photographs and assk them too
    tag themselves with those pictures. Mix it up annd post things that aree current aand you’d be
    suprised how much action you recieve. They
    don not require high end hardware or software; in some cases, you may
    have to download certain plug-ins, though.
    While this may seem a little Grinchy, it’s nonetheless very odd tto
    regularly post ‘Love X. A website is the backbone of your business and is like the face of
    your business and having a website adds a lot of credibility to
    any company. Click on it, then scroll down to ‘Privacy Settings’.
    What seemed to be only for teens is now proving extremely useful not
    only for individuals, but also businesses looking to connect with customers.
    In fact, they’re quite happy to visit your site as
    long as you offer them something of interest, so give it a try.
    He invites you to visit his websit for fdee video,
    audio and software training on how tto build a verey affordable home
    business at yokur own pace. Onlinbe communities can also be a great free advertising option.
    However, when the selection is too wide and poorly constructed, you can’t seem to focus on anyone.
    So how to get more fans on Facebook, followers on Twitter and other
    social ties. People in many countries use Facebook and the larger your fanbase and more diverse it is, your products will be
    known worldwide. Many newbies do not fully grasp the concept of internet marketing and fail in their marketing campaign.
    The Search Engines such as Google, Yahoo, and Bing are literally indexing tools to help
    you search, find and list the information. could also make use of the photo category characteristic on fb
    to obtain more Facebook fans. For instance, for Stumble – Upon,
    it is possible to exhibit the quantity of stumbles you’ve byy now received for your website.

    Thhis change had a lot of impact in the cknduct of Internet
    marketing. Like many people, I gained some weight over thhe
    holidays. When setting uup a profile many people jjust imagine that it.

  9. get more facebook page likes wrote:

    Therefore, ensure that your website is properly designed in order to
    give thhe right signs among the customers. logo couldd hen be posted
    on the Product Shops Facebook page allowing users too tag themselves.
    If he see that yoou aree calm and happy he will automatically be attracted to youu agsin and end
    up regretting his decision to dump you. You can also use a group and a
    page iin tandwm to keep users interested and if it makes sense for your business.
    Of course you hafe every reason to be unhappy at the moment, but make sure that yoou deal with it in
    private so that she does not see it. We allow you to pick and
    choose who you wsnt to follow, like, Friend, view oor visut aand
    skip those whho you’re not intersted in. Whilst any tentative approach into arenas like Facebook are of course likely to allow one
    to learn from their mistakes, something has to be said
    for missing an opportunity to be great, to capture the
    attention of your customers once and have them be. The subject can help you to know what
    you think or feel about starting a business. Many companies
    run competitions around the awareness of your business page.

    Moreover, joining the group is considered to be the best
    way for increasing the number of likes on the facebook.
    75 billion pieces of content on Facebook on any given day.
    You can also take the route of using other social networking sites.
    The higher the number of people or facebook users liking this
    page, higher is the probability of converting of viewers into consumers.
    Person should not pay fee for creating any account on
    the face book. 33- Remind your buddies to Like and Discuss Your
    Page. The whole getting-people-to-’Like’-your-Facebook-Page conundrum can be a serious buzz kill in the midst of your enthusiasm to embark on using social media to
    promote your business online. Twitter is one of the hot social networking sites that keeps everyone
    connected. If you do not have ‘like’ icons so people can quickly hit
    them, then by all means get them on your site. Create contents, discussions and participate with your own thoughts.
    When you dated your ex you were a big huge part of his life.

  10. facebook fan page likes wrote:

    Users can choose from 100+ frames, backgrounds, texts, andd stickeers to insert
    them in collages to make collages look more unique. Google
    gives a higher weighting to links to and from its oown social networking applications.

    When youu use Facebooik for marketing purposes, you must have a page that stands apart from the crowd.
    But again, the engagement of those new fwns is noot evident.

    If you aren’t prepared to do anything else with Facebook on a daily basis, then the one thing
    you must do is check your home page to see what recent activity your contacts have
    been getting up to, here you can comment on anything you
    like and offer support and help the second it may be needed.
    You can also get the cost per click down to just pennies when you target properly.
    The report also reveals that the purchased ads also increased the number of
    fans on the foreign language pages on Facebook.
    Saying the right thing at the right time also grabs the girl’s attention.
    Make iit super simple bby adding a “find us on Facebook” icon to your website and other communications.
    The Adbentures oof Scuba Jack is dedicated to providing high quality
    educational dvds for kids. Almost evrry second persopn is addicted too
    facebook. Way to get the most out of Facebook:
    Create a fan page. Firm like Fast – Facebook – Fanns deliver out serious Facebook enthusiast web page invites to people who are lively on Facebook and may
    have an interest in your products. The Neww
    England Post reported that the gpvernment aalso used Twitter to report oon storm damage and reports listing which roazds
    were cloosed ddue to the hurricane. buut if she’s the one making most of the contact,
    you’re welll on thee path to dating your ex again.
    If you don’t get the desired end result or the number of likes promised was not
    shipped you can get your money back. These tabs allow you to organize the
    information on your Facebook page for your visitors in a
    way that improves your business. In her article, Elizabeth
    Cohen offers five suggestions:. Now that you’ve learned hoow to avoid risks and
    understand tthe ins and outs of somme of the
    most poplular social netgworking sites, it’s time to
    go ahead and learn how you can market your business
    or service through these popular sites. Only add at the most around 30 people a day, as
    this could also make you appear to be spamming (and nobody likes

  11. sites like facebook wrote:

    So whether it is internal liunks orr external links – iit aways helps.
    Post regularly and always respond to answers or comments.

    Youu answer any uestions thgat are asked of you about
    the business you’re running. As the Timeline allows for more images with the profile picture plus the
    cover photo helps enrich the Facebook experience.
    Very first, locate an attractive layout along with content for the web page, and next utilize facebook apps to make it more fun as well as interactive.

    Weekly World News reports that they had tremendous success with this (they claim a gain of 37,
    066 users in only four days). Facebook makes it very easy to promote Facebook fan pages.
    This information can be misleading or wrong though, based
    on the fact that the individual is in control of it. New studies reveal
    that with the changes in the Facebook pages, people tend to read the pages on weekends than on weekdays.

    In order for Facebook to have the most impact, it must be set up correctly.

    s happening in Sussex and the regular posting of
    photos both in the shop, at local farms, at food fayres and school
    fates. But whenever a girl breaks up with you,
    there’s one thing most guys don’t realize. The business
    world is often dominated by men and this has long been the case, recently this issue has raised debates in parliament about what
    could be done to promote more women into UK boardrooms.
    Some even are designed to look amature just to put the visitor at ease.
    It is must to keep in mind your core target audience while creating your page.
    But may, on the contrary, the integration of social media online
    marketing strategy is as difficult as it seems. If the user doesn’t show up as a mutual
    friend, it is likely they have been deleted.

    the social network staryed weeding out bogus
    Likes caused by compromised accounts, ddeceived users, malware
    or purchased bulk Likes, it confirmed to Tech – Crunch.
    These providers cann supply youu many quawlity services. Moreover, this will help youu too better understand what people
    are searchbing for on you blog or site.

  12. get free food wrote:

    Plenty off agents are positioned on online with superior
    guarantee. If you are selling loots of products on your website then you must
    categorize it so visijtor can easily navigate
    and aboe to see every images of the product properly. This mmay make your
    debt repayment more relaxed and also saave you some time.

    As we discussed earlier that face book iss considered to be thee successful and best social media soo if person used the right andd
    best techniques for increasing the likes on the face book then person can increase the likes ass well
    as fans on tthe face book. Weather Channel gives accuraate reports of current weather
    conditions, including temperature, wind chill factor,
    UV index, and visibility. Once you connect and slowly build a friendship, it is only
    a matter of time before your Facebook crush cuanges their relationship status to
    “in a relationship with” YOU. Once upon a time, the pre-Facebook busines word used
    customer complaint forms or a customer hotline to interact with
    customers. If not, you may want to consider whether yours is
    a sharedd emotion. When it comes tto Facebook, for example, iff you do
    not knokw where and when to make a button on your website or blog,there’s someone out there
    who shares your pain. A marriage ceremony celebration is
    both equally enjoyable and demanding. Remember, a Facebook fans page is an extension of your
    website. It’s a clever wiidget to get more
    fans on Facebook likes, because it allows your external audience to know of their presence on Facebok likes and encourage them to join you
    there. The business world is oftern dominated by men and this has long been the case, recently this issuhe has raised debates in parliament about
    what could be doine to promote more women into UK
    boardrooms. Likeable Media,an advertising agency oout of NYC also has a simple, graphics-oriented page that doesn’t make you feel forced into liking their brand.
    And yes, social media has redefined how our customers produce and consume
    photographs. You want to use updates in your social network as
    promotional items. Don’t swutch too soon to ‘In a relationship’
    or ‘Single’. DO NOT dismiss them as soon as they comply with
    you back again. This knowledge will bbe secured from the social links that area unit enclosed within the social media sites, and wherever the regular links from ancient link buiding efforts haven’t got.
    In this article we will tell you how to get as more “Likes” on the page of blog or site in a social network as possible.

  13. Ilana wrote:

    Higher performance vehicles cost more to insure as they’re more cheap auto insurance quotes attractive to thieves.
    Depending on how grave your driving records and maybe take a state certified safe driving course, then you can
    solve your problem through the internet. We call this alopecia areata, but many people live
    long beyond that cap. Your spouse thinks you’re clever, and your driving record per infraction based on state law,
    cheap auto insurance quotes as well as preservation means productivity.

  14. Florentina wrote:

    If you are a first time parent, and maybe even if
    you have several kids already, you may have unresolved issues about baby’s
    sleep. Well keep reading and together we’ll hit it out of the park.
    At just over 5500 miles long it is the longest continuous construction
    in the entire world.

  15. Binh Nguyen Thanh wrote:

    Thanks, nice post

  16. maximum shred free trial wrote:

    Hello to every , since I am truly keen of reading this blog’s post to be updated regularly.
    It includes pleasant data.

Leave Your Comment

Powered by Wordpress and MySQL. Theme by Shlomi Noach,