fetchlog(1)fetchlog documentation fetchlog(1)NAMEfetchlog - fetch and convert new messages of a logfile
SYNOPSISfetchlog-f first:last:len:conv logfile bookmarkfile [ pattern .. ]
fetchlog-F first:last:len:conv logfile bookmarkfile [ pattern .. ]
fetchlog [-h|-V]
DESCRIPTION
The fetchlog utility displays the last new messages of a logfile. It is
similar like tail(1) but offers some extra functionality for output
formatting. To show only the new messages appeared since the last call
fetchlog uses a bookmark to remember which messages have been fetched.
fetchlog scans backwards logfile and collects all messages, optionally
only those matching any of the given regex-style patterns. Then
fetchlog converts found message lines for output. It stops scanning
when one of these conditions become true: The bookmark from bookmark‐
file is reached, or len characters are ready for output, or an error
occurs. fetchlog knows about rotated and uncompressed logfiles and
continues scanning in rotated logfiles by appending '.0', if that file
does not exist '.1', then upto '.9' to logfile when scanning in rotated
logfiles. Scanning stops without error when a rotated logfile does not
exist.
OPTIONS-f do not update bookmark in bookmarkfile.
-F update bookmark in bookmarkfile : set bookmark to the very last
line fetched from logfile
first The first column of text fetchlog will read from logfile. Lines
shorter than first will be show up as a single newline. The col‐
umn count starts with 1.
last The maximum last column fetchlog will read from logfile. Lines
longer than last will be cut off and a `~` will be set at column
last for output. The column count starts with 1.
len The maximum number of characters fetchlog will output. If more
than len characters are available after cutting and conversion,
the first line put out will start with '...'.
conv Conversion: one ore more of characters 'bpsno3'.
b [brackets] convert '<' and '>' to '(' and ')' for safe HTML
output.
p [percent] convert '%' to 'p' for safe printf(1) output.
s [shell] convert '$', '^', and the three quotes (backquote,
doublequote, singlequote) and '|' to '_' and '\' to '/'. This
conversion is useful when passing the result of fetchlog to a
shell command as a parameter.
n [newline] convert newline characters to '\n' sequence to get a
single line of output.
o [ok message] Show 'OK: no messages' if no new messages are
available for output.
3 [Nagios3] output in multiline format required for plugins
since Nagios3.
logfile
Absolute path to the unrotated logfile to fetch data from. The
user needs read access to logfile.
bookmarkfile
Absolute path to the file holding the bookmark. The user needs
read access to the file when using option -f and write access
plus permission to create files in the directory of bookarkfile
when using option -F (update bookmark).
If bookmarkfile does not exist fetchlog assumes an infinite old
bookmark.
pattern
A extended regular expression pattern, see re_format(7) for
details. If one or more pattern are defined, fetchlog will only
pick lines where any of these pattern match. Pattern matching is
done after trimming the lines with respect to first and last and
before any conversions takes place. In other words: pattern
matching operates on data that fetchlog shows when no conversion
is set.
-h print help message
-V print version
MULTIPLE FETCHING
Fetching the same logfile with different bookmarks works without
problem. Simultanously fetching with option -F (update mode)
using the same bookmark file works too, but unpredictable
results will occur. For safety reasons bookmarkfile will never
be opened for writing directly, instead a temporary file will be
used and renamed to bookmarkfile when writing has finished.
PERFORMANCE
Before opening logfiles for scanning fetchlog first checks the
modification time of logfile and compares this time with the
modification time stored in bookmarkfile. If both timestamps
are the same then fetchlog exits with 0 (no messages). Other‐
wise the logfile(s) get mapped to memory step by step and are
scanned backwards line by line until one of the end conditions
become true. fetchlog uses the logfiles inode to distinguish
different logs.
NAGIOSfetchlog may be used as a local plugin for the Nagios network
monitoring system to monitor a local logfile. It follows the
calling convention for Nagios plugins if at least conversions on
are set and len is 'short' enough for Nagios (330 prior to
Nagios 3, 4000 since Nagios 3). It is recommended to use con‐
version s also because shell metacharacters in fetched messages
may confuse Nagios' notification system.
Nagios 3 introduces a new interface for plugins sending out mul‐
tiline output as fetchlog does. Even with conversion 'n' Nagios
reads this as a multiline message. To be compatible with Nagios
3 plugin format enable conversion '3' also. Output format is
then: SHORT_MESSAGE|\nMESSAGE_LINE_1\n...\nMESSAGE_LINE_N where
SHORT_MESSAGE will be the last line fetched MESSAGE_LINE_N.
Please see README.Nagios for details.
When using fetchlog as a local plugin for Nagios then exit sta‐
tus is as follows:
OK No new messages in logfile where found. The single line
'OK: no messages' will be send to stdout.
WARNING
fetchlog detected an internal error while fetching. A one
line error message starting with 'ERROR: fetchlog:' is
send to stdout.
CRITICAL
New messages in logfile where found. A single line with
the last new messages will be send to stdout.
UNKNOWN
fetchlog was called with wrong parameters. A multiline
usage message is send to stdout.
Nagios can monitor remote logfiles together with NET-SNMP and
fetchlog using the check-snmp plugin. Please read the README
files coming with fetchlog how to setup this.
SNMP
The motivation for fetchlog was to create a helper tool for NET-
SNMP's snmpd to enable monitoring of remote kernel syslogs using
SNMP. If configured properly, snmpd replies to a specific SNMP
request with the output of an external helper program. With
fetchlog using update mode -F and conversions on one can peek at
a remote syslog file and gets either 'OK: no messages' or one
line with the new syslog messages appeared since the last SNMP
request.
Because of some limitiations of SNMP itself and the monitoring
applications using SNMP, the length of the SNMP reply must not
exceed a specific size. To ease the integration of SNMP in moni‐
toring software it is useful to have the SNMP reply only consist
of a single line of text rather than multiple lines.
COMPRESSING OUTPUT
The syslog messages fetched can be compressed by increasing
first to skip the timestamp and host entry from syslog. Lower‐
ing last gives even more compression for long syslog lines. As a
result one gets a very short message that gives an idea of what
is going wrong.
DIAGNOSTICSfetchlog sends all output and error messages to stdout. Exit
codes:
0 No new messages in logfile were found. If conversion o is
set, the single line 'OK: no messages' will be send to
stdout.
1 An internal error in fetchlog occured. A one line error
message will be send to stdout. The error message starts
with 'ERROR: fetchlog:' and shows detailed information
about what went wrong. Length limitation by parameter len
is applied, if an error message is too long the last part
will be cut off and a '~' is appended.
2 New messages in logfile were found. The new messages will
be send to stdout. If conversion n is set, a single line
of text is send, else zero or more lines of converted
syslog messages are send.
3 fetchlog was called with wrong parameters, a multiline
usage message is print to stdout.
Note: Since version 0.93 the meanings of exit code 1 and 2 have
been exchanged.
AUTHOR
Alexander Haderer, LoeScap Technology GmbH, Berlin - Germany
SEE ALSOtail(1), cat(1), head(1), sed(1), re_format(7), syslogd(8),
newsyslog(8)
NET-SNMP - Various tools relating to the Simple Network Manage‐
ment Protocol SNMP (NET-SNMP: formerly known as UCD-SNMP)
http://www.net-snmp.org
Nagios - A Network monitoring system
http://www.nagios.org
Nagios Plugins - Plugins for Nagios
http://nagiosplug.sourceforge.net
fetchlog homepage - download, support and bugtracking
http://fetchlog.sourceforge.net
BUGS
Bookmarkfiles are not portable across plattforms or fetchlog
versions.
Logfiles are expected not to shrink.
fetchlog does not work with compressed logfiles.
Fetching when logfile rotation takes place may result in some
messages to appear twice.
If an regex error occurs during pattern matching this error is
silently ignored and will be handled as non-match.
LEGAL
Nagios is a registered trademark of Ethan Galstad.
fetchlog(1) 23 Nov 2008 (1.2) fetchlog(1)
