@Retention(RUNTIME) @Target(FIELD) public @interface コンテキスト

イベント・フィールド注釈は、値がコンテキスト情報を保持することを指定します。

コンテキスト情報は、Contextualの注釈が付いたフィールドを使用して、イベントの先頭から末尾まで同じスレッドで発生するすべてのイベントに適用されるデータです。

たとえば、システム内のリクエストまたはトランザクションをトレースするには、コンテキストを提供するためにトレース・イベントを作成できます。

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

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

オーダー・サービス内の詳細を追跡するために、オーダーIDのみがコンテキストを提供するオーダー・イベントを作成できます。

@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

注釈インタフェース・コンテキスト