Logging API

The logging API used by OpenSurgSim code. More...

## Modules

| Internal logging helpers
| Not meant for public consumption.

## Files

file | Log.h
| The convenience header that provides the entirety of the logging API.

## Classes

class | SurgSim::Framework::Logger
| An object that can be used to control logging parameters, such as verbosity and log output destination. More...

## Macros

#define | SURGSIM_LOG(logger, level)
| Logs a message to the specified `logger` with the short `level` name. More...
#define | SURGSIM_LOG_DEBUG(logger) SURGSIM_LOG(logger, DEBUG)
| Logs a message to the specified `logger` at the DEBUG level. More...
#define | SURGSIM_LOG_INFO(logger) SURGSIM_LOG(logger, INFO)
| Logs a message to the specified `logger` at the INFO level. More...
#define | SURGSIM_LOG_WARNING(logger) SURGSIM_LOG(logger, WARNING)
| Logs a message to the specified `logger` at the WARNING level. More...
#define | SURGSIM_LOG_SEVERE(logger) SURGSIM_LOG(logger, SEVERE)
| Logs a message to the specified `logger` at the SEVERE level. More...
#define | SURGSIM_LOG_CRITICAL(logger) SURGSIM_LOG(logger, CRITICAL)
| Logs a message to the specified `logger` at the CRITICAL level. More...
#define | SURGSIM_LOG_IF(condition, logger, level)
| Logs a message to the specified `logger` with the short `level` name if `condition` is true. More...
#define | SURGSIM_LOG_ONCE(logger, level)
| Logs a message to the specified `logger` with the short `level` name, but only the first time this statement is reached. More...
#define | SURGSIM_LOG_ONCE_IF(condition, logger, level)
| Logs a message to the specified `logger` with the short `level` name if `condition` is true, but only the first time this particular condition is true. More...

## Enumerations

enum | SurgSim::Framework::LogLevel { SurgSim::Framework::LOG_LEVEL_DEBUG, SurgSim::Framework::LOG_LEVEL_INFO, SurgSim::Framework::LOG_LEVEL_WARNING, SurgSim::Framework::LOG_LEVEL_SEVERE, SurgSim::Framework::LOG_LEVEL_CRITICAL }
| Logging levels. More...

## Detailed Description

The logging API used by OpenSurgSim code.

See also
  Assertions

## Macro Definition Documentation

## SURGSIM_LOG

#define SURGSIM_LOG | ( |  | logger,
|  |  | level
| ) |  |

Logs a message to the specified `logger` with the short `level` name.

Parameters

  logger | Logger used to log the message
  level | Level of this log message (DEBUG, INFO, WARNING, SEVERE or CRITICAL).

Returns
  Stream to output the log message

Example

SURGSIM_LOG(logger, WARNING) << messageText;

## SURGSIM_LOG_CRITICAL

#define SURGSIM_LOG_CRITICAL | ( |  | logger | ) | SURGSIM_LOG(logger, CRITICAL)

Logs a message to the specified `logger` at the CRITICAL level.

Parameters

  logger | Logger used to log the message

Returns
  Stream to output the log message

Example

SURGSIM_LOG_CRITICAL(logger) << messageText;

## SURGSIM_LOG_DEBUG

#define SURGSIM_LOG_DEBUG | ( |  | logger | ) | SURGSIM_LOG(logger, DEBUG)

Logs a message to the specified `logger` at the DEBUG level.

Parameters

  logger | Logger used to log the message

Returns
  Stream to output the log message

Example

SURGSIM_LOG_DEBUG(logger) << messageText;

## SURGSIM_LOG_IF

#define SURGSIM_LOG_IF | ( |  | condition,
|  |  | logger,
|  |  | level
| ) |  |

Logs a message to the specified `logger` with the short `level` name if `condition` is true.

Parameters

  condition | Condition to test.
  logger | Logger used to log the message.
  level | Level of this log message (DEBUG, INFO, WARNING, SEVERE or CRITICAL).

Returns
  Stream to output the log message.

Example

SURGSIM_LOG_IF(size >= 100, logger, INFO) << "size is " << size;

## SURGSIM_LOG_INFO

#define SURGSIM_LOG_INFO | ( |  | logger | ) | SURGSIM_LOG(logger, INFO)

Logs a message to the specified `logger` at the INFO level.

Parameters

  logger | Logger used to log the message

Returns
  Stream to output the log message

Example

SURGSIM_LOG_INFO(logger) << messageText;

## SURGSIM_LOG_ONCE

#define SURGSIM_LOG_ONCE | ( |  | logger,
|  |  | level
| ) |  |

Logs a message to the specified `logger` with the short `level` name, but only the first time this statement is reached.

Parameters

  logger | Logger used to log the message.
  level | Level of this log message (DEBUG, INFO, WARNING, SEVERE or CRITICAL).

Returns
  Stream to output the log message.

Example

SURGSIM_LOG_ONCE(logger, level) << messageTextShownOnce;

## SURGSIM_LOG_ONCE_IF

#define SURGSIM_LOG_ONCE_IF | ( |  | condition,
|  |  | logger,
|  |  | level
| ) |  |

Logs a message to the specified `logger` with the short `level` name if `condition` is true, but only the first time this particular condition is true.

Parameters

  condition | Condition to test
  logger | Logger used to log the message
  level | Level of this log message (DEBUG, INFO, WARNING, SEVERE or CRITICAL).

Returns
  Stream to output the log message

Example

SURGSIM_LOG_ONCE_IF(condition, logger, level) << messageTextShownOnce;

## SURGSIM_LOG_SEVERE

#define SURGSIM_LOG_SEVERE | ( |  | logger | ) | SURGSIM_LOG(logger, SEVERE)

Logs a message to the specified `logger` at the SEVERE level.

Parameters

  logger | Logger used to log the message

Returns
  Stream to output the log message

Example

SURGSIM_LOG_SEVERE(logger) << messageText;

## SURGSIM_LOG_WARNING

#define SURGSIM_LOG_WARNING | ( |  | logger | ) | SURGSIM_LOG(logger, WARNING)

Logs a message to the specified `logger` at the WARNING level.

Parameters

  logger | Logger used to log the message

Returns
  Stream to output the log message

Example

SURGSIM_LOG_WARNING(logger) << messageText;

## Enumeration Type Documentation

## LogLevel

enum SurgSim::Framework::LogLevel

Logging levels.

Please note that most logging macros take an abbreviated version of these enumerations, without the leading `LOG_LEVEL_`, i.e. one of `DEBUG`, `INFO`, `WARNING`, `SEVERE` or `CRITICAL` .

Enumerator
LOG_LEVEL_DEBUG | Use at your discretion.
LOG_LEVEL_INFO | Informational, notify of state changes.
LOG_LEVEL_WARNING | Something failed, but the impact of the failure is not know or minimal (e.g. purely visual).
LOG_LEVEL_SEVERE | Something failed and will impact functionality, some parts of the program will not function correctly.
LOG_LEVEL_CRITICAL | Used by assertion, after using this level the program will not be functional at all.