jevlogstart
- Organization of this page
Function
The jevlogstart command starts the log file trapping. This command searches the specified log file for lines that satisfy the conditions specified in the action definition file for log file trapping. It converts each of the matched lines into a JP1 event, and then registers each event in the event server. Before executing this command, you must create an action definition file for log file trapping.
The locale information (language specified for LANG or other settings) in the environment in which this command was executed is used for monitoring logs and registering JP1 events. Therefore, you must set the same language for the action definition file for log file trapping and for the monitored log files.
For details about the languages of log files that can be monitored in UNIX, see 3.4.2 Setting the language (for UNIX). In Windows, the languages of log files that can be monitored are MS932, Unicode (UTF-8, UTF-16), and C. To monitor Unicode files, create an action definition file for log file trapping in the language of the OS, not in Unicode.
Log files that use different output data formats cannot be handled together by the log file trapping function. In such a case, execute the log file trapping function for each individual log file.
After you execute this command and a log file trap starts successfully, the ID of the log file trap is output to the standard output. This ID is a thread ID in Windows, or a process ID in UNIX. This ID is used by the following commands:
-
jbsgetopinfo command (Collect operating information)
-
jevlogstat command (Check the operating status)
-
jevlogstop command (Stop the log file trap)
-
jevlogreload command (Reload)
For details on the command used to collectively start the log file traps specified in a log-file trap startup definition file when a failover occurs in a cluster system, see jevlogstart (cluster environment only).
Format
jevlogstart [-f action-definition-file-for-log-file-trapping]
[-t file-monitoring-interval-in-seconds]
[-m data-size-for-conversion-in-bytes]
[-h]
[-n display-command-name-for-UNIX only]
[-p log-data-source-program-name]
[-r]
[-s destination-event-server-name]
[-a monitoring-target-name]
[{-g UTF-8 | -g [UTF-16] [-b { LE | BE }]}] (Windows only)
[-x]
{ log-file-name1[...log-file-name32(100)] |
log-file-name (when monitoring UPD log files) }
Required execution permission
In Windows: Administrators (If User Account Control (UAC) for Windows is enabled, you must execute the command from the administrator console.)
In UNIX: Superuser or JP1/Base administrator permission
Command directory
- In Windows:
-
installation-folder\bin\
- In UNIX:
-
/opt/jp1base/bin/
Arguments
-f action-definition-file-name
Specify the name of the action definition file for log file trapping in no more than 256 bytes. If you specify a relative path, make sure that the full path when the directory name is added will not exceed 256 bytes. Specify a path relative to the current directory where you execute the command.
Note that you cannot specify the action definition file for log file trapping under one of the following conditions:
-
The folder name, directory name, or file name contains an environment-dependent character.
-
In UNIX, the file name contains a space character.
-
In Windows, the file is a Unicode file.
You can omit this option if you have already created a jevlog.conf file in the conf folder, and have specified the action definitions in that file.
The jevlog.conf file resides in the following directory.
- In Windows:
-
installation-folder\conf\
- In UNIX:
-
/etc/opt/jp1base/conf/
-t file-monitoring-interval (in seconds)
Specify the interval for monitoring the log file. The specifiable range is 1 to 86,400 seconds (24 hours). If you omit this option, the default is 10.
- Monitoring a log file in WRAP1, WRAP2, or HTRACE format
-
If the wrap-around frequency is too high or if the monitoring interval is too long, the file might be overwritten before the log file trap reads the data and some entries might be missed. To prevent entries from being missed, use the following equation to estimate the monitoring interval:
log-file-size (bytes) x number-of-log-files > output-size-per-second (bytes) x monitoring-interval (seconds)
-m data-size-for-conversion (in bytes)
Specify how much data is to be converted into a JP1 event each time a specified log file is read. Specify the number of bytes (1 to 1,024) from the start of a line. The end-of-line character is converted into an end-of-line symbol (\0). This symbol is included in the specified data size. If a line read from a log file exceeds the specified number of bytes, the size of the converted data equals the number of bytes specified by -m, minus one byte.
The value specified in this option indicates the valid range of a line of data in the input log files. Thus, for regular expressions specified in the MARKSTR and ACTDEF parameters in the action definition file for log file trapping, the system check applies only to the regular expressions that are within the range specified in the -m option. Regular expressions that select columns outside this range are not checked. If you omit this option, the default is 512. The end-of-line character is converted into an end-of-line symbol (\0).
-h
Specify this option to read the log from the start of the file. If you execute the jevlogstart command without this option after the program that outputs log data has started, the log already output by the program will not be read. By specifying the -h option, however, you can read the log data from the start of the file.
If the log file is a wrap-around file, the trapping service first reads all the log data from the start of the file to the end of the file (EOF), and then finds the current pointer and reads the latest data.
-n display-command-name (for UNIX only)
This option is available for UNIX only.
Specify the display name of the command for the log file trapping. The command name specified in this option is displayed in the result of the ps command. Specify the command name in no more than 256 bytes. You cannot include a space character in the display command name. If you omit this option, log-file-name1 is assumed as the display command name.
-p log-data-source-program-name
Specify the name of the program that outputs the log data. Specify the program name in no more than 256 bytes. You cannot include a space character in the program name.
This name will appear in the Event Console window of JP1/IM - View. The program name is shown as follows.
- In Windows:
-
/HITACHI/JP1/NT_LOGTRAP/log-data-source-program-name
- In UNIX:
-
/HITACHI/JP1/UX_LOGTRAP/log-data-source-program-name
If you omit this option, the program name is shown as /HITACHI/JP1/NT_LOGTRAP (in a Windows system) or /HITACHI/JP1/UX_LOGTRAP (in a UNIX system).
-r
When the -r option is specified, if a specified log file does not exist when the log file trapping starts, the system keeps trying to access the file, according to the interval specified in the -t option, until the file is created. When file open processing succeeds, the trapping service starts searching the log data.
When monitoring UPD type log files, the log file trapping function checks for monitoring targets at the interval specified in the -t option, until it detects a log file whose file name matches the name (and wildcard pattern) specified when the log file trap was started.
When monitoring log files on a shared disk, configure the log file trap to start and stop when the logical host starts and stops. Use the -r option when you want to monitor log files that are created after the log file trap starts.
When the -r option is omitted, the log file trapping cancels access and terminates the processing if a specified log file does not exist when the log file trapping starts.
-s destination-server-name
Specify this option to change the destination server for JP1 event registration to the server specified here. Only an event server running on the local host can be specified. If you omit this option, the local host name is assumed as the event server name (host name returned by the hostname command). Specify a destination server name in no more than 255 bytes. Specify the destination server name in no more than 255 bytes. Destination server names are case sensitive.
This option is primarily for use in a cluster system.
If an event service on a physical host starts with FQDN in an environment with a short name for the local host name, you can use this option to explicitly specify the event server name in the FQDN format.
-a monitoring-target-name
Specify a monitoring target name as an alias for the ID number. You can enter a character string that is no more than 30 bytes for the target name. You can use alphanumeric characters, hyphens, and underscores for the target name. However, the name must start with an alphanumeric character. Event server names are case sensitive.
-g UTF-8 | -g [UTF-16] [-b { LE | BE }]
This option can be specified in Windows only.
If you specify this option, the log file trap monitors the log files as Unicode files. Also, JP1 events are registered in the UTF-8 code set. As the regular expressions used, extended regular expressions are applied to the conditions in the action definition file.
If you omit this option, the log file trap monitors the log files as non-Unicode files.
- -g UTF-8
-
The log file trap monitors the log files as UTF-8 Unicode files.
- -g [UTF-16]
-
The log file trap monitors the log files as UTF-16 Unicode files. You can omit the specification value, UTF-16. Note that this argument cannot be specified if HTRACE is specified for the FILETYPE parameter in the log file trap definition file.
The following UTF-16 Unicode types are supported for monitoring:
-
UTF-16: UTF-16 with BOM (Byte Order Mark)
-
UTF-16LE: Little-endian UTF-16 without BOM
-
UTF-16BE: Big-endian UTF-16 without BOM
- When monitoring Unicode files with BOM:
-
The byte order (Little-endian or Big-endian) is determined by the BOM value.
- When monitoring Unicode files without BOM:
-
You can use the -b {LE | BE} option to specify the byte order of the Unicode files. If you omit the -b {LE | BE} option, the byte order is determined depending on the processor architecture. In Windows, log files are monitored as Little-endian Unicode files (UTF-16LE format).
-
- -b { LE | BE }
-
You can use this option to explicitly specify the byte order of Unicode files. This option must be specified following the -g [UTF-16] option.
- When monitoring Unicode files with BOM:
-
This option is ignored and the byte order is determined by the BOM value.
- When monitoring Unicode files without BOM:
-
Log files are monitored as Unicode files with the specified format. You can specify either of the following values:
- LE
-
Log files are monitored as Little-endian Unicode files (UTF-16LE format).
- BE
-
Log files are monitored as Big-endian Unicode files (UTF-16BE format).
-x
Specify this option to set the output source host in the JP1_SOURCEHOST extended attribute of log file data converted to JP1 events.
log-file-name1[...log-file-name32(100)]
Specify each name of the monitored log file in no more than 256 bytes. If you specify a relative path, make sure that the full path when the directory name is added will not exceed 256 bytes. Specify a path relative to the current directory where you execute the command. Specify the log file names after the final option.
Do not specify the following log file names:
-
A file name that begins with a hyphen (-).
-
A folder name, directory name, or file name that contains an environment-dependent character
-
In UNIX, a directory name or file name that contains a space character
You can specify 32 log file names in Windows, and 100 in UNIX. Remember that since the number of files that can be accessed concurrently is system-dependent, the maximum number of files that can be actually specified might be fewer than 32 (or 100) in some cases. In a UNIX system, one process is required for monitoring one log file.
Note that when you specify a single log file for one execution of the jevlogstart command, the output order of log data matches the registration order of JP1 events. Conversely, when you specify multiple log files for one execution of the jevlogstart command, each log file is monitored independently. At this time, log data might be output over multiple log files during an interval between monitoring operations. In such a case, the output order of log data might not match the registration order of JP1 events because each log file is monitored in parallel.
Therefore, the ps command lists the command names in the form log-file-name.child.
log-file-name (when monitoring UPD log files)
Specify the log file name to use when monitoring UPD type files in no more than 256 bytes. Use this argument when you specify UPD in the FILETYPE parameter of the action definition file for log file trapping.
Specify a log file name using wildcards (* or ?). An asterisk represents a character string of zero or more characters, and a question mark represents any one character. You can use wildcards in the file name, but not the path. For UNIX, refer to the following examples to prevent the shell from evaluating wildcards:
- Example:
-
-
Enclose the file name with double quotation marks ("").
"/home/log*.log"
-
Escape the wildcard with a backslash (\).
/home/log\*.log
-
For both Windows and UNIX, you can specify only one file name.
You can specify only one file name in Windows and UNIX.
If you specify a relative path, make sure that the full path with the directory names added will not exceed 256 bytes. The path is interpreted relative to the current directory at command execution. Specify the log file name after the final option.
Do not specify the following log file names:
-
A file name that begins with a hyphen (-).
-
A folder name, directory name, or file name that contains an environment-dependent character
-
In UNIX, a directory name or file name that contains a space character
Notes
-
Some types of log files cannot be monitored. For details on the formats of log files that can or cannot be monitored, see 2.4.4 Types of log files that can be monitored and 2.4.5 Types of log files that cannot be monitored.
-
Start the log file trapping before you start the program that outputs the log you want to monitor. Trapping will not be performed correctly if the trapping is started while data is already being output to the specified log file. If you wish to specify a log file that does not yet exist, use the -r option to keep the log file trapping waiting for the file.
-
Before executing the jevlogstart command, ensure that the log-file trap management service (in Windows) or log-file trap management daemon (in UNIX) is running.
-
When monitoring UPD log files, if you start a log file trap that monitors a log file name specified using several wildcards (*), the log file trapping function might take a long time to search for monitoring targets. For this reason, use wildcards only where necessary.
-
When monitoring UPD log files, the log file trapping function will not monitor files with file names longer than 256 bytes, even if the file matches the wildcard pattern.
-
When monitoring UPD log files, the log file trapping function might monitor a non-log file created in the target directory if it happens to match the wildcard pattern. Do not use the monitoring-target directory as a destination for backup files or other data.
-
If the message KAVA3667-E or KAVA3672-E is output when you monitor UPD log files, there might be more than one log file with the most recent update time (within one second). Change the file names so that only one of these files matches the wildcard pattern, and then restart the log file trap.
-
If you executing the jevlogstart command with the -g option specified to monitor Unicode files, JP1 events are registered in the UTF-8 code set. Upgrade the JP1/Base on the host (to which those JP1 events are forwarded) to version 8 or later.
-
If you specify the -h option and a large log file is monitored, loading of the log data that was output after log file trapping started might be delayed or many events might occur. If a loading delay or the occurrence of many events adversely affects operation, stop the log file trapping and then restart it without specifying the -h option.
Return values
|
0 |
Normal end |
|
1 |
Invalid argument |
|
2 |
The log-file trap management service or log-file trap management daemon is inactive. |
|
3 |
The event service is inactive. |
|
4 |
A monitoring target with the same name has already been started (output only when the -a option is specified). |
|
255 |
Other error |
The jevlogstart command outputs an ID number to the standard output. The ID number is required to stop log file trapping.
Example
These examples are for Windows. Example 6 applies to monitoring UPD log files.
- Example 1
-
Search for and read data from log file c:\log\logfile1.log. This example omits all arguments except the log file name. In this case, the log-file trap startup definition file is jevlog.conf in the JP1/Base conf folder, the monitoring interval is 10 seconds, and the maximum data size for event conversion is 512 bytes.
jevlogstart c:\log\logfile1.log
- Example 2
-
Search for and read data from log file c:\log\logfile1.log, using the action definition file for log file trapping c:\conf\configfile.conf.
jevlogstart -f c:\conf\configfile.conf c:\log\logfile1.log
- Example 3
-
Search for and read data from the UTF-8 Unicode file logfile_uni.log in c:\log, using the action definition file for log file trapping c:\conf\configfile.conf.
jevlogstart -f c:\conf\configfile.conf -g UTF-8 c:\log\logfile_uni.log
- Example 4
-
Search for and read data from the UTF-16BE-format Unicode file logfile_uni_be.log in c:\log, using the action definition file for log file trapping c:\conf\configfile.conf.
jevlogstart -f c:\conf\configfile.conf -g UTF-16 -b BE c:\log\logfile_uni_be.log
- Example 5
-
Search for and read data from log files c:\log\logfile1.log and c:\log\logfile2.log, using a monitoring interval of 5 seconds.
jevlogstart -t 5 c:\log\logfile1.log c:\log\logfile2.log
- Example 6
-
Search for and read data from a file in the c:\log folder whose name begins with logfile., using the action definition file for log file trapping c:\conf\configfile.conf.
jevlogstart -f c:\conf\configfile.conf c:\log\logfile.*