1 files changed, 112 insertions, 0 deletions
diff --git a/docs/doxygen/other/main_page.dox b/docs/doxygen/other/main_page.dox
index 8f69a97373..c5d5a44cb7 100644
--- a/docs/doxygen/other/main_page.dox
+++ b/docs/doxygen/other/main_page.dox
@@ -48,4 +48,116 @@ Many blocks have already been converted to use Volk in their calls, so
 they can also serve as examples. See the gr_complex_to_xxx.h file for
 examples of various blocks that make use of Volk.
 
+
+\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 and will
+turn off if log4cxx is not available.
+
+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. When using the Debug
+level, for instance, all Debug and higher messages are logged and
+Trace is ignored.
+
+\subsection use_logging Using the Logging Features
+
+In a GNU Radio block, you use the logging features by calling macros
+that are defined in gr_log.h, which must be included for use.
+
+The logger must be properly configured, which is easiest by defining a
+configuration file. The log4cxx website 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:
+
+    $prefix/etc/gnuradio/gr_log_default.xml
+
+However, we use the global GNU Radio configuration file to tell the
+system where this file is located. In the [LOG] section of the
+configuration file, the location of the logger's XML file can be
+specified. The default configuration file is found in:
+
+    $prefix/etc/gnuradio/conf.d/gnuradio-core.conf
+
+A local "~/.gnuradio/config.conf" file can be used to override any
+parameter in the global file.
+
+For the following examples, we will assume that our local
+"~/.gnuradio/config.conf" looks like this:
+
+\code
+[LOG]
+log_file = /opt/gr/etc/gnuadio/gr_log_default.xml
+log_level = All
+\endcode
+
+The startup and configuration process proceeds as follows.
+
+\code
+  std::string log_file = gr_prefs::singleton()->get_string("LOG", "log_config", "");
+  std::string log_level = gr_prefs::singleton()->get_string("LOG", "log_level", "off");
+  GR_CONFIG_LOGGER(log_file);
+  GR_LOG_GETLOGGER(LOG, <name>);
+  GR_LOG_SET_LEVEL(LOG, log_level);
+\endcode
+
+The default config file has two names that can be used (as std::string
+types): "gr_log" and "gr_log_debug". The first one will print
+all levels of logging informaiton while the second one will only print
+Debug and above.
+
+Names of loggers are global, so "gr_log" as a name will be the same
+logger no matter where it is picked from.
+
+The "LOG" name for the logger is now a LoggerPtr object and can be
+named anything.
+
+For a given block, it is recommended that a new name be specified for
+individual control over the logger as loggers are globally held in a
+LoggerManager. Since log4cxx is hierarchical, a new name is created by
+appending a string to an existing logger. So a general logger used in
+the digital_costas_loop_cc.cc class, for instance, could look
+something like "gr_log.costas_loop". This will inherit all properties
+of the parent logger, "gr_log".
+
+After calling "GR_LOG_GETLOGGER", the LoggerPtr that was specified,
+"LOG" in the example above, is used to set the properties. The main
+setting we are generally interested in is the level of the
+logger. This will determine if this logger gets outputted or not. In
+this case, we are actually getting the gr_log level from the GNU Radio
+configuration file, stored in log_level. The macro GR_LOG_SET_LEVEL
+can take either a string or a log4cxx::LevelPtr object. The log_level
+variable in this case holds a string read in from the config file, and
+it's case insensitive. I can be "off", "all", "trace", "debug",
+"info", "warn", "error", or "fatal" to match with the levels above.
+
+In our example here, all logging information is displayed because the
+config file specifies "All". We can then easily turn off all reporting
+by setting this value to "Off".
+
+The various logging macros are defined in gr_log.h. Here are some
+simple exmaples 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
+
 */