Creates a log object to do LoxBerry-specific logging to a logfile or to the standard output (stderr, stdout). The LoxBerry logging module uses the user-defined loglevel from the plugin management, therefore no plugin-own setting and own loglevel-filtering is required.

This article is the specification of LoxBerry's log object-class. For starting examples, see the article Usage of the logging module.

The constructor of the log object takes several named parameters to adjust the logging behaviour. Some parameters are dependent to other parameters.

Info for LoxBerry-Core developers: Some parameters have fallback settings if used in a plugin, but are mandatory if used in widgets or other LoxBerry-Core components.

Named parameters are delivered in the form LoxBerry::Log::new( parameter ⇒ "value", parameter ⇒ "value", …). For numbers, the quotes are not required. Perl does not recognize Booleans (True, False), they need to be 1 or 0.

Simple 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";

After the log is initialized, you can access several properties from the log object (column "Readable"), and you also can change several properties ("Changeable"). 

Simple logging

use LoxBerry::Log;
# Creates a logging object
my $log = LoxBerry::Log->new ( 
    name => 'daemon', 
);
 
 
# Query the filename
my $filename = $log->filename;
 
 
# Query the current loglevel
my $loglevel = $log->loglevel;
 
 
# Set loglevel to 7
my $loglevel = $log->loglevel(7);
 
 
# Pipe text to the logfile during operation
my $filename = $log->close;
system("ls -l >> $filename");
$log->open;
 
# Change the logfile title during runtime
LOGTITLE "New logfile title";
$log->logtitle("Another new title");
print "Current title is " . $log->logtitle();
 
# Finish processing because of an unrecoverable error
if ($unrecoverable_error_occured) {
    LOGCRIT "Processing stopped because of an unrecoverable error";
    # Auto-Raise automatically switches to loglevel 6
    LOGERR "Occured error: $error";
    LOGINF "Current state is $state";
    # Finish the log
    LOGEND "Processing terminated";
    exit(1);
}

The LOGEND call should always be used to tell LoxBerry::Log and the logging database, that your logfile is finished.

The $message on LOGEND is optional. You can simply call LOGEND without parameter.

You can place LOGEND to an END block in your Perl script. The END is a "magic" block that is called from Perl on every script exit. In the END block, you can check if you already have called a LOGEND by simply checking the $log object: LOGEND unreferences your $log object.

END
{
    if ($log) {
        $log->LOGEND;
    }
}

The loglevel will be read from the plugin database once at the init of the log object, and then every minute, in the case you do not set the loglevel in the constructor or by $log→loglevel. 

If you don't set the loglevel in your code, it is taken from the loglevel setting the user has done in the Plugin Management (or in Log Manager, or in your plugin, if you offer the control). 

Available from LoxBerry V2.0

This feature is disabling the log sessions, and refrains from the logging headers and footers, and new log database entries for each file.

Notices:

• With nosession => 1, the filename => ... parameter is mandatory (the filename is the key)
• append => 1 is implicitely set.
• The first call will create one database entry (to view it in Log Manager). Every further call will update this database entry.
• The big headers and footers from LOGSTART and LOGEND will not be in the logfile.
• The LOGSTART and LOGEND requests are still required. The LOGSTART message will be inserted to the log as normal-formatted ok message. LOGEND will update the database state.
• If the logfile was deleted (e.g. by the logfile maintenance), the first lines in the log still are information about LoxBerry version, Plugin version and loglevel. They only appear once on the top.

Example:

Simple logging

use LoxBerry::Log;
$log = LoxBerry::Log->new (
        name => 'AJAX',
        filename => "$lbplogdir/ajax.log",
        stderr => 1,
        addtime => 1,
        nosession => 1,
    );
LOGSTART "ajax call: checksecpin";
LOGOK "Secure pin was ok";
LOGEND;

Example view in Log Manager and logfile:

Only a single line will exist in Log Manager, independent of the number of calls.

This is the logfile after two calls.