Summary

New JFR annotation to filter out stack frames from en event stack trace.

Problem

User-defined events can be created using the jdk.jfr API, for example:

void foo() {
  class HelloEvent extends Event {
    String message;
  }
  HelloEvent event = new HelloEvent();
  event.message = "hello, world!";
  event.commit();
}

In the above code snippet, a stack trace is taken where the commit() method is invoked. The stack trace starts with the foo() method as the top frame. This works well in most cases, but not when the event is part of a framework or committed in a utility method.

The following examples illustrates the problem with the implementation of a JDBC rollback event:

package com.example;

public class JFRInstrumentedConnection implements Connection {
  private final Connection delegate; 

  JFRInstrumentedConnection(Connection connection) {
    this.delegate = connection;
  }

  public void rollback() {
     RollBackEvent event = new RollBackEvent();
     event.begin();
     delegate.run();
     event.commit();
 }
 ...
}

In the above code snippet, the top frame becomes com.example.JFRInstrumentedConnection.rollback(), but the event would be easier to understand if the stack trace started where the application code invoked the rollback() method.

Furthermore, not having the correct top frame prevents tooling, such as JDK Mission Control, to aggregate events by top frame, for example, to see the total time spent doing database rollbacks grouped by where the rollback() method was called.

Solution

Add an annotation that lists class or method that should be excluded from an event stack trace, for example:

@StackFilter("com.example.JFRInstrumentedConnection");
public class RollBackEvent extends Event {
}

@StackFilter("com.example.JFRInstrumentedConnection::rollback");
public class RollBackEvent extends Event {
}

It would be possible to allow users to specify method parameters, but it would complicate the design and implementation, for example, should users be able specify varargs or unqualified class names? If there is a need for method parameters, it can be added later by appending parentheses to the method name.

In the future, the mechanism could also be extended to support wildcards, interfaces or other type of filtering by using a prefix/keyword, for example @StackFilter("skip-to:com.example.Foo:bar"), @StackFilter("skip-frames:3") or @StackFilter("ignore-lambda-frames").

An alternative would be to use dedicated annotations, i.e @SkipFrames(3), or multiple annotation values, i.e @StackFilter(skipFirst=3, ignoreLambda=true, depth=3). If so, we might consider using methods={"com.example.JFRInstrumentedConnection::rollback"},

Specification

/**
 * Event annotation, specifies method names or classes to exclude in the stack
 * trace.
 * <p>
 * The following example illustrates how the {@code StackFilter} annotation can
 * be used to remove the {@code Logger::log} method in a stack trace:
 * 
 * {@snippet class="Snippets" region="StackFilterOverview"}
 * 
 * @since 22
 */
@MetadataDefinition
@Target({ ElementType.TYPE })
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface StackFilter {
    /**
     * The methods or classes that should not be part of an event stack trace.
     * <p>
     * A filter is formed by using the fully qualified class name concatenated with
     * the method name using {@code "::"} as separator, for example
     * {@code "java.lang.String::toString"}
     * <p>
     * If only the name of a class is specified, for example {@code
     * "java.lang.String"}, all methods in that class will be filtered out.
     * <p>
     * Methods can't be qualified using method parameters or return types.
     * <p>
     * Instance methods belonging to an interface can't be filtered out.
     * <p>
     * Wilcards are not permitted.
     *
     * @return the method names, not {@code null}
     */
    public String[] value();
}