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:

Items to be specified	Description
`specification_format`	Specifies the methods to be traced. Specify one of the following formats for `specification_format`: To trace methods whose method name and argument type match `package_name.class_name.method_name(argument_type_of_the_method)` To trace methods whose name matches the specified method `package_name.class_name.method_name()` To trace all methods whose class name matches the specified class `package_name.class_name` To trace all methods whose package name matches the specified package `package_name.` The items to be specified in the specification format are as follows: `package_name` Specify the package name of the class or interface of the method to be traced. `class_name` Specify the class name or interface name of the method to be traced. If you specify an interface name instead of a class name and `true` is specified for the subclass flag, the methods that implement the specified interface will be traced. `method_name` Specify the name of the method to be traced. `argument_type_of_the_method` Specify the argument type of the method to be traced by using the fully qualified name.
`ID`	Specify the character string for identifying the method to be traced (hereinafter referred to as the ID). The specifiable characters are ASCII characters from 0x21 (`!`) to 0x7e (`~`). However, you cannot specify 0x22 (`"`), 0x23 (`#`), or 0x2c (`,`). The ID is output to the PRF trace file. Note that a maximum of 32 characters can be output to the PRF trace file. The 33rd and subsequent characters will be omitted, and an asterisk (`*`) will be output as the 33rd character. If a subclass exists in the class for which the method to be traced is defined and the method to be traced is not overridden in the subclass, the ID specified for the method to be traced in the superclass is output.
`subclass_flag`	Specify `true` or `false` to indicate whether the methods of the classes that have an inheritance relationship with the classes or interfaces of the specified method are to be included as trace targets. If you specify `true`, the specified method and the methods overriding the specified method will be traced. If you specify `false`, only the specified method will be traced, and the methods overriding the specified method will not be traced.
`event_ID`	Specify the point for which trace information is to be collected (trace collection point) by using a hexadecimal value from 0xae02 to 0xae7e, or from 0xc000 to 0xcffe. The default value is 0xae00. This value is output in the trace information that is output at the method entry. The value that is added 1 to this value is output in the trace information that is output at the method exit.
`comment`	A comment begins with a number sign (`#`). The character string from the number sign (`#`) to the end of the line is regarded as a comment.

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
Class or interface	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:

Figure 8‒3: Example of the class structure of an application

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

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.

To Page Top