5.3.3 cprflevel

The cprflevel command displays or changes the PRF trace collection level.

Synopsis

cprflevel [-PRFID prf-identifier] [-h] [-PrfChangeLevel
    prf-trace-collection-level[,[prf-trace-collection-level]...]]
    [-PrfLevelIndex index-number] [-PrfLevelAll]

Storage location

Application Server installation directory/common/PRF/bin/

Function

This command displays or changes the PRF trace collection level.

When the -PrfChangeLevel option is omitted, the PRF trace collection level set for the specified PRF identifier is displayed. When the -PrfChangeLevel option is specified, the PRF trace collection level set for the specified PRF identifier is changed to the value specified here.

When the -PrfLevelIndex option is specified, a list of PRF trace collection levels for the specified index is displayed. When the -PrfLevelAll option is specified, the PRF trace collection levels for all indexes are displayed.

Execution permission

A user who has the following permission:

Either the same user for the processes that obtain PRF or the superuser
In an environment that uses the same PRFSPOOL environment variable, the superuser and other users coexist and the PRF commands cannot be executed. The PRF commands must always be executed by the same user.

Precondition

You must execute this command while the PRF daemon is active. If this command is executed while the PRF daemon is not active, an error message is output.

The same PRFSPOOL environment variable as the one assumed by the request destination PRF daemon must be set.

Environment variable

PATH

Add Application Server installation directory/common/PRF/bin and /bin.
LD_LIBRARY_PATH(Linux)

Specify Application Server installation directory/common/PRF/lib.
PRFSPOOL

Specifies the execution environment directory of the performance tracer (PRF daemon).

The PRFSPOOL environment variable is set by the domain administration server when the domain administration server starts a JAVA EE server or a cluster. If a PRF association whose association source is the Java EE server exists, the PRFSPOOL environment variable is set in the following format based on the PRF name of the association destination:

"Java-EE-Server-log-output-destination-directory-for-the-node-in-which-the-JAVA-EE-server-is-built/nodes/node-name/PRF-name"
TZ(UNIX)

Specifies the time zone.

Arguments

-PRFID prf-identifier

For the PRF identifier, specify the PRF server name that is given when the PRF is created by using the create-prf subcommand of asadmin.

Specifies a PRF daemon identifier, as 1 to 31 alphanumeric characters and the underscore (_). Do not specify a character string that begins with TSC or tsc or with CTM or ctm.

Default value: PRF_ID

-h

Displays the command's usage.

-PrfChangeLevel prf-trace-collection-level [,[prf-trace-collection-level]...]

Specifies PRF trace collection levels, each as a 4-byte hexadecimal number (8-digit value). You can add 0x at the beginning of the 4-byte hexadecimal number, however, 0x will be ignored.

You can specify multiple trace collection level values, corresponding to the index numbers (left to right), delimited by a comma (,). If a level value specification is to be omitted, do not specify any value. To omit specification of level values for all index numbers beginning after a specific index number, omit all the subsequent comma delimiters. To set the PRF trace collection level for index No. 1 to (1) and the PRF trace collection level for index No. 2 to (2), specify the arguments as (1),(2),....

The table below shows examples of PRF trace collection level specifications.

PRF trace collection level specification example	Option specification
Specify a PRF trace collection level for index No. 1	`-PrfTraceLevel 0x44445555`
Specify PRF trace collection levels for index Nos. 1 and 2	`-PrfTraceLevel 0x44445555,0x55554444`
Specify a PRF trace collection level for index No. 2	`-PrfTraceLevel ,0x55554444`

Assignment of PRF trace collection levels at each functionality layer is explained here.

A PRF trace collection level is specified as an eight-digit hexadecimal number for each index. Each digit is allocated two functionality layers. When a hexadecimal number is expressed as a decimal number, the functionality layer allocated to the upper 2 bits is called the upper layer, and the functionality layer allocated to the lower 2 bits is called the lower layer.

The table below shows the functionality layers that are allocated to the upper and lower layers for each digit.

Index	Digits	Upper layer	Lower layer
Index 1	Digit 1	(None)	Java EE Server
	Digit 2	(None)	Java VM
	Digit 5	(None)	uCosminexus TP1 Connector, TP1/Client/J

To specify a PRF trace collection level, decide whether to specify Standard, Detail, or Maintenance for the PRF trace collection level of the upper and lower layers for each digit, and specify it as a hexadecimal number. The table below shows the correspondence between combinations of PRF trace collection levels for the upper and lower layers with specification values.

Note that because the Maintenance level is used for collecting maintenance information when an error occurs, it should not be specified during normal operation.

Upper layer	Lower layer	Specification value
Standard	Standard	0
Standard	Detail	1
Standard	Maintenance	2
Detail	Standard	4
Detail	Detail	5
Detail	Maintenance	6
Maintenance	Standard	8
Maintenance	Detail	9
Maintenance	Maintenance	a

Specification examples are shown below.

Index	Specification example	Explanation
Index 1	`00000000`	Acquires Standard-level trace information from each functionality layer of index 1.
	`10000000`	Acquires Detail-level trace information from Java EE Server layer only, and acquires Standard-level trace information from other functionality layers.
	`11000000`	Acquires Detail-level trace information from both Java EE Server and the Java VM layers.

-PrfLevelIndex index-number

Specifies the index number of the PRF trace collection level to be changed or referenced, as an integer in the range 1 to 16.

Default value: 1

When this argument is specified together with -PrfChangeLevel, the PRF trace collection level for the specified index number is changed to the value specified in -PrfChangeLevel.

When this argument is specified but -PrfChangeLevel is not specified, the PRF trace collection level for the specified index number is displayed.

When you specify this argument together with -PrfChangeLevel, be sure to specify only a single value in -PrfChangeLevel.

Example: Change the value for the second index number to 0x55554444

cprflevel -PrfChangeLevel 0x55554444 -PrfLevelIndex 2

If multiple values are specified in -PrfChangeLevel, an option error occurs.

Example: Specify multiple values in -PrfChangeLevel

cprflevel -PrfChangeLevel ,0x55554444,0x55554444 -PrfLevelIndex 2

This is because multiple values are specified in -PrfChangeLevel even though 2 is specified in -PrfLevelIndex. If the specification of -PrfLevelIndex is omitted, 1 is assumed.

-PrfLevelAll

Displays all level values. This option cannot be specified together with -PrfChangeLevel or -PrfLevelIndex. The table below shows the combinations of this option and -PrfLevelIndex.

cprflevel current level value display method		-PrfLevelIndex
cprflevel current level value display method		Specified	Not specified
-PrfLevelAll	Specified	Option error	Displays all level values
-PrfLevelAll	Not specified	Displays the level value of only the specified index	Displays the level value of index 1 only

The table below shows the command option combinations that can be specified.

Command option	`-h`	`-PRFID`	`-PrfChangeLevel`	`-PrfLevelIndex`	`-PrfLevelAll`
`-h`	--	#`-h`	#`-h`	#`-h`	#`-h`
`-PRFID`	#`-h`	--	Y	Y	Y
`-PrfChangeLevel`	#`-h`	Y	--	Y	N
`-PrfLevelIndex`	#`-h`	Y	Y	--	N
`-PrfLevelAll`	#`-h`	Y	N	N	--

Legend:

Y: Can be specified simultaneously

#: Valid with the option whose name follows the #

N: Cannot be specified simultaneously

--: Not applicable

Input/output examples

Input example 1

cprflevel
Output example 1

KFCT73415-I 2661 1: prf trace level is 0x12345678
Input example 2

cprflevel -PrfLevelAll

Output example 2

KFCT73418-I 2661 1: all prf trace levels are:
[ 1]=0x12345678 [ 2]=0x00000000 [ 3]=0x00000000 [ 4]=0x00000000 
[ 5]=0x00000000 [ 6]=0x00000000 [ 7]=0x00000000 [ 8]=0x00000000 
[ 9]=0x00000000 [10]=0x00000000 [11]=0x00000000 [12]=0x00000000 
[13]=0x00000000 [14]=0x00000000 [15]=0x00000000 [16]=0x00000000

Input example 3

cprflevel -PrfLevelIndex 5
Output example 3

KFCT73419-I 2661 1: prf trace level of [5] is 0x00000000.
Input example 4

cprflevel -PrfChangeLevel 000000001
Output example 4

KFCT73416-I 2661 1: prf trace level was changed from 0x00000000 to 0x00000001.
Input example 5

cprflevel -PrfChangeLevel 0x00000055,0x55554444

Output example 5

KFCT73420-I 2661 1: prf trace level was changed:
[ 1]=0x00000000 -> [ 1]=0x00000055
[ 2]=0x00000000 -> [ 2]=0x55554444

Input example 6

cprflevel -PrfChangeLevel 0x44445555 -PrfLevelIndex 2
Output example 6

KFCT73420-I 2661 1: prf trace level was changed: [ 2]=0x00000000 -> [ 2]=0x44445555

Exit Status

Exit Status	Explanation
`0`	The command terminated normally.
`1`	The PRF daemon is not active. Either the `PRFSPOOL` environment variable is different from the one assumed for the PRF daemon or the value of `-PRFID` is invalid.
`2`	The `PRFSPOOL` environment variable has not been set up.
Other than the above	An error occurred during command processing. Take the corrective action indicated in the output message, and then re-execute the command. The error message is output to the standard error output and a log file.

Notes

When the current PRF trace collection level is to be displayed, the message that is output is KFCT73415-I, KFCT73418-I, or KFCT73419-I depending on the combination of the -PrfLevelIndex and -PrfLevelAll specifications The following shows the message that is output:

Message output for displaying PRF trace collection level		`-PrfLevelAll`
Message output for displaying PRF trace collection level		Specified	Not specified
`-PrfLevelIndex`	Specified	-	`KFCT73419-I`
`-PrfLevelIndex`	Not specified	`KFCT73418-I`	`KFCT73415-I`

When changing the PRF trace collection level, the message that is output by the -PrfChangeLevel specification is either KFCT73416-I or KFCT73420-I. When both of the conditions listed below are satisfied, KFCT73416-I is output; otherwise, KFCT73420-I is output:
- Only a single value is specified, as in -PrfChangeLevel 0x44445555, and no comma (,) is used.
- -PrfLevelIndex is not specified.
When you use this command to change levels, the changes will be applied from the next request onwards.

To Page Top