This tutorial introduces the Byteman framework which is part of the JBoss Ecosystem, showing how it can be used to increase your productivity.

Byteman is addressed into the documentation as a tracing, debugging and testing tool which can be used on any Java application.

You might wonder why do we need to learn another tool for tracing and debugging applications ?

Let me tell you with a simple example why ByteMan can be a needful resource for your applications. Supposing that you are hitting a NPE in your Web application. The first and most obvious fix would be either starting a remote debugging session (which may not be always possible) or add some logs in the critical points. In most cases you will resort to modify your code, dedeploy you app and, once fixed the issue, disable or remove the logs.

Here's what you can do with Byteman: inject a rule into your code -without any change in your code- in which you can directly refer to app/runtime data & types. In other words you can write a simple rule which says:


The rule will inject dynamically the code in your application (in this case into the application server) and execute the rule. Once you don't need it any more, just tell to the JVM that you don't need anymore firing ByteMan rules.

Ok. Now let's get our hands dirty. Download Byteman from the source.

In order to start Byteman you need to provide the path to Byteman libs to the -javaagent option, specifying as well the path to the rule file.
For example on windows you would code (You need to define BYTEMAN_HOME as system environment variable):

java -javaagent:%BYTEMAN_HOME%\lib\byteman.jar=script:samplerule.btm com.sample.ByteManTest                        

On Linux

java -javaagent:${BYTEMAN_HOME}/lib/byteman.jar=script:samplerule.btm com.sample.ByteManTest    

A rule file is built-on the following skeleton:

RULE <rule name>
CLASS <class name>
METHOD <method name>
BIND <bindings>
IF   <condition>
DO   <actions>

The RULE keyword identifies the rule name (Rule names do not have to be unique but it obviously helps when debugging rule scripts if they clearly identify the rule).
The CLASS can identify a class either with or without the package qualification.
The METHOD name can identify a method with or without an argument list or return type.
The BIND specification ca be used to bind application variable into rule variables which can subsequently be referenced in the rule body.
The IF section can be ovbiously used to check Rule conditions
The DO section is the Rule action which can be a rule expression, return values or throw action

Let's try an HelloWorld example:

package com.sample;

public class SimpleTest  

         public static void main(String[] args)

                 System.out.println("Entering main");


And here's a simple rule, name it example.btm:

 RULE trace main entry

CLASS com.sample.SimpleTest


IF true

DO traceln("Byteman detected you are entering main")


As you might guess, here we are defining a rule named "trace main entry" which is fired on main method of the class com.sample.SimpleTest, as soon as the method is entered. In all conditions (IF true) a trace line is printed on the console.

Here's the Eclipse launch configuration for it.

byteman tutorial byteman tutorial byteman tutorial

By running this example you would just see a dummy message on the Console which prints
Byteman detected you are entering main