JBoss Community

Welcome to the Byteman Project

Byteman is a tool which simplifies tracing and testing of Java programs. Byteman allows you to insert extra Java code into your application, either as it is loaded during JVM startup or even after it has already started running. The injected code is allowed to access any of your data and call any application methods, including where they are private. You can inject code almost anywhere you want and there is no need to prepare the original source code in advance nor do you have to recompile, repackage or redeploy your application. In fact you can remove injected code and reinstall different code while the application continues to execute.

The simplest use of Byteman is to install code which traces what your application is doing. This can be used for monitoring or debugging live deployments as well as for instrumenting code under test so that you can be sure it has operated correctly. By injecting code at very specific locations you can avoid the overheads which often arise when you switch on debug or product trace. Also, you decide what to trace when you run your application rather than when you write it so you don’t need 100% hindsight to be able to obtain the information you need.

When testing your application you can use Byteman to inject faults or synchronization code, causing your application to perform unusual or unexpected operations required to exercise a test scenario. Byteman provides a library of built-in functions which allow you to do anything from generating simple error conditions to propagating complex error flows which require coordinated actions in different parts of your application. However, you are not limited to these operations. You can inject almost any Java code into your application so long as the classes you refer to are in scope at the injection point. You can also replace or extend the available built-in functions by supplying a POJO (plain old java object) as a plugin. So, Byteman makes it easy for you to program even the most complex test scenarios.

Byteman works by modifying the bytecode of your application classes at runtime. Since it only needs access to bytecode this means it can modify library code whose source is either unavailable or unable to be recompiled. This even includes the Java code which forms part of the Java virtual machine, classes such as String, Thread etc. So, with Byteman you can trace what the JVM is doing on behalf of your application code or cause JVM classes like FileInputStream or Map to throw exceptions when your application calls them.

Byteman uses a clear, simple scripting language, based on a formalism called Event Condition Action (ECA) rules to specify where, when and how the original Java code should be transformed. An event specifies a trigger point, a location where you want code to be injected. When execution reaches the trigger point the rule’s condition, a Java boolean expression, is evaluated. The Java expression (or sequence of expressions) in the rule action is executed only when the condition evaluates to true. Normally execution continues from the trigger point once the inejcted code has been executed. However, rule actions may also throw an exception or force an early return from the triggering method.

Byteman 2.2.0.1 is now available for download under the GNU LGPL. It requires a JDK 6 or higher JVM. The release includes a user guide which documents the scripting language and explains how to use byteman to inject faults or tracing and monitoring code. There is also a tutorial showing you how to get started with Byteman and a follow-up tutorial explaining how to use Byteman to perform fault injection testing. The 3rd Byteman tutorial details how to configure the maven plugin which automatically checks the validity of your Byteman rule scripts as part of the maven build. See the documentation page for more information.

The Byteman Community

Byteman is a community project so feedback and contributions are welcome. The project provides a community user forum where you can report any problems you encounter when trying to obtain, build or use Byteman. There is also a developer forum which should only be used by those who wish to contribute to discussions of the design and implementation of Byteman or to suggest enhancements and new features.

All changes made to Byteman are managed using the JIRA issue tracker system. This includes both unresolved issues scheduled for upcoming releases and issues which have been fixed by the current or previous releases. Before reporting an issue in the user forum please search JIRA and the user forum to see if it has already been notified.

JIRA is also used to record scheduled development tasks and new, nice-to-have features to be added to Byteman. If you wish to propose such a feature or vote for its early addition or for resolution of a issue which is important to you then your feedback will be welcome.