Versionen im Vergleich

Schlüssel

  • Diese Zeile wurde hinzugefügt.
  • Diese Zeile wurde entfernt.
  • Formatierung wurde geändert.
Kommentar: dbkey parameter and function

...

ParameterOptionalDefaultFunction
name

This is the "logical" name (better think of a group) of your logfile. This is not the filename. You may use a name like "webinterface" and "daemon" to group multiple logfiles of your plugin.

The name is optional only if you use the nofile parameter (to not write any logfile)

packagex$lbpplugindirThe package defines, where this log belongs to. In a plugin, the log always belongs to the plugin, therefore the $lbpplugindir variable is used automatically. For Core developers, or if LoxBerry cannot determine your plugin directory, the constructor will fail with an error "A package must be defined."
logdirx$lbplogdir

The logdir parameter defines, in which directory the logfile should be created. In a plugin, the directory is defaulted to the plugin log directory $lbplogdir.

If the logdir parameter is used, the filename of the log is generated (see filename explanation).

The logdir and filename parameters aremutually exclusive: If the logdir parameter is used, the filename is automatically generated. If - otherwise - the filename parameter is used, the logdir parameter is completely ignored.

filenamex(generated)

The filename parameter defines the absolute path and filename to the logfile. It is not combined with the logdir parameter.

Without filename parameter, the filename is created out of <timestamp>_<package>_<name>.log, so every call of the constructor creates a new logfile.

With filename, the full file path needs to be specified. Use the filename parameter, if you want to have a fixed filename everytime.

The logdir and filename parameters aremutually exclusive: If the logdir parameter is used, the filename is automatically generated. If - otherwise - the filename parameter is used, the logdir parameter is completely ignored.

appendx0

0 → The logfile will be overwritten

1 → If the file already exists, the log will be appended

The append parameter only makes sense when using the filename parameter.

Where the logging should take place
stderrx01 → Enables to output to STDERR
stdoutx01 → Enables to output to STDOUT
nofilex0

0 → A logfile to disk is written

1 → Writing to disk is disabled, no filehandle is created or opened.

Every parameter stands for itself - they are not exclusive. Therefore, you can combine stderr => 1 and nofile =>1 to only get logging output to STDERR (this can be very handy during development). Or you can enable stderr => 1 together with stdout => 1. Or you can only set stderr => 1 to get a logfile and the output to STDERR.
Special parameters
loglevelxuser-defined

You should not set the loglevel in your code. LoxBerry::Log determines the loglevel from the plugin management userinterface, where every user can set the desired loglevel. LoxBerry::Log will automatically filter your log events by the user-defined loglevel.

LoxBerry-Core developers: As no systemwide loglevel is available, you need to set the loglevel.

autoraisex1Auto-Raise will automatically set the loglevel to 6 ("raise"), if any event of severity 2, 1 or 0 (LOGCRIT, LOGALERT, LOGEMERGE) is triggert. LOGCRIT should be used for events that are unrecoverable (your program has to terminate). If you send an LOGCRIT event and auto-raise raises the loglevel, you can send additional logging events with more information about the shutdown reason. After the LOGCRIT, every severity is logged except LOGDEB (except loglevel was already on 7 before).
addtimex01 → A timestamp is added to every logging line triggered by a logging event. This is useful for time measurement.
dbkeyx<none>This is a special parameter for handing over logging sessions from script to script. The caller will query the dbkey with $log→dbkey and send this to the second script. The second script uses the dbkey parameter in the constructor to recover the logging session. No other parameters are needed and are recovered from the initial session. Additional parameters like strerr => 1 will overwrite the saved settings. (available from LoxBerry V1.2.5)


Usage

Codeblock
languageperl
titleSimple logging
use LoxBerry::Log;
# Creates a logging object with the filename $lbplogdir/<timestamp>_$lbpplugindir_daemon.log (e.g. /opt/loxberry/log/plugins/kodi/20180417_104703_kodi_daemon.log)
my $log = LoxBerry::Log->new ( 
	name => 'daemon', 
);


# Creates a logging object using the fixed filename $lbplogdir/mylogfile.log, append to existing log
my $log = LoxBerry::Log->new ( 
		name => 'cronjob', 
		filename => "$lbplogdir/mylogfile.log",
		append => 1,
);


# After init of the log object, start to log
LOGSTART "Update by cron job"; 
LOGOK "Everything ok";
LOGEND "Finished";

...

ParameterReadableChangeableReturn valueFunction
filenamex
String with absolute filename

You can query the currently used filename, also if it was generated (so, if you haven't used the filename parameter, but the logdir parameter).

If you need the filename to pipe other log output to the file, you should use the close function.

filehandlex
<filehandle>Returns the used filehandle to access the file. This can be used, if your function directly can write to the handle. Never close this filehandle by yourself.
closex
String with absolute filename

This will close the filehandle and return the current filename. Use this function before you pipe "foreign" output from other commands to the logfile.

It is required to close the filehandle before some other tool writes to the file, because the file is locked by LoxBerry::Log. Without closing the file, other commands may fail, or the writing is cached and written, when LoxBerry::Log closes the file after LOGEND.

After you have piped your output to the logfile, use the open method to re-open the filehandle.

openx

Re-opens the logfile after the filehandle was closed by close. No parameters are required.
defaultx

Sets the current log object to the default log. The shortcut functions (LOGDEB, LOGOK,...) use this log object.
Where the logging should take place
stderrxx0/1Enables or disables stderr output, or queries the current status.
stdoutxx0/1Enables or disables stdout output, or queries the current status.
nofilexx0/1

Disables or enables logfile output, or queries the current status.

Special parameters
loglevelxx0-7

Returns the currently set loglevel, and allows to change the current loglevel.

autoraisexx0/1Enable or disable Auto-Raise, and collect the current status.
addtimexx0/1Enables or disables writing a timestamp, or queries the current status.
dbkeyx
<int>Returns the unique number of this logging session for a handover to another script. The dbkey is initialized with the LOGSTART event. Before, the dbkey is undefined. (available from LoxBerry V1.2.5)
Writing to the logfile, e.g. $obj->OK("OK message") 

The writing functions exist both as method on the log object, and as shortcut function.

The method on the object is called with $log→WARN("text"). The shortcut function uses the default object and is directly called with LOGWARN("text").

LOGSTART
x
LOGSTART("Logfile title"); Submit a string for the title of the logfile, e.g. LOGSTART "Daemon was called". LoxBerry::Log automatically adds several information to the logfile, e.g. the current time, and a special header to signal a new logfile start in the logviewer. → Shortcut function is LOGSTART
LOGTITLExxTitle of the logAs LOGSTART defines the log title that is displayed in the loglist, you may change the title during runtime (e.g. because you have more specific information from a config file). The function does not write to the logfile.
LOGEND
x
LOGEND ("Final message"); Submit a string for the footer of the logfile, e.g. "LOGEND "Processing of daemon finished". LoxBerry::Log uses this information to know that your program did not terminate unexpected. If LOGEND is missing, LoxBerry::Log expects that your program died. → Shortcut function is LOGEND
DEB
x
Debug message (severity 7) → Shortcut function is LOGDEB
INF
x
Info message (severity 6)→ Shortcut function is LOGINF
OK
x
OK message (severity 5)→ Shortcut function is LOGOK
WARN
x
Warning message (severity 4)→ Shortcut function is LOGWARN
ERR
x
Error message (severity 3)→ Shortcut function is LOGERR
CRIT
x
Critical message (severity 2)→ Shortcut function is LOGCRIT
ALERT
x
Alter message (severity 1) - Currently you should not use this→ Shortcut function is LOGALERT
EMERGE
x
Emergency message (severity 0) - Currently you should not use this→ Shortcut function is LOGEMERGE

...