8.4 userprf.cfg
userprf.cfg is a configuration file for specifying the settings for performance-based trace analysis.
Description
The configuration file userprf.cfg is used to specify information about the methods to be traced by the performance-based trace analysis function.
Syntax
specification_format,ID,subclass_flag[,[event_ID][,[trace_collection_level]]] [#comment]
- Note
-
To set, as the trace targets, all methods whose class name and package name match the specified conditions, specify true for the value of the jvm.userprf.ExtendedSetting property.
The items to be specified in the performance-based trace analysis configuration file are as follows:
The specification rules for the performance-based trace analysis configuration file are as follows:
-
You can specify only single-byte characters.
-
Single-byte space characters (0x20) and tab characters (\t or 0x09) will be treated as space characters. Note that space characters are ignored when the performance-based trace analysis configuration file is read.
-
Specify one trace target method per line.
-
You can specify a maximum of 2,048 characters in one line. This character count includes space characters and comments.
-
The end of the line is indicated by one or more consecutive linefeed characters (\n or 0x0A) or carriage return characters (\r or 0x0D).
-
If the specification in the performance-based trace analysis configuration file is incorrect, a message indicating the error details is output. In addition, if an invalid value is specified for an item, a message indicating the error details is output, and the specification in that line is not applied.
The following table lists the logs that are output when the performance-based trace analysis configuration file is read during performance-based trace analysis:
Format of output
Output content
Description
[UPR#1]<DATE>Setting file not found.<file=FILEPATH>
-
DATE#2
Date and time when an attempt to read the performance-based trace analysis configuration file failed.
-
FILEPATH
Absolute path of the performance-based trace analysis configuration file that could not be read.
The default performance-based trace analysis configuration file or the file specified in the jvm.userprf.File property does not exist.
[UPR#1]<DATE>Failed to open setting file.<file=FILEPATH>
-
DATE#2
Date and time when an attempt to read the performance-based trace analysis configuration file failed.
-
FILEPATH
Absolute path of the performance-based trace analysis configuration file that could not be read.
The performance-based trace analysis configuration file could not be opened or read.
[UPR#1]<DATE>Failed to parse setting file.<file=FILEPATH><line=LINE>
-
DATE#2
Date and time when an error was detected in the performance-based trace analysis configuration file.
-
FILEPATH
Absolute path of the performance-based trace analysis configuration file.
-
LINE
Number of the line in the absolute path of the performance-based trace analysis configuration file.
There is a specification format error in the performance-based trace analysis configuration file.
[UPR#1]<DATE>Event ID is invalid value.<file=FILEPATH><eventID=EventID>
-
DATE#2
Date and time when an error was detected in the performance-based trace analysis configuration file.
-
FILEPATH
Absolute path of the performance-based trace analysis configuration file.
-
EventID
Event ID specified in the performance-based trace analysis configuration file.
The event ID of the performance-based trace analysis configuration file is outside the range of valid values.
[UPR#1]<DATE>No valid settings in setting file.<file=FILEPATH>
-
DATE#2
Date and time when it was detected that the performance-based trace analysis configuration file contained no valid settings.
-
FILEPATH
Absolute path of the performance-based trace analysis configuration file.
The settings in the performance-based trace analysis configuration file are invalid.
[UPR#1]<DATE>User Extended PRF started successfully.<file=FILEPATH>
-
DATE#2
Date and time when the performance-based trace analysis configuration file was successfully read.
-
FILEPATH
Absolute path of the performance-based trace analysis configuration file that was successfully read.
The performance-based trace analysis configuration file was read normally and performance-based trace analysis is now enabled.
- #1:
-
This is an identifier indicating that the log was output by the performance-based trace analysis function.
- #2:
-
This is output in the same format as the extended verbosegc information.
-
-
You cannot specify classes in Java VM and Application Server as the methods to be traced by the performance-based trace analysis function. The following packages are applicable:
-
Classes under java
-
Classes under javax
-
Classes under com.hitachi
-
Classes under JP.co.Hitachi
Thus, to specify a package name by using the jvm.userprf.ExtendedSetting property, specify the package name so that only application classes are included.
-
-
You cannot specify the following methods as the trace target methods:
-
Names of non-existent packages, classes, or methods
-
native method
-
abstract method
-
Classes in Java VM and the methods of those classes
Example: Classes of packages beginning with java or javax
-
Classes specified in -Xbootclasspath and the methods of those classes
-
Classes in products
-
-
If you specify the methods in the way as follows, the methods can be specified as trace target methods.
-
To specify a constructor, specify the same value for the method name and for the class name. Alternatively, specify <init>.
Example: Specifying the constructor of the MyMain class
MyMain.MyMain() or MyMain.<init>()
-
If a method that has the same name as a non-constructor class name is specified, it cannot be determined whether the specified name is that of a constructor or a method. As a result, both the constructor and the method will be traced.
-
To specify a method that has arguments of variable length, specify such arguments as an array.
Example: Specifying a method with arguments of variable length
Correct specification: com.sample.Test.method(java.lang.String[])
Incorrect specification: com.sample.Test.method(java.lang.String...)
-
To specify a nested class, delimit the class name by using a dollar sign ($) instead of a dot (.).
Example: Specifying a nested class
Correct specification: com.sample.Test$NestClass
Incorrect specification: com.sample.Test.NestClass
-
You can specify a non-generics and non-parameter classes (raw type).
Example: Specification of a non-generics class
Correct specification: com.sample.Test.method()
Incorrect specification: com.sample.Test<java.lang.String,java.lang.Object>.method()
-
-
The methods that are set as the trace target methods vary depending on whether a class name or an interface name is specified for the value of class_name in specification_format.
The following table describes the trace target methods that are set depending on whether a class name or an interface name is specified:
Class or interface
Trace target methods
When false is specified for the subclass flag
When true is specified for the subclass flag
Class
Methods of the specified class
Methods of the specified class and the methods overriding those methods
Interface
None
Methods of the classes that directly#1 or indirectly#2 implement the specified interface, and the methods overriding those methods
- #1:
-
This refers to classes that implement the specified interface by using implements in the class declaration.
- #2:
-
This refers to subclasses of a class that directly implements the specified interface and to classes that directly implement an interface that inherits the specified interface.
The following is an example of the specification format of the performance-based trace analysis configuration file:
com.sample.Test.method(),TEST1,false,0xae02,A com.sample.Test.method(),TEST1,false,0xae02 com.sample.Test.method(),TEST1,false,0xae02, com.sample.Test.method(),TEST1,false,,A com.sample.Test.method(),TEST1,false com.sample.Test.method(),TEST1,false, com.sample.Test.method(),TEST1,false,,
Storage location
installation_directory_for_JDK\usrconf\userprf.cfg
Examples
Note that this specification example is for an application whose package name is "com.sample" and whose class structure is as shown in the following figure:
The following is a specification example of a performance-based trace analysis configuration file that sets the methods whose method name and argument type match, as the trace target methods.
- If the subclass flag is false:
-
com.sample.ClassA.methodA1(java.lang.String,java.lang.Object),1000,false
If the subclass flag is false, the method whose name and argument type match the specified method is set as the trace target method.
The following method is to be traced:
-
methodA1(String,Object) of ClassA
No event ID is set for the trace target methods. As a result, when you invoke a trace target method, the default value 0xae00 is output as the event ID at the method entry, and 0xae01 is output at the method exit. In addition, 1000 is set for the ID, and thus 1000 is output as the ID.
-
- If the subclass flag is true:
-
com.sample.ClassA.methodA2(),2000,true
If the subclass flag is true, in addition to the method whose name and argument type match the specified method, the methods overriding the specified method are set as the trace target methods.
The following methods are to be traced:
-
methodA2() of ClassA
-
methodA2() of ClassB that overrides methodA2() of ClassA
No event ID is set for the trace target methods. As a result, when you invoke a trace target method, the default value 0xae00 is output as the event ID at the method entry, and 0xae01 is output at the method exit. In addition, 2000 is set for the ID, and thus 2000 is output as the ID for all methods to be traced.
-
The following is a specification example of a performance-based trace analysis configuration file that sets the methods whose name matches the specified method, as the trace target methods.
- If the subclass flag is false:
-
com.sample.ClassA.methodA1(*),methodA1,false,0xae30
If the subclass flag is false, all methods whose name matches the specified method are set as the trace target methods.
The following methods are to be traced:
-
methodA1(String,Object) of ClassA
-
methodA1(int) of ClassA
When you invoke a trace target method, 0xae30 is output as the event ID at the method entry, and 0xae31 is output at the method exit. In addition, methodA1 is output as the ID for all methods to be traced.
-
- If the subclass flag is true:
-
com.sample.ClassA.methodA1(*),methodA1,true,0xae30
If the subclass flag is true, all methods whose name matches the specified method are set as the trace target methods. In addition to the specified method, the methods overriding the specified method are also traced.
The following methods are to be traced:
-
methodA1(String,Object) and methodA1(int) of ClassA
-
methodA1(String,Object) of ClassB that overrides methodA1(String,Object) of ClassA
-
methodA1(String,Object) of ClassC that overrides methodA1(String,Object) of ClassB
When you invoke a trace target method, 0xae30 is output as the event ID at the method entry, and 0xae31 is output at the method exit. In addition, methodA1 is output as the ID for all methods to be traced.
-
The following is a specification example of a performance-based trace analysis configuration file that sets all methods whose class name matches the specified class as the trace target methods, when no method or argument is specified.
- If the subclass flag is false:
-
com.sample.ClassA,TEST01,false
If the subclass flag is false, all methods of the specified class name (ClassA class) are set as the trace target methods.
The following methods are to be traced:
-
methodA1(String,Object), methodA1(int), and methodA2() of ClassA
No event ID is set for the trace target methods. As a result, when you invoke a trace target method, when you invoke a trace target method, 0xae00 is output at the method entry and 0xae01 is output at the method exit. In addition, TEST01 is output as the ID for all methods to be traced.
-
- If the subclass flag is true:
-
com.sample.ClassB,TEST02,true
If the subclass flag is true, all methods of the specified class name (ClassB class) and all methods overriding those methods are set as the trace target methods.
The following methods are to be traced:
-
methodA1(String,Object) of ClassB
-
methodA2() of ClassB
-
methodB1() of ClassB
-
methodA1(String,Object) of ClassC that overrides methodA1(String,Object) of ClassB
No event ID is set for the trace target methods. As a result, when you invoke a trace target method, when you invoke a trace target method, 0xae00 is output at the method entry and 0xae01 is output at the method exit. In addition, TEST02 is output as the ID for all methods to be traced.
-
The following is a specification example of a performance-based trace analysis configuration file that sets all methods of all classes whose package name matches the specified package as the trace target methods, when no class name, method name, or argument is specified.
- Important note
-
This specification also sets subpackages as trace targets. When a subpackage is set as a trace target, the trace is output when the trace target method is invoked.
If the com.sample package has a subpackage, all methods of all classes of that subpackage are also set as trace targets.
- If the subclass flag is false:
-
com.sample.*,6000,false
If the subclass flag is false, all methods of all classes in the specified package (com.sample) are set as the trace target methods.
The following methods are to be traced:
-
All methods of ClassA, ClassB, ClassC, and ClassD
No event ID is set for the trace target methods. As a result, when you invoke a trace target method, when you invoke a trace target method, 0xae00 is output at the method entry and 0xae01 is output at the method exit. In addition, 6000 is output as the ID for all methods to be traced.
-
- If the subclass flag is true:
-
com.sample.*,6000,true
If the subclass flag is true, all methods of all classes in the specified package (com.sample) and all methods overriding those methods are set as the trace target methods.
The following methods are to be traced:
-
All methods of ClassA, ClassB, ClassC, and ClassD, and all methods overriding those methods
No event ID is set for the trace target methods. As a result, when you invoke a trace target method, when you invoke a trace target method, 0xae00 is output at the method entry and 0xae01 is output at the method exit. In addition, 6000 is output as the ID for all methods to be traced.
-
Notes
-
In the performance-based trace analysis configuration file, if you specify different IDs or event IDs for the same trace target method on multiple lines, the settings specified first will have priority.
-
If you specify settings for multiple trace target methods in the performance-based trace analysis configuration file, all methods will be output with the same ID or event ID. In such cases, if the output method names exceed the maximum number of characters that can be output, you might not be able to distinguish the methods. For this reason, specify the settings in the way that each method can be identified.
-
To set an interface as a trace target, specify true for the subclass flag. If you specify false for the subclass flag, trace information will not be output, because methods to be traced do not exist in interfaces.
-
Set multiple methods as targets of the performance-based trace analysis function only when you want to understand the behavior of applications. In the performance-based trace analysis configuration file, if true is specified for the subclass flag or the methods whose name matches the specified method are set as the trace target methods, many methods might be incorrectly set as the targets of the performance-based trace analysis function, and identifying the cause of performance deterioration might become difficult. For the purposes of identifying the cause of performance deterioration, we recommend that you limit the targets of the performance-based trace analysis function by specifying false for the subclass flag in the performance-based trace analysis configuration file, by setting the methods whose method name and argument type match the specified values as the trace target methods, or by other means.