Skip to content

Latest commit

 

History

History
777 lines (644 loc) · 30.6 KB

QuickReference.md

File metadata and controls

777 lines (644 loc) · 30.6 KB

BTrace Quick Reference

A cheat sheet for experienced users. For step-by-step instructions, see Getting Started. Back to README.


Quick Install

Method Command
JBang jbang catalog add --name btraceio https://raw.githubusercontent.com/btraceio/jbang-catalog/main/jbang-catalog.json && jbang btrace@btraceio <PID> script.java
SDKMan sdk install btrace
Docker docker pull ghcr.io/btraceio/btrace
Manual Download latest release

Java support: BTrace 3.0 runs on Java 8–27+. Running BTrace against a JVM older than Java 17 is deprecated: it continues to work throughout 3.x but emits a deprecation warning. Support for Java < 17 will be removed in the next major release (4.0).


Table of Contents

  1. Core Annotations
  2. Location Kinds
  3. Parameter Annotations
  4. Other Annotations
  5. Common Patterns
  6. CLI Commands
  7. Built-in Functions

Core Annotations

@BTrace

Marks a class as a BTrace script.

@BTrace
public class MyTrace { }

@OnMethod

Primary annotation for method instrumentation.

Parameter Type Description Example
clazz String Target class(es) "com.example.MyClass"
method String Target method(s) "processData"
type String Method signature filter "void (java.lang.String)"
location Location Where to inject code @Location(Kind.RETURN)
enableAt Level Instrumentation level control @Level(">=1")
exactTypeMatch boolean Exact type matching true

Examples:

// Match specific class and method
@OnMethod(clazz = "com.example.MyClass", method = "myMethod")

// Match with regex
@OnMethod(clazz = "/com\\.example\\..*/", method = "/get.*/")

// Match by annotation
@OnMethod(clazz = "@javax.ws.rs.Path", method = "@javax.ws.rs.GET")

// Match by signature
@OnMethod(clazz = "com.example.MyClass", method = "calculate", type = "int (int, int)")

@OnTimer

Execute periodically.

@OnTimer(5000)  // Every 5 seconds
public static void periodic() { }

@OnEvent

Handle custom events sent from BTrace console.

@OnEvent("myevent")
public static void onMyEvent() { }

@OnExit

Execute when the script calls exit(int) or the traced process shuts down.

@OnExit
public static void onExit(int exitCode) { }

@OnLowMemory

Execute when a memory pool's usage crosses a threshold, in bytes. Pool names depend on the GC (G1 Old Gen with G1, the default since JDK 9; PS Old Gen with Parallel, the JDK 8 default; Tenured Gen with Serial); for a pool that does not exist or has no usage threshold the agent warns and lists the pools it can watch. Several handlers may watch one pool: it is armed with the lowest threshold, and each handler runs once the reported usage reaches its own. When the probe exits, the pool gets back the threshold it had before. The handler takes no parameter or one MemoryUsage, which receives the pool's usage (any other signature is rejected); an exception thrown by the handler goes to @OnError.

@OnLowMemory(pool = "G1 Old Gen", threshold = 100000000)
public static void onLowMemory(MemoryUsage usage) { }

@Event

Define a JFR (Java Flight Recorder) event factory for high-performance event recording.

Requirements: OpenJDK 8 (with backported JFR) or Java 11+

@Event(
    name = "MyEvent",
    label = "My Custom Event",
    description = "Description of the event",
    category = {"myapp", "performance"},
    stacktrace = true,
    fields = {
        @Event.Field(type = Event.FieldType.STRING, name = "message"),
        @Event.Field(type = Event.FieldType.LONG, name = "duration",
                    kind = @Event.Field.Kind(name = Event.FieldKind.TIMESPAN))
    }
)
private static JfrEvent.Factory myEventFactory;

Field Types: BYTE, CHAR, SHORT, INT, LONG, FLOAT, DOUBLE, BOOLEAN, STRING, CLASS, THREAD

Field Kinds: TIMESTAMP, TIMESPAN, DATAAMOUNT, FREQUENCY, MEMORYADDRESS, PERCENTAGE, BOOLEANFLAG, UNSIGNED

See Getting Started: JFR Integration and Pattern #9 below.

@PeriodicEvent

Define a handler for periodic JFR events (OpenJDK 8 or Java 11+).

@PeriodicEvent(
    name = "PeriodicStats",
    label = "Periodic Statistics",
    period = "10 s",  // or "eachChunk", "beginChunk", "endChunk"
    fields = @Event.Field(type = Event.FieldType.LONG, name = "count")
)
public static void emitStats(JfrEvent event) {
    if (Jfr.shouldCommit(event)) {
        Jfr.setEventField(event, "count", getCount());
        Jfr.commit(event);
    }
}

Location Kinds

Specify where to inject code within a method using @Location(Kind.XXX).

Kind Description When Common Parameters
ENTRY Method entry Default Method args
RETURN Method return Normal exit @Return, @Duration
ERROR Exception thrown Uncaught exception Throwable (plain or @TargetInstance), @Duration
CALL Method call Before/after call @TargetInstance, @TargetMethodOrField
LINE Source line Specific line Line number
FIELD_GET Field read Getting field value @TargetInstance, @TargetMethodOrField
FIELD_SET Field write Setting field value New value, @TargetInstance
NEW Object creation After new Object type name
NEWARRAY Array creation After new[] Array type, dimensions
CATCH Exception catch Entering catch block @TargetInstance exception
THROW Throwing exception Before throw @TargetInstance Throwable
ARRAY_GET Array read Getting array element Array, index
ARRAY_SET Array write Setting array element Array, index, value
SYNC_ENTRY Enter synchronized Acquiring lock Lock object
SYNC_EXIT Exit synchronized Releasing lock Lock object
INSTANCEOF instanceof check Type check Type name, @TargetInstance
CHECKCAST Type cast Casting Type name, @TargetInstance

Location Modifiers:

@Location(value = Kind.CALL, clazz = "/.*/", method = "/.*/")  // Any call
@Location(value = Kind.CALL, clazz = "java.io.File", method = "delete")  // Specific call
@Location(value = Kind.LINE, line = 42)  // Line 42, in the methods @OnMethod(method = ...) selects

A Kind.LINE probe only sees the lines of the methods it selects. Lines in a lambda body belong to lambda$<method>$<n>, field initializers to <init> or <clinit>; select those too, or leave method empty to cover the whole class.

Parameter Annotations

Inject context information into probe handler parameters.

Annotation Type Description Available In
@Self Object Current instance (this) All
@Return Method return type Return value RETURN, CALL (after)
@Duration long Duration in nanoseconds RETURN, ERROR, CALL (after)
@ProbeClassName String Enclosing class name All
@ProbeMethodName String Enclosing method name All
@TargetInstance Object Target object; the exception at ERROR, CATCH, THROW CALL, FIELD_GET/SET, ERROR, CATCH, THROW
@TargetMethodOrField String Target name CALL, FIELD_GET/SET

At ERROR, CATCH and THROW, a handler can also take the exception as a plain Throwable parameter: when no parameter is annotated @TargetInstance, the last unannotated parameter declared as java.lang.Throwable receives it.

A handler whose parameters fit no matching method of a class is not applied there, and the client gets a [BTRACE WARN] Handler ... was not applied in <class> message naming the first method that rejected it. Each handler reports at most five classes. Classes newer than Java 27 (major version above 71) go through the ClassFile API backend, which does not send this message.

Examples:

// Method entry with arguments and context
@OnMethod(clazz = "MyClass", method = "process")
public static void onEntry(@Self Object self,
                          @ProbeClassName String clazz,
                          @ProbeMethodName String method,
                          String arg1, int arg2) { }

// Method return with value and duration
@OnMethod(clazz = "MyClass", method = "calculate", location = @Location(Kind.RETURN))
public static void onReturn(@Return int result, @Duration long duration) { }

// Method call tracking
@OnMethod(clazz = "MyClass", method = "/.*/", location = @Location(value = Kind.CALL, clazz = "/.*/", method = "/.*/"))
public static void onCall(@TargetInstance Object target, @TargetMethodOrField String method) { }

Other Annotations

@Injected

Injects an extension/service instance into your script.

  • Plain @Injected is enough to obtain the service. The invokedynamic injector auto-detects whether the service needs a runtime context or a no-arg construction and wires it accordingly. optional = true (with mode) only chooses the fallback when the extension is blocked; see Permission Policy.
  • Annotation type: io.btrace.core.annotations.Injected
  • Example:
import io.btrace.core.annotations.*;
import io.btrace.metrics.MetricsService;

@BTrace
public class LatencyProbe {
  @Injected
  private static MetricsService metrics;
}

See also: Architecture → architecture/ExtensionInvokeDynamicBridge.md.

@Sampled

Control sampling rate.

@Sampled(kind = Sampled.Sampler.Const)  // Constant sampling
@Sampled(kind = Sampled.Sampler.Adaptive)  // Adaptive sampling
@OnMethod(...)
public static void sampledHandler() { }

@Level

Control handler activation by instrumentation level.

@OnMethod(clazz = "...", enableAt = @Level(">=1"))   // Level 1 or higher
@OnMethod(clazz = "...", enableAt = @Level("(2,5)")) // Levels 2-5 inclusive ("(2;5)" also accepted)
@OnMethod(clazz = "...", enableAt = @Level("3"))     // Level 3 or higher (a bare number means >=)
@OnMethod(clazz = "...", enableAt = @Level("=3"))    // Exactly level 3 (also <, <=, >)

The starting level is 0 unless the script is given a level=N argument (btrace <pid> MyTrace.java level=2, or level=2 among the agent arguments for a startup script). Afterwards only a handler can change it, via BTraceUtils.setInstrumentationLevel(n) (typically from @OnEvent). Gating is a per-call MethodHandle guard in front of the handler; no classes are retransformed when the level changes.

@Export

Export data via JMX.

@Export
private static long counter;

@Property

Declare script properties.

@Property
public static String configValue = "default";

@TLS (Thread Local Storage)

Per-thread state.

@TLS
private static long threadStartTime;

Common Patterns

Pattern 1: Method Entry/Exit Timing

@TLS private static long startTime;

@OnMethod(clazz = "com.example.Service", method = "process")
public static void onEntry() {
    startTime = timeNanos();
}

@OnMethod(clazz = "com.example.Service", method = "process", location = @Location(Kind.RETURN))
public static void onReturn() {
    long duration = timeNanos() - startTime;
    println("Duration: " + str(duration / 1000000) + " ms");
}

Pattern 2: Method Call Counting

private static Map<String, AtomicInteger> counts = Collections.newHashMap();

@OnMethod(clazz = "com.example.Service", method = "/.*/")
public static void onMethod(@ProbeMethodName String method) {
    AtomicInteger counter = Collections.get(counts, method);
    if (counter == null) {
        counter = Atomic.newAtomicInteger(0);
        Collections.put(counts, method, counter);
    }
    Atomic.incrementAndGet(counter);
}

@OnTimer(5000)
public static void printStats() {
    printMap(counts);
}

Pattern 3: Exception Tracking

@OnMethod(clazz = "com.example.Service", method = "/.*/", location = @Location(Kind.ERROR))
public static void onError(@ProbeClassName String clazz,
                          @ProbeMethodName String method,
                          Throwable t) {
    println("Exception in " + clazz + "." + method + ": " + str(t));
    jstack();
}

Pattern 4: Field Access Monitoring

@OnMethod(clazz = "com.example.State", method = "/.*/", location = @Location(value = Kind.FIELD_SET, clazz = "/.*/", field = "status"))
public static void onFieldSet(@TargetInstance Object target,
                             @TargetMethodOrField String field,
                             Object newValue) {
    println("Field " + field + " set to: " + str(newValue));
}

Pattern 5: SQL Query Logging

@OnMethod(clazz = "+java.sql.Statement", method = "/execute.*/")
public static void onSqlExecute(@Self Object stmt, String sql) {
    println("SQL: " + sql);
}

Pattern 6: HTTP Request Tracking

@OnMethod(clazz = "+javax.servlet.http.HttpServlet", method = "service")
public static void onRequest(@Self Object servlet,
                            javax.servlet.http.HttpServletRequest req) {
    println(str(req.getMethod()) + " " + str(req.getRequestURI()));
}

Pattern 7: Object Allocation Tracking

private static long objectCount;

@OnMethod(clazz = "com.example.HeavyObject", method = "<init>")
public static void onNew() {
    objectCount++;
}

@OnTimer(5000)
public static void printCount() {
    println("Objects created: " + str(objectCount));
}

Pattern 8: JFR Event Recording

import io.btrace.core.jfr.JfrEvent;
import static io.btrace.core.BTraceUtils.*;

@BTrace
public class JfrMethodTrace {
    @Event(
        name = "MethodExecution",
        label = "Method Execution Event",
        category = {"myapp"},
        fields = {
            @Event.Field(type = Event.FieldType.STRING, name = "className"),
            @Event.Field(type = Event.FieldType.STRING, name = "methodName"),
            @Event.Field(type = Event.FieldType.LONG, name = "duration",
                        kind = @Event.Field.Kind(name = Event.FieldKind.TIMESPAN))
        }
    )
    private static JfrEvent.Factory execEventFactory;

    @TLS private static long startTime;

    @OnMethod(clazz = "com.example.Service", method = "/.*/")
    public static void onEntry() {
        startTime = timeNanos();
    }

    @OnMethod(clazz = "com.example.Service", method = "/.*/",
             location = @Location(Kind.RETURN))
    public static void onReturn(@ProbeClassName String clazz,
                               @ProbeMethodName String method) {
        JfrEvent event = Jfr.prepareEvent(execEventFactory);
        if (Jfr.shouldCommit(event)) {
            Jfr.setEventField(event, "className", clazz);
            Jfr.setEventField(event, "methodName", method);
            Jfr.setEventField(event, "duration", timeNanos() - startTime);
            Jfr.commit(event);
        }
    }
}

Benefits: <1% overhead, native JVM recording, offline analysis with Mission Control.

CLI Commands

btrace

Attach to running JVM and trace.

btrace [options] <PID> <script.java> [script-args]

Read-only readiness diagnostics:

btrace doctor <pid> [--json] [-v]

Doctor attaches only to read target system properties, then detaches; it never loads an agent or opens the BTrace command connection. It distinguishes Attach API availability from dynamic-agent loading permission, which is reported as not_tested. Add -v to print a stack trace when an unexpected provider or runtime failure prevents diagnosis.

Exit Status Meaning
0 READY A usable BTrace endpoint is published.
2 PREPARATION_REQUIRED The target is readable but has no usable endpoint.
3 INACCESSIBLE Attach is unavailable or denied.
4 UNEXPECTED_FAILURE Invocation or provider failure prevented diagnosis.

The human-readable report prints Status: <STATUS> (exit <code>); --json uses the lower-case form ("status": "preparation_required").

Common Options:

  • --version - Show the version as BTrace v.<version> (<build commit>); a build made outside a git checkout prints dev as the commit
  • -v - Run in verbose mode
  • -l - List all locally attachable JVMs
  • -lp - List the probes in the given JVM that no client is connected to (detached, or whose client went away), which -r can reconnect to; a probe a client is still connected to is not listed (expects PID or app name)
  • -le - List failed extensions in the given JVM (expects PID or app name)
  • -r <probe-id> - Reconnect to an active disconnected probe. If the probe id is unknown, or the JVM has no BTrace control endpoint, -r prints the reason and exits with code 1
  • -r help - Show help on remote commands
  • -o <file> - Output to file (disables console output)
  • -u - Run in trusted/unsafe mode, required to deploy a @BTrace(trusted = true) script; refused when the target JVM has a probe budget
  • -d <path> - Dump instrumented classes to specified path
  • -pd <path> - Search path for probe XML descriptors
  • -cp <path> / -classpath <path> - User class files and annotation processors path
  • -p <port> - Port for btrace agent listener (default: 2020)
  • -host <host> - Connect to an already running agent on the given host without attaching (default: localhost). Skips Attach API discovery, so it cannot authenticate to a 3.0 prepared endpoint; use it only for 2.x agents or endpoints opened by a previous dynamic attach
  • -statsd <host[:port]> - StatSD server configuration
  • -n <oneliner> / --oneliner <oneliner> - Run a oneliner instead of a script file
  • -x - Unattended mode (non-interactive)

Examples:

# List all Java processes
btrace -l

# Basic attach
btrace 12345 MyTrace.java

# Verbose with output file
btrace -v -o trace.log 12345 MyTrace.java

# List detached probes in a JVM
btrace -lp 12345

# Reconnect to an active probe
btrace -r myprobe-id 12345

# With script arguments
btrace 12345 MyTrace.java arg1 arg2

# Dump instrumented classes for debugging
btrace -d /tmp/instrumented 12345 MyTrace.java

# With StatSD integration
btrace -statsd localhost:8125 12345 MyTrace.java

btracec

Compile BTrace script.

btracec <script.java>

Examples:

# Compile script
btracec MyTrace.java

# Results in MyTrace.class

btracer

Launch Java app with BTrace agent. <java-args> is what you would pass to java (JVM options, class path, main class, application arguments), without the word java.

btracer [options] <script.class> <java-args>

Examples:

# First compile
btracec MyTrace.java

# Then launch
btracer MyTrace.class -jar myapp.jar

# With JVM options
btracer MyTrace.class -Xmx2g -jar myapp.jar

btracex

Extension management CLI: inspect, list, and install extensions and edit the permission policy.

btracex inspect [<path|dir|zip|id>] [--json]   # no args opens the interactive repo browser (TUI)
btracex list [--json]
btracex policy print [--policy-file <path>|--home|--classpath <outDir>] [--json]
btracex policy set [--allowExtensions <ids>] [--denyExtensions <ids>] [--allowPrivileged <bool>] [--policy-file <path>|--home|--classpath <outDir>]
btracex install <groupId:artifactId:version|zip|url> [--repo <url> ...] [--id <extId>] [--dry-run]

Examples:

# Inspect an extension archive (id, version, services, privileged status)
btracex inspect my-extension.zip

# List installed extensions
btracex list

# Install a BTrace-built extension package from the distribution's extensions/ directory
btracex install /path/to/btrace-statsd-3.0.0-extension.zip

btracep

Probe inspector: prints details of a compiled BTrace probe (handlers, required permissions, bytecode).

btracep <probe_file>

Example:

btracec MyTrace.java
btracep MyTrace.class

Java Agent Mode

Start app with BTrace agent directly.

java -javaagent:/path/to/btrace.jar=script=<script.class>,noServer=true[,arg=value]... YourApp

A plain java -javaagent:/path/to/btrace.jar MyApp (no arguments) is an authenticated prepared endpoint on port 2020. The command server starts unless noServer=true is given, or script= / scriptdir= is given and noServer is unset.

Agent Parameters:

  • script=<path>[:<path>...] - Compiled BTrace script(s) to run at startup, colon-separated
  • scriptdir=<dir> - Directory to load scripts from
  • port=<port> - Communication port (default 2020); prepared mode accepts 0 and publishes the selected port. A fixed port that is already in use is not an invalid option: binding fails with a BindException, agent initialization aborts and a JVM launched with -javaagent does not start
  • bindAddress=<address> - Loopback bind address (127.0.0.1 or ::1); non-loopback and wildcard addresses are rejected in 3.0.0. An invalid port or bindAddress is reported as invalid agent option <name>=<value>: ...; the command server was not started and the agent starts without a command server; the application and any startup script keep running
  • authTokenFile=<path> - Existing owner-protected prepared-mode token file, or a path where the agent creates one; the token value is never passed as an argument
  • noServer=true - Don't start the command server; use for startup scripts that need no later client connection
  • telemetry=true|false - Explicitly enable or disable the default-off agent_start telemetry event
  • allowExtensions=<id,...> / denyExtensions=<id,...> / allowPrivileged=true|false - Which extensions may link their implementation (see Permission Policy). grant=, deny= and grantAll= are accepted but have no effect
  • trusted=true - Trusted mode (no script verification); also required by the -Dbtrace.system.appendJar escape hatch. The -Dbtrace.trusted system property does not enable it: the agent logs a warning that names this argument
  • debug=true - Verbose agent logging
  • dumpClasses=true, dumpDir=<dir> - Dump instrumented classes
  • stdout=true - Write script output to stdout instead of a file
  • scriptOutputFile=<file>, scriptOutputDir=<dir> - Script output file, and the directory it is written to (default: the scriptdir= directory, else the target's working directory); an absolute scriptOutputFile= is used as given
  • fileRollMilliseconds=<ms>, fileRollMaxRolls=<n> - Roll the output file every ms and keep n rolled files (default 5)
  • cmdQueueLimit=<n> - Pending output commands per client before output is dropped (default 100)
  • trackRetransforms=true - Notify the client about every class a probe retransforms
  • startupRetransform=false - Skip retransforming already loaded classes on probe deployment (default true)
  • probeTtl=<seconds>, probeMaxRate=<hits/s> - Probe budgets: maximum lifetime of a probe, and maximum executions per second of its handlers attached to application code; a probe over budget is removed. Launch-time only (see probe budgets)
  • statsd=<host[:port]> - StatsD server for the StatsD extension
  • config=<name> - Configuration section to apply from an embedded agent.properties (fat agents; see Fat Agent Plugin)
  • probeDescPath=<dirs> - Search path for @OnProbe descriptor XML files
  • probes=<name>[,<name>...] - Bundled probes (fat agent) to load at startup, by Java binary name; replaces the probe selection made by embedded extensions
  • output=stdout - With probes=, send the output of the bundled probes to stdout; any other value keeps the default output file
  • help=true - Print the agent usage text and exit the JVM; the value is not checked, so a bare help does the same
  • bootClassPath=<path>, systemClassPath=<path> - Additional boot / system classpath

Any other name=value is passed to scripts as a script argument. A name that differs from a parameter above only in letter case, or (from five characters) by one typo, is logged as a warning such as Unknown agent option 'debgu': did you mean 'debug'?; the agent still starts.

Examples:

# Startup script with no command endpoint
java -javaagent:btrace.jar=script=MyTrace.class,noServer=true MyApp

# With debug logging and no command endpoint
java -javaagent:btrace.jar=script=MyTrace.class,noServer=true,debug=true MyApp

# Authenticated prepared endpoint on an automatically selected loopback port
java -javaagent:btrace.jar=port=0 MyApp

# Run a startup probe and retain the authenticated endpoint for later PID-based connections
java -javaagent:btrace.jar=script=MyTrace.class,noServer=false,port=0 MyApp

A 3.0 client obtains the prepared endpoint and token-file path through the target JVM's Attach API. Authentication precedes V1/V2 negotiation; older clients and missing or incorrect credentials fail closed. Generated credentials are removed at shutdown. Remote prepared mode is unsupported in 3.0.0.

Wire Protocol

Client and agent communicate over a pluggable wire protocol: V1 (Java serialization, backward compatible) and V2 (binary, faster). The version is auto-negotiated by default. System properties:

Property Default Description
btrace.comm.protocol v2 Protocol version (1/v1 or 2/v2)
btrace.comm.autoNegotiate true Enable automatic protocol negotiation
btrace.comm.forceVersion false Force the configured version without negotiation (mutually exclusive with auto-negotiation)
btrace.protocol.negotiation.timeout 5000 Negotiation timeout in milliseconds
btrace.heartbeat.interval 10000 Client: milliseconds between heartbeats on a V2 probe session; 0 disables them
btrace.heartbeat.timeout 30000 Client and agent: milliseconds of silence after which a V2 connection is closed (the agent detaches the probe, which keeps running); 0 disables the check

Built-in Functions

The BTrace compiler auto-imports import static io.btrace.BTrace.* into every script. That auto-import covers the core helper categories: output (print, println, printf), string manipulation, basic math, thread info, and basic stack printing.

Many functions in the sections below are not in io.btrace.BTrace and require import static io.btrace.core.BTraceUtils.*; — for example printArray, classOf, aggregation helpers, timeNanos, jstack, collection utilities, and Jfr.*. Adding that import suppresses the io.btrace.BTrace.* auto-import. BTraceUtils has its own print, println, str and exit; do not add both wildcard imports (the shared names such as str become ambiguous). Import a helper that only io.btrace.BTrace has by name instead, e.g. import static io.btrace.BTrace.threadName;.

Output Functions

println(String)           // Print line
print(String)            // Print without newline
printArray(Object[])     // Print array
printMap(Map)            // Print map
printf(String, ...)      // Formatted print (io.btrace.BTrace; the varargs array is rejected by the verifier, so trusted scripts only)

Reflection Functions

str(Object)              // Object to string
name(Class)              // Class name
probeClass()             // Get current probe class
classOf(Object)          // Get object's class
field(Class, String)     // Look up a field (java.lang.reflect.Field)

Time Functions

timeMillis()             // Current time in milliseconds
timeNanos()              // Current time in nanoseconds
timestamp()              // Formatted timestamp

Thread Functions

jstack()                 // Print stack trace
jstack(int)              // Print N frames
jstackAll()              // Print all thread stacks
threadId(currentThread())    // Current thread ID
name(currentThread())        // Current thread name (io.btrace.BTrace: threadName(Thread))

Collection Functions

Collections.newHashMap()      // Create HashMap
Collections.newDeque()        // Create Deque
Collections.put(Map, K, V)    // Put in map
Collections.get(Map, K)       // Get from map
Collections.size(Collection)  // Get size

Atomic Functions

Atomic.newAtomicInteger(int)        // Create AtomicInteger
Atomic.incrementAndGet(AtomicInteger)  // Increment and get
Atomic.get(AtomicInteger)            // Get value

System Functions

exit(int)                // Exit BTrace
property(String)         // System property
getenv(String)           // Environment variable
getInstrumentationLevel()  // Current level

Memory Functions

sizeof(Object)           // Object size
heapUsage()              // Heap memory usage
nonHeapUsage()           // Non-heap memory usage

JFR Event Operations

// Create event from factory
Jfr.prepareEvent(JfrEvent.Factory)    // Create new JFR event instance

// Set event field values (overloaded for all types)
Jfr.setEventField(JfrEvent, String, byte|boolean|char|short|int|float|long|double|String)

// Event lifecycle
Jfr.shouldCommit(JfrEvent)             // Check if event should be recorded
Jfr.commit(JfrEvent)                   // Commit event to JFR
Jfr.begin(JfrEvent)                    // Start timing for timespan events
Jfr.end(JfrEvent)                      // End timing for timespan events

Note: JFR functions require OpenJDK 8 (with backported JFR) or Java 11+. Not available in Java 9-10 (graceful degradation).

Restrictions

BTrace scripts have safety restrictions:

  • No new threads
  • No new classes
  • No synchronization
  • No loops (for, while, do-while, enhanced for)
  • No external method calls (methods within same BTrace class are allowed)
  • No calls from one handler to another (@OnMethod, @OnTimer, @OnEvent, @OnError, @OnProbe, @PeriodicEvent): the called handler would return without running, so the compiler rejects the call. Put shared code in a plain private static method and call it from both. @OnExit and @OnLowMemory handlers may call other handlers.
  • No file I/O (except via BTraceUtils)
  • No System.exit

To bypass them, annotate the script @BTrace(trusted = true) and deploy it with -u (trusted mode); -u alone does not relax them, and a trusted script deployed without -u is refused. Use this only in controlled environments.


See Also