モジュール jdk.management.jfr

パッケージ jdk.management.jfr

インタフェースFlightRecorderMXBean

すべてのスーパー・インタフェース:

PlatformManagedObject

public interface FlightRecorderMXBean
extends PlatformManagedObject

Flight Recorderを制御するための管理インタフェース。

プラットフォームMBeanサーバーでMXBeanを識別するObjectNameは次のとおりです:

jdk.management.jfr:type=FlightRecorder

Flight Recorderは複数の方法で構成できます。 次の値があります

• 「記録オプション」
  記録がどれくらい持続すべきかを決定し、データをいつどこに投棄すべきかを決定します。
• 「設定」
  どのイベントを有効にするか、各イベントでどの種類の情報をキャプチャするかを決定します。
• 「構成」
  複数のイベントを同時に構成するために、構成ファイルから派生した構成の事前定義されたセットです。

構成構文の説明については、パッケージjdk.jfrのドキュメントを参照してください。構成に関する情報については、ConfigurationInfoを参照してください。

記録オプション

setRecordingOptions(long, Map)とgetRecordingOptions(long)で使用されるオプション名のリスト。

記録のオプションとその目的。

名	記述	デフォルト値	Format	値の例
name	人間が判読可能な記録名を設定	記録IDの文字列表現	String	"My Recording", "profiling"
maxAge	記録の期間がmaxAgeのしきい値を超えると、最も古いデータが削除されることがあります。 disk=trueの場合のみ動作し、そうでない場合はパラメータが無視されます。	"0" (制限なし)	"0"を指定しなければなりません。そうでなければ、正のLong値の文字列表現の後に空白が続き、次の単位の1つ、 "ns" (nanoseconds) "us" (microseconds) "ms" (milliseconds) "s" (seconds) "m" (minutes) "h" (hours) "d" (days)	"2 h", "24 h", "2 d", "0"
maxSize	バイト単位で測定された記録のサイズがmaxSizeしきい値を超えると、最も古いデータが削除されることがあります。 disk=trueの場合のみ動作し、そうでない場合はパラメータが無視されます。	"0" (制限なし)	Long値の文字列表現、正の値でなければならない	"0", "1000000000"
dumpOnExit	JVM出口でディスクにデータを記録するダンプ	"false"	Boolean値、"true"または"false"の文字列表現	"true", "false"
destination	記録が停止したときに記録データを書き込むべきパス。	"false"	フォーマットについてはPaths#getPathを参照してください。 このメソッドが別のプロセスから呼び出された場合、データはターゲットVMが実行されているマシンに書き込まれます。 destinationが相対パスの場合、ターゲットVMが起動された作業ディレクトリからの相対パスです。	"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()	事前定義された構成のリストを返します。
List<EventTypeInfo>	getEventTypes()	登録されたイベント・タイプのリストを返します。
Map<String,String>	getRecordingOptions(long recordingId)	指定されたidを持つ記録用のoptionsを含むマップを返します。
List<RecordingInfo>	getRecordings()	使用可能な記録のリストを返します。必ずしも実行している必要はありません。
Map<String,String>	getRecordingSettings(long recordingId)	settingsを含むマップを、指定されたID(イベントしきい値など)で返します。
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()	利用可能なすべての記録データの記録スナップショットを作成します。

インタフェース java.lang.management.PlatformManagedObjectで宣言されたメソッド

getObjectName

フィールドの詳細

MXBEAN_NAME

static final String MXBEAN_NAME

FlightRecorderMXBeanのObjectNameの文字列表現。

関連項目:

定数フィールド値

メソッドの詳細

newRecording

long newRecording()
           throws IllegalStateException,
                  SecurityException

記録を作成しますが、記録は開始しません。

戻り値:

記録の開始、停止、終了、および構成に使用できる一意の識別子

例外:

IllegalStateException - 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 - 新しく作成されたクローンを停止してから戻す必要がある場合。

戻り値:

記録の開始、停止、終了、および構成に使用できる一意の識別子

例外:

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を開きます。

ストリーミング・オプションとその目的。

名	記述	デフォルト値	Format	値の例
startTime	記録ストリームの開始を示すある時点。 データがどのように格納されるかによって、startTimeの前に開始または終了するイベントがいくつか含まれることがあります。	Instant.MIN_VALUE.toString()	ISO-8601. Instant.toString()を参照 またはエポックからのミリ秒	"2015-11-03T00:00", "1446508800000"
endTime	記録ストリームの終わりを示す一時点。 データがどのように格納されるかによって、endTimeの後に開始または終了するイベントがいくつか含まれることがあります。	Instant.MAX_VALUE.toString()	ISO-8601. Instant.toString()を参照 またはエポックからのミリ秒	"2015-11-03T01:00", "1446512400000"
blockSize	readStreamへの呼び出しで読み取る最大バイト数	"50000"	正のlong値。 blockSizeを非常に高い値に設定すると、JVMが処理するには大きすぎると判断された場合、OutOfMemoryErrorまたはIllegalArgumentExceptionが返されることがあります。	"50000", "1000000",

オプションがマップから省略された場合、デフォルト値が使用されます。

ストリームを開く前に、指定されたIDを持つ記録を停止する必要があります。これは、将来のバージョンで解除される可能性のある制限です。

パラメータ:

recordingId - ストリームを開くための記録のID

streamOptions - データの量とその読み込み方法を制御するオプションを含むマップ、またはデフォルトのブロック・サイズで記録するためのすべてのデータを取得するnull

戻り値:

ストリームの一意の識別子。

例外:

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を持つ記録用のoptionsを含むマップを返します。 例えば、記録されたデータを保存するためのコピー先ファイルまたはタイムスパンです。

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

パラメータ:

recordingId - 記録のIDを取得するためのオプション

戻り値:

nullではなく、記録オプションを記述するマップ

例外:

IllegalArgumentException - 指定されたIDを持つ記録がない場合

SecurityException - セキュリティ・マネージャが存在し、呼び出し元にManagementPermission("monitor")がない場合

getRecordingSettings

Map<String,String> getRecordingSettings(long recordingId)
                                 throws IllegalArgumentException

settingsを含むマップを、指定されたID(イベントしきい値など)で返します。

複数の記録が同時に実行されている場合、このマップで指定されているものより多くのデータを記録できます。

マップ内の名前は、"#"で区切られたイベント名と設定名です(例:"com.oracle.jdk.VMInfo#period")。 値は設定値のテキスト表現です(例:"everyChunk")。

パラメータ:

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

指定した記録の以前の設定をすべて設定して置き換えます。

設定は、名前の値のペアで構成されます。ここで、名前は、構成するイベントと設定、および設定する値を指定します。

名前は2つの方法で形成することができますが、

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

or

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

たとえば、CPU Loadイベントのサンプル間隔を毎秒1回に設定するには、名前を"com.oracle.jdk.CPULoad#period"と値"1 s"にする必要があります。 イベント・クラスが複数のクラス・ローダーにロードされ、それらの間で区別が必要な場合など、複数のイベントが同じ名前を使用する場合は、2番目の形式を使用できます(例:"56#period")。 イベントのidはEventTypeInfo.getId()を呼び出すことで取得でき、このJVMインスタンスに対してのみ有効です。

使用可能なイベント名のリストは、getEventTypes()とEventTypeInfo.getName()を呼び出すことで取得できます。 イベント・タイプのサポートされる設定のリストは、EventTypeInfo.getSettingDescriptors()とSettingDescriptorInfo.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()

事前定義された構成のリストを返します。

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

指定されたファイルに記録データを書き込みます。

このメソッドが別のプロセスからリモートで呼び出された場合、データはターゲットVMが実行されているマシン上のoutputFileという名前のファイルに書き込まれます。 outputFileが相対パスである場合、ターゲットVMが起動された作業ディレクトリからの相対パスです。

パラメータ:

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)