Universal Logging System

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== Logfileadapter =====

Log files can be searched for lines which match specific patterns.
Matching lines are parsed and variables are filled with matching 
expressions. Output actions can contain these variables in 
executable commands.

lfa4uls = logfile adapter for ULS = Logfileadapter

Appended lines of constantly growing log files can be searched 
for regular expressions. Based on given format descriptions, 
the matching lines are parsed and defined variables or placeholders are set.
These variables can be embedded in action definitions for output, 
in which the whole matching line can, e.g., be sent to the ULS-server 
or be written to another log file or be sent via e-mail.

The lfa4uls does **not** need to be used in conjunction with the ULS-server, 
but can also be used as a stand-alone solution for log file parsing 
and processing.

The regular expressions are processed by the lfa4uls accordingly to 
POSIX.2 (1003.2). See also:

  man 7 regex

You may start the logfile adapter to parse a logfile once and write out 
the found matches or you start it as daemon to tail the given logfile
and parse each appended line.

  lfa4uls [-?] [-a|-A] [-c <conffile>] [-d <def>] [-D|-Dp <pidfile>] [-g]
          [-H <num>] [-s|-S] [-u] [-U] [-v <reg>|-vf <vfile>] [-f <inputformat>]
          [-r] [-t <sec>|-T <sec>] [-N <sec>]
          [-l <lreg>|-lf <lfile>|-la] [-lw <loutfmt>] [-L <logaction>]
          [-o <outputfile>] [-oh <header>] [-V]
          [-I <inputdir> | <inputfiles> ...]


:TODO: translate the remaining text

Protokolldateien können mit dem lfa4uls ausgewertet und durchsucht werden.

lfa4uls = logfile adapter for ULS = Logfileadapter

Mit dem lfa4uls können die Inhalte von stetig wachsenden Protokolldateien zeilenweise nach Textmustern (regulären Ausdrücken) durchsucht werden. Zeilen, die einem Textmuster entsprechen, werden nach einer Formatbeschreibung (inputformat, iformat) ausgewertet. Die Ergebnisse dieser Auswertung stehen für die Weiterverarbeitung (action) in der Ausgabe zur Verfügung, zB können diese Zeilen dann an das ULS geschickt werden. Die Ausgaben können auch direkt in eine Datei geschrieben werden, z. B. im ULS-Tabellenformat.

Trotz der Bezeichnung lfa4uls, kann er unabhängig vom ULS eingesetzt werden. Bei der Weiterverarbeitung in der Ausgabe können beliebige Kommandos verwendet werden.

Ablaufbeschreibung

Für jede neu hinzukommende Zeile werden folgende Aktionen durchgeführt:
  * passt die Zeile zum regulären Ausdruck von vreg, dann diese Zeile ignorieren => auf nächste Zeile warten
  * passt die Zeile zu einem regulären Ausdruck der reg oder reg+, dann die Zeile parsen mit iformat und entsprechende action, write oder syslog ausführen
    => wenn reg+, dann weiter vergleichen, sonst auf nächste Zeile warten
  * ist lreg_all = 1, dann laction ausführen => auf nächste Zeile warten
  * passt die Zeile zum regulären Ausdruck von lreg, dann die Zeile parsen mit inputformat und laction ausführen => auf nächste Zeile warten
  * wenn keine der obigen Bedingungen erfüllt sind, dann wird die Zeile ignoriert => auf nächste Zeile warten

Zu allen direkt eingetragenen regulären Ausdrücken reg[+] kann auch eine Datei reg_file[+] angegeben werden, die mehrere Zeilen mit jeweils einem regulären Ausdruck enthalten können. Die regulären Ausdrücke werden bei der Anwendung von reg_file logisch ODER verknüpft. Es wird entweder reg oder reg_file verwendet, der letzte Eintrag in der Konfigurationsdatei entscheidet.


=== Options ===

A mixture of command line parameters and entries in a configuration file <conffile> is supported.

== -? ==

Show a help page.


== -a ==

All lines of <inputfile> are searched from the beginning to the 
end and lfa4uls will wait for new lines.

== -A ==

Like [[.log_file_adapter#-a]], but lfa4uls terminates when the end of the file is reached.


== -c <conffile> ==

Complete path of the configuration file <conffile>.


== -d <def> ==

Defines variables like [[.log_file_adapter#-d <def>|-d]] "%h=Hostname" or [[.log_file_adapter#-d <def>|-d]] "%5=System".


== -D ==

Start lfa4uls as daemon.


== -Dp <pid_file> ==

Start lfa4uls as daemon and write its PID to file <pid_file>.


== -f <inputformat> ==

Format for parsing the lines of the <inputfile>.


== -g ==

Ignore the special meaning of '[]{}()' in regular expressions.


== -H <num> ==

Number of lines that can be aggregated.


== -l <regexp> ==

Define the regular expression, which fires the 'log' action.

== -la ==

Each line fires the 'log' action.


== -lf <regexp_file> ==

Like [[.log_file_adapter#-l <regexp>]] but read the regular expressions from file <regexp_file>.


== -lw <outputfmt> ==

Define the output line format <outputfmt> for 'log' action.


== -L <laction> ==

Action for each line matching the 'log' condition.


== -N <sec> ==

Ignore equal lines within <sec> seconds.


== -o <outputfile> ==

Output is appended to file name.

  
== -s ==

Print the actions, do not execute them.


== -S ==

Print the actions, lfa4uls terminates when the end of the file is reached.


== -t <sec> ==

Look for new lines in <inputfiles> after <sec> seconds.
Default is 5s.


== -T <sec> ==

Start reading from the beginning of the <inputfile> every <sec> seconds.


== -u ==

Print timestamps in coordinated universal time.


== -U ==

Read timestamps in coordinated universal time.


== -v <regexp> ==

Ignore lines with matching regular expressions.


== -vf <regexp_file> ==

Ignore lines with matching regular expressions read from <regexp_file>.


== -V ==

Show version of this 


== <inputfiles> ==

Specify the complete path of the <inputfiles> which shall be parsed.



=== Configuration File ===

The confoguration file defines all parsing and output actions.
It may be mixed with the usage of command line parameters.
This is the complete description, you may prefer to advance to 
the [[.log_file_adapter#Usage]] section below for a more 
practical approach.


== Description ==

<file - lfa4uls_configuration.txt>

#
# Konfigurationsdatei für lfa4uls
#

# Der Input kann aus mehreren Dateien gelesen werden 
#   * "inputfile": Dateipfad
#   * "inputfilepattern": Suchmuster (Es sind nur * und ? als Wildcards erlaubt, aber auch für Directories)
#
# oder einem Programm
#   * "inputcommand"
#
# oder es koennen
#   * ganze Verzeichnisse "inputdir", optional mit allen Unterverzeichnissen überwacht werden
# 
# Die Möglichkeiten können nicht kombiniert werden.


# ----- FILE -----

# es können bis zu 100 Dateien überwacht werden, die als feste Dateinamen oder Suchmuster angeben werden
# d. h. inputfile, inputfiles, inputfilepattern und inputfilepatterns dürfen mehrfach angegeben werden

# feste Dateinamen
#
# Zu überwachende Dateien, jede Datei mit "inputfile = "
inputfile = /var/log/messages

# Dateinamen nach Muster (alle)
#
# Alle Dateien, die dem Muster entspreche werden gescannt
inputfiles = /var/log/m*

# Dateien nach Muster (nur eine)
#
# Wenn der Name der Logdatei nicht feststeht. 
# Es wird die erste Datei, die zum Muster passt überwacht.
# Wenn die Datei gelöscht oder komprimiert wird, dann wird erneut gesucht.
#
inputfilepattern = /var/log/prod/logfile*.log

# Dateien nach Muster in mehreren Pfaden
#
# Wenn der Name der Logdatei nicht feststeht. 
# Es wird in allen Pfaden jeweils die erste Datei, die zum Muster passt überwacht.
# Wenn die Datei gelöscht oder komprimiert wird, dann wird erneut gesucht.
# Der letzte Wildcard gibt an, über welche Dateien die neueste gesucht werden soll.
# Wenn der veränderliche Teil nicht am Ende steht, dann muss der veränderliche Teil
# in {...} eingeschlossen werden.
#
inputfilepatterns = /var/log/*/logfile*.log  # jeweils die neueste Datei pro Ordner
inputfilepatterns = /var/log/*_logfile*.log  # mehrere Logfiles in einem Ordner
inputfilepatterns = /var/log/logfile_{*}_*.log  # mehrere Logfiles in einem Ordner, das Datum steht vorn


# Die Suchreihenfolge kann geändert werden:
# inputfilepatternsort = U|FN|O|N
#    U : unsortier - Reihenfolge des Betriebssysstems
#    FN: bei Restart die neueste, dann chronologisch aufsteigend
#    O : Bei Restart die äteste, dann chronologisch aufsteigend
#    N : bei Restart die neueste, dann die neueste
inputfilepatternsort = FN

# zyklische Suche nach neuen Dateien:
# inputfilepatternsearch = <Sekunden>
#   es wird alle <Sekunden> Sekunden nach neueren Dateien als die aktuelle gesucht.
#   unabhängig von inputfilepatternsort wird auf die neueste Datei gewechselt
inputfilepatternsearch = 60

# inputfilereopen
# Bei Linux werden die Logdateien nicht geschlossen
inputfilereopen = 1    # Logdateien schließen, wenn nicht gelesen wird (ist bei Windows standard)

# exit_on
# der lfa4uls kann beendet werden, wenn:
exit_on = EOF     # beenden, wenn Datei zu Ende gelesen wurde
exit_on = FNF     # wenn keine Datei gefunden wird, bzw. wenn es keine neue Datei gibt


# ----- Protokolldatei ----
#
# logfile: Ausgabedatei
# logfile = <Protokollpfad>
logfile = /tmp/lfa4uls_test.log
#
# loglevel: Aktionen, die geloggt werden sollen
# loglevel = <Liste der zu protokollierenden Aktionen>
#   mögliche Aktionen:
#     NONE            Nichts
#     ERROR           Errors
#     WARNING         Warnings
#     FILE            öffnen und schließen von Dateien
#     MATCH           gefundene Zeilen
#     ACTION          ausgelöste Aktionen
#     WRITE           geschriebene Zeilen
#     SYSLOG          Zeilen an Syslog
#     STORE           gespeicherte Daten
#     STORESEND       versenden der gespeicherten Daten
#     CANCEL          ausgelöste "cancel"
#     SCHEDULEACTION  ausgeführte Schedule Aktionen
#     SCHEDULEWRITE   geschriebene Schedule Zeilen
#     ALL             Alles
loglevel = ERROR WARNING


# ----- Ausgabedatei -----
#
# Daten können direkt im ULS Format in eine Ausgabedatei geschrieben werden.
outputfile = /tmp/lfaulsdata.uls
#
# outputfileheader: jede Ausgabedatei mit einem Header versehen. Z. B. um den Zeichensatz zu setzen
outputfileheader = L;;;;;;latin1
#
# writequoting: Sonderzeichen in Variablen quoten. Das erste Zeichen ist das Quotingzeichen, das allen
#               Zeichen aus writequoting bei Variablenersetzungen und "write" vorangestellt wird.
writequoting = \"

# ----- automatisches Versenden der Ausgabedatei -----
#
# Es kann eine Aktion definiert werden, die zeitgesteuert ausgeführt wird,
# nachdem Daten in die Ausgabedatei geschrieben wurden
#
# sendoutputfilesecs: Zeit in Sekunden, die nach dem ersten Schreiben gewartet wird,
# bis die Datei versendet wird
sendoutputfilesecs = 180
#
# sendoutputfile: auszuführendes Programm, es können die gleichen Codes wie bei der Ausgabe verwendet werden
sendoutputfile = send2uls "%O"

# ----- zwischenspeichern von Zeilen -----
# storepath: Pfad, unter dem Zeilen mit "store" zwischengespeichert werden
storepath = /tmp/lfa4uls_store


# ----- PROGRAM -----
#
# Es wird von stdout eines Programmes gelesen.
inputcommand = netstat -nlt


# ----- Variablen -----
#
# Beim Parsen von Zeilen stehen folgende Variablen zur Verfügung:
%h - Hostname
%q - Quelle
%W - String bis zum Zeilenende
%V - String bis zum Zeilenende, bei der Erkennung von Dubletten werden Zahlen ignoriert
%0 bis %9 - freie Variablen
# die Variablen %h, %q und %0 - %9 können global vorbelegt werden:
set <varname> = <value>


# ----- date time -----
utcin = 1|0    # read timestamps in UTC or localtime
utcout = 1|0   # write timestamps in UTC or localtime


# ----- INPUT LINE FORMAT -----

inputformat = %t %h %q: %sValue1: %1, Value2: %2, %W

# <inputformat> beschreibt, wie die Zeilen des <inputfile> zu interpretieren sind.
# Dabei sind KEINE regulaeren Asdruecke moeglich, nur feste Strings.
# Die Groß-/Kleinschreibung kann durch das Anfügen des Zeichens '|' ans '=' ignoriert werden:

inputformat =| %t %h %q: %svalue1: %1, value2: %2, %W

# Folgende Codes koennen zum Parsen der Zeilen benutzt werden:

%%      => %
%[<CHARS>] => ein beliebiges Zeichen aus <CHARS>
%s      => ein String (wird verworfen)
%.<n>s  => <n> Zeichen (werden verworfen)
%t      => Datum im Format: MMM TT hh:mm:ss (Monat Tag Stunde:Minute:Sekunde)
            oder im Format: YYYY-MM-DD[T ]hh:mm:ss[.ssssss][+-hh:mm]
%c      => ein Zeichen (wird verworfen)
%.<n>c  => <n> Zeichen (werden verworfen)
%h      => Host
%q      => Quelle, Besonderheit bei %q: Ausdrücke, die in '()', '[]' oder '{}' stehen gelten bei der Wiederarlarmierung als identisch.
%W      => Meldung (gelesen wird bis zum Zeilenende)
%D      => Datum im Format: DD.MM.YY oder DD.MM.YYYY
%F      => Datum im Format: YYYY-MM-DD
%T      => Zeit im Format: hh:mm:ss
%d      => Tag
%m      => Monat
%b      => Monatsname (erste drei Zeichen)
%y      => Jahr (zweistellig)
%Y      => Jahr (vierstellig)
%H      => Stunde
%M      => Minute
%S      => Sekunde
%0      => Variable 0
%.<n>:0 => <n> Zeichen in Variable 0
%#0     => Nur Zahlen (Float) nach Variable 0
%1      => Variable 1
%.<n>:1 => <n> Zeichen in Variable 1
...
%9      => Variable 9
%-0     => Bei Konsolidierung kann so ein Wert aus der %{0,DIST} Liste entfernt werden
...        Kann in Verbindung mit regsplit genutzt werden, um z. B. eine Pfad, der offline geht mit %0 zu setzen und wenn der wieder
%-9        online geht mit %-0 zu löschen. Die Zeile wird dann nach z. B. 10 Minuten nur dann geschrieben, wenn test auf %{0,DIST} > 0 erfüllt ist.
           Siehe Example2: Usage %{<n>,DIST}
%.<n>:9 => <n> Zeichen in Variable 9
%i<[hqVW0-9]> => dieses Feld wird geparst, aber bei der Deduplizierung ignoriert. %s und %c werden bei der Deduplizierung immer ignoriert.

Leerzeichen zwischen den Codes ersetzen soviele white-spaces wie moeglich.

# Die meisten Codes stehen in den ?action und ?write fuer eine Ausgabe zur Verfuegung,
# siehe ACTION FORMAT.

# ----- ACTION und WRITE FORMAT -----
#
# In <?action>, <action?>, <?write> und <write?> koennen Ergebnisse des Parsens der
# Zeilen verwendet werden. Folgende Codes können dafuer verwendet werden:
# alle Codes des Inputfomates ohne %t, %s, %s* und %c
#

%y => Jahr im Format YY
%Y => Jahr im Format YYYY
%b => Monatsname (erste drei Zeichen)
%d => Tag (01..31)
%m => Monat (01..12)
%N => Anzahl gleicher Zeilen bei (hist_secs > 0) oder Anzahl bei sum_hist
%F => Datum im Format: YYYY-MM-DD
%z => die ganze Zeile
%l => Gesamtzahl bisher gelesener Zeilen
%L => gelesene Zeilen seit letzter Ausgabe mit %L
%C => Änderungsdatum der Datei im Format YYYY-MM-DD hh:mm:ss
%B => Größe der Datei in Bytes (wenn von CMD oder Stdin gelesen wird, dann 0)
%p => Dateiname der überwachten Datei - Kann bei consolidate nicht genutzt werden
%{p,<c>,<start>[,[<end>][,<str>]]} => Dateiname nach Zeichen <c> trennen und Teil des Dateinamens
                                      von <start> bis <end> und ggf. <c> durch <str> ersetzen.
                                      Ist nur <start> angegeben, nur dieses Element des Dateinamens.
                                      0 oder -1 als <end> ist bis zum Ende. Wenn <start> oder <end> negativ ist,
                                      wird von hinten gezählt.
                                      Kann bei consolidate nicht genutzt werden
%P => kompletter Pfad der überwachten Datei - Kann bei consolidate nicht genutzt werden
%{P,<start>[,[<end>][,<str>]]} => Teil des Pfades von <start> bis <end> und ggf. '/' durch <str> ersetzen.
                                  Ist nur <start> angegeben, nur dieses Element des Pfades.
                                  0 oder -1 als <end> ist bis zum Ende. Wenn <start> oder <end> negativ ist,
                                  wird von hinten gezählt. Ist <start> 0, dann wird der führende '/' mit ausgegeben.
                                  Kann bei consolidate nicht genutzt weden
%O => kompletter Pfad der Ausgabedatei, wenn gesetzt
%0 … %9 => Variablen 0-9
%{<n>,HASH[,<len>]}     => gehaschte Variable 0-9 mit Länge <len> bzw. 8 wenn <len> nicht angegeben
%{<n>,LOW[ER]}          => Variable 0-9 nach lowercase wandeln
%{<n>,UPP[ER]}          => Variable 0-9 nach uppercase wandeln


# ----- Wenn „consolidate“ gesetzt, dann ist -----

%N                     => Anzahl der Zeilen
%{<n>,SUM[,<fmt>]}     => Summe über Variable <n>
%{<n>,AVG[,<fmt>]}     => Mittelwert der Variable <n>
%{<n>,MIN[,<fmt>]}     => Minimum der Variable <n>
%{<n>,MAX[,<fmt>]}     => Maximum der Variable <n>
%{<n>,FIR[ST][,<fmt>]} => erster Wert der Variablen <n>
%{<n>,LAS[T][,<fmt>]}  => letzter Wert der Variablen <n>
%{<n>,DIST}            => Anzahl verschiedener gelesener Werte der Variablen <n> 
%{FIRSTDATE,<datfmt>}  => Datum der zuerst gelesenen Zeile
%{LASTDATE,<datfmt>}   => Datum der zuletzt gelesenen Zeile
%{TIMERANGE}           => Sekunden von erster bis letzter Zeile
%{TIMEDIFF}            => Zeitdifferenz zur letzten Meldung in Sekunden
                      <fmt> ist optionales Ausgabeformat im Format [<a>][.<b>]: Mindestbreite <a> und <b> Nachkommastellen
                      <datfmt> Datumsformat wie bei Ausgabe mit %[abdDFHmMsSTwyY] z. B.: "%Y-%m-%d %H:%M:%S"

# ----- IGNORE -----
#
# Regulaeren Ausdruck fuer Zeilen definieren, die verworfen werden.
#
# vreg = INFO|MARK
#
# mit "ignore case"
#
# vreg =| info|warn
#
# Oder Datei mit regulaeren Ausdruecken angeben
#
# vreg_file = ignore_regexps_list.txt
# vreg_file =| ignore_regexps_list_ignore_case.txt

# ------ identische Zeilen ignorieren -----
# Sekunden, in denen gleiche Zeilen nicht noch einmal auslösen
#
# hist_secs = <seconds>
# 


# ----- REG[<n>] -----
# 
# 100 Moeglichkeiten mit einem regulaeren Ausdruck bestimmte Zeilen 
# herauszusuchen, diese mit eigenem Format (Standard ist <inputformat>) 
# zu Parsen und eine eigene Aktion auszuloesen. Wird eine Zeile
# gefunden, wird abgebrochen, außer das Schlüsselwort endet mit einem '+'

# Jeder Block muss mit einem der folgenden Schlüsselwörter beginnen

reg        = zu suchende Reg-EXP
reg+       = zu suchende Reg-EXP und weiter mit nächstem Block
!reg       = nicht zu suchende Reg-EXP
!reg+      = nicht zu suchende Reg-EXP und weiter mit nächstem Block
regsplit   = zu suchende Reg-EXP, mit Blöcken, nach denen getrennt wird
regsplit+  = wie regsplit und weiter mit nächsten Block
reg_file   = zu suchende Reg-EXPs werden aus Datei gelesen
reg_file+  = ... und weiter mit nächstem Block
!reg_file  = nicht zu suchende Reg-EXPs werden aus Datei gelesen
!reg_file+ = ... und weiter mit nächstem Block
regall       es passt alles - folgende Inputformate oder Aktionen werden ignoriert.
regignore  = zu suchende Reg-EXP, die ab hier ignoriert werden. Bei vreg wird die Zeile komplett ignoriert.
!regignore = Reg-EXP, die nicht passen werden ab hier ignoriert.
regignore_file  = wie regignore, nur die Reg-EXP werde aus Datei gelesen 
!regignore_file = wie !regignore, nur die Reg-EXP werden aus Datei gelesen


# die folgenden Definitionen beziehen sich auf das Schlüsselwort am Beginn des Blockes

iformat    = Inputformat wenn angegeben, sonst gilt globales inputformat (nicht bei regsplit)
splitvars  = Zuordnung der Variablen zum regsplit

# hist_secs = <s> individuelle Einstellung für diesen Block
#                 gleiche Zeilen werden für <s> Sekunden unterdrückt. Die erste passende Zeile wird ausgegeben.
#                 Bei der Prüfung auf gleiche Zeilen werden alle Felder mit Ausnahme der Zeitstempelfelder herangezogen,
#                 die als Ausgabe genutzt werden können. Also nicht %s, %c (ab Version 5.5).
#                 Wenn ein Feld nicht beachtet werden soll, dann muss das Feld um ein 'i' erweitert werden: %q -> %iq, %1 -> %i1, ...
#                 Beispiel:

reg = \[ERROR\]
hist_secs = 300
iformat   = %F %T%s %iq: %V
write     = V;%F %T;%h;Section;Teststep;%p;%q - %V;_
# hinter der Uhrzeit stehen noch Millisekunden, die bei der Deduplizierung ignoriert werden sollen.


# sum_hist = <CONSFMT> bestimmt Anzahl identischer Zeilen gruppiert nach den Variablen. (count distinct mit %N als Anzahl)
# Beispiel:
iformat  = %F %T - %1, %2, %iW
sum_hist = 0/5m        -> alle 5 Minuten distincte Zeilen mit Anzahl ausgeben
write    = %1, %2: %N

# sollen nur die Zeilen gezählt werden:
iformat = %F %T %iW   -> mit Datum
iformat = %iW         -> ohne Datum
write   = In Datei %p wurden %N Zeilen gelesen


# consolidate = <CONSFMT|CONSFMT2> fasst alle Zeilen des Musters zu einer Meldung zusammen. Es wird über alle Eingabedateien aufsummiert.
# Zusätzlich werden dann die Variablen aufsummiert, so dass Min, Max, Count, Sum und
# Average über die Variablen ausgegeben werden kann.
# <CONSFMT>:
#            <n>/<m>[s|m|h]<SFLEN>: <n> 0-59
#              <m> Anzahl s|m|h
#              s|m|h Sekunden, Minuten, Stunden, def. ist m
#              <SFLEN> Zeitstempelflag: S: Start, F: First, L: Last, E: End, N: Now, def. ist E
# Bedeutung: Beginnend mit <n> wird alle <m> s|m|h eine Zeile ausgegeben.
# Beispiele:

consoliate = 0/5m         -> alle 5 Minuten eine Zeile
consolidate = 3/10s       -> alle 10 Sekunden (3, 13, 23, 33, 43, 53) eine Zeile
#
# <CONSFMT2>:
# <m><smh><FLN>: <smh> für Sekunden, Minute, Stunden, <m> Anzahl
#                F|L|N first/last/now
# Bedeutung: Es wird auf pasende Zeilen gewartet, dann wird alle
# <m> Sekunden/Minuten/Stunden ein konsolidierter Wert         
# ausgegeben. Der Zeitstempel des Wertes ist der der ersten
# Zeile bei <FL> = F und der der letzten Zeile bei <FL> = L    
#   wenn consolidate gesetzt, dann wird Zeile erst nach Ablauf der Sekunden
#   ausgegeben oder bei SIGHUP|SIGUSR1
#
consolidatenull = 1      # Zeile auch ausgeben, wenn keine Zeilen konsolidiert wurden.
consolidatedistinct = 1  # Es werden nur unterschiedliche Zeilen betrachtet. Z. B. unterschiedliche User zählen.
consolidatedistinctinit = 100000  # distinct lines Vorbelegung, wenn größer als 10000.


nread       = n Folgezeilen zusätzlich lesen
nreadreg    = Folgezeilen, die Reg-EXP entsprechen lesen
nread!reg   = Folgezeilen, die Reg-EXP nicht entsprechen lesen
nreadtoreg  = Folgezeilen lesen, bis Reg-EXP gefunden
              nreadtoreg liest die gefundene Zeile ein, nread!reg nicht
nreadformat = Inputformat der Folgezeilen
nreadaction = Auszuführende Aktion der Folgenzeilen
nreadwrite  = Ausgabemuster der Folgezeilen für Ausgabedatei

test        = <Bedingung>    # Die Ausgabeaktion wird nur ausgeführt, wenn die <Bedingung> wahr ist (!= 0)
                             # Die Bedingung kann sich auch auf konsolidierte Variablen beziehen.
                             # Ops: + - * / ~ % < > <= >= = !=
                             # genutzt werden kann %0-%9, %N,
                             # %{<n>,SUM}, %{<n>,AVG}, %{<n>,MIN}, %{<n>,MAX}, %{<n>,FIRST}, %{<n>,LAST}, %{<n>,DIST}
                             # %{TIMERANGE}, %{TIMEDIFF}

action      = auszuführende Aktion
write       = Ausgabemuster für Ausgabedatei. Wenn mehrere Zeilen geschrieben werden sollen, ist '\n' der Zeilentrenner.
              Oder durch einschließen der write Zeile in '...' können auch mehrere Zeilen ausgegeben werden:
write  = 'V;%F %T;%h;Section;Teststep;%p;%q - %1;_
V;%F %T;%h;Section;Teststep;%p-Anzahl;%N;#
V;%F %T;%h;Section;Teststep;%p-Kennung;"%1";_'

syslog      = an Syslog senden, Format: <priority>, <Ausgabe>
                <priority>: LOG_DEBUG|LOG_INFO|LOG_NOTICE|LOG_WARNING|LOG_ERR|LOG_CRIT|LOG_ALERT|LOG_EMERG
store       = Ausgabeformat beim Schreiben in Temp-Datei (unter storepath)
writetopath = Pfad festlegen für "writeto"
writeto     = Ausgabemuster für Datei, die mit writetopath festgelegt wird.
exit        = <exitcode>           # lfa4uls beenden mit Exitcode <exitcode> (Der <exitcode> kann auch eine Variable z. B. %3 sein)


storesecs    = <seconds> - Sekunden, nach denen zwischengespeicherte Zeilen (store) gesendet werden
storesendreg = <regexp>  - oder Regular-Expression, bei der die zwischengespeicherten Zeilen gesendet werden
storesendaction = <cmd>  - Befehl zum Senden der gespeicherten Daten

cancelreg    = <regexp>  - Regular-Expression, bei der zwischengespeicherte Zeilen gelöscht werden und
                           konsolidierte Zeilen zurückgesetzt werden

# ----- Einschränkung der reg für verschiedene Logdateien -----
#
# Die anzuwendenden reg können pro "inputfile" bzw. "inputfilepattern" eingeschränkt werden.
# Dazu wird vor den entsprechenden "inputfile" und "inputfilepattern" Zeilen der Gültigkeitsbereich definiert:
#
# setregrange = <start> - <end>    # Geht übersichtlicher durch die Bildung von Blöcken.
#
# für die nun folgenden "input*" Zeilen gelten nur die reg<start> - reg<end>
#
# Sollte nicht mehr verwendet werden, denn das kann durch entsprechende Blöcke übersichtlicher abgebildet werden:

inputfile = file1
reg =
write =

reg = 
write = 

# durch Angabe eines neuen "inputfile*" wird ein neuer Block begonnen. Die vorherigen reg gelten nur für file1 und die folgenden nur für file2.
inputfile = file2
reg =
write =

reg = 
write =


# ----- SYSLOG -----
# festlegen der Syslog Parameter
syslogpars = <syslog-ident>, <syslog-facility>           # Siehe "man openlog"


# ----- LOG -----
#
# Regulären Ausdruck und Aktion für "Logging"
# ACHTUNG: lreg_all, lreg, laction und lwrite werden in einer der nächsten Versionen nicht mehr zur Verfügung stehen.
# Die Kombination aus lreg_all = 1 und lwrite kann durch regall und write abgelöst werden.

lreg_all    = 1
# lreg        = log
# lreg_file   =
laction     = echo 'Info: %z'
# lwrite    =

# alle [nread][!]reg[_file][+], iformat, nreadformat
# und lreg[_file]
# konnen durch anfügen eines '|' ans '=' auf "ignore case" geschaltet werden.

# ----- STAT -----
#
# Ausgabe statistischer Daten nach Zeit für alle Dateien
ssched  = <SCHEDFORMAT>
swrite  = 
saction = 
# <SCHEDFORMAT>: <n>/<m>[s|m|h]<se>
#                <n>: Startzeitpunkt
#                <m>: Intervall in Einheite s/m/h, def. ist m
#                <se>: Zeitstempelflag: S: Start, E: End, def. ist E
# Bedeutung: Beginnend mit <n> wird alle <m> s|m|h eine Zeile ausgegeben. Siehe auch <CONSFMT>
#            Bei mehreren überwachten Dateien wird swrite und saction pro Datei ausgeführt,
#            so dass zur Unterscheidung %p oder %P im Text enthalten sein sollte.
#
# Ausgabe statistischer Daten für ausgewählte Dateien
isched  = <SCHEDFORMAT>
iswrite  = 
isaction = 
# isched bezieht sich nicht auf alle Dateien, sondern nur auf die Dateien über dem isched und nach dem vorherigen isched bzw. dem Anfang.


# ----- SET -----
set <var> = <value>  # Die Variablen %0-%9, %h, %q mit Defaultwert vorbelegen


# ----- DIRECTORY -----
# Für die Directory-Funktionen wird I-Notify verwendet, das unter Windows nicht zur Verfügung steht.
# Da der Nutzen der Directory-Funktionen sehr beschränkt ist, kann es sein, dass die Funktionen in Zukunft entfallen.
#
# Zu überwachendes Verzeichnis (nicht zusammen mit inputfile oder inputfilepattern)
inputdir = /var/log

# inputdir_num_subdirs wenn auf größer 1 gesetzt, dann werden bis zu inputdir_num_subdirs Unterverzeichniss mit überwacht
inputdir_num_subdirs = 50

# inputdir_num_files: Anzahl gleichzeitig offener Dateien, die überwacht werden.
# std ist 300
inputdir_num_files = 100

# dirfilepattern legt die Dateien fest, die Zeilenweise ausgewertet werden. Hist und consolidate ist noch nicht möglich.
dirfilepattern = *.log

# dirfilepipepattern: Dateien, die nach dem schließen an Kommando gesendet werden
# dirfilepipecmd: Dateien werden an STDIN des CMDs gesendet.
#                 Es können Parameter mit Codes verwendet werden. Die Codes %p, %P und Datumswerte sind gesezt,
#                 die anderen Codes sind nur gesetzt, wenn die Datei auch bei dirfilepattern ausgewählt ist.
dirfilepipepattern = *.dat
dirfilepipecmd = send_compressed_file %p %P

# dirfileclosepattern  Das Schließen von Dateien überwachen
# dirfileclosecmd      CMD ausführen, Parameter siehe dirfilepipecmd
# dirfileclosewrite    angegebenen Text in Ausgabedatei schreiben, Codes wie bei dirfilepipecmd
dirfileclosepattern = *.info
dirfileclosecmd = echo "Datei %P wurde geschlossen"
dirfileclosewrite = V;%F %T;%h;LFA;Dirmon;Close;%P;_

# dirfilecreatepattern  Anlegen von Dateien monitoren
# dirfilecreatecmd
# dirfilecreatewrite

# dirfiledeletepattern  Löschen von Dateien monitoren
# dirfiledeletecmd
# dirfiledeletewrite

# dirfilemodifypattern  Ändern von Dateien monitoren
# dirfilemodifycmd
# dirfilemodifywrite

# dirfilemovedfrompattern  Wegmoven von Dateien monitoren
# dirfilemovedfromcmd
# dirfilemovedfromwrite

# dirfilemovedtopattern  Hinmoven von Dateien monitoren
#                       (Wird eine Datei umbenannt, gibt es ein movedfrom und ein movedto)
#                       (Wird eine Datei von einem Verzeichnis in ein anderes gemoved, dann
#                        werden movedfrom und movedto nur für überwachte Verzeichnisse generiert)
# dirfilemovedtocmd
# dirfilemovedtowrite

# dirfileopenpattern  Öffnen von Dateien monitoren
# dirfileopencmd
# dirfileopenwrite
</file>

=== Usage ===

This chapter describes the basic usage of the lfa4uls.
One log file is searched for lines containing matches to given pattern. 

Each new line is parsed, variables may be set to expressions.

This is a basic configuration file:

<file>

# ----- logfile -----
#
# file to search
inputfile = /var/log/sample.log

# ----- write quoting -----
#
writequoting = \"

# ----- line format -----
#
inputformat = %F %T.%s %V

# ----- filter -----
#
reg     =| error|warning

# ----- output -----
# write ULS file-format
write   = V;%F %T;%h;Sample;Logfileadapter;Log;"%V";_

</file>


Für jede neu hinzukommende Zeile werden folgende Aktionen durchgeführt:

  - passt die Zeile zum regulären Ausdruck von vreg, dann diese Zeile ignorieren => auf nächste Zeile warten
  - passt die Zeile zu einem regulären Ausdruck von reg[0]..reg[99] oder reg[0]+..reg[99]+, dann die Zeile parsen mit iformat[0..99] und entsprechende action, write oder sylog ausführen => wenn reg+, dann weiter vergleichen, sonst auf nächste Zeile warten
  - ist lreg_all = 1, dann laction ausführen => auf nächste Zeile warten
  - passt die Zeile zum regulären Ausdruck von lreg, dann die Zeile parsen mit inputformat und laction ausführen => auf nächste Zeile warten
  - wenn keine der obigen Bedingungen erfüllt sind, dann wird die Zeile ignoriert => auf nächste Zeile warten

Zu allen direkt eingetragenen regulären Ausdrücken reg[+] kann auch eine Datei reg_file[+] angegeben werden, 
die mehrere Zeilen mit jeweils einem regulären Ausdruck enthalten können.
Die regulären Ausdrücke werden bei der Anwendung von reg_file logisch ODER verknüpft. 
Es wird entweder reg oder reg_file verwendet, der letzte Eintrag in der Konfigurationsdatei entscheidet.

Mit dieser (logischen) Unterscheidung können verschiedene Aktionen für verschiedene reguläre Ausdrücke ausgeführt werden.


Über Signale kann das Verhalten eines laufenden lfa4uls beeinflusst werden:
  - SIGTERM - Alle bis jetzt consolidierten oder historifizierten Zeilen ausgeben und lfa4uls beenden.
  - SIGUSR1 - Alle bis jetzt consolidierten oder historifizierten Zeilen ausgeben.
  - SIGHUP  - Alle bis jetzt consolidierten oder historifizierten Zeilen ausgeben und Konfiguration neu einlesen.
  - SIGUSR2 - Alle offenen Dateien für 60 Sekunden schließen, damit z. B. das Dateisystem dismounted werden kann.


=== Examples ===

== Example1: knldiag.err of a MAX DB ==

Ein einfaches Beispiel zum Auswerten der knldiag.err Protokolldatei einer MAX DB Datenbank.

Auszug aus der "/var/log/knldiag.err":

<file - /var/log/knldiag.err>

2008-07-08 01:58:03 10953     11561 COMMUNIC Connected  T209 local 21792
2008-07-08 01:58:03 10953     11560 COMMUNIC Releasing  T209
2008-07-08 01:58:03 10953     12827 COMMUNIC wait for connection T209
+++++++++++++++++++++++++++++++++++++++ Kernel Exit ++++++++++++++++++++++++++++
2008-07-08 02:49:38     0     11987 dump_rte rtedump written to file 'rtedump'
2008-07-08 02:49:38     0 ERR 12005 DBCRASH  Kernel exited with core and exit status...
2008-07-08 02:49:38     0 ERR 12012 DBCRASH  No stack backtrace since signal handler...
2008-07-08 02:49:38     0 ERR 12009 DBCRASH  Kernel exited due to signal 11(SIGSEGV)
2008-07-08 02:49:38     0     12808 DBSTATE  Flushing knltrace pages
2008-07-08 02:49:39     0 WNG 11824 COMMUNIC Releasing  T206 kernel abort
2008-07-08 02:49:39     0 WNG 11824 COMMUNIC Releasing  T207 kernel abort
2008-07-08 02:49:39     0 WNG 11824 COMMUNIC Releasing  T212 kernel abort
...
</file>

Interessant sind die Zeilen mit "ERR", das sind fatale Fehler und sollen protokolliert werden. 
Dazu die passende Konfigurationsdatei:

<file - /tmp/lfa4uls_<srvname>.conf>

# inputfile = /var/log/knldiag.err

# %F = YYYY-MM-DD
# %T = hh:mm:ss
# %W = der ganze Rest
inputformat = %F %T %W

# Alle Zeilen, die ERR enthalten
reg = ERR

# Gebe die ganze Zeile auf stdout aus
action = echo %z

</file>

== Example2: Usage %{<n>,DIST} ==
<file - /etc/uls/lfa4uls_messages.conf>
...
# multipathd: checker failed nur senden, wenn innerhalb von 30 Sekunden kein
# multipathd:  reinstated kommt
reg+        = %t %h multipathd:|%t %h kernel: device-mapper: multipath:
iformat     = %t %h
regsplit    = multipathd: ((checker failed path ([0-9][^ ]*) in map .*)|(([0-9].*): reinstated))
splitvars   = %s %1 %2 %s %-2
consolidate = 30sF
test        = %{2,DIST} > 0
write       = V;%F %T;%h;System;Logfileadapter;Log;"multipathd: %{1,FIRST}";_;all
...
</file>

== Test Konfiguration ==

Starte den lfa4uls direkt in der Kommandozeile (nicht als Dämon), 
zeige die Aktionen nur an (-s), starte das Durchsuchen der Datei (<inputfile>) 
vom Beginn an(-a), mit der Konfigurationsdatei (-c /tmp/lfa4uls_<srvname>.conf)::

<code bash>

lfa4uls -S -A -c /tmp/lfa4uls_<srvname>.conf

</code>

Obiger Aufruf bietet sich an, um Konfigurationen zu testen. 
Die Ausgabe passend zu obiger /var/log/knldiag.err ist::

<file>

echo 2008-07-08 02:49:38     0 ERR 12005 DBCRASH  Kernel exited with core and exit...
echo 2008-07-08 02:49:38     0 ERR 12012 DBCRASH  No stack backtrace since signal...
echo 2008-07-08 02:49:38     0 ERR 12009 DBCRASH  Kernel exited due to signal 11(SIGS...

</file>

lfa4uls steht dann am Ende der Datei und wartet auf weitere Zeilen. Abbrechen mit Ctrl-C. 
Evtl -S (nicht am Ende der Datei auf weitere Zeilen warten) anstelle von -s.

Hat man die gewünschten Ergebnisse durch obige Tests erhalten, 
kann dies dann hinterlegt werden, sodass der lfa4uls als Dämon beim Booten des Rechners 
gleich mit gestartet wird. Dazu wird eine Konfigurationsdatei im Ordner /etc/uls/lfa4uls.d angelegt:

<code bash>
vi /etc/uls/lfa4uls.d/<srvname>.conf
...
LFA4ULSCONF=/tmp/lfa4uls_<srvname>.conf
</code>

:!: Keine Leerzeichen vor oder nach dem '='-Zeichen verwenden!
Es sind keine Leerzeichen in der Pfadangabe erlaubt!

Und den lfa4uls starten (Systeme mit systemd)::

<code bash>
systemctl enable lfa4uls@<srvname>
systemctl start lfa4uls@<srvname>
</code>

Bei Systemen ohne systemd::

<code bash>
/etc/init.d/lfa4uls restart <srvname>
</code>

In der Prozessstatusliste finden sich dann zwei Prozesse am Beispiel <srvname> = my:

<code bash>
ps -ef | fgrep lfa
...
root ... 00:00:00 /usr/local/bin/lfa4uls -D -c /etc/uls/lfa4uls_messages.conf
root ... 00:00:00 /usr/local/bin/lfa4uls -D -c /tmp/lfa4uls_my.conf
</code>
Universal Logging System

User Tools

Site Tools

Page Tools
