log: adding default loggers to all gr_blocks to make using them simpler.

log: improving logger configuration and default behavior. log: changed name from gr_log to gr_logger (felt it could be confuse with the math function log). docs: moved logging information out to its own page.
author: Tom Rondeau <trondeau@vt.edu> 2013-03-01 13:19:11 -0500
committer: Tom Rondeau <trondeau@vt.edu> 2013-03-03 17:23:38 -0500
commit: 4fd16922d4e7ae2e5fd9dd048a873cbef409a7ff (patch)
tree: ea35645ece07cf4ede44f47ad10e7b8a35213634 /docs/doxygen/other/logger.dox
parent: ce211603ff8821b50f7c9ebc3931498c6f2bd374 (diff)
1 files changed, 202 insertions, 0 deletions
diff --git a/docs/doxygen/other/logger.dox b/docs/doxygen/other/logger.dox
new file mode 100644
index 0000000000..f98a64657b
--- /dev/null
+++ b/docs/doxygen/other/logger.dox
@@ -0,0 +1,202 @@
+/*! \page page_logger Logging
+
+\section logging Logging
+
+GNU Radio has a logging interface to enable various levels of logging
+information to be printed to the console or a file. The logger derives
+from log4cxx (http://logging.apache.org/log4cxx) which is readily
+available in most Linux distributions. This is an optional dependency
+and GNU Radio will work without it.
+
+When configuring GNU Radio, the -DENABLE_GR_LOG=On|Off option to cmake
+will allow the user to toggle use of the logger on and off. The logger
+defaults to "on" and will use log4cxx if it is available. If log4cxx
+is not found, the default logging will output to standard output or
+standard error, depending on the level of the log message.
+
+Logging is useful for blocks to print out certain amounts of data at
+different levels. These levels are:
+
+    TRACE < DEBUG < INFO < WARN < ERROR < FATAL
+
+The order here determines the level of output. These levels are
+hierarchical in that specifying any level also includes any level
+above it. For example, when using the Debug level, all Debug and
+higher messages are logged and Trace is ignored.
+
+\subsection configfile Logging Configuration
+
+The logging configuration can be found in the gnuradio-core.conf file
+under the [LOG] section. This allows us fairly complete control over
+the logging facilities. The main configuration functions are to set up
+the level of the loggers and set the default output behavior of the
+loggers.
+
+There are two default loggers that all gr_block's have access to:
+d_logger and d_debug_logger. The first is a standard logger meant to
+output simple information about the block while it is running. The
+debug logger is meant for debugging purposes and is added to make it
+convenient to use a secondary logger that outputs to a different
+stream or file.
+
+The four main configure options are:
+
+<pre>
+  log_level = all
+  debug_level = all
+  log_file = stdout
+  debug_file = stderr
+</pre>
+
+This establishes the two loggers as having access to all levels of
+logging events (TRACE through FATAL). They are also configured not to
+use files but instead output to the console. The standard logger will
+output to standard out while the debug logger outputs to standard
+error.
+
+Changing these last two lines to another value will create files that
+are used to store the log messages. All messages are appended to the
+file.
+
+When using either standard error or standard out, the messages for the
+two different loggers will look like:
+
+<pre>
+  gr::log :\<level\>: \<block alias\> - \<message\>
+  gr::debug :\<level\>: \<block alias\> - \<message\>
+</pre>
+
+When using a file, the only difference in the format is that the
+message prefix of "gr::log" or "gr::debug" is not used. Instead, the
+time in milliseconds from the start of the program is inserted.
+
+Remember that a local "~/.gnuradio/config.conf" file can be used to
+override any parameter in the global file (see \ref prefs for more
+details).
+
+To use these loggers inside of a GNU Radio block, we use the protected
+data members of d_logger and d_debug_logger of gr_block and pass them
+to our pre-defined macros:
+
+\code
+  GR_LOG_<level>(<logger>, "<Message to print>");
+\endcode
+
+Where \<level\> is one of the levels as mentioned above, \<logger\> is
+either d_logger or d_debug_logger, and \<Message to print\> is the
+message we want to output. If we wanted to output an INFO level
+message to the standard logger and a WARN level message to the debug
+logger, it would look like this:
+
+\code
+  GR_LOG_INFO(d_logger, "Some info about the block");
+  GR_LOG_WARN(d_debug_logger, "Some warning about the block");
+\endcode
+
+When this is printed to wherever you are directing the output of the
+logger, it will look like:
+
+<pre>
+    gr::log :INFO: <block's alias> - Some info about the block
+    gr::debug :WARN: <block's alias> - Some warning about the block
+</pre>
+
+This provides us information about where the message came from, the
+level of the message, and the block that generated the message. We use
+the concept of the block's alias which by default (i.e., unless
+otherwise set by the user) includes the name of the block and a unique
+ID to distinguish it from other blocks of the same type.
+
+The various logging macros are defined in gr_logger.h. Here are some
+simple examples of using them:
+
+\code
+  GR_LOG_TRACE(LOG, "TRACE message");
+  GR_LOG_DEBUG(LOG, "DEBUG message");
+  GR_LOG_INFO(LOG, "INFO message");
+  GR_LOG_WARN(LOG, "WARNING message");
+  GR_LOG_ERROR(LOG, "ERROR message");
+  GR_FATAL(LOG, "FATAL message");
+  GR_ERRORIF(LOG, a>b, "CONDITIONAL ERROR message");
+  GR_ASSERT(LOG, a>b, "ASSERT error message");
+\endcode
+
+If the logger is not enabled, then these macros become nops and do
+nothing (and d_logger and d_debug_logger are NULL pointers). If
+logging is enabled but the log4cxx library is not found, then TRACE,
+DEBUG, and INFO levels go to stdout and the rest to stderr.
+
+
+\subsection adv_config Advanced Configuration Options
+
+If not using the simplified settings discussed above, where we can
+direct the logger messages to either a file or one of the standard
+outputs, we must use a more complicated configuration file. We do this
+by specifying the "log_config" option in the [LOG] section. The
+log4cxx documentation (found through
+http://logging.apache.org/log4cxx/) will provide more information on
+how configuration works and looks. Mostly, a default configuration
+script provided with GNU Radio can be used. After installation, the
+default configuration script is located at:
+
+<pre>
+    $prefix/etc/gnuradio/gr_log_default.xml
+</pre>
+
+For the following examples, we will assume that our local
+"~/.gnuradio/config.conf" looks like this:
+
+\code
+[LOG]
+log_config = /opt/gr/etc/gnuadio/gr_log_default.xml
+log_level = All
+debug_level = Off
+\endcode
+
+Inside of the XML default configuration file, we define the parameters
+for the two logger's, the standard logger the separate debug logger.
+
+If the levels of the two loggers are specified in our configuration
+file, as in the above example, these levels override any levels
+specified in the XML file. Here, we have turned on the standard logger
+(d_logger) to all levels and turned off the debug logger
+(d_debug_logger). So even if the debug logger is used in the code, it
+will not actually output any information. Conversely, any level of
+output passed to the standard logger will output because we have
+turned this value to "all."
+
+If both an XML configuration file is set and the "log_file" or
+"debug_file" options are set at the same time, both systems are
+actually used. So you can configure file access and the pattern
+through the XML file while also still outputting to stdout or stderr.
+
+
+\section advlog Advanced Usage
+
+The description above for using the logging facilities is specific to
+GNU Radio blocks. We have put the code necessary to access the
+debugger into the gr_block parent class to simplify access and make
+sure all blocks have the ability to quickly and easily use the logger.
+
+For non gr_block-based code, we have to get some information about the
+logger in order to properly access it. Each logger only exists once as
+a singleton in the system, but we need to get a pointer to the right
+logger and then set it up for our local use. The following code
+snippet shows how to do this to get access to the standard logger,
+which has a root of "gr_log." (access to the debug logger is similar
+except we would use "gr_log_debug." in the GR_LOG_GETLOGGER call):
+
+\code
+    gr_prefs *p = gr_prefs::singleton();
+    std::string log_file = p->get_string("LOG", "log_config", "");
+    std::string log_level = p->get_string("LOG", "log_level", "off");
+    GR_CONFIG_LOGGER(log_file);
+    GR_LOG_GETLOGGER(LOG, "gr_log." + "my_logger_name");
+    GR_LOG_SET_LEVEL(LOG, log_level);
+\endcode
+
+This creates a pointer called LOG (which is instantiated as a
+log4cxx:LoggerPtr in the macro) that we can now use locally as the
+input to our logging macros like 'GR_LOG_TRACE(LOG, "message")'.
+
+*/
author	Tom Rondeau <trondeau@vt.edu>	2013-03-01 13:19:11 -0500
committer	Tom Rondeau <trondeau@vt.edu>	2013-03-03 17:23:38 -0500
commit	4fd16922d4e7ae2e5fd9dd048a873cbef409a7ff (patch)
tree	ea35645ece07cf4ede44f47ad10e7b8a35213634 /docs/doxygen/other/logger.dox
parent	ce211603ff8821b50f7c9ebc3931498c6f2bd374 (diff)