Job Management Partner 1/Base User's Guide

1.5.1 Converting application program log files

The following figure shows how the log file trapping function converts the contents of application program log files into JP1 events and registers them in an event database.

Figure 1-9 Overview of application log conversion to JP1 event registration

To perform log file trapping, create an action definition file for log file trapping, and then specify the output format of the log file you want to monitor and the conditions for converting log data into JP1 events. After that, execute the command to generate log file traps from the Windows log-file trap management service (or UNIX log-file trap management daemon), and to monitor the log files. All log entries that match the monitoring conditions are converted into JP1 events, which are then registered in the event database. Because multiple log file traps can run simultaneously, you can monitor a variety of log files using different monitoring conditions. You can also monitor multiple log files with one log file trap.

By default, messages up to 511 bytes can be registered as JP1 events. If a message exceeds this limit, the message is truncated from the 512th byte when it is converted into a JP1 event. If you want to extend the length of the message, specify the number of bytes (up to 1023) in the -m option of the jevlogstart command.

If you use a log file trap, the following conditions must be satisfied:

The character codes of the following files or locale information (such as LANG) used when executing the following command must be unified:

Log file to be trapped

Action definition file for log file trapping

jevlogstart command

If the character codes or locale information (such as LANG) are not unified, the characters might become garbled or log file traps might be generated.

Both the event service and Windows log-file trap management service (or UNIX log-file trap management daemon) must be active.
In Windows, the event service and log-file trap management service are set by default to start automatically when the system is started up.
In UNIX, you must execute the appropriate commands to start the event service and log-file trap management daemon. For details on starting services, see 5.2 Starting and stopping JP1/Base (in UNIX).

Starting and stopping log file traps:

Use the jevlogstart and jevlogstop commands to start and stop log file traps. Even if a log file has not been created yet, by specifying the -r option in the jevlogstart command, you can set up a trap to wait for that log file.

You can also stop log file traps individually, or reload a specific action definition file while a trap is active. To do this, specify an ID number that is output to the standard output when the log file trap is activated, or specify a monitoring target name that you have specified in the jevlogstart command when the log file trap is activated.

For details on the attributes of JP1 events converted and registered to the JP1 event database by the log file trapping, see 15.3(10) Details about event IDs specified in the ACTDEF parameter in the action definition file.

Organization of this subsection

(1) Types of log files that can be monitored

(2) Estimating the number of log files that can be monitored

(3) Start and end of monitoring

(4) Reattempting to monitor a log file when a trap fails

(5) Reattempting to connect to the event service

(1) Types of log files that can be monitored

Using the log file trapping, you can monitor log files up to 2 gigabytes in size. Also, you can monitor log files in a variety of formats. Check which file formats are supported, and specify the appropriate log file format in the action definition file for log file trapping. The supported log file formats are shown below.

Sequential file (SEQ)
A log file that is written to continuously or, when it reaches a certain size, is replaced with a new log file with a different file name. In the action definition file for log file trapping, specify SEQ. The following figure illustrates the behavior of a sequential file (SEQ).

Figure 1-10 Behavior of a sequential file (SEQ)

Sequential file (SEQ2)

In Windows:
A log file that is renamed, and then replaced by a new log file created with the same name as the original file.

In UNIX:
A log file that is renamed or deleted, and then replaced by a new log file created with the same name as the original file.

In the action definition file for log file trapping, specify SEQ2. The following figure illustrates the behavior of a sequential file (SEQ2).

Figure 1-11 Behavior of a sequential file (SEQ2)

Wrap-around file (WRAP1)
When the file reaches a certain size, data is wrapped around from the end, overwriting the existing data from the top of the file. In the action definition file for log file trapping, specify WRAP1.
To monitor a log file in WRAP1 format, disk space equal to or greater than the size of the file is required. The following figure illustrates the behavior of a wrap-around file (WRAP1).

Figure 1-12 Behavior of a wrap-around file (WRAP1)

Wrap-around file (WRAP2)
When the file reaches a certain size, data is wrapped around from the end, all the data is deleted and the new log data is again written from the top of the file. In the action definition file for log file trapping, specify WRAP2. The following figure illustrates the behavior of a wrap-around file (WRAP2).

Figure 1-13 Behavior of a wrap-around file (WRAP2)

Multi-process trace file (HTRACE)
Hitachi middleware-products, such as Cosminexus, use this log file format. The log file format is a group of fixed-size trace files that are shared by multiple processes as memory-mapped files. In the action definition file for log file trapping, specify HTRACE. The write method is the same as WRAP1. When the file reaches a certain size, data is wrapped around from the end, overwriting the existing data from the top of the file. The file modification time is not updated when data is written to the file. To determine whether the log file to be monitored is a multi-process trace file, see the relevant program manual. The following figure illustrates the behavior of a multi-process trace file (HTRACE).

Figure 1-14 Behavior of a multi-process trace file (HTRACE)

You can also monitor files with symbolic links using the log file trapping. However, you can change the file destination only for log files in SEQ2 format.

The following log files cannot be monitored:

Wrap-around files (WRAP1) whose modification time is not updated when new data is added, or whose modification time is updated even when new data has not been added
When a log file trap reads a wrap-around file (WRAP1), it references the date and time at which the file was last modified. Monitoring this type of file might cause the log file traps to operate incorrectly.

Special file or device file
A log file that contains records with binary data other than the end-of-line character.

File without an identifiable file name
A file whose file name contains values (such as process IDs) that change from time to time.

Network file
Operation cannot be guaranteed if a network error or delay occurs when a file on a remote computer is accessed by a file share or other method.

Log file containing only one line of data
A log file that always has only one line of data.

File accessed in lock mode
Log file traps open log files in read mode. In Windows, therefore, the program that outputs the monitored log might not be able to lock a target log file, so messages might not be logged.

File output in a language not supported in JP1/Base
In Windows, JP1/Base supports both MS932 and C.

(2) Estimating the number of log files that can be monitored

In Windows or UNIX, estimate the number of log files that can be monitored as follows.

In Windows:

The maximum number of log files that can be monitored is given by the following equation:

Legend:

a: Total number of log files monitored (including files monitored by multiple traps)

b: Total number of log files monitored by a log file monitoring job executed in JP1/AJS (including files monitored by multiple traps)

m: Number of jevlogstart command executions

n: Number of log file monitoring jobs executed in JP1/AJS

In UNIX:

A maximum of 100 files can be monitored by one log file trap. However, the maximum number that can be monitored on a specific UNIX system depends on a setting in the kernel parameters (maximum number of open files).

(3) Start and end of monitoring

Log file monitoring begins when you activate the log file trapping function via the jevlogstart command. The activated log file traps monitor the log files at set intervals. The default is 10 seconds. You can change the monitoring interval by specifying the -t option in the jevlogstart command. The time at which log file monitoring stops depends on whether you specify the -w option in the jevlogstop command. For details on the commands, see 13. Commands.

If you restart a log file trap, log entries output between the time the trap stopped and the time it restarts are not monitored.

(4) Reattempting to monitor a log file when a trap fails

When the time at which a log file is being monitored conflicts with an update time, the log file might become locked by the updating program, which prevents the log file trap from opening and reading the log file. If this happens, you can still reattempt to monitor the log files.

If the log file trap is monitoring multiple log files and one of the files cannot be opened, the log file trap will reattempt to monitor the log file where the error occurred, and will also continue monitoring the other log files.

If a retry fails, the log file will no longer be monitored. Check the error message and determine whether there is an error in the log file. To restart the monitoring of a log file where an error occurred, restart the log file trap using the jevlogstart command.

The following describes the retry action when the log file trapping function is unable to open a log file at the start of monitoring or fails to read a log file during monitoring.

(a) When a log file cannot be opened for monitoring

The log file that will be monitored opens when you start a log file trap using the jevlogstart command. If the file has been locked by the updating program, it cannot be opened and monitoring will not start. In this case, by default, the log file trap will retry one second later, and only once. You can reconfigure the retry interval and retry count in the action definition file for log file trapping.

If the log file opens successfully upon the retry, monitoring resumes from the point at which the file was opened.

If the log file fails to open after the specified number of retries, or if the monitoring process has not opened after 3,600 seconds have elapsed since the retries began, the error is reported by an error message and JP1 event 00003A20. For details on this JP1 event, see 15.3(4) Details about event ID 00003A20.

The figure below shows an example of the retry process when the log file trap is temporarily unable to open a log file for monitoring. In this example, the retry interval is 1 second and the retry count is 3.

Figure 1-15 Example of the retry process when a log file cannot be opened for monitoring

(b) When a log file cannot be read during monitoring

The log file trapping function retries five times at 10-millisecond intervals when it fails to read a log file during monitoring. If monitoring has not recovered after five retries, the trap is suspended until the next monitoring time. If the trap is still unable to open the file the next time it attempts to monitor the file, it retries another five times at 10-millisecond intervals. The retry interval and retry count are fixed.

By default, 100 sets of five retries at 10 ms intervals are performed. You can specify a threshold value for how many retry sets to perform in the action definition file for log file trapping.

If monitoring cannot be recovered after the specified number of retries, monitoring of the log file where the error occurred stops and JP1 event 00003A21 is issued. For details on this JP1 event, see 15.3(5) Details about event ID 00003A21.

The figure below shows an example of the retry process when the log file trap is unable to read a log file during monitoring. In this example, a threshold of 3 is set for the number of retry sets.

Figure 1-16 Example of the retry process when a log file cannot be read during monitoring

(5) Reattempting to connect to the event service

By default, if a connection to the event service cannot be established, connection retry processing is not performed and the event log trapping fails to start, or stops if it is already active. To attempt a connection to the event service, set the parameter separately for specific log file traps in the action definition file for log file trapping. If the log file trapping function cannot connect to the event service after retrying for the specified number of times, it fails to start, or stops if already active.

The JP1 events converted during a retry are saved in the system up to a specified maximum number. When this maximum is reached, all subsequent JP1 events are deleted.

When successfully connected, the trap starts sending the retained JP1 events to the event service in the order in which they were held. Notification that a connection has been established is also sent as a JP1 event. For details on JP1 events, see 15.3(3) Details about event ID 00003A10.

[Contents][Back][Next]

[Trademarks]