/usr/share/doc/refdb/refdb-manual/ch05s06.html is in refdb-doc 1.0.2-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 | <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Logging data</title><link rel="stylesheet" type="text/css" href="manual.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="RefDB handbook" /><link rel="up" href="ch05.html" title="Chapter 5. refdbd administration" /><link rel="prev" href="ch05s05.html" title="Add, edit, or delete bibliography styles" /><link rel="next" href="ch05s07.html" title="Security issues" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Logging data</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch05s05.html">Prev</a> </td><th width="60%" align="center">Chapter 5. refdbd administration</th><td width="20%" align="right"> <a accesskey="n" href="ch05s07.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idp67007904"></a>Logging data</h2></div></div></div><p>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.</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idp67009248"></a>What to log</h3></div></div></div><p>The application server refdbd as well as all command-line clients can generate log messages. Message logging is most important for two purposes:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Keep track of non-interactive programs. This includes refdbd as well as all client-side tools if they are run from scripts.</p></li><li class="listitem"><p>Track down bugs or user errors.</p></li></ul></div><p>A useful approach is to log all messages with a log level (explained <a class="link" href="ch05s06.html#sect2-log-level" title="Log levels">below</a>) 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.</p><p>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.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idp67015344"></a>Destinations</h3></div></div></div><p>There are three possible destinations the log messages can be sent to. Select the proper destination with either the <code class="varname">logdest</code> variable in the configuration file or the <code class="option">-e</code> 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. <code class="option">-e 1</code> and <code class="option">-e syslog</code> are equivalent.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">0 (stderr)</span></dt><dd><p>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).</p></dd><dt><span class="term">1 (syslog)</span></dt><dd><p>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 <code class="filename">/var/log/user.log</code>. See the syslog(8) man page for information how to configure the syslog facility.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>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.</p></div></dd><dt><span class="term">2 (file)</span></dt><dd><p>You can define the full path of a custom log file with either the <code class="varname">logfile</code> configuration file parameter or the <code class="option">-L</code> command line option. By default, refdb applications write their log output to <code class="filename">/var/log/<appname>.log</code>. Make sure to set the appropriate access rights for these log files.</p></dd></dl></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>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 <code class="filename">/var/log/pgsql</code>.</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sect2-log-level"></a>Log levels</h3></div></div></div><p>You can select how verbose the log output of refdbd will be. You can do this by either setting the <code class="varname">loglevel</code> configuration file variable or the <code class="option">-l</code> 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. <code class="option">-l 5</code> and <code class="option">-l notice</code> 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 <code class="filename">syslog.h</code>:</p><div class="table"><a id="table-loglevel-definitions"></a><p class="title"><strong>Table 5.1. Log level definitions</strong></p><div class="table-contents"><table summary="Log level definitions" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>level</th><th>verbose</th><th>explanation</th></tr></thead><tbody><tr><td>0</td><td>emerg</td><td>system is unusable</td></tr><tr><td>1</td><td>alert</td><td>action must be taken immediately</td></tr><tr><td>2</td><td>crit</td><td>the system is in a critical condition</td></tr><tr><td>3</td><td>err</td><td>there is an error condition</td></tr><tr><td>4</td><td>warning</td><td>there is a warning condition</td></tr><tr><td>5</td><td>notice</td><td>a normal but significant condition</td></tr><tr><td>6</td><td>info</td><td>a purely informational message</td></tr><tr><td>7</td><td>debug</td><td>messages generated to debug the application</td></tr></tbody></table></div></div><br class="table-break" /><p>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.</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>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.</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idp67056064"></a>Interpreting the log information</h3></div></div></div><p>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.</p><p>A line in the custom log file looks like this:</p><pre class="programlisting">6:pid=267:Sun Jul 22 18:39:52 2001:application server started</pre><p>You will easily recognize the following fields:</p><pre class="programlisting">message_priority:process_id:time:message</pre><div class="variablelist"><dl class="variablelist"><dt><span class="term">message priority</span></dt><dd><p>This is the priority assigned to the message by refdbd. The values are explained <a class="link" href="ch05s06.html#table-loglevel-definitions" title="Table 5.1. Log level definitions">above</a>.</p></dd><dt><span class="term">process ID</span></dt><dd><p>This is the process ID (as seen in the <span class="command"><strong>ps ax</strong></span> 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.</p></dd><dt><span class="term">time</span></dt><dd><p>This is the full time and date information when the message was generated.</p></dd><dt><span class="term">message</span></dt><dd><p>This is the message text proper.</p></dd></dl></div><p>The message entries are sufficiently structured to allow easy access to the information with the standard Unix tools like <span class="application">awk</span> and <span class="application">grep</span>.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch05s05.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch05s07.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Add, edit, or delete bibliography styles </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Security issues</td></tr></table></div></body></html>
|