Hitachi

JP1 Version 12 JP1/Base User's Guide


Action definition file for log file trapping

Organization of this page

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 }

upd-output-event={ 0 | 1 }

FILETYPE={ SEQ | SEQ2 | SEQ3 | WRAP1 | WRAP2 | HTRACE | UPD }

RECTYPE={VAR { '\n ' | 'end-of-line-character' | 'end-of-line-symbol'} | FIX record-length }

HEADLINE=number-of-header-lines

HEADSIZE=header-size

unset-extattr={[TRAP_ID,TRAP_NAME] | [TRAP_ID] | [TRAP_NAME]}

MARKSTR=[!]"regular-expressions"

[!]"regular-expression"#

ACTDEF=[{EXIT}][<severity>] event-ID [!]"regular-expressions"

[!]"regular-expression"#

#: The regular expression n represents multiple specifications.

Parameters by type

Required parameters:

None

Custom parameters:
  • FILETYPE

  • RECTYPE

  • HEADLINE

  • HEADSIZE

  • MARKSTR

  • ACTDEF

File name

Any

jevlog.conf.model (model file of an action definition file for log file trapping)

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. Create an action definition file for log file trapping from the model file (jevlog.conf.model) in the following directory.

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 15. 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. The default is 3.

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.

upd-output-event={ 0 | 1 }

Specify whether to output JP1 events (00003A25 or 00003A26) when a monitoring target log file is detected, in situations where UPD is specified as the output file type for log files. If you omit this parameter, 0 is assumed. For output formats other than UPD, this parameter is ignored.

0

Specify this value if you do not want the log file trapping function to output the JP1 events.

1

Specify this value to output the JP1 events.

FILETYPE={ SEQ | SEQ2 | SEQ3 | WRAP1 | WRAP2 | HTRACE | UPD }

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.

SEQ3 (Windows only)

Specify SEQ3 when, in Windows, the system deletes the file when it reaches a certain size and then writes log data to a new file with the same name as the deleted file.

If you use a remote-monitoring log file trap with the IM configuration management functionality to monitor a log file of this type on a remote host, you can monitor the file as a SEQ2 file. However, when using a log file trap on a local machine, this type of log file needs to be monitored as SEQ3.

Notes
  • When monitoring the log file as SEQ3, if the system deletes a log file that contains data written since the last time the file was read, the log file trap cannot read that data. Caution is required when monitoring files that are deleted immediately after reaching the maximum size.

  • If you monitor SEQ2 files as SEQ3, when the log file is renamed and if the log file contains data written since the last time the file was read, the log file trap cannot read that data. This problem does not occur when the file is monitored as SEQ2.

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.

Notes
  • 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.

  • When a wrap-around file has any of the following characteristics, conversion to JP1 events might be delayed or not happen at all:

    - The file wraps around repeatedly within a short time.

    - Log data exceeding the file's capacity is output all at once.

    - The same log data is output multiple times.

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).

Apply WRAP2 when monitoring integrated trace log files.

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.

  • Messages output to the integrated trace log might corrupt if the messages from multiple processes are output at the same time. To monitor a specific message, enable the exclusive control functionality for the integrated trace log. For details on exclusive control, see hntr2conf in 15. Commands.

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.

In Windows, the monitoring of Unicode files is supported for logs that are output in UTF-8 character encoding. Logs output in UTF-16 character encoding cannot be monitored.

UPD

Specify UPD to ensure you always monitor the latest iteration of a log file.

To monitor the latest log files, use a wildcard pattern when you specify the file name of the monitored log file in the jevlogstart command. When the log file trap starts, the log-file trap management service (or daemon) monitors the most recently updated log file of those that match the wildcard pattern. As long as the trap is active, the service (or daemon) continuously switches its monitoring target to the newest file that matches the wildcard pattern.

The log file trap can keep track of a maximum of 1,000 log files matching the wildcard pattern. Files whose full path and file name exceed 256 bytes are not monitored.

UPD files must be sequential files (a log file that is written to continuously over time).

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.

If you monitor Unicode files in Windows and BOM exists at the beginning of the files, specify the header size excluding the BOM size (3 bytes for UTF-8 and 2 bytes for UTF-16).

unset-extattr={[TRAP_ID,TRAP_NAME] | [TRAP_ID] | [TRAP_NAME]}

In JP1/Base Version 10-50 or later, extended attributes of the JP1 events output by the log file trap include the monitor ID (JP1_TRAP_ID) and monitoring target name (JP1_TRAP_NAME). Specify these parameters if you do not want to output these attribute values. If you omit these parameters, the monitor ID and the monitoring target name are output.

TRAP_ID,TRAP_NAME

Specify this parameter if you do not want to output neither the monitor ID nor the monitoring target name.

TRAP_ID

Specify this parameter if you do not want to output the monitor ID.

TRAP_NAME

Specify this parameter if you do not want to output the monitoring target name.

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. After all values of this parameter are evaluated, ACTDEF is evaluated. 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.

You can specify multiple instances of this parameter. The number of instances that can be specified is not limited. If you specify multiple instances, they are combined with the OR condition. All log messages that match the specification of any instance are converted into JP1 events.

The regular expression specified in this parameter targets only a certain length of an input log message from the beginning. The length is specified by the -m option of the jevlogstart command.

For details about extending regular expressions, see 3.4.5 Extending regular expressions to be used.

If you want to monitor Unicode files in Windows, you must specify extended regular expressions. In this case, extended regular expressions are used for filtering regardless of whether the regular expression extension setting ("REGEXP"="EXTENDED") is specified. For details about how to specify extended regular expressions, see F.2 Extended regular expressions that can be used when regular expressions are extended.

You cannot omit this parameter.

{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 16‒6: 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.

ACTDEF=00000333  "jp1base"(line feed)
    [Figure] [Figure] [Figure] [Figure] [Figure]"error"
    [Figure]: Space

Notes

Definition examples