--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/logging.txt Thu Apr 21 14:57:45 2011 +0100
@@ -0,0 +1,96 @@
+DTN Logging
+===========
+
+The logging in DTN is organized into hierarchical paths. A partially
+complete list of the targets is below. In the .dtndebug file, specific
+targets can be enabled at the various logging levels. In addition,
+classes that inherit from the oasys::Logger base class also pass the
+class name to the log system, allowing logging to be enabled for the
+specific class as well as the hierarchical section.
+
+The basic idea is that a logf command contains an arbitrary log path,
+a level, and a printf-style body. For example:
+
+logf("/some/path", LOG_INFO, "something happened %d times", count);
+
+Each application should at intialization call Log::init(level) to
+prime the default level. All log messages with a level equal or higher
+than the default are output, others aren't.
+
+The code also checks for a ~/.dtndebug file which can optionally
+contain log paths and other levels. For example:
+
+# my ~/.dtndebug file
+% brief color
+/some/path debug
+/other info
+/other/more/specific debug
+
+The paths are interpreted to include everything below them, thus in
+the example above, all messages to /some/path/... would be output at
+level debug.
+
+In addition to the basic logf interface, there are also a set of
+macros (log_debug(), log_info(), log_notice(), log_warn(), log_err(),
+log_crit()) that are more efficient.
+
+For example, log_debug expands to
+
+#define log_debug(path, ...) \
+ if (log_enabled(LOG_DEBUG, path)) { \
+ logf(LOG_DEBUG, path, ## __VA_ARGS__); \
+ } \
+
+In this way, the check for whether or not the path is enabled at level
+debug occurs before the call to logf(). As such, the formatting of the
+log string, including any inline calls in the arg list are avoided
+unless the log line will actually be output. Under non-debug builds,
+all calls to log_debug are completely compiled out.
+
+.dtndebug file options
+======================
+
+There are several options that can be used to customize the display
+of debug output, and these options are specified on a line in the
+.debug file prefixed with '%' (see example above):
+
+no_path - Don't display log path
+no_time - Don't display time stamp
+no_level - Don't display log level
+brief - Truncate log name to a fixed length and use brief error codes
+color - Use terminal escape code to colorize output
+object - When possible, display the address of the object that
+ generated the log.
+classname - When possible, display the class that generated the log message.
+See comments in oasys/debug/{Log,Logger}.h for a more in-depth
+explanation.
+
+Logging Targets
+===============
+
+/command Singleton tcl command interpreter
+/command/<command_name> Specific command "command_name"
+/log Internal logging system
+/timer Timer system
+/thread Threading system
+
+/dtnd DTN daemon wrapper
+/dtn/bundle/actions BundleActions interface
+/dtn/bundle/daemon BundleDaemon forwarder and basic logic
+/dtn/bundle/fragmentation Fragmentation related code
+/dtn/bundle/list/<name> BundleList data structure
+/dtn/bundle/protocol Bundle wire protocol
+/dtn/bundle/refs Reference counting for in-memory bundle objs
+/dtn/cl/<name> Convergence layer
+/dtn/cl/tcp/conn TCP convergence layer connection
+/dtn/contact/manager Contact Managment
+/dtn/interface/table Local Interface table
+/dtn/link/<name> Links to next-hop peers
+/dtn/link/<name>/contact Open contact on links
+/dtn/route/<name> BundleRouter <name>
+/dtn/registration/<regid> Registration
+/dtn/registration/table Table of registrations
+/dtn/storage/bundles Storage backend for bundles
+/dtn/storage/global Storage backend for global data
+/dtn/storage/registration Storage backend for registrations
+