Skip to end of metadata
Go to start of metadata

In LoxBerry, you can use the integrated logging feature, currently available for Perl an Bash.

It enables a really easy way to create logfiles in Bash and Perl (and later PHP) and the logging features are geared to each other:

  • The initialization and logging commands are equal (or, as equal as possible in every language)
  • All logging features, in every language, create the same output format
  • All the logs from each language can be viewed in the integrated log viewer
  • The logfiles can be handed over from script to script, and even from language to language.

LoxBerry Log does not need to create logfiles. You can use LogBerry Log to print message to the default error log (syslog of Linux or cgierr log of Lighty).

The loglevel setting is integrated in LoxBerry. Your script logs entries in the desired loglevels, and LoxBerry will filter by the loglevel set by the user in the Plugin Management widget. Therefore, you don't need to create a logging switch or loglevel setting in your plugin.

Start easy logging

Inclusion

#!/bin/bash

. $LBHOMEDIR/libs/bashlib/loxberry_log.sh

Initialize the log

Start the log by executing STARTLOG.

You have to set the PACKAGE to the folder name of your plugin. To get your folder name, use on of there options: Wie findet man das eigene Installationsverzeichnis heraus? (LoxBerry V1.x)

PACKAGE=squeezelite
NAME=daemon
FILENAME=${LBPLOG}/${PACKAGE}/daemon.log
APPEND=1

LOGSTART "Squeezelite daemon started."

It is important to send the pluginfolder name with the PACKAGE parameter.

As you can see, no special loglevel was set. Using your plugin name from PACKAGE, the logging feature queries the plugin database for the loglevel set by the user.

Use APPEND=1 if you do not want to overwrite an existing logfile.

The following logging functions will filter your messages by the loglevel set by the user.

Start logging 

Now you can log with the loglevel function corresponding to the severity of your log entry:

LOGDEB "This is a DEBUG message (severity 7)"
LOGINF "This is an INFO message (severity 6)"
LOGOK "This is an OK message (severity 5)"
LOGWARN "This is a WARNING message (severity 4)"
LOGERR "This is an ERROR message (severity 3)"
LOGCRIT "This is a CRITICAL message (severity 2)"
LOGALERT "This is a ALERT message (severity 1)"
LOGEMERGE "This is a EMERGENCY message (severity 0)"

For normal logging, use LOGINF, LOGOK, LOGWARN and LOGERR. For debugging use LOGDEB.

Use LOGCRIT if your script has to terminate early because of an unrecoverable error. In this case, logging automatically switches to loglevel 6 ("Auto-Raise"), and you can add further log messages with e.g. LOGINF that appear in the logfile.

Currently do not use the severities 0 and 1 (LOGALERT and LOGEMERGE) because they may be used for email alerting in future versions.

Finish the log

For ending the log note LOGEND

LOGEND "Processing successfully finished"

Appending other output to the logfile

Simply pipe the output to the file:

echo "Hello" >> ${FILENAME}

This output does not get any severity level tags and automatically is detected as LOGINF from the log viewer.

Advanced features

Logfile and STDERR

In some situations you want logging appear on the screen and in the logfile.

Using the variable STDERR=1 before the LOGSTART event to write the log and show the messages:

PACKAGE=squeezelite
NAME=daemon
FILENAME=${LBPLOG}/${PACKAGE}/daemon.log
STDERR=1
LOGSTART "Squeezelite daemon started."

Messages are automatically sent to STDERR instead (and would therefore appear on the screen).

No logfile, only STDOUT

In some situations you don't need a logfile, but only want your log messages sent to STDOUT.

Using the variable NOFILE=1 before the LOGSTART event, you can disable your logfile at all:

PACKAGE=squeezelite
NAME=daemon
NOFILE=1

LOGSTART "Squeezelite daemon started."

Messages are automatically sent to STDOUT instead.

If you set STDERR=1, the messages will additionally be sent to STDERR.

Automatically create a new logfile everytime 

PACKAGE=squeezelite
NAME=daemon
LOGDIR=${LBPLOG}/${PACKAGE}

LOGSTART "Squeezelite daemon started."


echo "Logfile used is ${FILENAME}."

Used as plugin log, you can simply set the PACKAGE and NAME and LoxBerry Logging will always create a new logfile with a timestamp in your plugin log directory.

After the LOGSTART event, the current filename is set in the FILENAME variable, to use it for piping other output.

Multiple logfiles

If you want to have more than one log, no problem. You have to simply set your new variables an start the other log by executing LOGSTART. To select the log you have to set the variabel ACTIVELOG. every LOGSTART increases the number by 1. Use ACTIVELOG=2 for the second log.

LOGDEB "Loglevel: $LOGLEVEL"
LOGDEB "Logfile: $FILENAME"
FILENAME=${LBSTMPFSLOG}/test2.log
LOGLEVEL=3
NOFILE=1
LOGSTART "Log2 gestartet"
ACTIVELOG=2
LOGDEB "Loglevel: $LOGLEVEL"
LOGDEB "Logfile: $FILENAME"
LOGEND "Ich habe 2 fertig"
ACTIVELOG=1
LOGINF "Dies ist eine Info Meldung"
LOGOK "Dies ist eine OK Meldung"
LOGWARN "Dies ist eine Warn Meldung"

Logging levels

See the description of the log levels here: Perl-Modul LoxBerry::Log

All parameters you can set 

For starting the log you can set variables to change the behavoiur of logging. This is the full table of settings. Some settings are mutually exclusive and cannot be set together with other settings.

VariableDefault
Usage
PACKAGE-MandatoryThe name of the package is your plugin folders name (e.g. "squeezelite"). Use the replacement variable REPLACELBPPLUGINDIR if you are unsure.
NAME-MandatoryThe name of the specific log. You can have multiple logs in your plugin, that use different names.
FILENAME-Optional/RecommendedThe complete path of your logfile. If you want a fixed logfile name, set the FILENAME variable to the full path of your logfile.
LOGDIR-OptionalIf no FILENAME is given, the logfile will be created in the path set in LOGDIR. A new log will be created every time with a timestamp.
APPEND=10Optional/RecommendedAppend the log to an existing logfile. Used together with FILENAME, the logfile is not overwritten, but the new log messages appended to the existing log.
NOFILE=10OptionalNo logfile will be created, the output goes to STDOUT. This is useful if you don't need a logfile at all. Everything is written to the console.
STDERR=10OptionalSend the output (also) to STDERR.
ADDTIME=10OptionalAdd timestamp to your log entries. Usualley, only the start and end time are collected in the log. With ADDTIME=1, for every log entry a timestamp is created.
LOGLEVEL=(0-7)User settingOptional

You DO NOT NEED to set a loglevel, as the loglevel is read from the user setting in the plugin management.

You shouldn't set this, but you can override the loglevel set by the user.

Usage of the logging module

Usage of the notification functions


  • No labels