モジュール 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");
   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

  • コンストラクタの詳細

    • 記録

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

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

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

    • 記録

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

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

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

    • 記録

      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"が設定されていない場合。
      関連項目:
      Configuration

  • メソッドの詳細

    • 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を持っていない場合
      関連項目:
      setDestination(Path)

    • 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ではなく、レコーディング状態
      関連項目:
      RecordingState

    • close

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

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

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

    • copy

      public Recording copy​(boolean stop)
      新しいレコーディングIDと名前を使用して、このレコーディングのクローンを返します。 クローンは、レコーディングを停止せずにデータをダンプするのに便利です。 クローンが作成されると、コピーするデータ量はsetMaxAge(Duration)メソッドとsetMaxSize(long)methodで制約されます。
      パラメータ:
      stop - 新しく作成したコピーをすぐに停止する必要がある場合はtrue、それ以外の場合はfalse
      戻り値:
      nullではなく、レコーディング・コピー

    • dump

      public void dump​(Path destination) throws 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 - ストリームを開くことができない場合
      関連項目:
      setToDisk(boolean)

    • 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ではなく、さらなる構成のためのイベント設定
      関連項目:
      EventType

    • 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のサブクラスでない場合