diff options
| author | Marc Lichtman <marcll@vt.edu> | 2018-11-02 00:53:52 -0400 |
|---|---|---|
| committer | Marc L <marcll@vt.edu> | 2019-06-07 12:45:14 -0400 |
| commit | 73b074f121b0ab2ac38336916a60891c4d88d2cb (patch) | |
| tree | de8f1782c897af3c278c224dcfbf96345c5c6f1d /docs/doxygen/other/logger.dox | |
| parent | b6f15c59e96aa83142c47aeacd64da793dd8ba31 (diff) | |
docs: moved usage manual to wiki
docs: first snapshot of wiki's usage manual
Diffstat (limited to 'docs/doxygen/other/logger.dox')
| -rw-r--r-- | docs/doxygen/other/logger.dox | 247 |
1 files changed, 0 insertions, 247 deletions
diff --git a/docs/doxygen/other/logger.dox b/docs/doxygen/other/logger.dox deleted file mode 100644 index 00387768c0..0000000000 --- a/docs/doxygen/other/logger.dox +++ /dev/null @@ -1,247 +0,0 @@ -# Copyright (C) 2017 Free Software Foundation, Inc. -# -# Permission is granted to copy, distribute and/or modify this document -# under the terms of the GNU Free Documentation License, Version 1.3 -# or any later version published by the Free Software Foundation; -# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -# A copy of the license is included in the section entitled "GNU -# Free Documentation License". - -/*! \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 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. - -Logging is useful for blocks to print out certain amounts of data at -different levels. These levels are: - -<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 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 - -The logging configuration can be found in the gnuradio-runtime.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 = 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 (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. - -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_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_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 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 - -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 -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.conf -</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.conf -log_level = debug -debug_level = Off -\endcode - -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 -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 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 -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 - prefs *p = 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 -log4cpp:LoggerPtr in the macro) that we can now use locally as the -input to our logging macros like 'GR_LOG_INFO(LOG, "message")'. - -\subsection using_logging Using Logging in Out of Tree Modules - -In order to use the logging interface in an out of tree module based on a -gr_modtool template module, several CMake modifications are required. -Without these changes, logging will be disabled. - -GrMiscUtils.cmake module must be included in the OOT module top level -CMakeLists.Texts file, and the GR_LOGGING() function provided by GrMiscUtils -must be called from the same top level CMakeLists.txt file. This will -set the appropriate build environment and during that process, attempt -to find the log4cpp package using the FindLog4Cpp.cmake module. -This module is not included in the module by gr_modtool, but is part of -the GNU Radio codebase and can be copied directly into the cmake/Modules/ -directory of the OOT module. - -Once these CMake changes are made, the GR logging interface will function -as documented on this page. - -\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_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 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 -*/ |