4.2.4 Reusing the log files by wrapping around (rotatelogs2 program)

You can split the access log, error log, and request log based on the log file size and output them to multiple log files by wrap around. The rotatelogs2 program can be specified in the following directives:

CustomLog directive
ErrorLog directive
HWSRequestLog directive
HWSWebSocketLog directive
TransferLog directive

Specify the program in the following format.

Organization of this subsection

(1) Format
(2) Parameters
(3) How to use
(4) Notes

(1) Format

rotatelogs2 Log-file-prefix-name Log-file-size Number-of-log-files

To Page Top

(2) Parameters

Log-file-prefix-name

This parameter specifies the prefix of output log file with an absolute path.

The output log file name is 'Prefix.nnn'.

.nnn is from .001 up to the value specified in the number of log files.

If 'Number of log files' is considered as nnn files, the last modified file in nnn files when HTTP Server is started, becomes the current log file. The log files are categorized by adding an extension .001~.nnn to the file name. When the extension of the current log file is .mmm, and if the current log file is full, then .mmm+1 log file is cleared and output. When .mmm matches with .nnn, the next log file is output with .001 extension.

For the Windows version, the prefix.index file for index number storage is created. The prefix.index file, which is used for .nnn management, is created when the rotatelogs2 utility starts, and is deleted when the rotatelogs2 program stops. However, the prefix.index file might not be deleted because of a startup error. This does not affect subsequent Web server operation.
Log-file-size ~ ((1-2097151))

This parameter specifies the maximum size for a log file (unit: KB).

When the log file is output, and if the size exceeds the maximum size of log file, the rotatelogs2 utility clears the next log file and the output is continued.
Number-of-log-files ~ ((1-256))

This parameter specifies the maximum number of log files to be output.

When the log file exceeds the maximum size and moves to the next file, and if the extension of the processed log files is same as the maximum number of files, reuse the from the file with extension .001.

To Page Top

(3) How to use

Specify the rotatelogs2 utility by using the |program-name format in directives.

Example: Collecting a maximum number of five error log files for every 4,096 KB

ErrorLog "|\"\"Application-Server-installation-directory/httpsd/sbin/rotatelogs2.exe\" \"Application-Server-installation-directory/httpsd/logs/errorlog\" 4096 5\""

The log is output in the sequence of errorlog.001 ~ errorlog.005. If the errorlog.005 exceeds 4,096 KB, errorlog.001 is cleared and output is continued. If these log files already exist when HTTP Server starts, the last updated log file is output. If the size of this log file already exceeds 4,096 KB, the next log file is cleared and the log output is continued. When the file size does not exceed 4,096 KB, the output is continued to the same file.

To Page Top

(4) Notes

(a) Notes for the UNIX version

The rotatelogs2 program does not end the process even if a SIGTERM, SIGUSR1 or SIGHUP signal is received, but ends the process when the control process and server process end.

(b) Notes for the Windows version

Start the Web server as a service. If you do not start the Web server as a service, the wrong log file might be cleared when you stop or restart the Web server.
Do not edit or delete the index number storage file while the rotatelogs2 program is running. If you edit the index number storage file, logs might not be output correctly
If a file with the same name as the prefix.index file for index number storage already exists when the Web server starts, the file is overwritten.
If an incorrect argument is present at startup, the Web server starts but the rotatelogs2 program does not start. The rotatelogs2 program outputs messages that contain the following attributes to the event log.
- Type: Error
- Source: CosminexusHTTPServer
- Class: none
- Event: 3299
- Description: rotatelogs2.exe: (message)
  
  For the meaning of output messages, see 23.7.5 rotatelogs2 program in the manual uCosminexus Application Server Messages.
When this message is displayed, follow the instructions in the message and specify valid arguments before restarting the server. Note that the same message might be output multiple times.

(c) Common notes for the UNIX and Windows versions

Specify the prefix name of log file with an absolute path.
When HTTP Server starts, the last modified log file is targeted for output and if a wrong file is updated, a wrong file is output.
When specifying log file size, do not specify a size that is so small that multiple log files exceed the specified size within same seconds. If you specify such a small size, proper rotation does not take place and the latest log file is not output.
In the configuration file, do not specify the same prefix for log files at multiple places. When you specify at multiple places, all files except the latest file are output and correct rotation does not take place.
If an argument is not specified correctly in the rotatelogs2 program for TransferLog, CustomLog, ErrorLog, and HWSRequestLog directives, the rotatelogs2 program fails to start but the Web server starts properly. In this case, logs are not output. When you specify the rotatelogs2 program for TransferLog, CustomLog, ErrorLog, and HWSRequestLog directives, make sure that the log files are created and the files are divided as you intended.

To Page Top