Job Management Partner 1/Base User's Guide

[Contents][Glossary][Index][Back][Next]

Action definition file for log file trapping

Format

retry-times=number-of-retries (to connect to the event service)
retry-interval=retry-interval (to connect to the event service)
open-retry-times=retry-count (to open a log file)
open-retry-interval=retry-interval (to open a log file)
read-retry-times=retry-sets-threshold (to read a log file)
hold-count=number-of-JP1-events-to-be-held
keep-event={ OLD | NEW }
FILETYPE={ SEQ | SEQ2 | WRAP1 | WRAP2 | HTRACE }
RECTYPE={VAR { '\n ' | 'end-of-line-character' | 'end-of-line-symbol'} | FIX record-length }
HEADLINE=number-of-header-lines
HEADSIZE=header-size
MARKSTR=[!]"regular-expressions"
[!]"regular-expression"#
ACTDEF=[{EXIT}][<severity>][event-ID][!]"regular-expressions"
[!]"regular-expression"#

#: The regular expression n represents multiple specifications.

File name

Any

Storage destination directory

Any

If you have created an action definition file for log file trapping with the file name jevlog.conf in the following directory, you can omit the -f option in the jevlogstart command.

In Windows:
installation-folder\conf\

In UNIX:
/etc/opt/jp1base/conf/

You can create an action definition file for log file trapping in any directory, using any file name. However, you must specify a file name with the directory name added for the -f option of the jevlogstart command.

Description

Specifies the format of the monitored log file, the retry settings when monitoring fails and other settings. The action definition file for log file trapping is not provided by default. Users can create the file, or the file can be created by using the distribution definition function.

Application of settings

The settings are applied when you execute the jevlogstart command or the jevlogreload command. For details on the jevlogstart and jevlogreload commands, see jevlogstart and jevlogreload in 13. Commands.

Definition details

The following conventions apply to entries in the action definition file for log file trapping:

retry-times=number-of-retries (to connect to the event service)
Specify the number of retries to perform when a connection to the event service fails due to a temporary communication error. Specify a number from 0 to 86400. If you omit this parameter, retry processing is not performed.
Regardless of the settings in retry-times and retry-interval, an error occurs when 86,400 seconds (24 hours) have elapsed since the retries began.

retry-interval=retry-interval (to connect to the event service)
Specify the retry interval when a connection to the event service fails due to a temporary communication error. This parameter is valid only when you specify a value of 1 or greater in retry-times. The retry interval is the length of time from when the trap fails to connect to the event service until when it next tries to establish a connection. This interval does not include the time required for the connection processing. Specify a number from 1 to 600 (seconds). The default is 10.
Regardless of the settings in retry-times and retry-interval, an error occurs when 86,400 seconds (24 hours) have elapsed since the retries began.

open-retry-times=retry-count (to open a log file)
Specify the number of retries to perform when the log file trapping function is temporarily unable to read a log file for monitoring. Specify a number from 1 to 3600. The default is 1.
Regardless of the settings in retry-times and retry-interval, an error occurs when 3,600 seconds (1 hours) have elapsed since the retries began.

open-retry-interval=retry-interval (to open a log file)
Specify the retry interval when the log file trapping function is temporarily unable to read a log file for monitoring. The retry interval is the length of time from the open failure until the next time the trap attempts to open the log file. Specify a number from 1 to 600 (seconds). The default is 1.
Regardless of the settings in retry-times and retry-interval, an error occurs when 3,600 seconds (1 hours) have elapsed since the retries began.

read-retry-times=retry-sets-threshold (to read a log file)
Specify for a threshold value the number of continuous retry sets to perform when the log file trapping function is temporarily unable to read a log file. This threshold is the total number of retry sets, where one set is five retries at 10-millisecond intervals. When the specified threshold is exceeded, an error occurs. Specify a number from 1 to 1000. The default is 100.

hold-count=number-of-held-JP1-events
Specify the number of JP1 events that can be held during retry processing. Specify a number from 1 to 1000. The default is 100.
The system resources must be utilized to hold JP1 events converted from log data during retry processing. The memory requirement is as follows:
number-of-JP1-events-to-be-held (kilobytes)

keep-event={ OLD | NEW }
When the number of JP1 events held during retry processing exceeds the specified hold count, the excess JP1 events will be deleted. Specify whether to keep the older JP1 events or the recent JP1 events once the maximum number that can be held has been exceeded. The default is OLD.

OLD
Specify this value to keep older JP1 events. JP1 events will be held up to the number specified in the hold-count parameter. Any subsequent JP1 events will be deleted.

NEW
Specify this value to keep recent JP1 events. When the specified hold count has been exceeded, JP1 events will be deleted, starting from the oldest.

FILETYPE={ SEQ | SEQ2 | WRAP1 | WRAP2 | HTRACE }
Specify the data output format of the log file to be read. The default is SEQ.

SEQ
Specify for a sequential file (a log file that is written to continuously or, when it reaches a certain size, is replaced by a new log file with a different file name).

SEQ2
Specify SEQ2 for the following files:
  • 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.

Note
When SEQ2 is specified, the system reads the data written to the previous log file since the last read, and then reads the data from the new log file that was swapped in during the monitoring interval. If the log file is switched more than once during the monitoring interval, the system can only read data from the last file. When specifying the -t option (monitoring interval) in the jevlogstart command, consider how often the log file will be switched.

WRAP1
Specify in case of a wrap-around file (data is wrapped around from the end, overwriting the existing data from the top of the file).
To determine the read position of a WRAP1 file, the log file trapping function makes a copy of the log file to be read and compares it with the current log file. Therefore, the sizes of WRAP1 and the file to be monitored must be the same.

Note
When a large log file is being monitored with the WRAP1 setting, it will take a long time for the first JP1 event to be generated if the write data position is near the end of the file.

WRAP2
Specify in case of a wrap-around file (when all data is wrapped around from the end, overwriting the existing data from the top of the file).
Specify a SEQ2 file if you want to delete or rename the full log file and re-create the log file.

Notes
  • When WRAP2 is specified, some data might not be read if data is deleted as a result of wrapping around before the trapping service reads all the data. Remember this when specifying the -t option (monitoring interval) in the jevlogstart command because a long monitoring interval results in a large amount of data being read at one time.
  • JP1/Base detects a wraparound by detecting reduction in the file size. Note that JP1/Base does not assume a wraparound if the file size after a wraparound is equal to or greater than that before a wraparound.

HTRACE
Specify in case of a multi-process trace file (a pair of fixed-size trace files that are shared by multiple processes as memory-mapped files).
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.

RECTYPE={ VAR { '\n ' | 'end-of-line-character' | 'end-of-line-symbol'} | FIX record-length }]
Specify the record format of the log file to be read. The default is RECTYPE=VAR'\n '. In other words, the default format is variable-length records with \n at the end for the line separator.

VAR
For variable-length record format, specify the end-of-line character or end-of-line symbol. As with the single character specification in the C language, you can enclose the character or symbol with single quotation marks and specify an escape sequence.

FIX
For the fixed-length record format, specify the record length as the line separator. Specify the record length as a number in the range from 1 to 9999999 (bytes).

HEADLINE=number-of-header-lines]
If the log file has headers, specify the number of header lines as a number from 0 to 99999 (lines). The default is 0.

HEADSIZE=header-size]
If the log file has headers, and if the number of header lines cannot be specified, specify the header size as a number from 0 to 9999999 (bytes). Headers that cannot be specified with a header line count include headers in binary data, and headers whose record format differs from the log data. This parameter is invalid if the HEADLINE parameter is specified. The default is 0 bytes.

MARKSTR=[!]"regular-expressions"
Using regular expressions, specify any data that you do not want to monitor, for example, data other than log data. Enclose the regular expression with double quotation marks. Data other than log data includes, for example, data output to a log file at regular intervals. An example is shown below.
 
"==== 13:00:00 JP1/Base Event ===="
Specify an exclusion condition by writing an exclamation mark in front of the value enclosed with quotation marks. This excludes data that does not match the regular expression from being monitored.
More than one regular expression can be specified in one MARKSTR parameter. When multiple regular expressions are specified, they are interpreted as AND conditions, and only data that matches all the conditions, including the mismatch (!) condition, is not monitored. Separate regular expressions using linefeeds. Specify values only in the second and subsequent lines. In this case, insert one or more spaces before the value you specified. The following is an example of excluding data that contains ==== and MARK from being monitored.
MARKSTR="===="(line feed)
    [Figure] [Figure] [Figure] [Figure] [Figure]"MARK"
    [Figure]: Space
You can specify multiple values for this parameter. There is no limit on how many values can be specified. When multiple values are specified for this parameter, they are interpreted as OR conditions, all data that matches any one of the conditions is not monitored.
The check performed on regular expressions that are specified in this parameter applies to the input log data up to the length specified in the -m option of the jevlogstart command. When this parameter is omitted, the log-file trapping service assumes that there is no data other than log data.

ACTDEF=[{EXIT}][<severity>][event-ID][!]"regular-expressions"
Specify the conditions for converting specific log messages into JP1 events, and specify the event ID and severity of those JP1 events. When log data matches a regular expression, the JP1 event is issued with the specified event ID. Do not place a space or tab character anywhere between an equal sign, {EXIT}, <severity>, or event-ID. Placing a space or tab character between any of the above results in a syntax error.

{EXIT}
This parameter applies when specifying multiple ACTDEF parameters. Specify {EXIT} to halt monitoring log data as soon as data matching the condition tagged with {EXIT} has been detected.
Normally, when multiple ACTDEF parameters are specified and a particular log entry matches more than one of the conditions, the system issues a JP1 event for every such match. When you specify {EXIT} for a condition, a JP1 event with the specified event ID is issued if a match is found, and the conditions in the subsequent ACTDEF parameters are not monitored.
The following figure shows how the processing differs according to whether {EXIT} is specified.

Figure 14-5 Example of specifying an action definition file for log file trapping

[Figure]

<severity>
Specify in angle brackets (<>) the severity level, an extended JP1 event attribute. Specify the severity level and event ID in pair. You can specify any of the following values.
  • Emergency
  • Alert
  • Critical
  • Error
  • Warning
  • Notice
  • Information
  • Debug
The default is Notice.

event-ID
Specify an event ID, which is used when registering a JP1 event in an event server. An event ID is a hexadecimal number consisting of the upper four bytes (basic code) and the lower four bytes (extended code), separated by a colon. Write the characters A to F in upper case. The lower four bytes, or both the colon and lower four bytes, can be omitted. The default in this case is 0. If the upper and lower bytes do not add up to eight digits each, leading zeros are added. The specifiable range of values is 0:0 to 1FFF:0 and 7FFF8000:0 to 7FFFFFFF:0. Always specify 0 for the extended code. Three examples of event ID expressions are shown below.
Each represents the same event ID.
0000011A:00000000 
11A:0 
11A

"regular-expression"
Use regular expressions to specify the log data to be converted to JP1 events. Enclose the regular expression with double quotation marks. An exclamation mark before the opening quote specifies exclusion conditions, and data that does not match the specified regular expression is set to be converted.
More than one regular expression can be specified in one ACTDEF parameter. When multiple regular expressions are specified, they are interpreted as AND conditions, and only data that matches all the conditions, including the mismatch (!) condition, is converted into JP1 events. Separate regular expressions using linefeeds. Specify regular expressions only in the second and subsequent lines. In this case, insert one or more spaces before the value you specified. The following is an example of specifying data that contains jp1base and error to be converted into JP1 events by using event ID 00000333.
ACTDRF=00000333  "jp1base"(line feed)
    [Figure] [Figure] [Figure] [Figure] [Figure]"error"
    [Figure]: Space
You can specify multiple values for this parameter. There is no limit on how many values can be specified. When multiple values are specified for this parameter, they are interpreted as OR conditions, all data that matches any one of the conditions is converted into a JP event.
The check performed on regular expressions that are specified in this parameter applies to the input log data up to the length specified in the -m option of the jevlogstart command.
This parameter is mandatory.

Notes

Definition examples

[Contents][Back][Next]

[Trademarks]

All Rights Reserved. Copyright (C) 2009, Hitachi, Ltd.