diff options
Diffstat (limited to 'docs/doxygen/other/logger.dox')
| -rw-r--r-- | docs/doxygen/other/logger.dox | 76 |
1 files changed, 50 insertions, 26 deletions
diff --git a/docs/doxygen/other/logger.dox b/docs/doxygen/other/logger.dox index f98a64657b..f5228cfc55 100644 --- a/docs/doxygen/other/logger.dox +++ b/docs/doxygen/other/logger.dox @@ -4,25 +4,29 @@ 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 +from log4cpp (http://log4cpp.sourceforge.net/) 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 +defaults to "on" and will use log4cpp if it is available. If log4cpp 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 +<pre> + DEBUG < INFO < WARN < TRACE < ERROR < ALERT < CRIT < FATAL < EMERG +</pre> + 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. +above it. For example, when using the INFO level, all INFO and +higher messages are logged and DEBUG is ignored. A level NOTSET is provided +to disable a logger. \subsection configfile Logging Configuration @@ -42,14 +46,14 @@ stream or file. The four main configure options are: <pre> - log_level = all - debug_level = all + log_level = debug + debug_level = debug 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 +logging events (DEBUG through EMERG). 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. @@ -111,20 +115,21 @@ 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_NOTICE(LOG, "NOTICE 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"); + GR_LOG_CRIT(LOG, "CRIT message"); + GR_LOG_ALERT(LOG, "ALERT message"); + GR_LOG_FATAL(LOG, "FATAL message"); + GR_LOG_EMERG(LOG, "EMERG 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. +logging is enabled but the log4cpp library is not found, then TRACE, +INFO, and NOTICE levels go to stdout and the rest to stderr. \subsection adv_config Advanced Configuration Options @@ -133,14 +138,13 @@ 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: +log4cpp documentation 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 + $prefix/etc/gnuradio/gr_log_default.conf </pre> For the following examples, we will assume that our local @@ -148,12 +152,12 @@ For the following examples, we will assume that our local \code [LOG] -log_config = /opt/gr/etc/gnuadio/gr_log_default.xml -log_level = All +log_config = /opt/gr/etc/gnuadio/gr_log_default.conf +log_level = debug debug_level = Off \endcode -Inside of the XML default configuration file, we define the parameters +Inside of the 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 @@ -163,7 +167,7 @@ specified in the XML file. Here, we have turned on the standard 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." +turned this value to the lowest level "debug." 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 @@ -196,7 +200,27 @@ except we would use "gr_log_debug." in the GR_LOG_GETLOGGER call): \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")'. +log4cpp:LoggerPtr in the macro) that we can now use locally as the +input to our logging macros like 'GR_LOG_INFO(LOG, "message")'. + +\section logPy Logging from Python + +The logging capability has been brought out python via swig. The configuration +of the logger can be manipulated via the following calls: +\code + from gnuradio import gr + gr.logger_config(filename,watch_period) # Configures the logger with conf file filename + names = gr.logger_get_logger_names() # Returns the names of all loggers + gr.logger_reset_config() # Resets logger config by removing all appenders +\endcode +Once the logger is configured you can manipulate a logger via a wrapper class gr.logger(). +You can isntantiate this by the following. (Reference gr_logger.h for list of methods) +\code + from gnuradio import gr + log=gr.logger("nameOfLogger") + log.debug("Log a debug message") + log.set_level("INFO"); + +\endcode */ |