The refdb programs can spill out quite a lot of log messages to keep track of what is happening in your programs. This section explains the basics of setting up your message logging.
The application server refdbd as well as all command-line clients can generate log messages. Message logging is most important for two purposes:
Keep track of non-interactive programs. This includes refdbd as well as refdbc, bib2ris, and nmed2ris if they are run as CGI applications. It may include all clients if they are run from scripts.
Track down bugs or user errors.
A useful approach is to log all messages with a log level (explained below) of 6. This would give you a good overview over the usage of these programs but would not clutter the log files with debug information. Switch to log level 7 only if you suspect a bug or some user error and need the full debug information to understand the problem.
For the interactive use of the clients logging is usually not necessary, so you'd use a log level of -1 to prevent logging altogether or a log level of maybe 3 or 4. In the latter case you'd get log messages only if something goes badly wrong. Again, if you encounter bugs or user errors you may switch on debug messages by using a log level of 7.
There are three possible destinations the log messages can be sent to. Select the proper destination with either the logdest variable in the configuration file or the -e switch on the command line. In both cases the values in the following list are accepted. You may use either the numerical value or the case-insensitive string in brackets, e.g. -e 1 and -e syslog are equivalent.
stderr is mostly useful for debugging purposes when refdbd is run as a standalone process and when clients are run interactively. stderr does not make much sense if you run refdbd as a daemon (daemons detach from the console at startup, so all output to stderr is lost).
Sending the data to syslog integrates the log data with the rest of your system's log output. The log messages will be sent to the user facility, which usually is configured to write to /var/log/user.log. See the syslog(8) man page for information how to configure the syslog facility.
Note: If you run refdbd on Cygwin, the syslog messages are sent to the application message list in the NT message logging system. If you are used to going through your log output with tools like grep and awk, you may find it more useful to write to a custom log file instead.
You can define the full path of a custom log file with either the logfile configuration file parameter or the -L command line option. By default, refdb applications write their log output to /var/log/<appname>.log. Make sure to set the appropriate access rights for these log files.
Note: Some libraries used by refdb, e.g. the PostgreSQL client library, send log messages to stderr. This is not controlled by the log settings of refdbd. The same PostgreSQL log messages show up in the PostgreSQL log which is usually sent to /var/log/pgsql.
You can select how verbose the log output of refdbd will be. You can do this by either setting the loglevel configuration file variable or the -l command line option to an appropriate value. You may either use the numerical value or the case-insensitive string as explained in the table below. E.g. -l 5 and -l notice are equivalent. Set the log level to -1 to disable logging completely. Use a value from 0 through 7 to generate increasingly verbose log output. The definitions of the log levels are taken from the include file syslog.h:
Table 5-1. Log level definitions
| level | verbose | explanation |
|---|---|---|
| 0 | emerg | system is unusable |
| 1 | alert | action must be taken immediately |
| 2 | crit | the system is in a critical condition |
| 3 | err | there is an error condition |
| 4 | warning | there is a warning condition |
| 5 | notice | a normal but significant condition |
| 6 | info | a purely informational message |
| 7 | debug | messages generated to debug the application |
Setting the log level to a given value means that all messages with a priority level up to the given value will be logged. E.g. if you set the log level to 6 (which is a reasonable default value), all messages with a priority from 0 through 6 will be logged, whereas messages with a priority level of 7 will be ignored.
| Warning |
Use log level 7 with caution. The amount of log messages is considerable and sufficient to slow down the application. You should not use this level in everyday use, only to track down bugs or user errors that you may encounter. |
If the messages are sent to stderr, only the message proper will be printed. If the messages are sent to the syslog facility, the default format including the process name and process ID is used.
A line in the custom log file looks like this:
6:pid=267:Sun Jul 22 18:39:52 2001:application server started |
You will easily recognize the following fields:
message_priority:process_id:time:message |
This is the priority assigned to the message by refdbd. The values are explained above.
This is the process ID (as seen in the ps ax listing) of the refdb process that generated the message. In the case of refdbd this may either be the parent process (the one that generated the above "application server started" message) or one of the children that are forked off to answer client requests.
This is the full time and date information when the message was generated.
This is the message text proper.
The message entries are sufficiently structured to allow easy access to the information with the standard Unix tools like awk and grep.