[BTrace Bits: Part 1] Templated variables in BTrace

Foreword

There have been a fair number of additions to BTrace in the last year or two which, I am afraid, might have slipped the user attention as they were not given a lot of publicity at the time they were introduced.

The followup series of mini blog posts covering the potentially obscure but cool functionality available in BTrace - whimsically named 'BTrace Bits' - intends to fix it.


Ok. Let's start with something simple.

---

[1] Templated Variables

Since version 1.3.11 it has been possible to use template variables in the probe declarations. This allows delayed configuration at deployment time and makes the probe definition much more flexible.

A template variable has a value defined at deployment time and can be referenced using ant-like format - eg. ${refresh}. The variable value will be resolved as a plain string and will be the subject of any conversions necessary for the corresponding place of use.

Example: Templated uptime probe

The following probe will run the uptime check each uptime_period_ms milliseconds. 

@BTrace
public class Uptime {
    @OnTimer(from  = "${uptime_period_ms}")
    public static void f() {
        println("uptime: " + Sys.VM.vmUptime());
    }
}

The uptime check period value must be provided to BTrace agent - either as a javaagent argument or an argument to btrace dynamic attach launcher.

Attach on launch:

java -jar application.jar -javaagent:btrace-agent.jar=script=Uptime.class,uptime_period_ms=3000

Dynamic attach:

btrace <pid> Uptime.java uptime_period_ms=3000

Elements supporting templated variables

• @OnMethod
  Templating similar to what was shown in the previous example is available for all @OnMethod attributes - clazz, method, type and location whereas again the templated variables can be used in its clazz, method and type attributes in turn.
• @OnTimer
  The timer period can be defined via templated variable and is to be provided in the annotation's from attribute. The usage is shown in the previous example.