The SER Getting Started Log System

The Getting Started Log System

Experience has shown that finding errors in a SERi configuration file can be tricky. Based on experience on supporting SER users on all levels on serusers and serdev, this log system has been developed to be of benefit to both beginners and experts (called 'Getting Started Log System' because it was in that effort it was created). The main idea is to create a coherent and simple way of logging in seri.cfg.  For example, the Getting Started feature package uses this standardized logging so that people with problems can submit logs that can easily be read by anyone familiar with how Getting Started uses logging.

Before you can understand the log system, you must understand logging in general in SER. Syslog (a Linux/Unix system service for central server logging) is used to log everything. Syslog uses so called "facilities" to categorize log messages and determine which files to log messages to. In addition, each message also has a level of importance, a priority (ex. DEBUG, INFO, NOTICE, etc), which each log line will normally show at the beginning of the line.  The file /etc/syslog.conf controls to which files various facilities and priorities are logged.

Default, SER logs to a standard facility that on most systems default ends up in /var/log/messages. The Getting Started feature package changes SER to log to the local0 facility (the facility to use is defined in common/local.m4). 

TIP! 
If you want to log all SER messages to a specific file, you can thus add this line to your /etc/syslog.conf:
local0.*          -/var/log/ser.log
You should also add ;local0.none to the line that defines logging to /var/log/messages.

The priorities are important in SER, because when you log ser.cfg using the log or xlog commands, you specify the priority to use for that message. Dependent on the debug log level that you have defined in ser.cfg (or started SER with, -D -D etc), log lines in your ser.cfg will be actually logged or not (the ser.cfg debug level is defined by DEBUG_LEVEL in common/local.m4). The tricky thing is that increasing this global debug level also increases the amount of logging you get from SER itself. So, if you follow the priority system for your ser.cfg logging, you can end up with a LOT of log messages...

The fix this, the log system we have built into this buildsystem is de-coupled from SER's internal log system, and this is what you need to know:

1. All your ser.cfg logging is done at ONE syslog level, which default is 2, also called NOTICE. This means that even if INCLUDE_GETTING_STARTED_LOGGING is defined, you can turn off all logging by setting DEBUG_LEVEL (in common/local.m4) to 1. 
2. You can log with three priorities using the Getting Started log system: low/NOTICE, medium/INFO, high/DEBUG
3. You log simple info with the commands: NOTICE(`text'), INFO(`text'), DEBUG(`text')
4. You log more advanced (using the xlog module, so see xlog documentation for codes to use in the text you log) using: XNOTICE(`text'), XINFO(`text'), XDEBUG(`text')
5. You can scatter logging all over your log files and then control logging in two ways: statically (by actually preventing logging from going into the ser.cfg you generate) and dynamically (by turning on and off logging on a live SER server without restarting it)

Below is how logging is controlled. If the macro is NOT defined:

Some comments on using the log system:

• You can always include logging in your configuration files, even production configs, as you can quickly remove all logging code if you want by changing the INCLUDE_* macros.
• Each log message is found within an if-test that checks the global flag. This test is very efficient, so you can safely leave logging code in your configuration file and just turn off logging using the global flags.
• If you have a problem on a production server where you due to very high scalability requirements have undefined logging code, you can quickly generate a new ser.cfg that includes the code by changing the INCLUDE_* macros.
• If you are used to using the debug level in SER/syslog, you can configure Which priorities are actually used for NOTICE, INFO, and DEBUG in common/local.m4.