Action definition file for event log trapping (Windows only)
- Organization of this page
Format
server event-server-name retry-times retry-count retry-interval retry-interval matching-level [0 | 1] filter-check-level [0 | 1] ext-attr-option extended-attribute-name unicode-trap [0 | 1] # filter filter log-type [id=event-ID] [trap-name=trap-name] condition-statement-1 condition-statement-2 : condition-statement-n end-filter |
Parameters by type
- Required parameters:
-
None
- Custom parameters:
-
-
matching-level
-
filter-check-level
-
unicode-trap
-
filter
-
id
-
trap-name
-
Storage destination directory
installation-folder\conf\event\
Description
Specifies the conditions for converting event log data into JP1 event and the retry settings when monitoring fails.
Application of settings
To apply the settings, start the event log trapping service or reload the action definition file for event log trapping by executing the jeveltreload command. For details on the jeveltreload command, see jeveltreload (Windows only) in 15. Commands.
Definition details
An action definition file for event log trapping (ntevent.conf) consists of a destination event server name, retry setting, and one or more filters. Comments are marked with hash marks and disregarded.
- server event-server-name
-
Specify the name of the destination event server for registering JP1 event converted from the event log. Specify a server name that is no more than 255 bytes. Enclose the event server name with double quotation marks. You can only specify an event server that runs on the local host. When no event server is specified, the local host name is assumed.
- retry-times retry-count
-
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.
- retry-interval retry-interval
-
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 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.
- matching-level [0|1]
-
Specify the comparison level for the event log and definitions when the log entry explanation cannot be read because, for example, you specified a message attribute in the filter condition but the message DLL is not properly configured. When 0 is specified, the next filter condition will be compared skipping the current one. When 1 is specified, the current filter condition is compared. The default is 0.
- filter-check-level [0|1]
-
Specify a checking level when an invalid log type (log type that does not exist in the system) or invalid regular expression is found in a filter condition. Invalidate the filter condition when 0 is specified and the filter condition contains an invalid log type or invalid regular expression. If there are one or more valid filter conditions, the service will start up and the settings will be reloaded successfully. If there are no valid filter conditions, the service will not startup and the settings will not be reloaded. When 1 is specified and one or more of the filter conditions contains an invalid log type or invalid regular expression, the service will not start up and the settings will not be reloaded. The default is 0.
- ext-attr-option extended-attribute-name
-
Specify this option to create additional extended attributes other than A0 to A6, PLATFORM, and PPNAME.
You can add multiple extended attributes by separating the attribute names with single-byte spaces. The attributes can be specified in any order.
The following table lists the extended attributes you can specify:
Extended attribute
Meaning
A7
Windows logging level
A8
Windows log keywords
A9
Windows log opcode
OS_VERSION
Windows version number
If you omit this parameter, the event service does not create these extended attributes when it converts JP1 events.
The following shows an example in which all four extended attributes are created:
ext-attr-option A7 A8 A9 OS_VERSION
- unicode-trap [0 | 1]
-
Specify the matching method for event log trapping.
Although the Windows event log is output in the Unicode format, JP1/Base itself does not support Unicode. Therefore, if the event log contains Unicode-specific environment-dependent characters, mismatches in event log trap regular expressions might occur or garbled event log data might be registered in the JP1 event. This parameter causes the event log trapping function to use a Unicode search-based matching method, to prevent mismatches in regular expressions and garbled event log data.
If you specify 0, the matching method for event log trapping is based on the Windows system locale. Because the event log is converted to a character code supported by JP1/Base before matching, mismatches in event log trap regular expressions might occur or garbled event log data might be registered in the JP1 event. Also, the default code set is used when JP1 events are registered.
If you specify 1, the matching method for event log trapping is based on a Unicode search. Because the event log data are matched in its original Unicode-format characters, the event log data can be registered in a JP1 event without garbling. Also, UTF-8 is used as the code set when JP1 events are registered. Extended regular expressions are applied as the regular expressions used for condition statements in event filters.
If you omit this parameter, the value 0 is used.
Note that the value set for this parameter cannot be changed by reloading (jeveltreload command). If you change the value set for this parameter, restart the event log trapping service.
Filter syntax
A filter is a set of condition statements for converting event log data into JP1 events. The condition statements within a filter are AND conditions, and those between filters are OR conditions. If you define multiple filters in the file, the system parses them in the order they are defined (from the top down), and parsing stops when the first valid filter is parsed. You must specify at least one filter condition. The following figure shows the syntax conventions of a filter.
Log type
Specify the type of event logs to be monitored. The log type is the name of each log listed in the Windows Event Viewer. Enclose the log type with double quotation marks. Note that the same log type can be specified for multiple filters.
The following shows the log types that can be specified:
-
Windows logs#1, #2
-
"Application"
-
"Security"
-
"System"
-
"Setup"
-
-
Application and service logs
-
"DNS Server"
-
"Directory Service"
-
"File Replication Service"
-
"DFS Replication"#3
-
"Internet Explorer"
-
"Key Management Service"
-
"HardwareEvents" and others#4
-
- #1
-
You cannot specify "Forwarded Events" output to a Windows log.
- #2
-
The event service cannot properly convert an event log entry transferred to an application or system event log from a remote machine. To monitor event log data generated on a remote machine, use an event log trap on the machine that generated the event.
- #3
-
You cannot specify Japanese characters.
- #4
-
Use the following procedure to check the log types you can specify in a filter. Log types that do not meet the criteria are invalid.
-
At the MS-DOS command prompt, execute the wevtutil command and review the list of log types registered in the system.
An example of the command line is as follows:
>wevtutil el
-
For each log type listed in step 1, check whether the log is enabled and the log type.
An example of the command line is as follows:
>wevtutil gl Application
name: Application
enabled: true
type: Admin
:
You can specify a log type in a filter if both of the following conditions are met:
- enabled is true
- type is Admin or Operational
-
[id=event-ID]
Specify the event ID to be assigned when a JP1 event is registered on the event server. Each event ID consists of high-order 4 bytes (basic code) and low-order 4 bytes (extended code) separated by a colon (:). The basic and extended codes are written with hexadecimal values. You can omit the extended code. When you omit it, you can also omit a colon (:). If omitted, 0 is assumed. For both basic and extended codes, if the specified value has eight or fewer digits, 0s are prefixed. Specify values that users can specify. That is, specify values in the range from 0:0 to 1FFF:0 and the range from 7FFF8000:0 to 7FFFFFFF:0. For the extended code, you must specify 0.
The following shows three examples of an event ID. The representations in these examples have the same meaning.
id=0000011A:00000000 id=11A:0 id=11A
Do not insert a space or tab between id= and an event ID. Conversely, insert a space between log-type and trap-name=trap-name. You can specify the same event ID for multiple filters. If you omit this parameter, 00003A71 is assumed as the event ID.
[trap-name=trap-name]
Specify the trap name that is used to identify the filter through which the JP1 event was converted (from an event log message) and registered. Specify a trap name of no more than 30 bytes. You can use alphanumeric characters, hyphens (-), and underscores (_). The trap name must begin with an alphanumeric character. Uppercase and lowercase are distinguished.
Do not insert a space or tab between trap-name= and trap-name. You can specify the same trap name for multiple filters. If you omit this parameter, no extended attributes are created when the JP1 event is converted. This parameter is not specified in the action definition file for event log trapping in the initial state.
Condition statement format
In condition-statement, specify an attribute name (shown in the table below) and the corresponding item that is displayed in the General tab of the Event Viewer properties.
Attribute name |
Meaning |
---|---|
type |
Specify log types. Specify the level displayed in the Event Viewer properties, by referring to Table 16-19 Log types specifiable in type and the corresponding JP1 event severity. In Windows Vista or later, specify the level displayed in the Event Viewer properties, referring to Table 16-12 Log types specifiable in type and the corresponding JP1 event severity. Audit_success and Audit_failure are displayed in Keyword in the Event Viewer properties. |
source |
Specify the source information displayed in the Event Viewer properties. If information is different, change the specified information to the source information. |
category# |
Specify the category information displayed in the Event Viewer properties. |
id |
Specify the event ID information displayed in the Event Viewer properties. |
user |
Specify the user name displayed in the Event Viewer properties. |
message# |
Specify the message text displayed in the Event Viewer properties. |
computer |
Specify the computer name displayed in the Event Viewer properties. |
level# |
Specify the level displayed in the Event Viewer properties. |
keyword# |
Specify the keyword displayed in the Event Viewer properties. |
opcode# |
Specify the opcode displayed in the Event Viewer properties. |
The coding format is shown below.
- type log-type-1 log-type-2 log-type-3...
-
Specify log types. When multiple types are specified, the condition will be satisfied when a match is found with any one of the specified types. The severity level of a JP1 event after conversion depends on the log type. The following table lists the specifiable log types and the corresponding JP1 event severity.
Table 16‒19: Log types specifiable in type and the corresponding JP1 event severity Log type
Contents
JP1 event severity
Information
Information
Information
Warning
Warning
Warning
Error
Error
Error
Critical
Critical
Critical
Verbose
Verbose
Information
Audit_success
Audit succeeded
Notice
Audit_failure
Audit failed
Notice
Log types not listed in the above table cannot be specified in type. In addition, when converting log data to something other that a listed type, the JP1 event severity level is set to Information.
- Attribution names other than type
-
attribute-name 'regular-expression-1' 'regular-expression-2' 'regular-expression-3'...
Using regular expressions, specify an attribute name other than type. Enclose the regular expression with single quotation marks. Sets exclusion conditions by writing an exclamation mark in front of the value enclosed with single quotation marks. This specifies data that does not match the regular expression to be converted.
To specify a single quotation mark (') in a regular expression, place a backslash (\) before the single quotation mark. The regular expressions that you can use depend on the OS. For details on the syntax of regular expressions, see F. Syntax of Regular Expressions.
If 1 is specified for the unicode-trap parameter, use extended regular expressions for condition statements. For details about how to extend regular expressions, see 3.4.5 Extending regular expressions to be used.
If an event log message contains a line feed character, because the statements in the filter are AND conditions, we recommend that you split the message and specify them separately.
If you absolutely need to specify a line feed character in a regular expression for operational reasons, note the following:
-
Line feed characters differ between the applications that output the data. If the character code is \n, specify \n. If the character code is \r\n, specify .\n. Note that which code a line feed has cannot be visibly distinguished. Contact the application developer or conduct an operation test before starting monitoring.
-
Notes
-
You can specify a combination of values for the retry count and retry interval that causes the system to continue retrying for more than 24 hours. When retry processing exceeds 24 hours, however, the system aborts retrying and stops the event log trapping service.
-
The retry functionality can be used to prevent the Windows media sense functionality from stopping the service.
-
When the filter-check-level is set to 0 (or is unspecified) and a filter condition is invalidated, the KAVA3025-W or KAVA3026-W message is output to the event log and integrated trace log. (For file reloading, the message is output only to the standard error output.) Only 10 or fewer messages are output for invalidated filters.
-
When the filter-check-level is set to 0 (or is unspecified) and there are no valid filter conditions, the KAVA3027-E or KAVA3028-E message (reloading) is output to the event log and integrated trace log. (For file reloading, the message is output to the event log, integrated trace log, and standard error output.)
-
The file name ntevent2.conf is a reserved name. Do not use this name when you back up definition files.
-
If 1 is specified for unicode-trap, and a JP1 event for which UTF-8 is used as the code set is registered, upgrade the JP1/Base on the host to which the JP1 event is to be forwarded to version 8 or later.
-
In JP1/Base 11-00 or later, you no longer need to specify the trap-interval and the jp1event-send parameters. However, if you do specify these parameters, JP1/Base operation is not adversely affected.
-
In a JP1/Base version earlier than 11-00, the default of the retry-times parameter was 0. From JP1/Base version 11-00, the default has been changed to 3.
Supplied action definition file for event log trapping
According to the setting in the supplied action definition file for event log trapping (ntevent.conf), if a connection to the event service fails, the event log trap will retry three times, once per 10-second interval. As conditions for conversion to JP1 events, the defaults also specify that Warning and Error entries output to the System log or Application log are to be converted into JP1 events. The following table shows the settings of the provided file:
retry-times 3 retry-interval 10 filter "System" type Warning Error end-filter filter "Application" type Warning Error end-filter
If you use the action definition file for event log trapping (ntevent.conf) and forwarding settings file (forward) in their default state, the message KAJP1037-E is output to the event log and converted to a JP1 event when an attempt to forward a JP1 event fails. The converted JP1 event is then resent, and another transfer error will occur.
To prevent the event transfer from looping, change the setting in the action definition file, so that the message KAJP1037-E will not be trapped. A setting example is shown below:
retry-times 3 retry-interval 10 filter "System" type Warning Error end-filter # Trap event log entries with severity level Error or Warning # that were not output by the JP1/Base Event service. filter "Application" type Warning Error source !'JP1/Base Event' end-filter # Trap event log entries with severity level Error or Warning # from the JP1/Base Event service, except entries with ID 1037. filter "Application" type Warning Error source 'JP1/Base Event' id !'1037' end-filter
Examples of defining a filter
Definition examples1: Using OR and AND conditions
- Definition example using an OR condition
-
Select data entries of the System log type containing any one of the strings TEXT, MSG, or -W in the explanatory information.
filter "System" message 'TEXT' 'MSG' '-W' end-filter
Specify an OR condition by separating conditions using spaces and tag characters.
- Definition example using an AND condition
-
Select data entries of the System log type containing all of the strings TEXT, MSG, and -W in the explanatory information.
filter "System" message 'TEXT' message 'MSG' message '-W' end-filter
Specify an AND condition by separating conditions using a linefeed character. After inserting a linefeed character, write the condition starting from the attribute names.
Definition example 2: Using multiple filters
Trap event log entries that have the Application log type and that satisfy the following conditions.
- Filter 1:
-
-
Type: Application log:
-
Type: Error
-
Explanation: Contains -E and JP1/Base.
-
- Filter 2:
-
-
Type: Application log:
-
Type: Warning
-
Explanation: Contains -W or warning.
# Filter 1 filter "Application" type Error message '-E' message 'JP1/Base' end-filter # Filter 2 filter "Application" type Warning message '-W' 'warning' end-filter
-
Definition example 3: Using regular expressions
Trap event log entries that satisfy the following conditions.
-
Type: Application log
-
Type: Error
-
Event ID: 111
Explanation: Contains -E or MSG, and does not contain TEXT. filter "Application" type Error id '^111$' message '-E' 'MSG' message !'TEXT' end-filter
To specify the event ID 111 condition using a regular expression, specify id '^111$'. If you specify id '111', the event ID must contain 111, so event IDs 1112 and 0111 will also satisfy the condition. Writing an exclamation mark in front of the value enclosed with quotation marks selects data that does not match the regular expression. For details on regular expressions, see F. Syntax of Regular Expressions.
Definition example 4: Excluding specific event log entries
Trap event log entries that have System log type and a Warning severity level, but exclude entries that satisfy the following conditions.
-
Source: AAA
-
Event ID: 111
-
Explanation: Contains TEXT.
# Do not trap event log entries from source AAA. filter "System" type Warning source !'AAA' end-filter # Trap all event log entries from source AAA, # except those with an event ID of 111. filter "System" type Warning source 'AAA' id !'^111$' end-filter # From source AAA, trap all event log entries # whose event ID is 111 and do not contain TEXT # in the explanatory information. filter "System" type Warning source 'AAA' id '^111$' message !'TEXT' end-filter
Definition example 5: Specifying the event ID and trap name of a JP1 event
In this example, if a log message satisfies the condition of filter 1, the message is converted to a JP1 event with event ID 0000111A. At this time, Action-1 is set for the JP1_TRAP_NAME attribute.
If a log message satisfies the condition of filter 2, the log message is converted to a JP1 event with event ID 0000111B. At this time, Action-2 is set for the JP1_TRAP_NAME attribute.
- Filter 1:
-
-
Type: Application log
-
Type: Error
-
- Filter 2:
-
-
Type: Application log
-
Type: Warning
# Filter 1 filter "Application" id=111A trap-name=Action-1 type Error end-filter # Filter 2 filter "Application" id=111B trap-name=Action-2 type Warning end-filter
-