text_logging.h File Reference

Detailed Description

This is the entry point for all text logging within Drake.

Once you've included this file, the suggested ways you should write log messages include:

  drake::log()->trace("Some trace message: {} {}", something, some_other);

Similarly, it provides:

  drake::log()->debug(...);
  drake::log()->info(...);
  drake::log()->warn(...);
  drake::log()->error(...);
  drake::log()->critical(...);

If you want to log objects that are expensive to serialize, these macros will not be compiled if debugging is turned off (-DNDEBUG is set):

  DRAKE_LOGGER_TRACE("message: {}", something_conditionally_compiled);
  DRAKE_LOGGER_DEBUG("message: {}", something_conditionally_compiled);

The format string syntax is fmtlib; see https://fmt.dev/latest/syntax.html. (Note that the documentation link provides syntax for the latest version of fmtlib; the version of fmtlib used by Drake might be older.)

When formatting an Eigen matrix into a string you must wrap the Eigen object with fmt_eigen(); see its documentation for details. This holds true whether it be for logging, error messages, etc.

When logging a third-party type whose only affordance for string output is operator<<, use fmt_streamed(); see its documentation for details. This is very rare (only a couple uses in Drake so far).

When implementing a string output for a Drake type, eventually this page will demonstrate how to use fmt::formatter<T>. In the meantime, you can implement operator<< and use drake::ostream_formatter, or else use the macro helper DRAKE_FORMATTER_AS(). Grep around in Drake's existing code to find examples.

Warning

This file should only be included from cc files, not header files. Formatting a log messages is necessarily an expensive operation, so does not meet our style guide rules for inline functions. (This is enforced in CI by Drake's linter.)

#include <string>
#include "drake/common/fmt.h"
#include "drake/common/drake_copyable.h"

Include dependency graph for text_logging.h:

Classes
struct	Warn
	When constructed, logs a message (at "warn" severity); the destructor is guaranteed to be trivial. More...

Namespaces
	drake
	drake::logging

Typedefs
using	logger = spdlog::logger
	The drake::logging::logger class provides text logging methods. More...

Functions
logging::logger *	log ()
	Retrieve an instance of a logger to use for logging; for example: More...
sink *	get_dist_sink ()
	(Advanced) Retrieves the default sink for all Drake logs. More...
std::string	set_log_level (const std::string &level)
	Sets the log threshold used by Drake's C++ code. More...
void	set_log_pattern (const std::string &pattern)
	Invokes drake::log()->set_pattern(pattern). More...

Variables
constexpr bool	kHaveSpdlog = true
	True only if spdlog is enabled in this build. More...
const char *const	kSetLogLevelUnchanged
	The "unchanged" string to pass to set_log_level() so as to achieve a no-op. More...
const char *const	kSetLogLevelHelpMessage
	An end-user help string suitable to describe the effects of set_log_level(). More...
const char *const	kSetLogPatternHelpMessage
	An end-user help string suitable to describe the effects of set_log_pattern(). More...