5.2.2 cprfstart

The cprfstart command starts the PRF daemon.

Synopsis

cprfstart [-h] [-PRFID prf-identifier] [-PrfTraceLevel
    prf-trace-collection-level[,[prf-trace-collection-level]...]]
    [-PrfTraceCount prf-trace-file-count]
    [-PrfTraceFileSize prf-trace-file-size] 
    [-PrfTraceBufferSize prf-trace-file-size]
    [-PrfRemakeBuffer] [-PrfNoBackUp [0|1]] [-PrfConsole {0|1}]
    [-PrfLogShiftTime PRF-log-shift-time]
    [-PrfLogFileSize PRF-log-file-size] [-PrfLogFileCount Maximum-number-of-PRF-log-files]

Storage location

Application Server installation directory/common/PRF/bin/

Function

This command starts the PRF daemon (cprfd). You must start the PRF daemon before starting other processes.

Once the PRF daemon starts, you must change the current directory to the following:

prf-trace-output-directory$PRFSPOOL/utt/prf/prf-identifier/

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 set the PRFSPOOL environment variable. If it is not set, the command returns an error.
In the default settings after the OS is installed, the local host name is set for the IP address 127.0.0.1 in the /etc/hosts file. When a PRF is used, the local host name must be set for the IP address assigned to the network interface. For this reason, in the /etc/hosts file, set the correct IP address that is assigned to the network interface for the local host.

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

-h

Displays the command's usage.

-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

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

When -PrfTraceLevel is omitted, the information is output in Standard-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.

-PrfTraceCount prf-trace-file-count

Specifies the number of trace files, as a value in the range 3 to 256.

The PRF trace files are backed up during a normal stop and during a restart following a forced stop. If the total PRF trace file size is large, it might take a considerable amount of time to start and stop the PRF daemon because of the backup processing. Consequently, when Management Server is used to monitor processes, a timeout might occur if the monitoring time is set to the default value. If a timeout occurs, increase the monitoring time.

Default value: 4

-PrfTraceFileSize prf-trace-file-size

Specifies the maximum size (in kilobytes) of each PRF trace file, as a value in the range 1024 to 1048576. To set 1 megabyte as the file size, specify 1024. The actual file size may be slightly more or less than this value. The maximum difference will be 32 KB less than the value specified in -PrfTraceBufferSize.

If you specify 0 for the -PrfNoBackUp option, the PRF trace files are backed up during a normal stop, and during a restart following a forced stop.

If the total PRF trace file size is large, it might take a considerable amount of time to start and stop the PRF daemon because of the backup processing.

Therefore, if you specify 0 for the -PrfNoBackUp option to monitor processes by the domain administration server, a timeout might occur if the monitoring time is set to the default value.

If a timeout occurs, increase the monitoring time.

Default value: 8192

If you specify a value that is smaller than the default value of 8192, you must also specify a value smaller than the default value in -PrfTraceBufferSize.

-PrfTraceBufferSize prf-trace-buffer-size

Specifies the size (in kilobyte) of the buffer to be allocated in the shared memory, as a value in the range 512 to 102400. In this you cannot specify a value greater than the value specified in -PrfTraceFileSize with this option.

If the buffer area is insufficient, the KFCT26999-W message is displayed and the PRF trace might be omitted. Therefore, extend the buffer area until the message is no longer displayed.

Default value: 8192

-PrfRemakeBuffer

Re-creates the shared memory before restarting the PRF daemon. If the shared memory cannot be re-created, an error occurs.

-PrfNoBackUp [0|1]

Specifies whether to take a back up of the PRF trace file when the PRF daemon starts and stops.

If 0 is specified in the value, take the back up of the PRF trace file. Because the PRF trace file is copied, it might take time to start and stop the PRF daemon. After failure occurs, if the PRF trace file cannot be extracted until the PRF trace is wrapped, specify 0 in the value.

Note that when Management Server is used, the snapshot log containing PRF trace files is collected automatically after failure.

If 1 is specified, do not take a back up of the PRF trace file. If a value is not specified, the operation is same as when 1 is specified.

The following is the relation between the timings for taking backup of the PRF trace file, availability of backup, and the -PRFNoBackUp option:

Execution Command	End condition of PRF daemon which has started previously	Backup of PRF trace file
Execution Command	End condition of PRF daemon which has started previously	`-PrfNoBackUp 0`	`-PrfNoBackUp 1`
`cprfstart`	Normal end	No	No
`cprfstart`	Forceful end or abnormal end	Yes	No
`cprfstop`	Not dependent on end condition	Yes	No
`cprfstop -Force`	Not dependent on end condition	No	No

Default value: 1

-PrfConsole {0|1}

Specify whether to display the DOS prompt of the PRF daemon when the cprfstart command is executed from a Windows desktop. This option is available for the Windows OS only.

The following values can be specified:

1

Displays the DOS prompt.
0

Does not display the DOS prompt.

Default value: 0

-PrfLogShiftTime PRF-log-shift-time

If you want to shift the log file to be output by the PRF according to time, specify the shift time. Logs are shifted when logs are output to the log file. Therefore, logs are shifted only if logs are output.

The following values can be specified:

000000 to 235959

Default value: 000000

-PrfLogFileSize PRF-log-file-size

Specify, in megabytes, the maximum size of the log file to be output by the PRF.

The following values can be specified:

1 to 100

Default value: 10

-PrfLogFileCount Maximum-number-of-PRF-log-files

Specify the maximum number of log files that the PRF can output.

The following values can be specified:

1 to 32

Default value: 8

Exit Status

Exit Status	Explanation
`0`	The PRF daemon started normally.
`1`	Startup of the PRF daemon failed. 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

If you have to restart the PRF daemon, specify the same values in -PrfTraceCount and -PrfTraceFileSize as were set previously. Otherwise, when the PRF daemon is restarted without these options specified, the values that were being used during the previous session will not be inherited for the PRF trace file count and the PRF trace file size, so the default values will be used.
If the PRF daemon terminated abnormally and is then restarted, the trace collection level that was in effect when the PRF daemon terminated is inherited. Consequently, if the abnormal termination occurred after the trace collection level had been changed, a value that is different (changed value) from the trace collection level specified during the restart (the same value as was used during the previous session) is set. An example follows:
1. PRF daemon startup: cprfstart -PrfTraceLevel 0x00000001
2. Trace collection level change (0x00000001 to 0x0000000f)
3. PRF daemon abnormal termination
4. PRF daemon restart: cprfstart -PrfTraceLevel 0x00000001
In this case, the trace collection level following the restart is 0x000000f.
When the PRF daemon is restarted, the buffer that was used during the previous session is reused and the trace collection level is inherited. If the buffer size has been changed, the previous buffer is deleted and a new one is re-created. If another process is accessing the buffer, this re-creation process fails.

$PRFSPOOL/utt/prf/prf-identifier/spool/save/
If the PRF daemon terminates abnormally, re-start only the PRF daemon.
The trace, collected from the period of abnormal termination of the PRF daemon until the PRF daemon re-starts, is destroyed.
If a big value is specified in -PrfTraceCount or -PrfTraceFileSize, the re-starting of the PRF daemon after the abnormal termination might take time.

To Page Top