7.5.3 Settings for the methods to be traced by the user-extended trace based performance analysis

(1) Format of description

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

specification-format#, identity-ID, subclass-flag [, [event-ID][,[trace-collection-level]]] [# Comment]

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

To Page Top

(2) Description items

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.

Important 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 (display or change the 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.

To Page Top

(3) Rules of description

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[])

    Example of incorrect specification: com.sample.Test.method(java.lang.String...)

  • 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.

To Page Top

(4) Example of description of the configuration file for the user-extended trace based performance analysis

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

To Page Top

(5) Notes on creating the configuration file for the user-extended trace based performance analysis

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.

To Page Top