diff options
| author | Tom Rondeau <trondeau@vt.edu> | 2013-03-03 17:39:55 -0500 |
|---|---|---|
| committer | Tom Rondeau <trondeau@vt.edu> | 2013-03-03 17:39:55 -0500 |
| commit | dea9e149718cf900f509f79abbb4ace2c40d6ce5 (patch) | |
| tree | fab791d34bfe3117d1109a8e1dacf9b624f36c85 /docs/doxygen | |
| parent | 47e6a7a0cdd65136735b2ae89fe86990431d230f (diff) | |
| parent | 5fe234f18360b4680a7b9fef1eb710cb7fe37a07 (diff) | |
Merge branch 'master' into next
Conflicts:
gnuradio-core/CMakeLists.txt
gnuradio-core/gnuradio-core.conf
gnuradio-core/src/lib/filter/gr_fir_sysconfig_x86.cc
gnuradio-core/src/lib/runtime/runtime.i
gr-atsc/src/lib/CMakeLists.txt
gr-audio/lib/CMakeLists.txt
gr-comedi/src/CMakeLists.txt
gr-digital/lib/CMakeLists.txt
gr-howto-write-a-block/CMakeLists.txt
gr-howto-write-a-block/lib/CMakeLists.txt
gr-noaa/lib/CMakeLists.txt
gr-qtgui/lib/CMakeLists.txt
gr-trellis/src/lib/CMakeLists.txt
gr-uhd/lib/CMakeLists.txt
gr-video-sdl/src/CMakeLists.txt
gr-vocoder/lib/CMakeLists.txt
gr-wavelet/lib/CMakeLists.txt
Diffstat (limited to 'docs/doxygen')
| -rw-r--r-- | docs/doxygen/other/extra_pages.dox | 2 | ||||
| -rw-r--r-- | docs/doxygen/other/logger.dox | 202 | ||||
| -rw-r--r-- | docs/doxygen/other/main_page.dox | 1 |
3 files changed, 205 insertions, 0 deletions
diff --git a/docs/doxygen/other/extra_pages.dox b/docs/doxygen/other/extra_pages.dox index d40c692e03..44cdf9d483 100644 --- a/docs/doxygen/other/extra_pages.dox +++ b/docs/doxygen/other/extra_pages.dox @@ -79,6 +79,8 @@ audio-osx and audio-windows to be either satisfied or built. \subsection dep_gr_comedi gr-comedi: Comedi hardware interface \li comedilib (>= 0.8) http://www.comedi.org/ +\subsection dep_gr_log gr-log: Logging Tools (Optional) +\li log4cxx (>= 0.10.0) http://logging.apache.org/log4cxx \section build_gr_cmake Building GNU Radio 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")'. + +*/ diff --git a/docs/doxygen/other/main_page.dox b/docs/doxygen/other/main_page.dox index 41aeba7e04..c7acac33dc 100644 --- a/docs/doxygen/other/main_page.dox +++ b/docs/doxygen/other/main_page.dox @@ -39,6 +39,7 @@ More details on packages in GNU Radio: \li \ref page_vocoder More details on GNU Radio concepts: +\li \ref page_logger \li \ref page_pmt \li \ref page_msg_passing \li \ref page_metadata |