11 Event Threshold

Setting a threshold on an event means that Flight Recorder won't record it if its duration is less than the threshold. This enables you to limit the number of events that Flight Recorder records. By default, events have a threshold of 0 ms. It's recommended to set a threshold if an operation occurs frequently and outliers are of greatest concern.

The SetThresholdSample.java example creates ten events with a random duration. Flight Recorder records only those events whose duration is greater than 50 ms.

import java.util.Random;
import jdk.jfr.Event;
import jdk.jfr.Label;
import jdk.jfr.Name;
import jdk.jfr.Threshold;

public class SetThresholdSample {

    @Name("com.oracle.RandomSleep")
    @Label("Random Sleep")
    @Threshold("50 ms")
    static class RandomSleep extends Event {
        @Label("Event number")
        int eventNumber;
        @Label("Random Value")
        int randomValue;
    }

    public static void main(String... args) throws Exception {
        Random randNum = new Random();
        for (int i = 0; i < 10; i++) {
            RandomSleep event = new RandomSleep();
            event.begin();
            event.eventNumber = i;
            event.randomValue = Math.abs(randNum.nextInt() % 100);
            System.out.println("Event #" + i + ": " + event.randomValue);
            Thread.sleep(event.randomValue);
            event.commit();
        }
    }
}

Note that the commit method ends the timing of an event without the need of an explicit call to the end method.

Run SetThresholdSample with the following commands:

java -XX:StartFlightRecording:filename=st.jfr SetThresholdSample.java
jfr print --events RandomSleep st.jfr

The first command prints output similar to the following:

Event #0: 97
Event #1: 15
Event #2: 25
Event #3: 73
Event #4: 38
Event #5: 11
Event #6: 5
Event #7: 28
Event #8: 42
Event #9: 37

The last command prints output similar to the following:

com.oracle.RandomSleep {
  startTime = 23:17:42.050
  duration = 103.813 ms
  eventNumber = 0
  randomValue = 97
  ...
}

com.oracle.RandomSleep {
  startTime = 23:17:42.197
  duration = 77.726 ms
  eventNumber = 3
  randomValue = 73
  ...
}

The shouldCommit Method

You can reduce the overhead of expensive operations with the Event.shouldCommit method, which only commits an event if its duration is within a specified threshold.

The example ShouldCommit.java creates ten events with a random duration. Flight Recorder commits only those events whose duration is greater than 20 ms.

import java.util.Random;

import jdk.jfr.Event;
import jdk.jfr.Label;
import jdk.jfr.Name;
import jdk.jfr.Threshold;

public class ShouldCommitSample {

    @Name("com.oracle.RandomSleep")
    @Label("Random Sleep")
    @Threshold("20 ms")
    static class RandomSleep extends Event {
        @Label("ID")
        int id;
        @Label("Value Kind")
        String valueKind;
    }

    public static void main(String... args) throws Exception {
        Random randNum = new Random();
        for (int i = 0; i < 10; i++) {
            RandomSleep event = new RandomSleep();
            event.begin();
            event.id = i;
            int value = randNum.nextInt(40);
            System.out.println("ID " + i + ": " + value);
            Thread.sleep(value);
            event.end();
            if (event.shouldCommit()) {
                // Format message outside timing of event
                if (value < 10) {
                    event.valueKind = "It was a low value of " +
                        value + "!";
                } else if (value < 20) {
                    event.valueKind = "It was a normal value of " +
                        value + "!";
                } else {
                    event.valueKind = "It was a high value of " +
                        value + "!";
                }
                event.commit();
            }
        }
    }
}

Run this example with the following commands:

java -XX:StartFlightRecording:filename=shouldcommit.jfr ShouldCommit.java
jfr print --events RandomSleep shouldcommit.jfr

The first command prints output similar to the following:

ID 0: 8
ID 1: 2
ID 2: 34
ID 3: 0
ID 4: 11
ID 5: 2
ID 6: 14
ID 7: 28
ID 8: 27
ID 9: 11

The last command prints output similar to the following:

com.oracle.RandomSleep {
  startTime = 23:27:10.642
  duration = 36.711 ms
  id = 2
  valueKind = "It was a high value of 34!"
  ...
}

com.oracle.RandomSleep {
  startTime = 23:27:10.711
  duration = 29.390 ms
  id = 7
  valueKind = "It was a high value of 28!"
  ...
}

com.oracle.RandomSleep {
  startTime = 23:27:10.741
  duration = 28.475 ms
  id = 8
  valueKind = "It was a high value of 27!" 
  ...
}