Numeric Value extraction

Problems with a technology (application, server, device, etc.) are not always as simple as a sentence explaining that an "error has occurred." Sometimes, a technology reports its health by providing critical numbers, like a queue length, a processing time, a utilization percentage, etc. These numbers may be reported by the technology through its files, in the output of commands, in a database, in a Web page, etc. Monitoring Studio extracts these values and reports them as graphs in the PATROL Console. This feature is called Numeric Value Extraction as its purpose is to extract numeric values from a text input (the output of a command, a Web page, the result of a SQL query, or WBEM query etc.).

All you need to do is indicate how to find the numeric value(s) within the Monitor. The basic mechanism is:

2.	Specify with a regular expression the location of the numeric value within the searched lines

3.	Indicate the numeric value’s position in these lines i.e. before/after the string; column number etc.

4.	Indicate which numbers are to be considered if several lines contain the searched numeric value: first value, last value, calculate average; highest value; lowest value.

The numeric value searching function works a bit differently on "running sources" (Log files and never-ending command lines) than on flat sources (flat files, command lines, Web requests, etc.):

•	On "running sources" (Log files and never-ending command lines); the numeric values are searched only in new lines since the last polling.

•	On "flat sources" (flat files, command lines, Web requests, database queries), the numeric values are searched in the entire source (the whole file, the whole standard output, the whole HTTP response, the whole data-set).

If several values are found, it is possible to select which value should be kept: the last value found, the average of all values, the minimum or maximum or a total of all values. A graph is then built with this value.

To extract a numeric value

2.	In the PATROL Console, right-click the Monitor icon (file, Web request, etc.) and select KM Commands > New > Numeric Value Extraction...

3.	Specify which lines are to be searched for the numeric value. The information to enter subsequently depends on this first choice. There are three modes to choose from:

▪	All lines: All lines of the text will be scanned for the Numeric value search. There is no need to provide further information.

▪	The Line numbers below: Only specific line numbers will be scanned. If this mode is selected, the line numbers must be specified in the text field below. Line numbers are specified as follows:

Example

Here are some examples of formats that can be used when specifying line numbers: "4;6;8", or "3-", or "-5", or "1;3-5;7-9"

If the Skip blank lines option is selected, empty lines will be ignored in the line-count.

▪	Lines matching the regular expression below: The lines scanned will be the lines matching the regular expression specified in the field.

▪	The numeric values are located: There are four different modes to choose from and the information to enter depends on this choice.

▪	After the string specified below: If the numeric value is located after the string to be entered in the text field.

▪	Before the string specified below: If the numeric value is located before the string to be entered in the text field.

▪	At the character offset specified below: The value should be at a specific character offset in the line. Enter the offset number in the box. Monitoring Studio will look for the numeric value at that exact character offset in the line. If no numeric data is found, no value will be collected.

▪	In the column number specified below: The previously selected lines contain several columns identified by a separator character. Enter the column number that should contain the value.

7.	If the option in the column number specified below was previously selected, you will have to indicate how columns are separated:

▪	Select or de-select applicable separators. For custom separators, type the character(s) one after the other in the Others field.

▪	Consecutive separators must be treated as a single one (useful for data separated by blank spaces): Typically, it indicates that consecutive separators must be treated as a single separator.

▪	Consecutive separators mean empty columns: Each separator is treated as an individual column separator and the column is considered empty. The above two options are especially useful for data separated by blanks.

▪	Do not interpret quotes: All applicable separators will be considered as a column separator even when enclosed in quotes.

▪	Consider text in "double quotes" as a single column: Numeric values enclosed in double quotes will be considered as a single column. Any separator found within double quotes will not be considered as a column separator.

▪	Consider text in 'single quotes' as a single column: Numeric values enclosed in single quotes will be considered as a single column. Any separator found within single quotes will not be considered as a column separator.

▪

From the Expected format drop-down list, select how the numeric values are formatted. This option allows you to extract numeric values that use blank, comma, or points as decimal and thousand separators. Monitoring Studio will look for a number in the location specified previously. When a character that does not match the expected format is found, the parsing will stop. So if the expected format is 1,000 and Monitoring Studio finds 1 000, the returned value will be 1.

▪	Check the box Support negative values if the numeric values that you are looking for can be negative. The '-' sign will be considered as an acceptable character when looking for the number.

▪	Check the Convert units option to convert the extracted numeric value from kilobytes, megabytes, gigabytes, terabytes to bytes or from days, hours, minutes to seconds. (For example: 2.1 KB will be converted to 2150 bytes and 1 hour will be converted to 3600 seconds).

▪	Indicate which value should be used to set the parameter value and build the graph in the PATROL Console if several values are found in the searched text. The possible values are:

▪	Delta: The value reported corresponds to the difference between values collected during two consecutive polling.

▪	Delta per second/minute/hour: The value reported corresponds to the result of the division of the Delta by the number of seconds/minutes/hour elapsed between the collection times.

▪	Select the option Discard negative Delta values if you do not want negative values to be reported on the graph.

▪	Use the Rescaling option to configure Monitoring Studio to rescale the value that is being extracted in order to have a more readable graph in the PATROL Console. The available rescaling options are:

This can be useful if you extract numeric values in bytes but prefer to show a graph in megabytes. In such a case, you would divide the values by 1048576 (1024*1024).

11.	Click Finish. The corresponding Numeric Value Extraction instance (Numeric Value Extraction: <Display Name>) is created in the PATROL Console. The collected parameters for Numeric Value Extraction Monitors are listed in the SEN_MS_NUMBER chapter.

If Monitoring Studio does not find a number at the specified location, no numeric value will be extracted and the PATROL graph will not be refreshed (space characters are ignored).

Extracting Numeric Values

To extract a numeric value