Byteman Rule Syntax and Usage Guide

Byteman rules are defined in scripts composed of rule definitions interleaved with comment lines that start with the # character. Comments can appear before, after, or within a rule body.

######################################
# 示例规则集
#
# 单个规则定义
RULE example rule
# 规则正文中的注释行，FunTester
. . .
ENDRULE

The basic rule pattern consists of a skeleton where you specify the rule name, target class, method, optional binding, condition, and action.

# 规则骨架
RULE <规则名称>
CLASS <类名称>
METHOD <方法名称>
BIND <绑定>
IF  <条件>
DO  <动作>
ENDRULE

After the RULE keyword, the rule name can be any free‑form text containing at least one non‑whitespace character. The name is not required to be unique but helps during debugging.

The CLASS and METHOD keywords must appear on the same line; class names may be fully qualified, and method names may include parameter lists or return types. Constructors are identified with <init> and class initializers with <clinit> .

# 类和方法示例
RULE any commit on any coordinator engine
CLASS CoordinatorEngine
METHOD commit
. . .
ENDRULE

More precise matching can be achieved by providing a full signature, optionally including the return type.

# 类和方法示例 2
RULE commit with no arguments on wst11 coordinator engine
CLASS com.arjuna.wst11.messaging.engines.CoordinatorEngine
METHOD State commit()
AT LINE 324
. . .
ENDRULE

Byteman can also attach rules to interfaces by replacing the CLASS keyword with INTERFACE . The rule then applies to any class implementing the specified interface.

# 接口规则示例
RULE commit with no arguments on any engine
INTERFACE com.arjuna.wst11.messaging.engines.Engine
METHOD commit()
. . .
ENDRULE

When a rule should affect overridden methods, a caret ( ^ ) prefix before the class name tells the agent to apply the rule to the class itself and any subclass that overrides the method.

RULE trace Object.finalize
CLASS ^java.lang.Object
METHOD finalize
IF TRUE
DO System.out.println("Finalizing " + $0)
ENDRULE

To avoid multiple triggers when a method calls its super implementation, you can add a condition that checks the caller name.

RULE trace Object.finalize at initial call
CLASS ^java.lang.Object
METHOD finalize
IF NOT callerEquals("finalize")
DO System.out.println("Finalizing " + $0)
ENDRULE

Byteman provides a rich set of location specifiers that determine where the trigger point is inserted. If no specifier is given, the default is AT ENTRY . Examples include specifying a line number, a field read/write, or an invoke point.

# 位置说明符示例
RULE countdown at commit
CLASS CoordinatorEngine
METHOD commit
AFTER WRITE $current
. . .
ENDRULE

In the example above, $current denotes a local variable that is written after it is initialized in the method.

public State commit()
{
  final State current ;
  synchronized(this)
  {
    current = this.state ;
    if (current == State.STATE_PREPARED_SUCCESS) {
      . . .

Another example shows a trigger after the first read of a field:

# 位置说明符示例 2
RULE add countdown at recreate
CLASS CoordinatorEngine
METHOD <init>
AT READ CoordinatorEngine.recovered
. . .
ENDRULE

The complete list of location specifiers includes AT ENTRY , AT EXIT , AT LINE number , AT READ , AFTER READ , AT WRITE , AFTER WRITE , AT INVOKE , AFTER INVOKE , AT NEW , AFTER NEW , AT SYNCHRONIZE , AFTER SYNCHRONIZE , AT THROW , and AT EXCEPTION EXIT . Each specifier must follow the METHOD clause; otherwise, AT ENTRY is assumed.

AT ENTRY

The AT ENTRY specifier places the trigger before the first executable instruction of the method, with a special case for constructors where it is placed after the super‑constructor call.

AT EXIT

The AT EXIT specifier places the trigger at every normal return point of the method, but not at exception exits.

FunTester 原创精华 【连载】从 Java 开始性能测试 混沌工程、故障测试、Web 前端 服务端功能测试 性能测试专题 Java、Groovy、Go 白盒、工具、爬虫、UI自动化 理论、感悟、视频