4.2.10 Collecting the internal trace (hwstraceinfo command)
When an application program is executed and a request is received, the events that occur in the system are collected as internal trace. The internal trace is output once to the shared memory, and then it is output to the file as per the specification in the directive or command.
- Organization of this subsection
(1) Collecting trace information
Internal traces are collected in the shared memory when various events occur in the Web server. The memory identifiers of shared memory are stored in the file specified in the HWSTraceIdFile directive.
(2) How to output to a file
The internal trace that is collected in the shared memory is output to a file when the server process terminates abnormally or when the hwstraceinfo command is executed. When the server process terminates abnormally, the trace is output to the file specified in the HWSTraceLogFile directive.
Specify the memory identifier and file name of output destination, in the hwstraceinfo command. For the UNIX version, only the user specified in the User directive or the superuser can execute the hwstraceinfo command. For the Windows version, only the user with administrative permission can execute the hwstraceinfo utility.
The internal trace information output file size is as follows:
- For the UNIX version
-
- When the prefork MPM is used
-
Output size of the ps -efl command + output size of the vmstat command + output size of the ipcs -a command + 7 KB × MaxClient value
- When the worker MPM is used
-
Output size of the ps -efl command + output size of the vmstat command + output size of the ipcs -a command + 2 KB × total number of server threads (ServerLimit value × ThreadLimit value)
- For the Windows version
-
7 KB × ThreadPerChild value
(3) hwstraceinfo command
This section describes how to specify the hwstraceinfo command.
(a) Format
hwstraceinfo -i shared-memory-identifier {-l file-name|-r}
(b) Parameters
-
-i shared-memory-identifier
This parameter specifies the shared memory identifier that is output to the file specified in the HWSTraceIdFile directive.
-
-l file-name
This parameter specifies the file that outputs the trace corresponding to the shared memory identifier specified with -i.
-
-r
This parameter releases the shared memory allocated to the shared memory identifier specified in -i. In UNIX version, the shared memory for trace remains even if the Web server stops. Use this parameter to release the remaining shared memory. In Windows version, the shared memory for trace is released when you terminate the Web server, so this parameter is not provided.
(c) Usage example
The following is an example to output the trace corresponding to the shared memory identifier 1800_1133780652_0, to the traceinfo.log file:
hwstraceinfo -i 1800_1133780652_0 -l traceinfo.log
(4) Points to be noted when releasing shared memory and restarting (UNIX Version)
To retain trace information, the Web server does not release the shared memory even when the Web server stops. The shared memory is reused when the server restarts.
When you stop the server and restart it later, the Web server releases the shared memory once and then restores it depending upon the file value specified in the HWSTraceIdFile directive. However, in the following cases, the shared memory used earlier cannot be released:
-
When the same user does not restart the server (the User directive value or the Group directive value has changed)
-
The value of the HWSTraceIdFile directive has changed
-
The file specified in the HWSTraceIdFile directive is deleted
When you release the shared memory, execute the hwstraceinfo command in which -r is specified.