See www.zabbix.com for the official Zabbix site.

Docs/specs/ZBXNEXT-1653

From Zabbix.org
Jump to: navigation, search

Regular Expression Extraction

ZBXNEXT-1653

Status: v1.0

Owner: Andris Zeila

Summary

There is a need to return a portion of data from file. The current vfs.file.regexp[] item returns the whole matched string. It should be extended to allow returning captured part of the matching line .

Specification

The following table describes changes needed to implement the vfs.file.regexp[] item extension and to keep consistency between existing items:

Old format New format Changes

vfs.file.regexp [

file,
regexp,
<encoding>

]

vfs.file.regexp [

file,
regexp,
<encoding>,
<start line>,
<end line>,
<output>

]

parameters added
<start line> (optional)
the first line to match. Defaults to the first line of file.
<end line> (optional)
the last line to match. Defaults to the last line of file.
<output> (optional)
the text to return when a match happens. All '\<character>' sequences in the text is replaced for the following <character> values:
0 - is replaced with the matched text
1-9 - is replaced with the captured group or empty string if the value exceeds the total number of captured groups
\ - is replaced with the backslash character '\'
If <output> is not specified the whole line is returned.
return value changed
Empty string is returned instead of 'EOF' on failure (failed match).

vfs.file.regmatch [

file,
regexp,
<encoding>

]

vfs.file.regmatch [

file,
regexp,
<encoding>,
<start line>,
<end line>

]

parameters added
<start line> (optional)
the first line to match. Defaults to the first line of file.
<end line> (optional)
the last line to match. Defaults to the last line of file.

vfs.file.contents [

file,
<encoding>

]

vfs.file.contents [

file,
<encoding>

]

return value changed
Empty string is returned instead of 'EOF' on failure.

web.page.get [

host,
<path>,
<port>

]

web.page.get [

host,
<path>,
<port>

]

return value changed
Empty string is returned instead of 'EOF' on failure.

web.page.regexp [

host,
<path>,
<port>,
<regexp>,
<length>

]

web.page.regexp [

host,
<path>,
<port>,
<regexp>,
<length>,
<output>

]

parameters added
<output> (optional)
the text to return when a match happens. All '\<character>' sequences in the text is replaced for the following <character> values:
0 - is replaced with the matched text
1-9 - is replaced with the captured group or empty string if the value exceeds the total number of captured groups
\ - is replaced with the backslash character '\'
If <output> is not specified the whole line is returned.
return value changed
Empty string is returned instead of 'EOF' on failure (failed match).

log [

file,
<regexp>,
<encoding>,
<maxlines>,
<mode>

]

log [

file,
<regexp>,
<encoding>,
<maxlines>,
<mode>,
<output>

]

parameters added
<output> (optional)
the text to return when a match happens. All '\<character>' sequences in the text is replaced for the following <character> values:
0 - is replaced with the matched text
1-9 - is replaced with the captured group or empty string if the value exceeds the total number of captured groups
\ - is replaced with the backslash character '\'
If <output> is not specified the whole line is returned.
Note that all global regular expression types except 'Result is TRUE' always return the whole matched line and the <output> parameter is ignored.

logrt [

file_format,
<regexp>,
<encoding>,
<maxlines>,
<mode>

]

logrt [

file_format,
<regexp>,
<encoding>,
<maxlines>,
<mode>,
<output>

]

parameters added
<output> (optional)
the text to return when a match happens. All '\<character>' sequences in the text is replaced for the following <character> values:
0 - is replaced with the matched text
1-9 - is replaced with the captured group or empty string if the value exceeds the total number of captured groups
\ - is replaced with the backslash character '\'
If <output> is not specified the whole line is returned.
Note that all global regular expression types except 'Result is TRUE' always return the whole matched line and the <output> parameter is ignored.

Use cases

log/logrt extraction. An application is writing amount of "entries" to a logfile every now and then for a specific period of time. There's a need to graph and trigger on it being above some threshold. Graphing without extracting is not possible, triggering on entries exceeding 10k is done with expression like this : regexp("Entries\: [1][0-4][0-9]{3}",1800)}=1, which is overly complicated.

The current solution would not solve this use case as the data type would still be "Log" - it is not possible to graph such values, but it is possible to compare them in triggers.

log/logrt extraction. If entries are parsed for timestamp, extraction could discard the timestamp from actual log entry.

Documentation

  • What's new
  • Item table
  • Log monitoring page
    • Mention that extracted numbers from logfiles may be compared in triggers but may not be graphed.

Test cases

  • Timestamp parsing and then discarding it works

ChangeLog

  • N/A