FKM Plugin Technical Reference

files > file > tables

The tables setting specifies the keyword tables to use for this file. Lines from the file are scanned for the first matching keyword in the keyword tables, which will trigger a new row in the dataview. The file status will also change to the table severity.

Mandatory: No

files > file > tables > table

Specifies a single keyword table to use for the file.

Mandatory: No

files > file > tables > table > severity

Specifies the severity of this table for the file. The severity controls the resulting file status when a keyword in this table is detected. It may also control which order the tables are checked in, depending upon the value of the reorderKeywordTables setting.

Possible values are as follows:

Mandatory: Yes

files > file > tables > table > keyTable

The key table setting contains the actual table definition (the keywords). This setting can either reference an FKM table defined in the "static variables" section of the gateway setup, or a table can be defined here directly.

See the fkmTable setting for a full description of keyword configuration options.

Mandatory: Yes

files > file > tables > table > activeTime

The activeTime setting references an activeTime definition from elsewhere in the gateway setup. When FKM checks a file for keywords, the activeTime for the keyword table is also checked. If the time is inactive, then the keyword table referencing this time is skipped (no keys defined within the table are checked for in the file).

This setting can be used to configure a file with different sets of keywords, allowing different conditions to be monitored during different periods of the day.

This setting can be used in conjunction with the keyword-level activeTime. If the time is active, then the keyword's activeTime is further checked for scanning.

Inactive keyword tables can optionally be scanned for any clear-keys in the table using the checkInactiveClearKeys plug-in setting.

files > file > failTable

The fail table setting specifies an optional fail table of keys for the file. Any file lines which contain a key defined in this table will cause the file status to change to FAIL.

This setting has been deprecated in favour of the more general table setting. Please configure a table with a severity of "fail" rather than use this setting.

Mandatory: No

files > file > warningTable

The warning table setting specifies an optional table of warning keys for the file. Any file lines which contain a key defined in this table will cause the file status to change to WARNING.

This setting has been deprecated in favour of the more general table setting. Please configure a table with a severity of "warning" rather than use this setting.

Mandatory: No

fkmTable > keys

This setting defines a set of keys to make up an FKM key table. This table will only be accessible for the specific file it is being configured for. To share a table definition between files, configure a table as a static variable and reference it using the fkmTable setting.

Mandatory: No

fkmTable > keys > key

Defines a single key in a set of keys.

Mandatory: No

fkmTable > keys > key > setKey

A set key defines a key to search for. If this key matches, a trigger will be created.

Mandatory: No

fkmTable > keys > key > setKey > match

A match set key specifies some text which must appear in the file line to cause a match.

Mandatory: No

fkmTable > keyearchString > key > setKey > match > searchString

Specifies the string literal or regular expression to search for in the file line.

The search string may also contain a date expansion, which will be replaced with the formatted date on the first sample of each day. If the search string is a regex, then the expansion will be performed before the string is interpreted as a regex. Date expansions can be controlled using the expandDatesInKeywords plug-in setting.

Mandatory: Yes

fkmTable > keys > key > setKey > match > rules

Specifies the match mode to be used when matching.

fkmTable > keys > key > setKey > updated

If an updated key is added to a key set, then this will trigger when the file is updated or changed in any way (including the creation of a new file with the same name). This can be used for example, to ensure that a system configuration file does not change.

If an updated key has been specified in a key table, then any notUpdatedIn keys will be ignored.

Mandatory: No

fkmTable > keys > key > setKey > notUpdatedIn

The notUpdatedIn key type is the inverse of the updated key above. This key can be used to alert users if the associated file has not been updated for a period of time. The value of this setting specifies this period as a number of seconds.

Mandatory: No

fkmTable > keys > key > clearKey

A clear key specifies an additional match for this key. If a file line matches the match key (creating a trigger) and a file line later match this clear key, the created trigger will be automatically removed.

Mandatory: No

fkmTable > keys > key > clearKey > match

A match clear key specifies some text which must appear in the file line to cause a match.

Mandatory: No

fkmTable > keys > key > clearKey > match > searchString

Specifies the string literal or regular expression to search for in the file line.

Search strings can refer to specific parts of the matching text to clear specific conditions. See Using dollar references and capture groups.

Mandatory: Yes

fkmTable > keys > key > clearKey > match > rules

Specifies whether the searchString will be matched using case-insensitive matching (BASIC) or regular expressions (REGEXP). See the match key rules setting for more information.

fkmTable > keys > key > clearKey > mode

The mode setting controls what rows are cleared when a clear key match is found. This setting overrides the plug-in default value (as specified by the defaultClearMode setting) for a particular key.

fkmTable > keys > key > clearTime

This setting controls the length of time a trigger row will remain in the dataview after it is first detected. The setting value specifies the number of seconds the row will remain. If this setting is not specified the trigger row will remain in the view until manually accepted by the user, or is removed as part of accepting (or clearing) a file.

fkmTable > keys > key > message

Specifies an optional message which is displayed in the triggerDetails column of the created trigger row (in addition to the normal trigger details).

The message can refer to specific parts of the matching text to provide additional information. See Using dollar references and capture groups.

fkmTable > keys > key > tags

This setting specifies start and end tags which can be used to parse the triggerDetails output for a line matching this key. This can be helpful for extracting useful information from a long file line.

Tags specified at key level override those specified in the plug-in tags setting. The parseTriggerDetails setting must be enabled for this to take effect.

Mandatory: No

fkmTable > keys > key > extractors

This section allows you to specify a list of extractors for your keyword. An extractor is a regex pattern which is applied to the file line after the line is found to match the keyword.

The extractor regex is then matched against the file line and used to extract a piece of text, which is displayed in a dataview column against the trigger row created for the key. These columns can give hints to users of AC as to important parts of a message, and are also passed to action scripts if an action fires for that row.

Mandatory: No

fkmTable > keys > key > extractors > extractor > name

This setting sets the name of the extractor - this name is also used as the column name in FKM and so must not be the same as any existing FKM columns. The name should also be different to any other extractors defined in the key, but the same name can be used across multiple keys.

Mandatory: Yes

fkmTable > keys > key > extractors > extractor > regex

Specifies the regex pattern used to extract part of the file line. This regex pattern must contain a grouping (parentheses), which will then be used as the extracted value.

e.g. For the extractor "Connectionerror#([0-9]*)" the extracted part of the message is the part which matches the parenthesised part of the pattern "[0-9]*". Given the file line "Connection error #2058 - check queue manager name", the extracted string is then "2058".

Mandatory: Yes

fkmTable > keys > key > severity

This severity setting allows the user to override the severity of a table for a particular key definition. For example using this setting you could configure a "warning" key inside a table which is defined with a "fail" severity (i.e. a fail table). If this setting is not specified then the key inherits the table severity.

Possible values are described below:

fkmTable > keys > key > activeTime

The activeTime setting references an activeTime definition from elsewhere in the gateway setup. This time controls whether a keyword defined in the keyword table for a file is enabled or disabled.

If the activeTime for the file-level and keyword table-level is active or not configured, then the time for the keyword is scanned. If the time is inactive then file lines are not scanned for the keyword (which includes set-key and ignore-key).

fkmTable > keys > ignoreKey

An ignore key works in the same was as a match key. However rather than creating a trigger row when the key is detected, an ignore key silently ignores the line.

Ignore keys are typically used to filter out file lines which would otherwise match a key and create a trigger. For example, a server log may contain several lines starting "Failed to …" where some of these messages are innocuous. An ignore key could be used to ignore the known messages, and a match key configured to catch all other failures.

As keys in a key table are checked against a file line in order of definition, an ignore key must be specified earlier in the table than the key(s) which it is protecting.

Mandatory: No

fkmTable > keys > ignoreKey > searchString

Specifies the string literal or regular expression to search for in the file line.

Mandatory: Yes

fkmTable > keys > ignoreKey > rules

Specifies whether the searchString will be matched using case-insensitive matching (BASIC) or regular expressions (REGEXP). See the match key rules setting for more information.

fkmTable > keys > ignoreKey > activeTime

The activeTime setting references an activeTime definition from elsewhere in the gateway setup. This time controls whether a keyword defined in the keyword table for a file is enabled or disabled.

If the activeTime for the file-level and keyword table-level is active or not configured, then the time for the keyword is scanned. If the time is inactive then file lines are not scanned for the keyword (which includes set-key and ignore-key).

display

This section is used to configure display-related settings. These settings change how data is displayed by FKM in the published dataview, and so affects the whole plug-in rather than a particular file.

Mandatory: No

display > columns

The columns setting allows users to configure the list of columns displayed by FKM in the dataview. The contents of these columns are described in more detail in the example view table legend above.

Possible values are as follows:

display > triggerMode

The trigger mode describes how multiple triggers are displayed by FKM. Trigger rows in a dataview always appear with the name indented, underneath the file row.

display > lastTriggerInStatus

When FKM detects a new trigger, the file status is to include the file line of the latest-detected trigger. This setting enables users to disable this behaviour (by setting the value to false), so that the file status is displayed only as FAIL or WARNING.

display > notFoundMessage

When a file could not be opened, FKM changes the status to NOT_FOUND and also displays an additional information message on why the file could not be opened. Typically this is because the file does not exist, but can sometimes be due to other errors such as insufficient permissions. These additional messages can be disabled by changing this setting to false.

display > triggerMessages

If a message has been configured for a key, the triggerDetails column of the trigger row for this key will display the text <message>(<line>) where line is the line of the file in which the key was detected. Setting the value of this setting to false will omit the message text from this column.

display > showLastModificationTimeInSeconds

The last modification time as displayed in the lastModificationTime column is shown in a human-readable format. Setting this setting to true will show this time as the number of seconds since Jan 1 1970 (aka Unix time) which allows for numerical comparisons in rules.

display > showSecondsSinceLastTrigger

Adds the secondsSinceLastTrigger column to the list of columns displayed by default. This column can also be displayed by setting it explicitly using the display columns setting.

The behaviour of this column can be affected by the Trigger Count Mode setting.

display > showControlCharsAsSpaces

When monitoring binary file, the contents of a file line can sometimes contain non-printing binary (control) characters. If a key is detected on this line the triggerDetails column will display the line but any control characters will not be displayed, leading to a compacted line which can be hard to read. This is particularly relevant for files containing FIX messages.

Enabling this setting will cause FKM to replace all control characters with spaces when data is published in a dataview. This is done after the file line has been scanned for trigger keys. Control characters are also replaced when using the "View File" and "View File near Trigger" right-click menu commands so that the output appears as expected.

Whitespace characters such as spaces, tabs or newline characters are not counted as control characters for the purposes of replacement.

display > showControlCharsAsChar

This setting is similar to the showControlCharsAsSpaces above, however it allows the user to configure the character which will be used to replace non-printing control characters. Characters are replaced prior to the file line being displayed in the FKM dataview, and also in the results of any "view file" right-click menu command options.

Characters can be specified by entering a single replacement character. Alternatively, it can also be specified using the hexadecimal character code in the form 0xHH where HH is a hexadecimal number. E.g. 0x20 specifies the space character. A list of characters and their codes can be found on the ASCII table website.

Whitespace characters such as spaces, tabs or newline characters are not counted as control characters for the purposes of replacement.

display > triggerCountMode

The trigger count mode setting controls the contents displayed in the triggerCount and secondsSinceLastTrigger columns. This setting only takes effect if the triggerMode setting is set to MULTIPLE_GROUPED_TRIGGER or MULTIPLE.

The following values can be specified for this setting:

display > useFullPathInRowNames

If set, causes the full path of the file to be used in the rowName. This prevents duplicate rows when monitoring files of the same name in different directories using wildcard filenames, with the wildcardMonitorAllMatches setting enabled. By default, only filenames are used as row names when displaying wildcard matches with wildcardMonitorAllMatches enabled.

display > fileSizeDisplayMode

This setting controls how the fileSize column in the Dataview is formatted. If left un-specified the fileSize column is formatted in kilobytes, otherwise the chosen unit is used.

The following values can be specified for this setting:

isPCREMode

If enabled, allows the FKM sampler to use Perl Compatible Regular Expressions (PCRE).

By default, this setting is disabled and the FKM uses the Portable Operating System Interface (POSIX) extended regular expressions, instead.

For more information on using regular expressions on the FKM, see the following:

• Regular Expressions
• Notable differences between POSIX and PCRE

maxSamplesLagging

This setting determines how many samples a file can lag for before the file is ignored as updating too fast. A file is counted as lagging if the last line processed for the file in a sample is not (currently) the last line in the file. This will typically occur because the limit of lines to process has been reached (see maxLinesProcessed below).

If a file is lagging for more than the maximum number of samples, it will then be ignored until a user manually accepts the file. An alert to this effect is displayed in the status column for the file.

maxLinesProcessed

This setting controls how many lines (per file) will be processed in a single sample. This works in conjunction with the maxSamplesLagging setting (above) to determine if a file is updating too fast.

excessiveUpdatesTimeout

If a file is updating at a very fast rate, this indicates that a process is malfunctioning. FKM reads a maximum of 20,000 lines per sample. If more than this limit is written to the file for 20 consecutive samples, then the processing of this file stops. The FKM file displays the WARNING: FKM stopped on this file - excessive update rate detected. error message in the status column.

It is possible by enabling this setting to automatically accept an excessive update rate error. When this option is enabled and FKM detects a file that grows rapidly, it skips to the end of a file, and generates a condition (as if a keyword was detected) to display a warning error message. After the specified period of time, the system removes this condition. If you do not wish to manually remove the condition, set the timeout to 0.

The WARNING: FKM stopped on this file - excessive update rate detected. error is not a message contained in the files you are monitoring with FKM. Therefore, you cannot use the ignore key to ignore this error.

To clear the warning status, do any of the following:

• Manually accept the file.
• Configure a timeout for the sampler to automatically accept it. The timeout setting is in the FKM sampler > Advanced tab > excessiveUpdatesTimeout (in seconds). This makes the sampler accept the warning, and start reading the file from the end automatically.
• Modify other FKM settings such as maxLinesProcessed to allow it to read more than 20,000 lines.
• Increase the maxSamplesLagging to determine the number of samples a file can lag for before the file is ignored, as it updates too fast. Adjusting these settings and lowering the FKM sample interval enable the Netprobe to perform frequent sampling, and read more lines each time.

maxConditionsPerSample

This setting controls how many trigger rows (conditions) are recorded in a single sample. This is used primarily in multiple trigger mode (see triggerMode above) to limit the number of triggers which will be created. Triggers created after this limit is reached are displayed in the next sample.

maxConditionsPerFile

This setting controls how many trigger rows (conditions) are recorded per file. This is used primarily in multiple trigger mode (see triggerMode above) to limit the number of triggers which will be created. Triggers created after this limit is reached are lost.

maxConditionsPerKey

This setting controls how many trigger rows (conditions) are recorded per file, for a particular key which generated them. This is used primarily in multiple trigger mode and single grouped message mode (see triggerModeabove) to limit the number of triggers which will be created.

This setting gives finer-grained control than the maxConditionsPerFile setting, since it ensures that a lot of one type of detected key cannot prevent a different key from being displayed.

If a new trigger arrives after this limit has been reached, the oldest trigger for the key will be removed, and replaced with the new trigger.

maxConditionID

This setting controls the numbering of trigger rows (conditions) when using multiple trigger mode (see triggerMode above). Successive triggers are numbered in increasing order, until this limit is reached at which point numbering starts again from 0. Numbering is also reset when accepting a file.

checkIgnoreFiles

Setting this setting to true instructs FKM plug-in to check monitored files for the presence of an ignore file, which is required when using the ignore file feature. This feature is disabled by default, since it increases CPU usage by a small (but unnecessary for most users) amount.

defaultIgnoreFilePath

By default the netprobe looks in the current working directory for ignore files. This option allows the user to configure an alternate location. This functionality is only available for Gateway2.

defaultIgnoreFileName

Specifies the default ignore file to reference for all files monitored by the sampler. This functionality is only available for Gateway2.

Mandatory: No

continueTriggerScan

By default FKM will stop scanning a file line for matching keys as soon as the first match is found, at which point a trigger is created. By enabling this option, FKM will match a file line against every configured key and display a trigger for each one that matched. This also therefore means that ignore keys will have no effect.

This option should only be used when absolutely required, as it will increase the processing requirements of the FKM plug-in (and hence increase CPU usage).

singleTriggerCleartimes

In single trigger mode, enabling this option will cause the triggerCount column to display a total count of triggers currently detected, for the key associated with that trigger row.

This count will also be affected by a clearTime configured for that key, so that as a keys are cleared this count decreases, which is not the case if this setting is disabled.

wildcardMonitorAllMatches

This setting controls how FKM treats files containing wildcard characters (* and ?). By default only the latest file (see wildcardMatchTime setting below) will be monitored. By enabling this option all files matching the pattern will be monitored.

When matching all files, new file rows are created for each matching file found. Settings for these files are coped from the wild-carded file definition. These rows are removed when the file is no longer found to match the pattern, which can happen if the file is deleted or if the date changes and the filename contains a <today> expansion.

wildcardMatchTime

This setting controls which file timestamp is used to determine the file to monitor, when a filename is configured that contains wildcard characters (* and ?). Possible values are as follows:

tags

This setting defines trigger parsing tags used in conjunction with the parseTriggerDetails setting. If trigger parsing is enabled, then the text displayed in the triggerDetails column is parsed according to the startTag and endTag settings. This feature can be used to reduce the file line displayed, allowing the user to quickly focus on the important information.

If a startTag has been configured and is contained within the line, the result will be the text following the first instance of the startTag (if found) - the text from the start to the first startTag (inclusive) will be removed.

An endTag works similarly, except that the text from the last instance of an endTag (if found) until the end of the line is removed.

For example:

SELECT * from _InstanceModified
WHERE Instance "Win32_Process"
AND Load > 50

SELECT * from _InstanceModified
WHERE Instance "Win32_Process"
AND Load > 50

Either or both of these tags can be overridden by tags in a key definition for more specific parsing.

Mandatory: No

parseTriggerDetails

This setting controls whether the values that appear in the triggerDetails column will be parsed using start and end tags. These tags can be defined either globally for the FKM plug-in instance (see tags above), or selectively for specific keys via the key tags setting.

wrapViewFileNearTriggerLines

This option controls the wrapping of lines in the output of a View file near trigger command.

When enabled, line wrapping will be performed when a line reaches approximately 130 characters in length. If disabled, lines will be displayed in the Active Console at their full length.

reorderKeywordTables

By default, file lines are checked for external ignore keys, then keywords from any fail tables, and finally keywords from warning tables. This is done by reordering the keyword tables for a file to be in this order.

The reorderKeywordTables setting controls whether this reordering is performed. If disabled (set to false) the keyword tables will be checked in the order they are defined in the file configuration.

checkInactiveClearKeys

This setting controls whether clear keys inside an inactive keyword table are checked against a file.

A keyword table is made up of several keywords types; keys, ignore keys, and clear keys. An activeTime can be configured on a file, keyword table or on a keyword itself.

For a keyword: When this time is inactive, the keyword will not be scanned.

For a keyword table: When this time is inactive, then the whole table is not used for scanning.

For a file: When this time is inactive, no file content will be scanned.

If this option is enabled, then only the active clear keys in an inactive keyword table will still be checked. Inactive keywords will not be checked.

defaultClearMode

The default clear mode specifies how clear keys operate on a plug-in global basis. All clear keys will use this behaviour, unless specifically overridden for the key by the clearKey mode setting.

expandDatesInKeywords

FKM keywords may be configured with a date expansion string, e.g. <today>. This string updated each day with the current date. This feature can be controlled by means of this setting.

monitoredDays

This setting allows the FKM to resolve date expansion codes used in file names based only on certain days of the week. For example, this can be set to resolve date codes based only on weekdays, i.e. yesterday resolves to last Friday if the current day is a Monday or a weekend, and tomorrow resolves to next Monday if the current day is a Friday or a weekend. Check the appropriate day boxes to mark them as monitored. The today code always resolves to the current day, even if the current day is not marked as monitored.

internalTextEncoding

The internal text encoding is used by FKM when reading Unicode files. The value of this setting is passed to the iconv library (used for Unicode conversion) as the target encoding for text conversion. It is not recommended to change the value of this setting unless advised to do so by ITRS Support.

ignoreIfNotInActiveTime

Allows a user to suppress updates to the STATUS column for a file if the file is outside the configured activetime if this option has been enabled.

defaultFileActiveTime

Specifies a default for the file active time setting. Files with no individual file active time specified will use this setting, files that do specify an active time override this setting.

Mandatory: No

extendedNTEventLogOutput

If set, FKM will output the event text using an extended format containing additional fields for each event, rather than just the defaults. The fields output are prefixed with the field name in extended mode, but not in default mode.

The mapping of the fields Geneos logs to the Event Viewer Windows application is as follows:

Example:

Date:07/11/2011 13:02:32 Type:Information event Source
Source:MSSQL$EXPRESS_2008_X86 EventID:26059 User:N/A Category:Server
Computer:ITRSPC139.ldn.itrs Description:The SQL Server Network Interface
library successfully registered the Service Principal Name (SPN) [
MSSQLSvc/ITRSPC139.ldn.itrs:EXPRESS_2008_X86 ] for the SQL Server
service.

These additional fields will also be present in the triggerDetails column.

If this option is not enabled the output would be in this format:

Mon Nov 07 13:02:32  INFO  MSSQL$EXPRESS_2008_X86    The SQL Server Network Interface
library successfully registered the Service Principal Name (SPN)
[ MSSQLSvc/ITRSPC139.ldn.itrs:EXPRESS_2008_X86 ] for the SQL Server service.

Date generation

File Keyword Monitor file definitions can be configured to generate a filename using the current date and time. The target filename is generated every sample, and if a file exists which matches this name the file will be monitored by FKM (once the current file has been processed to the end).

To use the Date generation function when the dynamicFiles option is selected, see Use date generation function when using dynamic files option in File Keyword Monitor (FKM) Plug-in User Guide.

Filenames can be generated using one of five date codes; yesterday, today, tomorrow, previous_monitored_day, andnext_monitored_day. These are replaced in the filename using the appropriate date.

For example, if the current date is 22 August, 2018, then the following will be produced:

The output format for dates can be controlled by placing format codes in the date tag. Examples of this usage are shown below.

The following formatting codes can be used with this feature.

Monitoring files containing binary data

Some log files may contain a mixture of text and binary data. This may cause a problem monitoring the file if the binary data contains a NUL character (ASCII 0), as the file line is truncated at the first occurrence of this character.

FKM can read these lines correctly, provided it knows the file contains binary data. This is slightly more CPU intensive than ordinary reading of pure text-files, and so is not enabled by default. Files can be marked as binary using the file contentType setting.

In addition, the showControlCharsAsSpaces display setting may also be useful when monitoring binary files. This setting replaces control characters (non-printing characters) with spaces which can help to spread out FKM output making it easier to read.

Unicode files

FKM can monitor Unicode files, by using the iconv library (available on most Unix boxes by default) to convert the text from Unicode to the native system encoding. Because of this conversion, Unicode characters which cannot be represented by the native encoding will be skipped, and are therefore not available in FKM for keyword scanning or viewing.

To use this feature configure the file contentType setting to the encoding of the file. If you do not know the encoding FKM can attempt to detect this for you. Users can also specify the iconv encoding name directly, rather than using the drop-down menu to select an option.

Ignore files feature

Ignore files provide a mechanism for configuring ignore keys for an FKM file externally to the gateway setup. This allows users to dynamically ignore known problems (perhaps on a single machine) without reconfiguring the plug-in.

FKM will check for an ignore file once per sample, for each file. If the ignore file has been created (or the last modification time altered) the ignore file will be read. This file should contain a number of ignore keys, one key per file line. Ignore keys can be written as string literals or regular expressions. To specify regular expressions in an ignore file and differentiate them from string literals, they must be prefixed by "$$$RE " for case-sensitive expressions, or "$$$NCRE " if the case should be ignored.

ex.

$$$RE KEY_\d\d$

This ignores strings with "KEY_<two-digit number>" at the end, such as. "KEY_01"

$$$NCRE KEY_\d\d$

Using $$$NCRE ignores the case of "KEY", so "key_01" would also be ignored.

Ignore keys are processed before keys defined in a fail or warning table. If the ignore file is removed, all ignore keys from that file will also be removed.

The steps to configure this feature are below:

1. Enable the ignore files feature by enabling the checkIgnoreFiles setting.
2. Set the ignore file name to look up:
   1. Using file alias - Configure an FKM file you wish to monitor with an alias that is different to the filename. This alias then forms the base of the filename for the ignore file., with .ignore as the file extension (E.g. If the alias is myAlias then the expected ignore filename becomes myAlias.ignore).
   2. Set ignore file name directly using ignoreFileName to specify an ignore file for a monitored file, or defaultIgnoreFileName to specify a default ignore file for an entire sampler.
3. Create an ignore file with the appropriate name in the Netprobe working directory, and add any desired ignore keys to the file, one per line.
4. FKM will detect when this file is created, updated or deleted. All previously added ignore keywords will be removed and the file contents re-read on these events. A message indicating this will be shown in the Netprobe log file.

Regular Expressions

Perl Compatible Regular Expressions (PCRE) can be used if isPCREMode is selected, please see isPCREMode for how to enable it. Using PCRE allows for more powerful and succinct regexs to be written. Examples are presented below:

A great source for common Regular Expressions is http://www.regular-expressions.info/.

Some online tools which may also be helpful are http://www.regexpal.com or http://www.internetofficer.com/seo-tool/regex-tester.

If isPCREMode isn't enabled Regular Expressions in FKM use the POSIX extended regular expression syntax, and is typically implemented by system libraries. More information about these expressions can be found at Wikipedia or from the command line by typing "man7 regex".

A regular expression specifies a pattern of text to match, which can appear anywhere in the file line. This behaviour can be altered by using the special anchor characters ^ and $ (see below). Unless using these characters, it is not necessary to specify a pattern which matches the whole file line, since this will reduce matching speed.

Once a regular expression has been configured, it is highly recommended that the expression be tested by echoing the intended match text into a monitored file, to ensure that a match is detected.

Regular expressions match sequences of literal characters exactly. A character is a literal character if it is not a special character below.

Some example regular expressions are listed below.

Multi Line Variables In Actions

Outputting multi line messages stored in environment variables are not supported by any of the built-in echo commands for Windows, Solaris and Linux. To work around this issue you could use the following examples to output multi line messages from an environment variable.

Option Explicit

Dim objWindowsShell
Dim objEnvironment

Set objWindowsShell = WScript.CreateObject("WScript.Shell")

For Each objEnvironment In objWindowsShell.Environment("PROCESS")
        WScript.Echo objEnvironment
Next

Set objWindowsShell = Nothing
Solaris

#!/bin/sh

/usr/bin/echo _ACTION         = "${_ACTION}"
/usr/bin/echo _SEVERITY       = "${_SEVERITY}"
/usr/bin/echo _VARIABLEPATH   = "${_VARIABLEPATH}"
/usr/bin/echo _GATEWAY        = "${_GATEWAY}"
/usr/bin/echo _PROBE          = "${_PROBE}"
/usr/bin/echo _NETPROBE_HOST  = "${_NETPROBE_HOST}"
/usr/bin/echo _MANAGED_ENTITY = "${_MANAGED_ENTITY}"
/usr/bin/echo _SAMPLER        = "${_SAMPLER}"
/usr/bin/echo _DATAVIEW       = "${_DATAVIEW}"
/usr/bin/echo _VARIABLE       = "${_VARIABLE}"
/usr/bin/echo _REPEATCOUNT    = "${_REPEATCOUNT}"
/usr/bin/echo _VALUE          = "${_VALUE}"

#!/bin/sh

/bin/echo _ACTION         = "${_ACTION}"
/bin/echo _SEVERITY       = "${_SEVERITY}"
/bin/echo _VARIABLEPATH   = "${_VARIABLEPATH}"
/bin/echo _GATEWAY        = "${_GATEWAY}"
/bin/echo _PROBE          = "${_PROBE}"
/bin/echo _NETPROBE_HOST  = "${_NETPROBE_HOST}"
/bin/echo _MANAGED_ENTITY = "${_MANAGED_ENTITY}"
/bin/echo _SAMPLER        = "${_SAMPLER}"
/bin/echo _DATAVIEW       = "${_DATAVIEW}"
/bin/echo _VARIABLE       = "${_VARIABLE}"
/bin/echo _REPEATCOUNT    = "${_REPEATCOUNT}"
/bin/echo _VALUE          = "${_VALUE}"

Using dollar references and capture groups

The set key search string can be a regular expression. In a regular expression, you can use parentheses to denote a numbered sub-expression, called a capturing group or capture group. Capture group zero denotes the entire matching text, capture group one is the first parenthesised expression, and so on.

The clear key search string and message settings can refer to capture groups in the set key regular expression to include text from the set key result. This is achieved using dollar references, in the form of $<number> or ${<number>}:

• $1
• $2
• ${3}

An example for clear keys follows.

Suppose that your monitored file contained messages that looked something like:

Error machine A: Some details about the error
...
Error machine B: Some details about the error

Your set key search string could look like:

Errormachine(\w+)

And your clear key search string could look like:

Fixed machine ${1}

This allows you to clear errors specific to results from a particular match. If you have errors reported on machines A, B, and C when the matching message for machine A is received, your error condition for machine A will be cleared.

Be sure when writing your clear key search strings or messages that the dollar reference number actually matches a capture group in the set key search string regular expression. Otherwise, your clear key or message may not match.

Suspending File Sampling

FKM file access and sampling can be temporarily suspended to allow users to perform cleanup or housekeeping of monitored files without encountering possible file access conflicts with the plugin. This is done through the use of "lock files", which may correspond to suspending the sampling of a single file, an entire FKM sampler, or all FKM samplers configured in a netprobe at once. FKM checks for the existence of lock files on every sample. When the plugin detects a lock file, it suspends its operation based on the scope of the lock. File operations remain suspended until the lock file is removed. The plugin then resumes sampling based on where it left off before the lock was applied. This behavior is similar to when active times are used to deactivate and reactivate a plugin.

Extended Audit Details

FKM provides extended audit details if this feature is enabled in the gateway. For more information regarding the general extended audit details mechanism, see the section on "Extended Audit Details" in the gateway reference guide.