Logging is a set of functionality designed to quietly track the operation of a software program to be stored for later examination. It is generally used for debugging purposes.
For basic use of the log class, the only functions you need to worry about are
enable logging with log level
INFO, and use
log to write your own messages to the log file.
This usage is covered in the Log examples, available for the core languages.
Anatomy of a Log
To better understand the concepts in this guide, we will dissect a log entry to clarify its component parts.
Sources are a property of Phidgets Log messages that indicate where the log message originated. By default, the writing to the log using the
log function of your language will write to the source named phidget22.
For more advanced applications, some log functions will allow you to specify custom sources to allow for specialized logging implementations.
In addition to the default phidget22 source, there are a number of background log sources that are hidden by default. This is to keep log files relatively clean and allow focus on messages that matter to the application.
These sources are:
|_phidget22bridge||Internal Use Phidget Bridge Logs (Not the physical device)|
|_phidget22channel||Internal Use Channel Information Logs|
|_phidget22disp||Internal Use Phidget Dispatch Logs|
|_phidget22match||Internal Use Channel Matching Logs|
|phidget22netctl||Network Control Logs|
|phidget22usb||USB Processing Logs|
Log levels are designed to sort messages in terms of importance, with lower log levels being generally the most important, and higher log levels carrying supplemental information.
Log levels are arranged as follows:
|Lowest Level||CRITICAL||Indicates something very important that should always be logged.|
|ERROR||Describes errors that occur during a program's operation.|
|WARNING||Warnings about a program's behaviour.|
|INFO||Supplemental information about a program's status.|
|DEBUG||Extra information that is only useful for debugging purposes.|
|Highest Level||VERBOSE||More information than is useful for most applications except intensive debugging.|
Setting the log level will filter log entries to only allow messages of that level and below to be added to the log. For example, if the log level was INFO, then logs of level DEBUG and VERBOSE will be ignored, while all other logs would be stored.
Log levels can be independently set for all sources using the variant of
setSourceLevel for your language. This is useful for filtering out log messages from sources that would otherwise flood the log. It can also be used to show logs from sources that are hidden by default.
The time that the message was logged in local time, formatted as:
This is the message written to the log. It will contain the information intended to be logged.
Log rotation is the automated process of archiving the current log file and starting a new one once the log becomes too large. Rotating log files is a method of keeping file size down while still keeping track of all the latest log information.
Log rotation is enabled by default in Phidget22, and will keep two files: the current log file and the latest archived log file. The maximum size and number of archived log files can be adjusted using the
setRotating function in your language of choice.
Archived log files will have a timestamp of the time they were archived appended to the end of the log filename, as follows: