Zum Ende der Metadaten springen
Zum Anfang der Metadaten

$logobject = LBLog::newLog( @parameter_array );


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.

LoxBerry Compatibility

This feature is available starting with LoxBerry V1.2.1. Set this as minimum version in your plugin.cfg.

Constructor

This article is the specification of LoxBerry's log object-class.

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

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

Named parameters are delivered in the form LBLog::newLog ( [ "parameter" => "value", parameter => "value", ... ] ). Take note to the square brackets [ ] inside the round brackets ( ) that define the array. 


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" or "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 are mutually 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 are mutually 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 → An existing 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. LBLog determines the loglevel from the plugin management userinterface, where every user can set the desired loglevel. LBLog 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.

addtimex01 → A timestamp is added to every logging line triggered by a logging event. This is useful for time measurement.
dbkeyx
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 value 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

Simple logging
require_once "loxberry_log.php";


// Creates a log object, automatically assigned to your plugin, with the group name "PHPLog"
$log = LBLog::newLog( [ "name" => "PHPLog" ] );

// For better realability, you also can define the parameter array first, and use the array as parameter
// This parameters create a log object with name "Daemon" and the specific filename mylogfile.log. Log entries are appended to an existing log.
$params = [ 
	"name" => "Daemon", 
	"filename" => "$lbplogdir/mylogfile.log",
	"append" => 1
];
$log = LBLog::newLog ($params);

// After your log object is created, you start the logging with LOGSTART
// A start timestamp and other information is added automatically
LOGSTART("Daemon script started");

// Do the logging in your script


LOGINF("Processing query");
LOGOK("Query successfully processed");
LOGERR("Error on processing the query");
LOGCRIT("Unable to process, terminating");


// Close the log with an LOGEND event
// Use LOGEND for every quitting of you script (independent of successful or not). A logfile without LOGEND will be shown open and unexpectedly terminated.
LOGEND("Daemon stopped");


Object functions

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

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).

Where the logging should take place
stderrx
0/1Enables or disables stderr output, or queries the current status.
stdoutx
0/1Enables or disables stdout output, or queries the current status.
nofilex
0/1

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

Special parameters
loglevelx
0-7

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

addtimex
0/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("Log title"); Submit a string as the title of the logfile, e.g. LOGSTART "Daemon was called". LBLog 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 log

V1.2.5 and above Method is $obj->logtitle($title), shortcut is LOGTITLE($title).

As 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, but the title is shown in the loglist.

LOGEND
x
LOGEND ("Final message"); Submit a string for the footer of the logfile, e.g. "LOGEND "Processing of daemon finished". LBLog uses this information to know that your program did not terminate unexpected. If LOGEND is missing, LBLog 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

Usage

Simple logging
require_once "loxberry_log.php";

// Creates a log object, automatically assigned to your plugin, with the group name "PHPLog"
$log = LBLog::newLog( [ "name" => "PHPLog" ] );

// Query the filename
$filename = $log->filename;

// Query the current loglevel
$loglevel = $log->loglevel;

// Pipe text to the logfile during operation
$filename = $log->filename;
system("ls -l >> $filename");

// Change the title of the log (V1.2.5 and above)
$log->logtitle("New title");
LOGTITLE("Another new title");

// Finish processing because of an unrecoverable error
if ($unrecoverable_error_occured) {
	LOGCRIT("Processing stopped because of an unrecoverable error");
	LOGERR("Occured error: $error");
	LOGINF("Current state is $state");
	// Finish the log

	LOGEND("Processing terminated");
	exit(1);
}

LoxBerry-Core developers

The following, additional methods exist, for interface functionality e.g. for the Bash logging SDK, used by initlog.php. 

ParameterReadableChangeableReturn valueFunction
STATUSxx0-7

Returns the highest (in numbers: lowest) severity level logged yet.

This is managed by the object class itself and doesn't need to be modified. If the highest level needs to be managed outside of the class (Bash logging), the highest severity can be set by this method. (available from LoxBerry V1.2.5)

ATTENTIONMESSAGESxx<string>

Returns a string including all yet logged messages from severity WARN and higher. The string includes the logging tags (e.g. <ERROR>), multiple lines are separated by \n line-breaks.

This is managed by the object class itself and doesn't need to be modified.

If the messages are maintained outside of the class (Bash logging), the string can be set by this method. (available from LoxBerry V1.2.5)

  • Keine Stichwörter