モジュール jdk.jfr
パッケージ jdk.jfr

クラスRecording

java.lang.Object
jdk.jfr.Recording
すべての実装されたインタフェース:
Closeable, AutoCloseable
public final class Recording extends Object implements Closeable
レコーディング・データをディスクに構成、開始、停止、ダンプする手段を提供します。

次の例は、レコーディング・データをディスクに構成、起動、停止およびダンプする方法を示しています。 

Configuration c = Configuration.getConfiguration("default");
try (Recording r = new Recording(c)) {
    r.start();
    System.gc();
    Thread.sleep(5000);
    r.stop();
    r.dump(Files.createTempFile("my-recording", ".jfr"));
}

導入されたバージョン:
9

  • コンストラクタのサマリー

    コンストラクタ
    コンストラクタ
    説明
    Recording()
    設定なしでレコーディングを作成します。
    Recording(Map<String,String> settings)
    名前/値ペアのマップの設定を使用してレコーディングを作成します。
    Recording(Configuration configuration)
    構成からの構成でレコーディングを作成します。

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    void
    close()
    このレコーディングに関連付けられているすべてのデータを解放します。
    Recording
    copy(boolean stop)
    新しいレコーディングIDと名前を使用して、このレコーディングのクローンを返します。
    EventSettings
    disable(Class<? extends Event> eventClass)
    イベントを無効にします。
    EventSettings
    disable(String name)
    指定された名前のイベントを無効にします。
    void
    dump(Path destination)
    レコーディング・データをファイルに書き込みます。
    EventSettings
    enable(Class<? extends Event> eventClass)
    イベントを有効にします。
    EventSettings
    enable(String name)
    指定された名前のイベントを有効にします。
    Path
    getDestination()
    レコーディングが停止したときにレコーディング・データが書き込まれる宛先ファイルを返します。宛先が設定されていない場合はnullを返します。
    boolean
    getDumpOnExit()
    このレコーディングがJVMの終了時にディスクにダンプされるかどうかを返します。
    Duration
    getDuration()
    このレコーディングに指定された継続時間を返します。継続時間が設定されていない場合はnullを返します。
    long
    getId()
    このレコーディングの一意のIDを返します。
    Duration
    getMaxAge()
    データが削除される前にディスク・リポジトリに保持される時間の長さを返します。
    long
    getMaxSize()
    ディスクのリポジトリに保存されなくなったデータの最大サイズ(バイト単位)を返します。
    String
    getName()
    このレコーディングの名前を返します。
    Map<String,String>
    getSettings()
    このレコーディングで使用される設定を返します。
    long
    getSize()
    ディスク・レポジトリ内のこのレコーディングの現在のサイズをバイト単位で返します。
    Instant
    getStartTime()
    このレコーディングが開始された時間を返します。
    RecordingState
    getState()
    このレコーディングが現在保持されているレコーディング状態を返します。
    Instant
    getStopTime()
    このレコーディングが停止した時間を返します。
    InputStream
    getStream(Instant start, Instant end)
    指定された間隔のデータ・ストリームを作成します。
    boolean
    isToDisk()
    このレコーディングがディスク・リポジトリを使用する場合はtrueを返し、そうでない場合はtrueを返します。
    void
    scheduleStart(Duration delay)
    遅延後にこのレコーディングを開始します。
    void
    setDestination(Path destination)
    データがレコーディング停止時に書き込まれるロケーション、またはデータがダンプされない場合はnullを設定します。
    void
    setDumpOnExit(boolean dumpOnExit)
    このレコーディングを、JVMの終了時にディスクにダンプするかどうかを設定します。
    void
    setDuration(Duration duration)
    レコーディングが停止するまでの期間を設定します。
    void
    setMaxAge(Duration maxAge)
    ディスク・リポジトリに保存されるバック・データの量を決定します。
    void
    setMaxSize(long maxSize)
    ディスク・リポジトリに保持されるデータ量を決定します。
    void
    setName(String name)
    解読可能な名前(たとえば、"My Recording")を設定します。
    void
    setSettings(Map<String,String> settings)
    このレコーディングのすべての設定を置き換えます。
    void
    setToDisk(boolean disk)
    このレコーディングをディスク・リポジトリに継続的にフラッシュするか、またはメモリー・バッファで使用可能なデータに制限するかを決定します。
    void
    start()
    このレコーディングを開始します。
    boolean
    stop()
    このレコーディングを停止します。

    クラスjava.lang.Objectで宣言されたメソッド

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • コンストラクタの詳細

    • Recording

      public Recording(Map<String,String> settings)
      名前/値ペアのマップの設定を使用してレコーディングを作成します。

      新しく作成されたレコーディングは、RecordingState.NEW状態にあります。 レコーディングを開始するには、start()メソッドを呼び出します。

      パラメータ:
      settings - nullではなく、名前/値ペアのマップとしての設定
      スロー:
      IllegalStateException - flight Recorderを(たとえば、Java Virtual Machine (JVM)にFlight Recorderのサポートがない場合や、ファイル・リポジトリを作成したり、アクセスできない場合などです。)の作成できないか
      SecurityException - セキュリティ・マネージャが使用され、FlightRecorderPermission "accessFlightRecorder"が設定されていない場合。
      関連項目:

    • Recording

      public Recording()
      設定なしでレコーディングを作成します。

      新しく作成されたレコーディングは、RecordingState.NEW状態にあります。 レコーディングを開始するには、start()メソッドを呼び出します。

      スロー:
      IllegalStateException - flight Recorderを(たとえば、Java Virtual Machine (JVM)にFlight Recorderのサポートがない場合や、ファイル・リポジトリを作成したり、アクセスできない場合などです。)の作成できないか
      SecurityException - セキュリティ・マネージャが使用され、FlightRecorderPermission "accessFlightRecorder"が設定されていない場合。

    • Recording

      public Recording(Configuration configuration)
      構成からの構成でレコーディングを作成します。

      次の例は、事前定義済の構成を使用するレコーディングの作成方法を示しています。 

      Recording r = new Recording(Configuration.getConfiguration("default"));
      新しく作成されたレコーディングは、RecordingState.NEW状態にあります。 レコーディングを開始するには、start()メソッドを呼び出します。

      パラメータ:
      configuration - 使用する設定が含まれている(nullではない)構成
      スロー:
      IllegalStateException - flight Recorderを(たとえば、Java Virtual Machine (JVM)にFlight Recorderのサポートがない場合や、ファイル・リポジトリを作成したり、アクセスできない場合などです。)の作成できないか
      SecurityException - セキュリティ・マネージャが使用され、FlightRecorderPermission "accessFlightRecorder"が設定されていない場合。
      関連項目:

  • メソッドの詳細

    • start

      public void start()
      このレコーディングを開始します。

      このメソッドを呼び出す前に、レコーディング・オプションとイベント設定を構成することをお薦めします。 これを行う利点は、記録されたデータを分析するときの一貫性のある状態となり、構成をアトミックに適用できるためパフォーマンスが向上します。

      このメソッドが正常に起動されると、このレコーディングはRUNNING状態になります。

      スロー:
      IllegalStateException - レコーディングがすでに開始されているか、CLOSED状態にあるか

    • scheduleStart

      public void scheduleStart(Duration delay)
      遅延後にこのレコーディングを開始します。

      このメソッドが正常に起動されると、このレコーディングはDELAYED状態になります。

      パラメータ:
      delay - nullではなく、このレコーディングを開始する前に待機する時間
      スロー:
      IllegalStateException - レコーディングがNEW状態でないかどうか

    • stop

      public boolean stop()
      このレコーディングを停止します。

      レコーディングを停止すると、再開できません。 このレコーディングに宛先が含まれる場合、データはその宛先に書き込まれ、レコーディングは閉じられます。 レコーディングを閉じると、データは使用できなくなります。

      このメソッドが正常に起動されると、このレコーディングはSTOPPED状態になります。

      戻り値:
      レコーディングが停止するとtrue、それ以外の場合はfalse
      スロー:
      IllegalStateException - レコーディングが開始されていないか、すでに停止している場合
      SecurityException - セキュリティ・マネージャが存在し、呼出し側が宛先パスに書き込むFilePermissionを持っていない場合
      関連項目:

    • getSettings

      public Map<String,String> getSettings()
      このレコーディングで使用される設定を返します。

      返されたMapを変更しても、このレコーディングの設定は変更されません。

      このレコーディングの設定がない場合、空のMapが返されます。

      戻り値:
      nullではなく、レコーディング設定

    • getSize

      public long getSize()
      ディスク・レポジトリ内のこのレコーディングの現在のサイズをバイト単位で返します。

      レコーディング・バッファがフラッシュされると、サイズが更新されます。 レコーディングがディスク・リポジトリに書き込まれない場合、返されるサイズは常に0です。

      戻り値:
      レコーディングがディスク・リポジトリに書き込まれない場合にレコーディングされたデータの量(バイト単位)、または0

    • getStopTime

      public Instant getStopTime()
      このレコーディングが停止した時間を返します。
      戻り値:
      このレコーディングが停止されない場合は時間(null)

    • getStartTime

      public Instant getStartTime()
      このレコーディングが開始された時間を返します。
      戻り値:
      時間。このレコーディングが開始されていない場合はnull

    • getMaxSize

      public long getMaxSize()
      ディスクのリポジトリに保存されなくなったデータの最大サイズ(バイト単位)を返します。
      戻り値:
      最大サイズが設定されていない場合は、最大サイズ(バイト単位)、または0

    • getMaxAge

      public Duration getMaxAge()
      データが削除される前にディスク・リポジトリに保持される時間の長さを返します。
      戻り値:
      最長時間が設定されていない場合はnull

    • getName

      public String getName()
      このレコーディングの名前を返します。

      デフォルトでは、名前はレコーディングIDと同じです。

      戻り値:
      nullではなく、レコーディング名

    • setSettings

      public void setSettings(Map<String,String> settings)
      このレコーディングのすべての設定を置き換えます。

      次の例は、レコーディングのイベント設定の設定方法を示しています。 

          Map<String, String> settings = new HashMap<>();
    settings.putAll(EventSettings.enabled("jdk.CPUSample").withPeriod(Duration.ofSeconds(2)).toMap());
    settings.putAll(EventSettings.enabled(MyEvent.class).withThreshold(Duration.ofSeconds(2)).withoutStackTrace().toMap());
    settings.put("jdk.ExecutionSample#period", "10 ms");
    recording.setSettings(settings);
      次の例は、設定をマージする方法を示しています。 
          Map<String, String> settings = recording.getSettings();
    settings.putAll(additionalSettings);
    recording.setSettings(settings);

      パラメータ:
      settings - nullではなく、設定する設定

    • getState

      public RecordingState getState()
      このレコーディングが現在保持されているレコーディング状態を返します。
      戻り値:
      nullではなく、レコーディング状態
      関連項目:

    • close

      public void close()
      このレコーディングに関連付けられているすべてのデータを解放します。

      このメソッドが正常に起動されると、このレコーディングはCLOSED状態になります。

      定義:
      close、インタフェースAutoCloseable
      定義:
      close、インタフェースCloseable

    • copy

      public Recording copy(boolean stop)
      新しいレコーディングIDと名前を使用して、このレコーディングのクローンを返します。

      クローンは、レコーディングを停止せずにデータをダンプするのに便利です。 クローンが作成されると、コピーするデータ量はsetMaxAge(Duration)メソッドとsetMaxSize(long)methodで制約されます。

      パラメータ:
      stop - true新しく作成したコピーをすぐに停止する必要がある場合はfalse、それ以外の場合はfalse
      戻り値:
      nullではなく、レコーディング・コピー

    • dump

      public void dump(Path destination) throws IOException
      レコーディング・データをファイルに書き込みます。

      ダンプが成功するには、レコーディングが1)実行中であるか、または2)停止してディスクにある必要があります。 レコーディングが他の状態の場合は、IOExceptionがスローされます。

      パラメータ:
      destination - nullではなく、レコーディング・データが書き込まれるロケーション
      スロー:
      IOException - 指定したロケーションにレコーディング・データをコピーできない場合(レコーディングが閉じている場合や宛先パスが書込み可能でない場合など)
      SecurityException - セキュリティ・マネージャが存在し、呼出し側が宛先パスに書き込むFilePermissionを持っていない場合
      関連項目:

    • isToDisk

      public boolean isToDisk()
      このレコーディングがディスク・リポジトリを使用する場合はtrueを返し、そうでない場合はtrueを返します。

      値が設定されていない場合、trueが戻されます。

      戻り値:
      レコーディングでディスク・リポジトリが使用される場合は、true、そうでない場合はtrue

    • setMaxSize

      public void setMaxSize(long maxSize)
      ディスク・リポジトリに保持されるデータ量を決定します。

      ディスクに格納されるデータのレコーディング量を制御するために、保持するデータの最大量を指定できます。 上限を超えた場合、Java Virtual Machine (JVM)は最も古いチャンクを削除し、新しいチャンクのための余裕を作成します。

      最大限度または最大経過時間を設定しないと、レコーディングのサイズが無期限に拡大することがあります。

      パラメータ:
      maxSize - 保存するデータの量(無限大の場合は0)
      スロー:
      IllegalArgumentException - maxSizeが負の場合
      IllegalStateException - レコーディングがCLOSED状態にある場合

    • setMaxAge

      public void setMaxAge(Duration maxAge)
      ディスク・リポジトリに保存されるバック・データの量を決定します。

      ディスクに格納されるデータのレコーディング量を制御するために、データを保持する最大時間を指定できます。 指定した時間よりも古いディスクに格納されているデータは、Java Virtual Machine (JVM)によって削除されます。

      最大限度または最大経過時間を設定しないと、レコーディングのサイズが無期限に拡大することがあります。

      パラメータ:
      maxAge - データが保持される時間の長さ(無限大の場合はnull)。
      スロー:
      IllegalArgumentException - maxAgeが負の場合
      IllegalStateException - レコーディングがCLOSED状態にあるかどうか

    • setDestination

      public void setDestination(Path destination) throws IOException
      データがレコーディング停止時に書き込まれるロケーション、またはデータがダンプされない場合はnullを設定します。

      宛先が設定されている場合、データが宛先パスに正常にコピーされた後、このレコーディングは自動的に閉じられます。

      宛先が設定されていない場合、Flight Recorderでは、このレコーディングがクローズされるまでレコーディング・データを保持します。 dump(Path)メソッドを使用して、データを手動でファイルに書き込みます。

      パラメータ:
      destination - 宛先パス、または、レコーディングを停止時にダンプしない場合はnull
      スロー:
      IllegalStateException - レコーディングがSTOPPEDまたはCLOSED状態にあるかどうか。
      SecurityException - セキュリティ・マネージャが存在し、呼出し側がFilePermissionを持ってdestinationファイルの読取り、書込みおよび削除を行うことができない場合
      IOException - パスが書込み可能でない場合

    • getDestination

      public Path getDestination()
      レコーディングが停止したときにレコーディング・データが書き込まれる宛先ファイルを返します。宛先が設定されていない場合はnullを返します。
      戻り値:
      宛先ファイル、または設定されていない場合はnull。

    • getId

      public long getId()
      このレコーディングの一意のIDを返します。
      戻り値:
      レコーディングID

    • setName

      public void setName(String name)
      解読可能な名前(たとえば、"My Recording")を設定します。
      パラメータ:
      name - nullではなく、レコーディング名
      スロー:
      IllegalStateException - レコーディングがCLOSED状態にある場合

    • setDumpOnExit

      public void setDumpOnExit(boolean dumpOnExit)
      このレコーディングを、JVMの終了時にディスクにダンプするかどうかを設定します。
      パラメータ:
      dumpOnExit - このレコーディングをJVMの終了時にダンプする必要がある場合

    • getDumpOnExit

      public boolean getDumpOnExit()
      このレコーディングがJVMの終了時にディスクにダンプされるかどうかを返します。

      終了時にダンプが設定されていない場合、falseが戻されます。

      戻り値:
      レコーディングが終了時にダンプされる場合はtrue、それ以外の場合はfalse。

    • setToDisk

      public void setToDisk(boolean disk)
      このレコーディングをディスク・リポジトリに継続的にフラッシュするか、またはメモリー・バッファで使用可能なデータに制限するかを決定します。
      パラメータ:
      disk - このレコーディングがディスクに書き込まれる場合true、イン・メモリーならばfalse

    • getStream

      public InputStream getStream(Instant start, Instant end) throws IOException
      指定された間隔のデータ・ストリームを作成します。

      ストリームには、指定された範囲外のデータが含まれる場合があります。

      レコーディングがディスクにない場合、ストリームを作成できず、nullが返されます。

      パラメータ:
      start - ストリームの開始時間。レコーディングの開始時間からデータを取得する場合はnull
      end - ストリームの終了時間。現在の時間までデータを取得する場合はnull。
      戻り値:
      入力ストリーム。期間内に使用可能なデータがない場合、またはレコーディングがディスクに記録されなかった場合はnull
      スロー:
      IllegalArgumentException - endがstartより前に発生した場合
      IOException - ストリームを開けない場合
      関連項目:

    • getDuration

      public Duration getDuration()
      このレコーディングに指定された継続時間を返します。継続時間が設定されていない場合はnullを返します。

      レコーディングがRecordingState.NEW状態にある場合にのみ、期間を設定できます。

      戻り値:
      希望のレコーディング時間、または時間が設定されていない場合はnull。

    • setDuration

      public void setDuration(Duration duration)
      レコーディングが停止するまでの期間を設定します。

      デフォルトでは、レコーディングには(null)の期間はありません。

      パラメータ:
      duration - 期間が設定されていない場合はnull
      スロー:
      IllegalStateException - レコーディングがSTOPPEDまたはCLOSED状態にあるかどうか

    • enable

      public EventSettings enable(String name)
      指定された名前のイベントを有効にします。

      複数のイベントの名前が(たとえば、同じクラスが別のクラス・ローダーにロードされたとします。)である場合、名前と一致するすべてのイベントが有効になります。 特定のクラスを有効にするには、イベント・タイプIDのenable(Class)メソッドまたはString表現を使用します。

      パラメータ:
      name - nullではなく、イベントの設定
      戻り値:
      nullではなく、さらなる構成のためのイベント構成
      関連項目:

    • disable

      public EventSettings disable(String name)
      指定された名前のイベントを無効にします。

      (たとえば、同じクラスが別のクラス・ローダーにロードされたとします。)同じ名前のイベントが複数ある場合(たとえば、同じクラスが別のクラス・ローダーにロードされる)、名前に一致するすべてのイベントが無効になります。 特定のクラスを無効にするには、イベント・タイプIDのdisable(Class)メソッドまたはString表現を使用します。

      パラメータ:
      name - nullではなく、イベントの設定
      戻り値:
      nullではなく、さらなる構成のためのイベント構成

    • enable

      public EventSettings enable(Class<? extends Event> eventClass)
      イベントを有効にします。
      パラメータ:
      eventClass - nullではなく、有効にするイベント
      戻り値:
      nullではなく、さらなる構成のためのイベント構成
      スロー:
      IllegalArgumentException - eventClassが抽象クラスであるか、Eventのサブクラスでない場合

    • disable

      public EventSettings disable(Class<? extends Event> eventClass)
      イベントを無効にします。
      パラメータ:
      eventClass - nullではなく、有効にするイベント
      戻り値:
      nullではなく、さらなる構成のためのイベント構成
      スロー:
      IllegalArgumentException - eventClassが抽象クラスであるか、Eventのサブクラスでない場合