Byteman 2.0.0: Bytecode Manipulation, Testing, Fault Injection, Logging

| by Bienvenido David Follow 1 Followers on Jan 30, 2012. Estimated reading time: 2 minutes |

JBoss has released Byteman 2.0.0, an open source Java bytecode manipulation tool licensed under GNU LGPL 2.1. Byteman is a Java agent which helps testing, tracing, and monitoring code. It allows developers to change the operation of Java applications, either as it is loaded or during runtime. It works without the need to rewrite or recompile the application, and can even modify Java Platform classes like String, Thread, etc.

Here are what's new with Byteman 2.0.0.

  • File and Line Debug Information. Compiled Byteman rules now contain file and line number information. This is one step in providing full debugger support.
  • TestNG Import of BMunit using @Listener. TestNG classes can now import BMUnit behavior using @Listener annotation. Previous versions required TestNG classes to subclass BMNGRunner, which causes conflicts when test classes already extend another test class.
  • Throw Error Rule. Byteman now allows for a throw Error rule even if it is undeclared by the target class.
  • Bug Fixes. The latest release has fixed eight bugs found in the previous 1.6.0 release.


Byteman uses a simple Event Condition Action (ECA) scripting language to specify where, when and how the target Java code should be transformed. Code execution continues once the injected code has been executed, although the injected code may throw an exception or force an early return. Here's an example of a simple Byteman script.


# script.btm
RULE trace main entry
IF true
DO traceln("entering main")


Here we have a script that tells Byteman to print "entering main" at the start of the App.main() method. To enable Byteman in your application, and specify the script, add the Java agent JVM argument.




Note you can also add Byteman on already running application using For more complex rules and code injection, you can use the built-in Byteman Rule Helpers, or you can create your own POJO as a plug-in.

Similar to Byteman, AOP is capable of instrumenting classes and inject code. With Byteman however, there is no need to create classes or compile code. You don't need 100% hindsight when you write your code, and can decide what code to inject at a later time. Byteman is also simpler to use and easier to change, especially for testing and ad hoc logging purposes.

To get started, you can download the Byteman binaries and specify it as a Java agent to your application. Note that Byteman requires JDK 6 or higher. Read the Byteman Programmer's Guide for in depth details. More information about this release can be found in the Byteman 2.0.0 release notes. You can also visit the official Byteman documentation and forum. Source code is available at GitHub.

Rate this Article

Adoption Stage

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Byteman by Bela Ban

I found Byteman extremely useful to test some of the edge cases of JGroups; tests that couldn't be written using only the public APIs. One example was to get thread timing off, in order to trigger an edge case that would produce an error.
The example involved 2 threads T1 and T2; T2 would be blocked and T1 would run first. T1 executed a part of the code, then it would be blocked, then T2 would execute, be blocked again, and T1 would continue.
I used sleeps to mimic this before, but the issue was that the JGroups test suite might run up to 20 tests in parallel, and thus a simple GC, or one of the threads getting enough CPU could get the timings off.
What I haven't used yet, but probably will is the capability to inject rules at runtime and remove them again later. This will be very handy when trying to dignose a running system.
Kudos to the Byteman team !

Re: Byteman by Andrew Dinn

Thanks for posting about the Byteman project, I'd just like to correct a few details though.

Byteman does indeed include file and line number info into injected rule code but this is only one step in providing full debugger support. A couple of contributors are working on extending an IDE/debugger (specifically, Eclipse and IntelliJ Idea) to support both Byteman development and execution but neither of them is yet complete.

Byteman rules can be used to throw unexpected exceptions and errors in both application and JVM runtime code -- a very useful feature in both unit and integration tests. Indeed it can also be used to bypass method execution and return synthetic return values. However, code injected by Byteman is type-checked and type-safe, hence it will not break method contracts. So, you can only throw an exception declared by the method (or, of course, a RuntimeException or Error) and you can only return a value whose type matches the method return type.

Re: Byteman by Bienvenido David

Thanks Andrew. I've amended the text.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

3 Discuss

Login to InfoQ to interact with what matters most to you.

Recover your password...


Follow your favorite topics and editors

Quick overview of most important highlights in the industry and on the site.


More signal, less noise

Build your own feed by choosing topics you want to read about and editors you want to hear from.


Stay up-to-date

Set up your notifications and don't miss out on content that matters to you