https://github.com/btraceio/btracel

Simple tool allowing to write BTrace oneliners similar to the ones in DTrace
https://github.com/btraceio/btracel

Last synced: about 2 months ago
JSON representation

Simple tool allowing to write BTrace oneliners similar to the ones in DTrace

• Host: GitHub
• URL: https://github.com/btraceio/btracel
• Owner: btraceio
• Created: 2013-04-10T11:47:49.000Z (almost 12 years ago)
• Default Branch: master
• Last Pushed: 2023-08-11T18:51:27.000Z (over 1 year ago)
• Last Synced: 2024-03-27T03:18:53.529Z (10 months ago)
• Language: Java
• Size: 1.03 MB
• Stars: 11
• Watchers: 9
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
btracel

=======

Simple tool allowing to write BTrace oneliners similar to the ones in DTrace

While BTrace scripts are rather powerful writing them is a tedious process because they are in fact complete java classes. This tool adds the possibility to use "oneliner" syntax to specify what and how should be traced. The syntax resembles DTrace a bit and is designed to be concise and easy to use even if not that powerful.

This project uses ANTLR to parse the oneliners and generate full-fledged BTrace scripts which can be submitted to the standard BTrace infrastructure.

### Oneliner

A oneliner has the following form:

<class definition>:<method definition>:[entry,exit,exception]{<code>}(,[entry,exit,exception]{<code>})*

The three main parts of the oneliner are separated by colon ":".

**<class definition>: Either a full class name or regex matching class names**

* java.util.ArrayList

* java\\.util\\..*

**<method definition>: Either a full method name or regex matching the method names. The method definition can contain full signature definition.**

* size

* .*All

* int calculate(int a, int b)

**handlers: Valid handlers are "entry", "exit" and "error". The handler code may contain calls to any valid BTrace methods (eg. println(), jstack() etc.)**

* entry: Matches a method entry; before any other code is executed

* exit: Matches any successful method return (eg. no uncaught exception)

* error: Matches method return upon uncaught exception

### Parameters

The handler code can reference various parameters. They are either built in parameters (eg. @pmn, @self) or the ones inferred from the method signature, if provided.

#### Built-in parameters

* @pcn: Probe Class Name; the name of the class currently probed

* @pmn: Probe Method Name; the name of the method currently probed

* @self: java.lang.Object reference to **this** valid at the time of probing

* @return: A value returned by the probed method; valid only for **exit** handlers

* @caught: A java.lang.Throwable that has caused the probed method to terminate; valid only for **error** handlers

#### Simplified string concatenation

You can use "+" operator to concatenate strings - eg. it is valid to call 'println("entering method" + @pcn + "." + @pmn + " at " + jstackStr())'

#### Inferred parameters

The parameters may be inferred from the method signature if provided. They represent the arguments passed to the probed method. The method signature must specify the argument names which will be then used in the handler code.

**Example**

```

java.util.ArrayList:java.lang.Object get(int arrIndex):entry {println(str(@arrIndex));}

```

This will print the value of the int argument passed to each invocation of *java.util.ArrayList.get()* method.

### Installation

After checking out and building the project you can find the distribution directory in **{basedir}/dist/ext**. While you can use the command **bin/btracel** directly from that location a more convenient would be copying the contents of **{basedir}/dist/ext** over to the directory where your **BTrace** installation resides.

You can invoke "btracel -?" to display the command help.

### Warning

This is just a proof-of-concept project. It might not be complete and the syntax may be changed in future.