The format for coding the configuration file for the user-extended trace based performance analysis is as follows:

#1:

You can omit the items enclosed within [ ].

#2:

To trace all the methods with matching class names and package names, set up true in the value of the jvm.userprf.ExtendedSetting property.

#:

Specify specification-format in one of the following formats:

• To trace a method with matching method name and argument types
  package-name.class-name.method-name (type name of the method argument)
  
• To trace methods with matching method names
  package-name.class-name.method-name(*)
  
• To trace all the methods with matching class names
  package-name.class-name
  
• To trace all the methods with matching package names
  package-name.*
  

Example of coding format:

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,,

The items coded in the configuration file for the user-extended trace based performance analysis are as follows:

Specification-format

Specify the method to be traced.

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 the interface name instead of the class name, and if true is specified in the subclass flag, the method implementing that interface is traced.

method-name

Specify the method to be traced.

type-name-of-the-method-argument

Specify the argument type of the method to be traced using the fully qualified name.

identity-ID

Specify the character string for identifying the method to be traced.

The characters you can use are the ASCII characters from 0x21(!) to 0x7e(~). However, you cannot specify 0x22(") , 0x23(#), and 0x2c(,).

The identity ID is output to the PRF trace file. Note that up to 32 characters are output to the PRF trace file. The 33^rd and subsequent characters are omitted and * (asterisk) is output as the 33^rd character.

Note

If a subclass exists in the class defining the method to be traced and if the method to be traced is not overridden in that subclass, the specified identity ID is output for the superclass method to be traced.

subclass-flag

Specify whether to trace the methods of the class that has an inheritance relationship with the classes or interfaces of the specified method, using true or false.

• If you specify true, the specified method and the methods overriding the specified method are traced.
• If you specify false, only the specified method is traced, and the methods overriding the specified method are not traced.

event-ID

Specify the point for acquiring the trace information (trace collection point) using a hexadecimal value (0xae02 to 0xae7e and 0xc000 to 0xcffe). The default value is 0xae00.

This value is output in the trace information that is output at the method entry, and this value + 1 is output in the trace information that is output at the method exit.

trace-collection-level

Specify A, B, C, or their respective lower cases in the trace collection level of the methods to be traced. The default value is A.

• A: Standard level
• B: Advanced level
• C: Maintenance level

Reference note

The trace collection level is the same as the PRF trace collection level of the cprflevel command. All the methods to be traced reference the levels of the Java VM layers. For details on the PRF collection levels and layers, see cprflevel (Displaying and changing PRF trace collection level) in the uCosminexus Application Server Command Reference Guide.

comment

A comment begins with # (hash mark). All the characters from # (hash mark) up to the end of the line are assumed to be a comment.

The rules for coding the configuration file for the user-extended trace based performance analysis are as follows:

• You can use only single-byte characters in the code.
• A space character becomes a single-byte space character (0x20) or a tab character (\t or 0x09). Note that the space characters are ignored when the configuration file for the user-extended trace based performance analysis is read.
• Code one method to be traced on one line.
• You can specify up to 2,048 characters in 1 line. This character count includes the spaces and comments.
• The end of the line is indicated by 1 or more continuous linefeed characters (\n or 0x0A) or carriage return characters (\r or 0x0D).
• If the description in the configuration file for the user-extended trace based performance analysis is incorrect, a message describing the incorrect contents is displayed. Also, if invalid values are coded for the items, a message indicating incorrect contents is output, and the settings for that line are disabled.
  For details on the message, see 7.6 Logs output when the user-extended trace based performance analysis is executed.
  
• With the user-extended trace based performance analysis, you cannot specify the JavaVM classes and Cosminexus classes in the methods to be traced. The following packages are applicable:
  
  • Classes beneath java
  • Classes beneath javax
  • Classes beneath com.hitachi
  • Classes beneath JP.co.Hitachi
  Therefore, when you want to specify a package name by specifying the jvm.userprf.ExtendedSetting property, code the package name such that only the application classes are included.
  
• You cannot specify the following methods as the methods to be traced:
  
  • Non-existent package name, class name, and method name
  • native method
  • abstract method
  • Classes in JavaVM and the methods of those classes
    (Example) Classes of packages beginning with java and javax
    
  • Classes specified in -Xbootclasspath and the methods of those classes
  • Classes in Cosminexus
• You can specify the following methods as the methods to be traced using the following code:
  
  • You can specify the constructor using the same method name as the class name, or <init>.
    (Example) Specify as follows for the constructor of the MyMain class:
    MyMain.MyMain() or MyMain.<init>()
    
  • If you specify a method with the same name as a non-constructor class name, whether a constructor or a method has been specified cannot be determined, therefore, the constructor and method are traced.
  • When specifying a method with variable length arguments, describe the variable length arguments as an array.
    (Example) Specification of a method with variable length argument
    Example of correct specification: com.sample.Test.method(java.lang.String[] args)
    Example of incorrect specification: com.sample.Test.method(java.lang.String args)
    
  • Specify the name of a nested class using '$' (dollar sign) as a delimiter instead of '. ' (period).
    (Example) Specification of a nested class
    Example of correct specification: com.sample.Test$NestClass
    Example of incorrect specification: com.sample.Test.NestClass
    
  • You can specify a non-generics and non-parameter class name (raw type).
    (Example) Specification of a non-generics class
    Example of correct specification: com.sample.Test.method()
    Example of incorrect specification: com.sample.Test<java.lang.String,java.lang.Object>.method()
    
• The methods to be traced differ when you specify a class name and when you specify an interface name in class-name in specification-format.
  The following table describes the methods to be traced based on the class or interface specification.
  

  Table 7-8 Methods to be traced based on the class or interface specification

  Class or interface	Method to be traced
  	When false is specified in the subclass flag	When true is specified in the subclass flag
  Class	Method of the specified class	The methods of the specified class and the methods overriding these methods
  Interface	None	The methods of the class#1 that directly implements the specified interface and the class#2 that indirectly implements the interface, and the methods overriding these methods

  #1

  This class implements the interface specified by using implements when the class is declared.

  #2

  This subclass of the class that directly implements the specified interface, or the class that directly implements the interface that inherits the specified interface.

  
  

This section describes the examples of coding of the configuration file for the user-extended trace based performance analysis for each method to be traced.

Note that the examples of code assume that the package name is com.sample, and that the application has the class structure shown in the following figure.

Figure 7-8 Example of the class structure of the application

(a) To trace a method with matching method name and argument types

The following is an example of coding the user-extended trace based performance analysis configuration file when you want to trace a method with a matching method name and argument types:

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 coded method with a matching method name and argument types is traced.

Method to be traced

• methodA1(String,Object) of the ClassA class

The event ID is not set for the method to be traced, so if you invoke the method to be traced, the default value 0xae00 is output as the event ID at the method entry, 0xae01 is output at the method exit. Also, 1000 is set in the identity ID, so 1000 is output as the identity ID.

If the subclass flag is true

 
com.sample.ClassA.methodA2(),2000,true
 

If the subclass flag is true, in addition to the method in which the method name and argument types match the code, the methods overriding the coded method are also traced.

Methods to be traced

• methodA2() of the ClassA class
• methodA2() of the ClassB class that overrides methodA2() of the ClassA class

The event ID is not set for the method to be traced, so if you invoke the method to be traced, the default value 0xae00 is output as the event ID at the method entry, 0xae01 is output at the method exit. Also, 2000 is set in the identity ID, so 2000 is output as the identity ID for all the methods to be traced.

(b) To trace methods with matching method names

The following is an example of coding the user-extended trace based performance analysis configuration file when you want to trace methods with matching method names:

If the subclass flag is false

 
com.sample.ClassA.methodA1(*),methodA1,false,0xae30
 

If the subclass flag is false, all the methods matching with the coded method names are traced.

Methods to be traced

• methodA1(String,Object) of the ClassA class
• methodA1(int) of the ClassA class

If the method to be traced is invoked, 0xae30 is output as the event ID at the method entry, and 0xae31 is output at the method exit. Also, methodA1 is output as the identity ID for all the methods to be traced.

If the subclass flag is true

 
com.sample.ClassA.methodA1(*),methodA1,true,0xae30
 

If the subclass flag is true, all the methods matching with the coded method names are traced. Also, in addition to the coded method, the methods overriding the coded method are also traced.

Methods to be traced

• methodA1(String,Object) and methodA1(int) of the ClassA class
• methodA1(String,Object) of the ClassB class that overrides methodA1(String,Object) of the ClassA class
• methodA1(String,Object) of the ClassC class that overrides methodA1(String,Object) of the ClassB class

If the method to be traced is invoked, 0xae30 is output as the event ID at method entry, and 0xae31 is output at method exit. Also, methodA1 is output as the identity ID for all the methods to be traced.

(c) To trace all the methods with matching class names

The following is an example of coding the user-extended trace based performance analysis configuration file when you trace all the methods with matching class names, omitting the methods and arguments.

If the subclass flag is false

 
com.sample.ClassA,TEST01,false
 

If the subclass flag is false, all the methods with the coded class name (ClassA class) are traced.

Methods to be traced

• methodA1(String,Object), methodA1(int), and methodA2() of the ClassA class

If the method to be traced is invoked, 0xae00 is output at method entry and 0xae01 is output at method exit because the event ID is omitted. Also, TEST01 is output as the identity ID for all the methods.

If the subclass flag is true

 
com.sample.ClassB,TEST02,true
 

If the subclass flag is true, all the methods with the coded class name (ClassB class), and all the methods that override these methods are traced.

Methods to be traced

• methodA1(String,Object) of the ClassB class
• methodA2() of the ClassB class
• methodB1() of the ClassB class
• methodA1(String,Object) of the ClassC class that overrides methodA1(String,Object) of the ClassB class

If the method to be traced is invoked, 0xae00 is output at method entry and 0xae01 is output at method exit because the event ID is omitted. Also, TEST02 is output as the identity ID for all the methods.

(d) To trace all the methods with matching package names

The following is an example of coding the user-extended trace based performance analysis configuration file when you trace all the methods of all the classes with matching package names, omitting the class names, method names, and arguments.

Note

This specification also includes the sub-packages as trace targets. When a sub-package is to be traced, the trace is output when the target method is invoked.

If the com.sample package has a sub-package, all the methods of all the classes of that sub-package are also traced.

If the subclass flag is false

 
com.sample.*,6000,false
 

If the subclass flag is false, all the methods of all the classes in the coded package (com.sample) are traced.

Methods to be traced

All the methods of ClassA, ClassB, ClassC, and ClassD are traced.

If the method to be traced is invoked, 0xae00 is output at method entry and 0xae01 is output at method exit because the event ID is omitted. Also, 6000 is output as the identity ID for all the methods.

If the subclass flag is true

 
com.sample.*,6000,false
 

If the subclass flag is true, all the methods of all the classes in the coded package (com.sample), and all the methods that override these methods are traced.

Methods to be traced

All the methods of ClassA, ClassB, ClassC, and ClassD, and all the methods that override these methods are traced.

If the method to be traced is invoked, 0xae00 is output at method entry and 0xae01 is output at method exit because the event ID is omitted. Also, 6001 is output as the identity ID for all the methods.

The precautions to be taken when you create a configuration file for the user-extended trace based performance analysis are as follows:

• If you specify a different event ID or identity ID in multiple lines for the same method in the configuration file for the user-extended trace based performance analysis, the settings coded first in the configuration file for the user-extended trace based performance analysis will have priority.
• If you code multiple methods as targets in the configuration file for the user-extended trace based performance analysis, all the target methods are output with the same event ID or identity ID. In this case, if the method name that is output exceeds the number of characters that can be output, you might not be able to identify the method. Specify the settings so that one method can be identified.
• If you want to trace an interface, specify true in the subclass flag. If you specify false in the subclass flag, the trace information is not output because the methods to be traced do not exist in an interface.
• Use the specification format where multiple methods are the targets for user-extended analysis trace only when you want to understand the application operations.
  In the code of the configuration file for the user-extended trace based performance analysis, if true is specified in the subclass flag, and you specify the specification format by which the methods with matching method names are traced, many unintended methods become targets of the user-extended trace based performance analysis, and identifying the cause of performance deterioration might become difficult. To identify the cause of performance deterioration, we recommend that you limit the targets for user-extended trace based performance analysis by specifying false in the subclass flag of the configuration file for the user-extended trace based performance analysis, or use the specification format by which the methods with matching method name and argument types are traced.