byteman

Byteman — Runtime Java Code Injection

Overview

Byteman is a Java agent that injects code into running applications without recompiling. Use it to:

• Trace method calls, arguments, return values
• Read private fields, internal state
• Mutate state — change field values, force return values, throw exceptions
• Verify behavior — assert methods were called, check ordering
• Debug production-like issues — simulate failures, delays, race conditions

Announce at start: "I'm using the byteman skill to inject diagnostic/mutation code into the Java process."

Setup via JBang

No manual Byteman download needed. JBang has a Byteman catalog that handles everything — agent JAR resolution, classpath, boot classpath — all via --javaagent.

The Key Pattern

# Run ANY jar/artifact/script with Byteman attached:
jbang --javaagent=byteman@bytemanproject myapp.jar
jbang --javaagent=byteman@bytemanproject org.group:artifact:version
jbang --javaagent=byteman@bytemanproject alias@catalog

# With a Byteman rule script:
jbang --javaagent=byteman@bytemanproject=script:rules.btm myapp.jar

# With a REMOTE rule script (jbang 0.104+):
jbang --javaagent=byteman@bytemanproject=script:%{https://url/to/rules.btm} myapp.jar

# With boot classpath (needed for injecting into JDK classes):
jbang --javaagent=byteman@bytemanproject=boot:$(jbang info classpath byteman@maxandersen),script:rules.btm myapp.jar

That's it. No BYTEMAN_HOME, no manual JAR downloads, no java -javaagent:... wrangling. JBang resolves Byteman, installs Java if needed, and runs everything.

For Non-JBang Use (manual JAR path)

If you need the raw JAR path for use with plain java or Maven:

BYTEMAN_JAR=$(jbang info classpath org.jboss.byteman:byteman:4.0.25)

Byteman Rule Syntax

Byteman rules are written in .btm files using a simple DSL:

RULE <descriptive name>
CLASS <fully.qualified.ClassName>       # or INTERFACE for interface methods
METHOD <methodName>[(parameter types)]  # optional parameter types for overloads
AT <location>                           # WHERE to inject (see locations below)
HELPER <helper class>                   # optional, defaults to org.jboss.byteman.rule.helper.Helper
BIND <variable bindings>                # optional, bind variables for use in conditions/actions
IF <condition>                          # guard condition (use TRUE for always)
DO <action>                             # what to do
ENDRULE