NAME
Config::Manager::Report - Error Reporting and Logging Module
SYNOPSIS
use Config::Manager::Report qw(:all);
$logobject = Config::Manager::Report->new([TOOL[,PATH[,FILE]]]);
$newlogobject = $logobject->new([TOOL[,PATH[,FILE]]]);
$default_logobject = Config::Manager::Report->singleton();
$logobject->report($CMD,$LEVEL,@text);
Config::Manager::Report->report($CMD,$LEVEL,@text);
Fuer ($CMD,$LEVEL) sollte stets eine der folgenden
(oeffentlichen) Konstanten verwendet werden:
@TRACE
@INFO
@WARN
@ERROR
@FATAL
Beispiel:
Config::Manager::Report->report(@ERROR,@text);
$logobject->trace();
Config::Manager::Report->trace();
$logfile = $logobject->logfile();
$logfile = Config::Manager::Report->logfile();
[ $oldlevel = ] $logobject->level([NEWLEVEL]);
[ $oldlevel = ] Config::Manager::Report->level([NEWLEVEL]);
[ $oldflag = ] $logobject->notify([NEWFLAG]);
[ $oldflag = ] Config::Manager::Report->notify([NEWFLAG]);
$lines = $logobject->ret_hold();
@text = $logobject->ret_hold();
$lines = Config::Manager::Report->ret_hold();
@text = Config::Manager::Report->ret_hold();
$logobject->clr_hold();
Config::Manager::Report->clr_hold();DESCRIPTION
Das Logging ist so realisiert, dass die Ausgabe der Meldungen auf den verschiedenen Ausgabekanaelen einzeln (unabhaengig voneinander) gesteuert werden kann. Es gibt die Ausgabekanaele STDOUT, STDERR, Logdatei und Halde.
STDOUT und STDERR sind die ueblichen Standard-Ausgabekanaele. Auf Wunsch koennen Meldungen aber auch in das Logfile geschrieben werden. Auf der Halde koennen Meldungen gekellert werden. Die Meldungen werden dann erst auf Anforderung auf dem Bildschirm ausgegeben.
Bei Verwendung der Funktion "ReportErrorAndExit()" aus dem Modul "Config::Manager::Base.pm" wird vor Beendigung des Programms die Halde auf STDERR ausgegeben, falls sie nicht leer ist.
Bei Verwendung der Standard-Konstanten @TRACE @INFO @WARN @ERROR @FATAL werden alle Meldungen immer auch in die Logdatei geschrieben, damit keine (moeglicherweise wichtige!) Information verlorengehen kann.
Das sollte man auch dann immer tun, wenn man diese Standard-Konstanten nicht verwendet.
private &_warn_($text,...)Dieser Signal-Handler gibt alle Warnungen weiter an das Modul "Config::Manager::Report.pm", indem er die Methode "report()" aufruft. Trailing Whitespace im Parameter wird eliminiert - es geht hier vor allem um moegliche Newlines am Zeilenende, die entfernt werden muessen.
Parameter: $text - Text der Warnungsmeldung ... - weitere Parameter, die Perl liefert Rueckgabe: -Durch diesen Handler wird sichergestellt, dass auch Warnungen in die Logdatei geschrieben werden, wo sie zur Aufklaerung von Fehlern nuetzlich sein koennen.
Dies ist in erster Linie fuer externe Module gedacht, die Warnungsmeldungen absetzen, und nicht fuer Tools der vorliegenden SPU. Letztere sollten statt "warn" immer die Methode "report()" mit dem Parameter "
@WARN" verwenden.Dieser Signal-Handler wird jedoch nur dann aktiviert, wenn das Singleton-Log-Objekt angelegt wird (dies geschieht durch alle Aufrufe von Objekt-Methoden, die statt
$objekt->methode();die FormConfig::Manager::Report->methode();verwenden).private &_die_($text,...)Dieser Signal-Handler gibt alle Ausnahmen weiter an das Modul "Config::Manager::Report.pm", indem er die Methode "report()" aufruft, vorausgesetzt das "die" trat nicht waehrend der Compilierung (beim Programmstart) auf. Trailing Whitespace im Parameter wird eliminiert - es geht hier vor allem um moegliche Newlines am Zeilenende, die entfernt werden muessen.
Parameter: $text - Text der Fehlermeldung ... - weitere Parameter, die Perl liefert Rueckgabe: -Durch diesen Handler wird ermoeglicht, dass man statt "ReportErrorAndExit()" theoretisch auch einfach nur "die" verwenden kann. Im Unterschied zu ersterem wird mit "die" aber die Halde nicht mit ausgegeben. Man sollte daher "die" lieber nicht benutzen. Dieses Feature ist vielmehr dafuer gedacht, dass auf diese Art und Weise auch "die"s in Modulen abgefangen werden, die nicht zur SPU gehoeren aber von dieser verwendet werden (Perl Standard-Module, externe Module wie Net::FTP, usw.), damit auch deren Fehlermeldungen in der Logdatei landen, wo sie bei der Fehlersuche hilfreich sein koennen.
Dieser Signal-Handler wird jedoch nur dann aktiviert, wenn das Singleton-Log-Objekt angelegt wird (dies geschieht durch alle Aufrufe von Objekt-Methoden, die statt
$objekt->methode();die FormConfig::Manager::Report->methode();verwenden).private &_adjust($pack,$file,$line,$sub,$hargs,$warray,$eval,$require)Diese Routine bereitet die Parameter auf, die von der System-Funktion "caller()" zurueckgeliefert werden.
Die Routine ist aus dem Standard-Modul "Carp.pm" "geklaut"; sie sorgt dafuer, dass im Stacktrace hinterher die "richtigen" Subroutine-Namen und -Parameter ausgegeben werden.
Parameter: $pack - Package-Name des Aufrufers $file - Dateiname des Aufrufers $line - Zeilennummer des Aufrufers $sub - Name der aufgerufenen Routine $hargs - wahr falls Aufrufparameter vorhanden $warray - wahr falls in List-Kontext aufgerufen $eval - wahr falls eval-Aufruf $require - wahr falls require-Aufruf Rueckgabe: $sub - aufbereiteter Name der aufgerufenen Routineprivate &_ShortTime()Rueckgabe: Die aktuelle Zeit im Format MMTT-HHMMSSprivate &_LongTime()Rueckgabe: Die aktuelle Zeit im Format TT.MM. HH:MM:SSprivate &_which($self)Parameter: $self - Referenz auf Log-Objekt oder Klassenname Rueckgabe: $self, falls $self eine Objekt-Referenz ist, oder eine Referenz auf das Singleton-Objekt sonstFalls der Aufrufparameter eine Referenz ist, wird diese unveraendert zurueckgegeben.
Falls der Aufrufparameter ein Skalar ist (z.B. durch den Aufruf als Klassenmethode), wird eine Referenz auf das Default-Log-Objekt (das sogenannte "Singleton"-Objekt) dieser Klasse zurueckgeliefert.
Falls das Singleton-Objekt noch nicht existiert, wird es durch den Aufruf dieser Routine erzeugt.
Man kann diese Routine uebrigens sowohl als Funktion als auch als Methode verwenden; der Aufruf als Funktion ist jedoch etwas schneller.
private $self->DESTROY([$close])In dieser Methode werden Aktionen definiert, die beim "Tod" eines Log-Objekts (typischerweise bei Beendigung des Programms, im Rahmen der Global Destruction) noch durchgefuehrt werden muessen. Dazu gehoeren:
- Auf (vorherige) Anforderung Ausgabe des Logfilenamens auf dem Bildschirm - Den Footer der Logdatei schreiben - Logdatei schliessen Parameter: $self - Referenz auf das zu zerstoerende Objekt $close - Optional; ein "true"-Wert, falls von "close()" aufgerufen Rueckgabe: Text der Fehlermeldung falls close(FILEHANDLE) nicht erfolgreich, Leerstring falls alles OKDiese Methode wird implizit von Perl aufgerufen und sollte nicht explizit aufgerufen werden.
Statt dessen sollte bei Bedarf die Methode "close()" verwendet werden (die ihrerseits "DESTROY()" aufruft).
reserved &end()Diese Routine setzt die Signal-Handler fuer "warn" und "die" wieder auf "DEFAULT" zurueck, die moeglicherweise (falls das Singleton-Log-Objekt benutzt wurde) auf die Routinen "&_warn_()" und "&_die_()" eingestellt waren.
Dies ist notwendig, um Endlos-Rekursionen im Zusammenhang mit "DESTROY()" zu vermeiden.
Ausserdem wird hier die Aufloesung aller Log-Objekte (d.h. der Aufruf von "DESTROY()" fuer alle diese Objekte) getriggert, d.h. die Log- Objekte werden geschlossen (zuvor wird noch ein Footer in die Datei geschrieben).
Ohne diese explizite Triggerung der Zerstoerung der Log-Objekte wuerde es zu Fehlern (Footer nicht geschrieben, Datei nicht ordnungsgemaess geschlossen) bei der Global Destruction kommen.
Die Zerstoerung aller Log-Objekte erfolgt in umgekehrter Reihenfolge ihrer Erzeugung.
Parameter: - Rueckgabe: -Diese Funktion wird implizit von Perl aufgerufen (durch die Funktion "END") und sollte im Normalfall nicht explizit verwendet werden.
reserved &abort()Diese Funktion bricht die Programmausfuehrung ab.
Zuvor wird die Funktion "&end()" aufgerufen, um die Signal-Handler fuer "die" und "warn" zurueckzusetzen und ggfs. alle Log-Dateien zu schliessen.
Anschliessend werden die als Parameter mitgegebenen Zeilen Text auf STDERR ausgegeben, gefolgt von der Zeile "<Program aborted>"; zuletzt wird dann die Ausfuehrung des Programms beendet.
Parameter: Beliebig viele Zeilen Fehlermeldung (oder keine) (MIT Newlines ("\n") wo gewuenscht!) Rueckgabe: -Der Exit-Code des Programms wird auf 1 gesetzt.
Diese Funktion sollte im Normalfall NICHT verwendet werden (statt dessen sollte die Funktion "ReportErrorAndExit()" aus dem Modul "Config::Manager::Base.pm" gerufen werden, die ihrerseits auf der "abort()"-Funktion beruht).
public Config::Manager::Report->singleton()Diese Methode gibt eine Referenz auf das Singleton-Objekt zurueck.
Das Singleton-Objekt ist die Default-Logdatei. Man ist als Benutzer des Report-Moduls jedoch nicht gezwungen, dieses Singleton-Objekt zu verwenden (es wird nur dann automatisch erzeugt, wenn man sich implizit darauf bezieht). Vielmehr kann man mit diesem Modul beliebig viele Log-Objekte (denen jeweils eine separate Logdatei und eine eigene Halde zugeordnet sind) erzeugen und benutzen.
Alle Methodenaufrufe der Form "
Config::Manager::Report->methode();" beziehen sich auf das Singleton-Objekt und legen es automatisch an, falls es noch nicht existiert (genauer gesagt alle Objekt-Methoden, in denen auf den Parameter "$self" nur ueber die Funktion "&_which()" zugegriffen wird).Parameter: - Rueckgabe: Gibt eine Referenz auf das Singleton-Objekt zurueck oder einen String mit einer Fehlermeldung, falls das Singleton-Objekt nicht erzeugt werden konnteFalls das Singleton-Objekt noch nicht existiert, wird es durch diesen Aufruf erzeugt.
"
Config::Manager::Report->methode();" ist dabei dasselbe wie "Config::Manager::Report->singleton()->methode();" oder wie "$Singleton = Config::Manager::Report->singleton();" und "$Singleton->methode();".Es sollte jedoch immer die erste dieser Formen ("
Config::Manager::Report->methode();") verwendet werden. Ausserdem darf der Rueckgabewert dieser Methode nicht dauerhaft im Programm gespeichert werden, da es sonst zu Fehlern kommen kann, wenn die Log-Datei inzwischen woanders geschlossen wurde.Es gibt im Grunde nur eine einzige sinnvolle Verwendung fuer diese Methode, naemlich, um die Erzeugung des Singleton-Objekts auszuloesen (wie das beispielsweise in "Config::Manager::Base.pm" geschieht).
public $class->new([$tool[,$path[,$file]]])Bei Aufruf - in der Regel bei Toolstart - wird das Logfile angelegt. Ist das Logverzeichnis nicht angegeben und das automatisch gewaehlte Logverzeichnis nicht vorhanden, so wird auch dieses angelegt (jedoch nur die letzte Ebene).
Danach wird der Header des Logfiles geschrieben. Dieser enthaelt z.B. Uhrzeit, Namen des Aufrufers und Kommandoaufruf samt Optionen.
Parameter: $class - Name der Klasse oder ein Objekt derselben Klasse $tool - Optional; wird kein Toolname uebergeben, so wird er in der Funktion ermittelt $path - Optional; wird kein Logpfad angegeben, so wird er aus der Konfiguration ausgelesen $file - Optional; wird kein Dateiname angegeben, wird automatisch einer vergeben Rueckgabe: Eine Referenz auf das neue erzeugte Objekt, falls das Oeffnen der Log-Datei und das Schreiben des Headers in diese Log-Datei geklappt hat, ansonsten (bei einem Fehler) ein String mit der entsprechenden FehlermeldungDiese Methode muss (d.h. darf) nicht explizit aufgerufen werden, falls man nur die Default-Logdatei ("Singleton-Log-Objekt") verwenden will (in diesem Fall ist statt dessen die Methode "singleton()" zu verwenden).
public $self->close()Diese Methode schliesst die Log-Datei, die zu dem angegebenen Objekt gehoert, und schreibt zuvor noch einen Footer (mit Datum, Uhrzeit sowie einer kleinen Ausgabestatistik) in die Datei.
Bei einem Fehler wird ein String mit der entsprechenden Fehlermeldung zurueckgeliefert, ansonsten der leere String.
Parameter: - Rueckgabe: Ein Leerstring bei Erfolg, ein String mit der entsprechenden Fehlermeldung bei einem FehlerDiese Methode kann auch fuer das Singleton-Objekt als Klassenmethode aufgerufen werden:
Config::Manager::Report->close();In diesem Fall wird das Singleton-Objekt geloescht, so dass ein erneuter Aufruf von Klassenmethoden aus dieser Klasse automatisch ein neues Singleton-Objekt erzeugt (und eine neue Log-Datei mit neuem Namen).
public $self->report($command[,$level[,@zeilen]])Die Funktion realisiert das bereits im allgemeinen Teil beschriebene Loggingkonzept. Meldungen werden auf Anforderung entsprechend eingerueckt.
Besonderheit: Der Stacktrace wird nie auf dem Bildschirm ausgegeben, sondern nur in das Logfile. Damit sind fuer den Benutzer die Fehlermeldungen uebersichtlicher. Parameter: $self - Referenz auf Log-Objekt oder Klassenname (Es wird das Singleton-Objekt verwendet, falls die Methode als Klassen- und nicht als Objekt-Methode aufgerufen wurde) $command - Angabe darueber, wohin die Meldung geleitet werden soll. Moegliche Werte: $TO_HLD $TO_OUT $TO_ERR $TO_LOG $FROM_HOLD $USE_LEADIN $STACKTRACE Diese Werte koennen beliebig durch Addition oder Bit-Or ("|") kombiniert werden. $level - Auf welcher Stufe ist die Meldung einzuordnen: $LEVEL_TRACE $LEVEL_INFO $LEVEL_WARN $LEVEL_ERROR $LEVEL_FATAL @zeilen - Beliebig viele weitere Parameter. Jeder wird als Textzeile fuer das Log interpretiert. Die Zeilen sollten nicht mit Newlines abgeschlossen werden, ausser man will (entsprechend viele) Leerzeilen nach der betreffenden Meldungszeile erzwingen. Rueckgabe: -Es ist moeglich, Newlines im Inneren der Meldungszeilen zu verwenden; dies sollte jedoch vermieden werden (Einrueckungen erfolgen dennoch auch bei Verwendung von eingebetteten Newlines "richtig").
Generell sollte jedes Element der Parameterliste eine Zeile der Meldung darstellen, und es sollten keinerlei Newlines verwendet werden, auch und insbesondere nicht am Zeilenende.
Mit Hilfe des Kommando-Bestandteils "$FROM_HOLD" lassen sich die Inhalte der Halde wiederum auf STDOUT, STDERR und/oder in die Logdatei ausgeben, z.B. wie folgt:
Config::Manager::Report->report($FROM_HOLD+$TO_ERR);Durch die Verwendung von "$FROM_HOLD" wird die Halde automatisch (nach ihrer Ausgabe) geloescht, ausser bei einem Kommando wie
Config::Manager::Report->report($FROM_HOLD+$TO_HLD);welches (da sinnlos) vollstaendig ignoriert wird.
Es ist auch moeglich, ein Kommando wie z.B.
Config::Manager::Report->report($FROM_HOLD+$TO_HLD+$TO_ERR);anzugeben, hier wird die Halde auf STDERR ausgegeben aber NICHT geloescht.
Die Methode zaehlt automatisch die Anzahl der Meldungen, die auf jedem Level ausgegeben wurden, mit - unabhaengig davon, auf welchem Kanal (STDOUT, STDERR, Halde oder Logdatei) diese Meldungen ausgegeben wurden.
Meldungen, die zuerst auf die Halde gelegt wurden und spaeter von dort aus (mit Hilfe des Kommando-Bestandteils "$FROM_HOLD") auf einem der anderen Kanaele ausgegeben werden, werden nicht noch einmal gezaehlt (das ginge auch schon allein deshalb nicht, weil der Level der Meldung zu diesem Zeitpunkt nicht mehr bekannt ist).
Diese kleine "Statistik" wird von der Methode "DESTROY()" mit in den Footer der Logdatei geschrieben.
public $self->trace()Diese Methode erlaubt es, Funktions- und Methodenaufrufe zu "tracen".
Parameter: $self - Referenz auf Log-Objekt oder Klassenname (Es wird das Singleton-Objekt verwendet, falls die Methode als Klassen- und nicht als Objekt-Methode aufgerufen wurde) Rueckgabe: -Indem man die Zeile
Config::Manager::Report->trace(); (unter Verwendung der Default-Logdatei) oder $objekt->trace(); (unter Verwendung der dem "$objekt" zugeordneten Logdatei)ganz an den Anfang einer Funktion (insbesondere VOR irgendwelche "shift"-Anweisungen, die sich auf die Aufrufparameter beziehen!) oder Methode setzt, wird automatisch ein Stacktrace, zusammen mit allen Aufrufparametern der aktuellen Funktion oder Methode, in die betreffende Logdatei geschrieben.
Setzt man den Ausgabe-"Level" (siehe dazu auch die Methode "
level()" direkt hierunter) vom Default-Wert ("$LEVEL_TRACE") auf den Wert "$LEVEL_INFO", werden alle Trace-Ausgaben effizient unterdrueckt, d.h. Trace-Informationen werden dann gar nicht erst erzeugt, sondern die Methode "trace()" kehrt sofort (nach einem "if") mit "return" zur aufrufenden Routine zurueck.public $self->level([$value])Gibt den bisherigen Level des Loggings zurueck. Kann auch dazu verwendet werden, diesen Level zu setzen, falls im Aufruf ein Wert angegeben wurde.
Moegliche Werte in diesem Zusammenhang sind:
$SHOW_ALL $LEVEL_TRACE $LEVEL_INFO $LEVEL_WARN $LEVEL_ERROR $LEVEL_FATALEs sollten stets nur diese vordefinierten Konstanten zum Setzen des Levels verwendet werden.
Das Setzen eines Levels groesser als Null (= Konstante "
$SHOW_ALL", bzw. "$LEVEL_TRACE", die Default-Einstellung) bewirkt, dass alle Meldungen mit einem Level kleiner als diesem Wert unterdrueckt werden (und insbesondere auch nicht in der Logdatei erscheinen).Parameter: $self - Referenz auf Log-Objekt oder Klassenname (Es wird das Singleton-Objekt verwendet, falls die Methode als Klassen- und nicht als Objekt-Methode aufgerufen wurde) $value - Optional der neue Wert Rueckgabe: Es wird immer der bisherige Wert zurueckgeliefert.public $self->logfile()Gibt den Namen und Pfad der Logdatei des betreffenden Log-Objekts zurueck.
Parameter: $self - Referenz auf Log-Objekt oder Klassenname (Es wird das Singleton-Objekt verwendet, falls die Methode als Klassen- und nicht als Objekt-Methode aufgerufen wurde) Rueckgabe: Gibt den Namen und Pfad der Logdatei zurueck.public $self->notify([$value])Gibt den bisherigen Wert des Flags zurueck, das angibt, ob bei Programmende der Name und Pfad der Logdatei auf dem Bildschirm ausgegeben werden soll. Kann auch dazu verwendet werden, dieses Flag zu setzen oder zu loeschen, falls im Aufruf ein Wert angegeben wurde.
Parameter: $self - Referenz auf Log-Objekt oder Klassenname (Es wird das Singleton-Objekt verwendet, falls die Methode als Klassen- und nicht als Objekt-Methode aufgerufen wurde) $value - Optional der neue Wert Rueckgabe: Es wird immer der bisherige Wert zurueckgeliefert.public $self->ret_hold()In List-Kontext:
Gibt die Halde des betreffenden Objekts (als Liste von Zeilen) zurueck (ohne sie zu veraendern).
In Scalar-Kontext:
Gibt die Anzahl der Zeilen zurueck, die sich auf Halde befinden.
Parameter: $self - Referenz auf Log-Objekt oder Klassenname (Es wird das Singleton-Objekt verwendet, falls die Methode als Klassen- und nicht als Objekt-Methode aufgerufen wurde) Rueckgabe: Liste der Zeilen der Halde (jedes Element der Liste ist eine Zeile der Halde) - oder - Anzahl der Zeilen auf der Haldepublic $self->clr_hold()Loescht die Halde des betreffeden Objekts.
Parameter: $self - Referenz auf Log-Objekt oder Klassenname (Es wird das Singleton-Objekt verwendet, falls die Methode als Klassen- und nicht als Objekt-Methode aufgerufen wurde) Rueckgabe: -
SEE ALSO
Config::Manager(3), Config::Manager::Base(3), Config::Manager::Conf(3), Config::Manager::File(3), Config::Manager::PUser(3), Config::Manager::SendMail(3), Config::Manager::User(3).
VERSION
This man page documents "Config::Manager::Report" version 1.4.
AUTHORS
Steffen Beyer <sb@engelschall.com>
http://www.engelschall.com/u/sb/download/
Gerhard AlbersCOPYRIGHT
Copyright (c) 2003 by Steffen Beyer & Gerhard Albers.
All rights reserved.LICENSE
This package is free software; you can use, modify and redistribute it under the same terms as Perl itself, i.e., under the terms of the "Artistic License" or the "GNU General Public License".
Please refer to the files "Artistic.txt" and "GNU_GPL.txt" in this distribution, respectively, for more details!
DISCLAIMER
This package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the "GNU General Public License" for more details.