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

インタフェースFlightRecorderMXBean

  • すべてのスーパー・インタフェース:
    PlatformManagedObject
    public interface FlightRecorderMXBean
extends PlatformManagedObject
    Flight Recorderを制御するための管理インタフェース。

    プラットフォームMBeanサーバーでMXBeanを識別するためのオブジェクト名は、次のとおりです。

    jdk.management.jfr:type=FlightRecorder

    Flight Recorderは、次の方法で構成できます。

    • 「レコーディング・オプション」
      レコーディングを最後にする期間およびデータのダンプ場所と場所を指定します。
    • 「設定」
      使用可能にするイベントおよび各イベントで取得する情報の種類を指定します。
    • 「構成」
      通常は設定ファイルから導出される事前定義済の設定セットで、複数のイベントの構成を同時に指定します。

    設定構文の説明はjdk.jfrパッケージのドキュメントを、構成情報はConfigurationInfoクラスのドキュメントを参照してください。

    レコーディング・オプション

    次の表に、setRecordingOptions(long, Map)およびgetRecordingOptions(long)で使用するオプション名を示します。

    レコーディング・オプション
    名 記述 デフォルト値 書式 値の例
    name 人間が判読可能なレコーディング名を設定 レコーディングIDの文字列表現 String "My Recording",
    "profiling"
    maxAge 最も古いデータが削除されるまで、そのデータがディスク・リポジトリに保持される期間を指定します。 disk=trueの場合にのみ機能します。そうでない場合、このパラメータは無視されます。 "0" (制限なし) 制限に影響がない場合は"0"、そうでない場合は正のLong値の文字列表現の後に空白と次の単位のいずれかが続きます。

    "ns" (nanoseconds)
    "us" (microseconds)
    "ms" (milliseconds)
    "s" (seconds)
    "m" (minutes)
    "h" (hours)
    "d" (days)
    		"2 h",
    "24 h",
    "2 d",
    "0"
    maxSize データがディスク・リポジトリに保持されるサイズ(バイト単位)を指定します。 disk=trueの場合にのみ機能します。そうでない場合、このパラメータは無視されます。 "0" (制限なし) Long値の文字列表現、正の値でなければならない "0",
    "1000000000"
    dumpOnExit Java Virtual Machine (JVM)終了時のディスクへのデータのレコーディング "false" Boolean値、"true"または"false"の文字列表現 "true",
    "false"
    destination レコーディングが停止したときにレコーディング・データが書き込まれるパスを指定します。 "false" フォーマットについてはPaths#getPathを参照してください。
    このメソッドが別のプロセスから呼び出された場合、ターゲットJVMが実行されているマシンにデータが書き込まれます。     宛先が相対パスの場合、ターゲットJVMが起動された作業ディレクトリに対する相対パスです。}     		"c:\recording\recotding.jfr",
    "/recordings/recording.jfr", "recording.jfr"
    disk 記録されたデータを記録時に保存します。 "false" Boolean値、"true"または"false"の文字列表現 "true",
    "false"
    duration レコーディングの実行時間を設定 "0" (無制限、連続) "0"を指定しなければなりません。そうでなければ、正のLongの文字列表現の後に空白があり、次の単位の1つが続きます:

    "ns" (nanoseconds)
    "us" (microseconds)
    "ms" (milliseconds)
    "s" (seconds)
    "m" (minutes)
    "h" (hours)
    "d" (days)
    		"60 s",
    "10 m",
    "4 h",
    "0"

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

    • フィールドのサマリー

      フィールド 
      修飾子と型 フィールド 説明
      static String MXBEAN_NAME
      FlightRecorderMXBeanのObjectNameの文字列表現。

    • メソッドのサマリー

      修飾子と型 メソッド 説明
      long cloneRecording​(long recordingId, boolean stop)
      レコーディングの一部の抽出に役立つ、既存のレコーディングのコピーを作成します。
      void closeRecording​(long recordingId)
      指定されたIDでレコーディングを閉じ、レコーディングに関連付けられているすべてのシステム・リソースを解放します。
      void closeStream​(long streamId)
      指定されたIDでレコーディング・ストリームを閉じ、そのストリームに関連するすべてのシステム・リソースを解放します。
      void copyTo​(long recordingId, String outputFile)
      指定されたファイルにレコーディング・データを書き込みます。
      List<ConfigurationInfo> getConfigurations()
      このJava Virtual Machine (JVM)の事前定義された構成のリストを返します。
      List<EventTypeInfo> getEventTypes()
      現在登録されているイベント・タイプのリストを返します。
      Map<String,​String> getRecordingOptions​(long recordingId)
      指定されたID (たとえば、記録されたデータを保持する宛先ファイルまたは期間などです。)を使用してレコーディングのオプションを含むマップを返します。
      List<RecordingInfo> getRecordings()
      必ずしも実行されているとはかぎらず、使用可能なレコーディングのリストを返します。
      Map<String,​String> getRecordingSettings​(long recordingId)
      指定されたID ((たとえば、イベントしきい値))のレコーディングの設定を含むMapを返します
      long newRecording()
      レコーディングを作成しますが、レコーディングは開始しません。
      long openStream​(long recordingId, Map<String,​String> streamOptions)
      レコーディングに関係なくデータを取得するために、指定されたIDまたは0のレコーディングのデータ・ストリームを開きます。
      byte[] readStream​(long streamId)
      指定されたIDのストリームからデータの一部を読み取ります。使用できるデータがなくなった場合はnullを返します。
      void setConfiguration​(long recordingId, String contents)
      指定されたIDでレコーディングの文字列表現として構成を設定します。
      void setPredefinedConfiguration​(long recordingId, String configurationName)
      指定されたIDでレコーディングの事前定義済の構成を設定します。
      void setRecordingOptions​(long recordingId, Map<String,​String> options)
      レコーディング・オプション(たとえば、データを保持する宛先ファイルと期間などです。)を構成します。
      void setRecordingSettings​(long recordingId, Map<String,​String> settings)
      指定したレコーディングの以前の設定をすべて設定して置き換えます。
      void startRecording​(long recordingId)
      指定したIDでレコーディングを開始します。
      boolean stopRecording​(long recordingId)
      指定したIDで実行中のレコーディングを停止します。
      long takeSnapshot()
      使用可能なすべてのレコーディング済データのスナップショット・レコーディングを作成します。

    • フィールドの詳細

    • メソッドの詳細

      • newRecording

        long newRecording()
           throws IllegalStateException,
                  SecurityException
        レコーディングを作成しますが、レコーディングは開始しません。
        戻り値:
        レコーディングの開始、停止、クローズおよび構成に使用できる一意のID
        例外:
        IllegalStateException - flight Recorderを(たとえば、Java Virtual Machine (JVM)にFlight Recorderのサポートがない場合や、ファイル・リポジトリを作成したり、アクセスできない場合などです。)の作成できないか
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元にManagementPermission("control")がない場合
        関連項目:
        Recording

      • takeSnapshot

        long takeSnapshot()
        使用可能なすべてのレコーディング済データのスナップショット・レコーディングを作成します。

        スナップショットは、停止状態の合成レコーディングです。 データが使用できない場合、サイズが0のレコーディングが返されます。

        スナップショットによって、後の操作である(たとえば、時間間隔の変更やデータ・サイズの削減のための操作)のデータに安定したアクセスが提供されます。

        データへのアクセスが不要になった場合、呼出し側はレコーディングを閉じる必要があります。

        戻り値:
        nullではなく、利用可能なすべてのレコーディング・データのスナップショット
        例外:
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元にManagementPermission("control")がない場合
        関連項目:
        Recording

      • cloneRecording

        long cloneRecording​(long recordingId,
                    boolean stop)
             throws IllegalArgumentException,
                    SecurityException
        レコーディングの一部の抽出に役立つ、既存のレコーディングのコピーを作成します。

        クローニングされたレコーディングには元のレコーディング・データと同じものが含まれますが、新しいIDと名前の先頭に"Clone of recording"が付いています。 元のレコーディングが実行中の場合は、クローンも実行中です。

        パラメータ:
        recordingId - クローンの作成元のレコーディングのレコーディングID
        stop - 戻る前に新しく作成したクローンを停止した場合。
        戻り値:
        レコーディングの開始、停止、クローズおよび構成に使用できる一意のID
        例外:
        IllegalArgumentException - 指定したIDのレコーディングが存在しない場合
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元にManagementPermission("control")がない場合
        関連項目:
        Recording

      • startRecording

        void startRecording​(long recordingId)
             throws IllegalStateException,
                    SecurityException
        指定したIDでレコーディングを開始します。

        停止したレコーディングは再開できません。

        パラメータ:
        recordingId - 開始するレコーディングのID
        例外:
        IllegalArgumentException - 指定したIDのレコーディングが存在しない場合
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元にManagementPermission("control")がない場合
        IllegalStateException
        関連項目:
        Recording

      • stopRecording

        boolean stopRecording​(long recordingId)
               throws IllegalArgumentException,
                      IllegalStateException,
                      SecurityException
        指定したIDで実行中のレコーディングを停止します。
        パラメータ:
        recordingId - 停止するレコーディングのID
        戻り値:
        レコーディングが停止した場合にtrue、それ以外の場合はfalse
        例外:
        IllegalArgumentException - 指定したIDのレコーディングが存在しない場合
        IllegalStateException - レコーディングが実行されていない場合
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元にManagementPermission("control")がない場合
        関連項目:
        newRecording()

      • closeRecording

        void closeRecording​(long recordingId)
             throws IOException
        指定されたIDでレコーディングを閉じ、レコーディングに関連付けられているすべてのシステム・リソースを解放します。

        レコーディングがすでに終了している場合、このメソッドを呼び出すことは効果がありません。

        パラメータ:
        recordingId - 閉じるレコーディングのID
        例外:
        IllegalArgumentException - 指定したIDのレコーディングが存在しない場合
        IOException - 入出力エラーが発生した場合
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元にManagementPermission("control")がない場合
        関連項目:
        newRecording()

      • openStream

        long openStream​(long recordingId,
                Map<String,​String> streamOptions)
         throws IOException
        レコーディングに関係なくデータを取得するために、指定されたIDまたは0のレコーディングのデータ・ストリームを開きます。
        レコーディング・ストリームのオプション
        名 記述 デフォルト値 書式 値の例
        startTime レコーディング・ストリームを開始する時点を指定します。 データの格納方法が原因で、開始時間の前に開始または終了するイベントが含まれる場合があります。 Instant.MIN_VALUE.toString() ISO-8601. Instant.toString()を参照
        またはエポックからのミリ秒                 		"2015-11-03T00:00",
        "1446508800000"
        endTime レコーディング・ストリームを終了する時点を指定します。 データの格納方法が原因で、終了時間の後に開始または終了するイベントが含まれる場合があります。 Instant.MAX_VALUE.toString() ISO-8601. Instant.toString()を参照
        またはエポックからのミリ秒                 		"2015-11-03T01:00",
        "1446512400000"
        blockSize readStreamの呼出しで読み取る最大バイト数を指定します。 "50000" 正のlong値。

        blockSizeを非常に高い値に設定すると、Java Virtual Machineが未処理の値とみなされる場合、OutOfMemoryErrorまたはIllegalArgumentExceptionが発生する可能性があります。                 		"50000",
        "1000000",
        オプションがマップから省略された場合は、デフォルト値が使用されます。

        ストリームをオープンする前に、指定されたIDのレコーディングを停止する必要があります。 この制限は将来のリリースで解除される可能性があります。

        パラメータ:
        recordingId - ストリームを開くレコーディングのID
        streamOptions - データの量とその読み方を制御するオプションを含むマップ、またはデフォルト・ブロック・サイズでレコーディングのすべてのデータを取得するnull
        戻り値:
        ストリームの一意のID。
        例外:
        IllegalArgumentException - iDによるレコーディングが存在しない場合、またはoptionsに無効な値が含まれる場合
        IOException - レコーディングが閉じている場合、I/Oエラーが発生するか、指定したレコーディングまたは間隔でデータを使用できません
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元にManagementPermission("control")がない場合

      • closeStream

        void closeStream​(long streamId)
          throws IOException
        指定されたIDでレコーディング・ストリームを閉じ、そのストリームに関連するすべてのシステム・リソースを解放します。

        ストリームがすでに閉じられている場合、このメソッドを呼び出すことは効果がありません。

        パラメータ:
        streamId - ストリームのID
        例外:
        IllegalArgumentException - 指定されたIDのストリームが存在しない場合
        IOException - ストリームを閉じようとしているときにI/Oエラーが発生した場合
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元にManagementPermission("control")がない場合
        関連項目:
        openStream(long, Map)

      • readStream

        byte[] readStream​(long streamId)
           throws IOException
        指定されたIDのストリームからデータの一部を読み取ります。使用できるデータがなくなった場合はnullを返します。

        レコーディングのデータをすべて読み取るには、nullが返されるまでこのメソッドを繰り返し呼び出します。

        パラメータ:
        streamId - ストリームのID
        戻り値:
        データのレコーディングを含むバイト配列、または使用できるデータがなくなった場合のnull
        例外:
        IOException - ストリームがクローズされているか、ストリームを読み込もうとしているときにI/Oエラーが発生した場合
        IllegalArgumentException - ストリームIDのレコーディングが存在しない場合
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元にManagementPermission("monitor")がない場合

      • getRecordingOptions

        Map<String,​String> getRecordingOptions​(long recordingId)
                                      throws IllegalArgumentException
        指定されたID (たとえば、記録されたデータを保持する宛先ファイルまたは期間などです。)を使用してレコーディングのオプションを含むマップを返します。

        使用可能なオプション名については、FlightRecorderMXBeanを参照してください。

        パラメータ:
        recordingId - オプションを取得するレコーディングのID
        戻り値:
        nullではなく、レコーディング・オプションを記述するマップ
        例外:
        IllegalArgumentException - 指定したIDのレコーディングが存在しない場合
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元にManagementPermission("monitor")がない場合

      • getRecordingSettings

        Map<String,​String> getRecordingSettings​(long recordingId)
                                       throws IllegalArgumentException
        指定されたID ((たとえば、イベントしきい値))のレコーディングの設定を含むMapを返します

        複数のレコーディングが同時に実行されている場合、Mapオブジェクトに指定された内容よりも多くのデータがレコーディングされる可能性があります。

        Mapの名前はイベント名であり、"#" (たとえば、"jdk.VMInfo#period"です。)で区切られた設定名です。 この値は、設定値(たとえば、"60 s")のテキスト表現です。

        パラメータ:
        recordingId - 設定を取得するレコーディングのID
        戻り値:
        レコーディング設定を説明するマップ(nullではありません)
        例外:
        IllegalArgumentException - 指定したIDのレコーディングが存在しない場合
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元にManagementPermission("monitor")がない場合

      • setConfiguration

        void setConfiguration​(long recordingId,
                      String contents)
               throws IllegalArgumentException
        指定されたIDでレコーディングの文字列表現として構成を設定します。
        パラメータ:
        recordingId - レコーディングのID
        contents - nullではなく、使用する構成ファイルの文字列表現
        例外:
        IllegalArgumentException - 指定されたIDのレコーディングが存在しない場合、または構成を解析できなかった場合。
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元にManagementPermission("control")がない場合
        関連項目:
        Configuration.getContents()

      • setPredefinedConfiguration

        void setPredefinedConfiguration​(long recordingId,
                                String configurationName)
                         throws IllegalArgumentException
        指定されたIDでレコーディングの事前定義済の構成を設定します。
        パラメータ:
        recordingId - 構成を設定するレコーディングのID
        configurationName - (たとえば、"profile"や"default"などです。)ではなく、null構成の名前
        例外:
        IllegalArgumentException - 指定したIDのレコーディングが存在しない場合
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元にManagementPermission("control")がない場合
        関連項目:
        getConfigurations()

      • setRecordingSettings

        void setRecordingSettings​(long recordingId,
                          Map<String,​String> settings)
                   throws IllegalArgumentException
        指定したレコーディングの以前の設定をすべて設定して置き換えます。

        設定は名前と値のペアで構成され、nameは構成するイベントと設定を示し、valueはその設定内容を示します。

        名前は、次の方法で構成できます。

        <event-name> + "#" + <setting-name>

        or

        <event-id> + "#" + <setting-name>

        たとえば、CPU負荷イベントのサンプル間隔を1秒ごとに1回設定するには、"jdk.CPULoad#period"という名前と"1 s"という値を使用します。 複数のイベントが同じ名前を使用する場合、たとえばイベント・クラスが複数のクラス・ローダーにロードされ、それらの間に区別が必要な場合、名前は"56#period"になります。 イベントのIDは、EventType.getId()メソッドを呼び出して取得され、イベントが登録されているJava Virtual Machine (JVM)インスタンスに対して有効です。

        使用可能なイベント名のリストは、FlightRecorder.getEventTypes()およびEventType.getName()を起動することによって取得されます。 イベント・タイプに使用可能な設定のリストは、EventType.getSettingDescriptors()およびValueDescriptor.getName()を起動することで取得されます。

        パラメータ:
        recordingId - レコーディングのID
        settings - nullではなく、設定する設定の名前値マップ
        例外:
        IllegalArgumentException - 指定したIDのレコーディングが存在しない場合
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元にManagementPermission("control")がない場合
        関連項目:
        Recording.getId()

      • setRecordingOptions

        void setRecordingOptions​(long recordingId,
                         Map<String,​String> options)
                  throws IllegalArgumentException
        レコーディング・オプション(たとえば、データを保持する宛先ファイルと期間などです。)を構成します。

        使用できるオプションおよび値の詳細は、FlightRecorderMXBeanを参照してください。 値をnullに設定すると、値がデフォルト値に戻ります。

        パラメータ:
        recordingId - オプションを設定するレコーディングのID
        options - 設定する設定の名前/値マップ(nullではありません)
        例外:
        IllegalArgumentException - 指定したIDのレコーディングが存在しない場合
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元にManagementPermission("control")がない場合、またはオプションに、呼び出し元が操作を許可されていないファイルが含まれている場合。
        関連項目:
        Recording.getId()

      • getRecordings

        List<RecordingInfo> getRecordings()
        必ずしも実行されているとはかぎらず、使用可能なレコーディングのリストを返します。

        MBeanServerアクセス:
        RecordingInfoのマップされたタイプは、RecordingInfo.fromメソッドで指定された属性を持つCompositeDataです。

        戻り値:
        nullではなく、レコーディングのリスト
        例外:
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元に ManagementPermission("monitor")がない場合
        関連項目:
        RecordingInfo, Recording

      • getConfigurations

        List<ConfigurationInfo> getConfigurations()
        このJava Virtual Machine (JVM)の事前定義された構成のリストを返します。

        MBeanServerアクセス:
        ConfigurationInfoのマップされたタイプは、ConfigurationInfo.fromメソッドで指定された属性を持つCompositeDataです。

        戻り値:
        nullではなく、事前定義された構成のリスト
        例外:
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元にManagementPermission("monitor")がない場合
        関連項目:
        ConfigurationInfo, Configuration

      • getEventTypes

        List<EventTypeInfo> getEventTypes()
        現在登録されているイベント・タイプのリストを返します。

        MBeanServerアクセス:
        EventTypeInfoのマップされたタイプは、EventTypeInfo.fromメソッドで指定された属性を持つCompositeDataです。

        戻り値:
        nullではなく、登録されたイベント・タイプのリスト
        例外:
        SecurityException - セキュリティ・マネージャが存在し、呼び出し元にManagementPermission("monitor")がない場合
        関連項目:
        EventTypeInfo, EventType

      • copyTo

        void copyTo​(long recordingId,
            String outputFile)
     throws IOException,
            SecurityException
        指定されたファイルにレコーディング・データを書き込みます。

        このメソッドが別のプロセスからリモートに呼び出された場合、ターゲットJava Virtual Machine (JVM)が実行されているマシン上のoutputFileという名前のファイルにデータが書き込まれます。 ファイルのロケーションが相対パスの場合、ターゲットJVMが起動された作業ディレクトリを基準とした相対パスになります。

        パラメータ:
        recordingId - データをダンプするレコーディングのID
        outputFile - データが書き込まれるシステム依存のファイル名(nullではありません)
        例外:
        IOException - I/Oエラー(たとえば、無効なパスです)のためにレコーディングをダンプできない場合
        IllegalArgumentException - 指定したIDのレコーディングが存在しない場合
        IllegalStateException - レコーディングがまだ開始されていないか、すでに閉じられている場合
        SecurityException - セキュリティ・マネージャが存在し、そのSecurityManager.checkWrite(java.lang.String)メソッドが指定されたファイルへの書き込みアクセスを拒否した場合、または呼び出し元にManagmentPermission("control")がない場合
        関連項目:
        Path.toString(), Recording.dump(java.nio.file.Path)