oasys::Log Class Reference

#include <Log.h>

List of all members.


Detailed Description

Dynamic Log system implementation.

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. All output goes to stdout.

The code also checks for a ~/.debug file which can optionally contain log paths and other levels. For example:

 # my ~/.debug 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.

In addition, under non-debug builds, all calls to log_debug are completely compiled out.

.debug 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.

Definition at line 180 of file Log.h.

Public Member Functions

virtual void getlogtime (struct timeval *tv)
 Sets the time to print for the logging.
int vlogf (const char *path, log_level_t level, const char *classname, const void *obj, const char *fmt, va_list ap)
 Core logging function that is the guts of the implementation of other variants.
int log_multiline (const char *path, log_level_t level, const char *classname, const void *obj, const char *msg)
 Alternative core log function that expects a multi-line, preformatted log buffer.
log_level_t log_level (const char *path)
 Return the log level currently enabled for the path / class.
void parse_debug_file (const char *debug_path=NULL)
 Parse the debug file and repopulate the rule list.
void set_prefix (const char *prefix)
 Set the logging prefix after initialization.
void rotate ()
 Close and reopen the log file.
void add_rotate_handler (int sig)
 Set up a signal handler for the given signal to do log rotation.
void add_reparse_handler (int sig)
 Set up a signal handler for the given signal to re-parse the debug file.
void dump_rules (StringBuffer *buf)
 Debugging function to print the rules list.
void redirect_stdio ()
 Redirect stdout/stderr to the logging file descriptor by using dup2.

Static Public Member Functions

static Loginstance ()
 Singleton instance accessor.
static void init (const char *logfile="-", log_level_t defaultlvl=LOG_DEFAULT_THRESHOLD, const char *prefix=NULL, const char *debug_path=LOG_DEFAULT_DBGFILE)
 Initialize the logging system.
static void init (log_level_t defaultlvl)
 Initialize the logging system.
static bool initialized ()
 Hook to determine if logging is initialized yet.
static void shutdown ()
 Shut down the logging system.

Static Public Attributes

static bool __debug_no_panic_on_overflow
 Debugging hook used for the log unit test to test out the overflow guard without actually triggering a panic.

Protected Member Functions

 Log ()
virtual ~Log ()
void do_init (const char *logfile, log_level_t defaultlvl, const char *prefix, const char *debug_path)
 Initialize logging, should be called exactly once from the static Log::init or LogSim::init.

Static Protected Attributes

static Loginstance_
 Singleton instance of the Logging system.

Private Types

enum  {
  OUTPUT_PATH = 1<<0, OUTPUT_TIME = 1<<1, OUTPUT_LEVEL = 1<<2, OUTPUT_CLASSNAME = 1<<3,
  OUTPUT_OBJ = 1<<4, OUTPUT_SHORT = 1<<10, OUTPUT_COLOR = 1<<11
}
 Output format types. More...
typedef std::vector< RuleRuleList
 Use a vector for the list of rules.

Private Member Functions

size_t gen_prefix (char *buf, size_t buflen, const char *path, log_level_t level, const char *classname, const void *obj)
 Generate the log prefix.
Rulefind_rule (const char *path)
 Find a rule given a path.

Static Private Member Functions

static bool rule_compare (const Rule &rule1, const Rule &rule2)
 Sorting function for log rules.
static void sort_rules (RuleList *rule_list)
 Sort a rules list.

Private Attributes

int output_flags_
 Output control flags.
std::string logfile_
 Log output file (- for stdout).
int logfd_
 Output file descriptor.
bool stdio_redirected_
 Flag to redirect std{out,err}.
RuleListrule_list_
 Pointer to current list of logging rules.
RuleList rule_lists_ [2]
 Double-buffered rule lists for reparsing.
SpinLockoutput_lock_
 Lock for write calls and rotating.
std::string debug_path_
 Path to the debug file.
std::string prefix_
 String to prefix log messages.
log_level_t default_threshold_
 The default threshold for log messages.

Static Private Attributes

static bool inited_
 Flag to ensure one-time intialization.

Friends

class LogCommand

Classes

struct  Rule
 Structure used to store a log rule as parsed from the debug file. More...


Member Typedef Documentation

typedef std::vector<Rule> oasys::Log::RuleList [private]

Use a vector for the list of rules.

Definition at line 348 of file Log.h.


Member Enumeration Documentation

anonymous enum [private]

Output format types.

Enumerator:
OUTPUT_PATH 
OUTPUT_TIME 
OUTPUT_LEVEL 
OUTPUT_CLASSNAME 
OUTPUT_OBJ 
OUTPUT_SHORT 
OUTPUT_COLOR 

Definition at line 353 of file Log.h.


Constructor & Destructor Documentation

oasys::Log::Log (  )  [protected]

Definition at line 96 of file Log.cc.

References output_lock_, rule_list_, and rule_lists_.

Referenced by init().

oasys::Log::~Log (  )  [protected, virtual]

Definition at line 153 of file Log.cc.

References logfd_, and output_lock_.


Member Function Documentation

static Log* oasys::Log::instance (  )  [inline, static]

Singleton instance accessor.

Note that Log::init must be called before this function, hence static initializers can't use the logging system.

Definition at line 187 of file Log.h.

References oasys::__log_assert(), and instance_.

Referenced by oasys::__log_enabled(), oasys::LogCommand::exec(), dtn::DTND::init_log(), oasys::Logger::log_multiline(), oasys::log_multiline(), oasys::LogCommand::LogCommand(), oasys::logf(), oasys::reparse_handler(), oasys::rotate_handler(), dtnsim::Simulator::run(), dtnsim::Node::set_active(), oasys::Logger::vlogf(), and oasys::vlogf().

void oasys::Log::init ( const char *  logfile = "-",
log_level_t  defaultlvl = LOG_DEFAULT_THRESHOLD,
const char *  prefix = NULL,
const char *  debug_path = LOG_DEFAULT_DBGFILE 
) [static]

Initialize the logging system.

Must be called exactly once.

Definition at line 106 of file Log.cc.

References do_init(), and Log().

Referenced by init(), dtntunnel::DTNTunnel::init_log(), dtn::DTND::init_log(), main(), and oasys::UnitTester::run_tests().

static void oasys::Log::init ( log_level_t  defaultlvl  )  [inline, static]

Initialize the logging system.

Must be called exactly once.

Definition at line 204 of file Log.h.

References init().

static bool oasys::Log::initialized (  )  [inline, static]

Hook to determine if logging is initialized yet.

Definition at line 212 of file Log.h.

References inited_.

void oasys::Log::shutdown (  )  [static]

Shut down the logging system.

Definition at line 162 of file Log.cc.

References inited_, and instance_.

Referenced by main(), and dtn::DTNServer::shutdown().

void oasys::Log::getlogtime ( struct timeval *  tv  )  [virtual]

Sets the time to print for the logging.

Definition at line 503 of file Log.cc.

References dtnsim::gettimeofday().

Referenced by gen_prefix().

int oasys::Log::vlogf ( const char *  path,
log_level_t  level,
const char *  classname,
const void *  obj,
const char *  fmt,
va_list  ap 
)

Core logging function that is the guts of the implementation of other variants.

Returns the number of bytes written, i.e. zero if the log line was suppressed.

Definition at line 602 of file Log.cc.

References __debug_no_panic_on_overflow, oasys::__log_enabled(), ASSERT, errno, gen_prefix(), inited_, oasys::SpinLock::lock(), LOG_MAX_LINELEN, LOG_MAX_PATHLEN, logfd_, output_lock_, oasys::SpinLock::unlock(), and oasys::IO::writeall().

Referenced by oasys::logf(), oasys::Logger::vlogf(), and oasys::vlogf().

int oasys::Log::log_multiline ( const char *  path,
log_level_t  level,
const char *  classname,
const void *  obj,
const char *  msg 
)

Alternative core log function that expects a multi-line, preformatted log buffer.

Generates a single prefix that is repeated for each line of output.

Definition at line 697 of file Log.cc.

References oasys::__log_enabled(), ASSERT, end, errno, gen_prefix(), inited_, oasys::SpinLock::lock(), LOG_MAX_LINELEN, LOG_MAX_PATHLEN, logfd_, output_lock_, oasys::SpinLock::unlock(), and oasys::IO::writevall().

Referenced by oasys::Logger::log_multiline(), and oasys::log_multiline().

log_level_t oasys::Log::log_level ( const char *  path  ) 

Return the log level currently enabled for the path / class.

Definition at line 491 of file Log.cc.

References default_threshold_, find_rule(), and oasys::Log::Rule::level_.

Referenced by oasys::__log_enabled().

void oasys::Log::parse_debug_file ( const char *  debug_path = NULL  ) 

Parse the debug file and repopulate the rule list.

Called from init or from an external handler to reparse the file. If debug_path is unspecified, it defaults to the existing file.

Definition at line 170 of file Log.cc.

References ASSERT, debug_path_, inited_, oasys::LOG_ALWAYS, oasys::LOG_DEBUG, oasys::LOG_INVALID, oasys::logf(), OUTPUT_CLASSNAME, OUTPUT_COLOR, output_flags_, OUTPUT_LEVEL, OUTPUT_OBJ, OUTPUT_PATH, OUTPUT_SHORT, OUTPUT_TIME, rule_list_, rule_lists_, sort_rules(), and oasys::str2level().

Referenced by do_init(), oasys::LogCommand::exec(), and oasys::reparse_handler().

void oasys::Log::set_prefix ( const char *  prefix  )  [inline]

Set the logging prefix after initialization.

Definition at line 260 of file Log.h.

References prefix_.

Referenced by oasys::LogCommand::exec(), and dtnsim::Simulator::run().

void oasys::Log::rotate (  ) 

Close and reopen the log file.

Definition at line 429 of file Log.cc.

References errno, oasys::SpinLock::lock(), oasys::LOG_ERR, oasys::LOG_NOTICE, oasys::LOG_WARN, oasys::logf(), logfd_, logfile_, output_lock_, redirect_stdio(), stdio_redirected_, and oasys::SpinLock::unlock().

Referenced by oasys::LogCommand::exec(), and oasys::rotate_handler().

void oasys::Log::add_rotate_handler ( int  sig  ) 

Set up a signal handler for the given signal to do log rotation.

Definition at line 470 of file Log.cc.

References oasys::LOG_DEBUG, oasys::logf(), and oasys::rotate_handler().

void oasys::Log::add_reparse_handler ( int  sig  ) 

Set up a signal handler for the given signal to re-parse the debug file.

Definition at line 484 of file Log.cc.

References oasys::LOG_DEBUG, oasys::logf(), and oasys::reparse_handler().

void oasys::Log::dump_rules ( StringBuffer buf  ) 

Debugging function to print the rules list.

Definition at line 355 of file Log.cc.

References oasys::StringBuffer::appendf(), ASSERT, inited_, oasys::level2str(), and rule_list_.

Referenced by oasys::LogCommand::exec().

void oasys::Log::redirect_stdio (  ) 

Redirect stdout/stderr to the logging file descriptor by using dup2.

Note that if done once at startup time, this is repeated whenever the log file is rotated.

Definition at line 412 of file Log.cc.

References ASSERT, errno, log_err, logfd_, and stdio_redirected_.

Referenced by rotate().

void oasys::Log::do_init ( const char *  logfile,
log_level_t  defaultlvl,
const char *  prefix,
const char *  debug_path 
) [protected]

Initialize logging, should be called exactly once from the static Log::init or LogSim::init.

Definition at line 114 of file Log.cc.

References ASSERT, default_threshold_, errno, inited_, instance_, oasys::LOG_DEBUG, oasys::LOG_INFO, logfd_, logfile_, parse_debug_file(), and prefix_.

Referenced by init().

bool oasys::Log::rule_compare ( const Rule rule1,
const Rule rule2 
) [static, private]

Sorting function for log rules.

The rules are stored in descending length order, so a linear scan through the list will always return the most specific match. For equal-length rules, the lower-level (i.e. more permissive) rule should be first so for equal paths, the more permissive rule wins.

Definition at line 320 of file Log.cc.

References oasys::Log::Rule::level_, and oasys::Log::Rule::path_.

Referenced by sort_rules().

size_t oasys::Log::gen_prefix ( char *  buf,
size_t  buflen,
const char *  path,
log_level_t  level,
const char *  classname,
const void *  obj 
) [private]

Generate the log prefix.

Returns:
The length of the prefix string.

Definition at line 510 of file Log.cc.

References getlogtime(), oasys::level2str(), OUTPUT_CLASSNAME, OUTPUT_COLOR, output_flags_, OUTPUT_LEVEL, OUTPUT_OBJ, OUTPUT_PATH, OUTPUT_SHORT, OUTPUT_TIME, and prefix_.

Referenced by log_multiline(), and vlogf().

Log::Rule * oasys::Log::find_rule ( const char *  path  )  [private]

Find a rule given a path.

Definition at line 367 of file Log.cc.

References ASSERT, oasys::Glob::fixed_glob(), inited_, oasys::Log::Rule::path_, and rule_list_.

Referenced by log_level().

void oasys::Log::sort_rules ( RuleList rule_list  )  [static, private]

Sort a rules list.

Definition at line 333 of file Log.cc.

References ASSERT, oasys::Log::Rule::path_, and rule_compare().

Referenced by parse_debug_file().


Friends And Related Function Documentation

friend class LogCommand [friend]

Definition at line 301 of file Log.h.


Member Data Documentation

bool oasys::Log::__debug_no_panic_on_overflow [static]

Debugging hook used for the log unit test to test out the overflow guard without actually triggering a panic.

Definition at line 298 of file Log.h.

Referenced by vlogf().

Log * oasys::Log::instance_ [static, protected]

Singleton instance of the Logging system.

Definition at line 316 of file Log.h.

Referenced by do_init(), instance(), and shutdown().

int oasys::Log::output_flags_ [private]

Output control flags.

Definition at line 366 of file Log.h.

Referenced by gen_prefix(), and parse_debug_file().

bool oasys::Log::inited_ [static, private]

Flag to ensure one-time intialization.

Definition at line 387 of file Log.h.

Referenced by do_init(), dump_rules(), find_rule(), initialized(), log_multiline(), parse_debug_file(), shutdown(), and vlogf().

std::string oasys::Log::logfile_ [private]

Log output file (- for stdout).

Definition at line 388 of file Log.h.

Referenced by do_init(), and rotate().

int oasys::Log::logfd_ [private]

Output file descriptor.

Definition at line 389 of file Log.h.

Referenced by do_init(), log_multiline(), redirect_stdio(), rotate(), vlogf(), and ~Log().

bool oasys::Log::stdio_redirected_ [private]

Flag to redirect std{out,err}.

Definition at line 390 of file Log.h.

Referenced by redirect_stdio(), and rotate().

RuleList* oasys::Log::rule_list_ [private]

Pointer to current list of logging rules.

Definition at line 391 of file Log.h.

Referenced by dump_rules(), find_rule(), Log(), and parse_debug_file().

RuleList oasys::Log::rule_lists_[2] [private]

Double-buffered rule lists for reparsing.

Definition at line 392 of file Log.h.

Referenced by Log(), and parse_debug_file().

SpinLock* oasys::Log::output_lock_ [private]

Lock for write calls and rotating.

Definition at line 393 of file Log.h.

Referenced by Log(), log_multiline(), rotate(), vlogf(), and ~Log().

std::string oasys::Log::debug_path_ [private]

Path to the debug file.

Definition at line 394 of file Log.h.

Referenced by parse_debug_file().

std::string oasys::Log::prefix_ [private]

String to prefix log messages.

Definition at line 395 of file Log.h.

Referenced by do_init(), gen_prefix(), and set_prefix().

log_level_t oasys::Log::default_threshold_ [private]

The default threshold for log messages.

Definition at line 396 of file Log.h.

Referenced by do_init(), and log_level().


The documentation for this class was generated from the following files:
Generated on Fri Dec 22 14:48:06 2006 for DTN Reference Implementation by  doxygen 1.5.1