Аннотационный интерфейс Contextual

@Retention(RUNTIME) @Target(FIELD) public @interface Contextual

Аннотация поля события, указывающая, что значение содержит контекстную информацию.

Контекстная информация — это данные, применимые ко всем событиям, происходящим в одном потоке от начала до конца события, поле которого аннотировано с помощью Contextual.

Например, для отслеживания запросов или транзакций в системе можно создать событие трассировки, предоставляющее контекст.

@Label("Trace")
@Name("com.example.Trace")
class TraceEvent extends Event {
    @Label("ID")
    @Contextual
    String id;

    @Label("Name")
    @Contextual
    String name;
}

Для отслеживания сведений в службе заказов можно создать событие заказа, в котором контекст предоставляет только идентификатор заказа.

@Label("Order")
@Name("com.example.Order")
class OrderEvent extends Event {
    @Label("Order ID")
    @Contextual
    long id;

    @Label("Order Date")
    @Timestamp(Timestamp.MILLISECONDS_SINCE_EPOCH)
    long date;

    @Label("Payment Method")
    String paymentMethod;
}

Если обработка заказа в службе заказов приостанавливается из-за конкуренции за блокировку, пользовательский интерфейс может отображать контекстную информацию вместе с событием JavaMonitorEnter, упрощая поиск и устранение неполадок, например:

  $ jfr print --events JavaMonitorEnter recording.jfr
  jdk.JavaMonitorEnter {
    Context: Trace.id = "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01"
    Context: Trace.name = "POST /checkout/place-order"
    Context: Order.id = 314159
    startTime = 17:51:29.038 (2025-02-07)
    duration = 50.56 ms
    monitorClass = java.util.ArrayDeque (classLoader = bootstrap)
   previousOwner = "Order Thread" (javaThreadId = 56209, virtual = true)
   address = 0x60000232ECB0
   eventThread = "Order Thread" (javaThreadId = 52613, virtual = true)
   stackTrace = [
     java.util.zip.ZipFile$CleanableResource.getInflater() line: 685
     java.util.zip.ZipFile$ZipFileInflaterInputStream.<init>(ZipFile) line: 388
     java.util.zip.ZipFile.getInputStream(ZipEntry) line: 355
     java.util.jar.JarFile.getInputStream(ZipEntry) line: 833
     ...
   ]
  }

Различие между аннотациями Relational и Contextual заключается в том, что Relational связывает данные событий, формируя глобальную структуру данных, подобно внешнему ключу в реляционной базе данных, тогда как Contextual представляет состояние, применимое ко всем событиям, происходящим одновременно в одном потоке. Поле может одновременно быть контекстным и реляционным.

Контекстное поле может увеличить нагрузку на анализатор, читающий файл записи, поскольку ему необходимо отслеживать активный контекст. Поэтому его следует использовать экономно и только при необходимости.

Начиная с версии:: 25

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/25/docs/api/jdk.jfr/jdk/jfr/Contextual.html