rcutils  master
C API providing common utilities and data structures.
Classes | Macros | Typedefs | Enumerations | Functions | Variables
logging.h File Reference
#include <stdarg.h>
#include <stdbool.h>
#include <stdio.h>
#include "rcutils/allocator.h"
#include "rcutils/error_handling.h"
#include "rcutils/macros.h"
#include "rcutils/time.h"
#include "rcutils/types/rcutils_ret.h"
#include "rcutils/visibility_control.h"
Include dependency graph for logging.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  rcutils_log_location_t
 The structure identifying the caller location in the source code. More...
 

Macros

#define RCUTILS_LOGGING_SEPARATOR_STRING   "."
 The separator used when logging node names. More...
 
#define RCUTILS_DEFAULT_LOGGER_DEFAULT_LEVEL   RCUTILS_LOG_SEVERITY_INFO
 The default severity level of the default logger. More...
 
#define RCUTILS_LOGGING_AUTOINIT
 Initialize the rcl logging library. Usually it is unnecessary to call the macro directly. All logging macros ensure that this has been called once. More...
 

Typedefs

typedef struct rcutils_log_location_t rcutils_log_location_t
 The structure identifying the caller location in the source code. More...
 
typedef void(* rcutils_logging_output_handler_t) (const rcutils_log_location_t *, int, const char *, rcutils_time_point_value_t, const char *, va_list *)
 The function signature to log messages. More...
 

Enumerations

enum  RCUTILS_LOG_SEVERITY {
  RCUTILS_LOG_SEVERITY_UNSET = 0, RCUTILS_LOG_SEVERITY_DEBUG = 10, RCUTILS_LOG_SEVERITY_INFO = 20, RCUTILS_LOG_SEVERITY_WARN = 30,
  RCUTILS_LOG_SEVERITY_ERROR = 40, RCUTILS_LOG_SEVERITY_FATAL = 50
}
 The severity levels of log messages / loggers. More...
 

Functions

rcutils_ret_t rcutils_logging_initialize_with_allocator (rcutils_allocator_t allocator)
 Initialize the logging system using the specified allocator. More...
 
rcutils_ret_t rcutils_logging_initialize (void)
 Initialize the logging system. More...
 
rcutils_ret_t rcutils_logging_shutdown (void)
 Shutdown the logging system. More...
 
rcutils_ret_t rcutils_logging_severity_level_from_string (const char *severity_string, rcutils_allocator_t allocator, int *severity)
 Get a severity value from its string representation (e.g. DEBUG). More...
 
rcutils_logging_output_handler_t rcutils_logging_get_output_handler ()
 Get the current output handler. More...
 
void rcutils_logging_set_output_handler (rcutils_logging_output_handler_t function)
 Set the current output handler. More...
 
rcutils_ret_t rcutils_logging_format_message (const rcutils_log_location_t *location, int severity, const char *name, rcutils_time_point_value_t timestamp, const char *msg, rcutils_char_array_t *logging_output)
 Formats a log message according to RCUTILS_CONSOLE_OUTPUT_FORMAT. More...
 
int rcutils_logging_get_default_logger_level ()
 Get the default level for loggers. More...
 
void rcutils_logging_set_default_logger_level (int level)
 Set the default severity level for loggers. More...
 
int rcutils_logging_get_logger_level (const char *name)
 Get the severity level for a logger. More...
 
int rcutils_logging_get_logger_leveln (const char *name, size_t name_length)
 Get the level for a logger and its name length. More...
 
rcutils_ret_t rcutils_logging_set_logger_level (const char *name, int level)
 Set the severity level for a logger. More...
 
bool rcutils_logging_logger_is_enabled_for (const char *name, int severity)
 Determine if a logger is enabled for a severity level. More...
 
int rcutils_logging_get_logger_effective_level (const char *name)
 Determine the effective level for a logger. More...
 
void rcutils_log (const rcutils_log_location_t *location, int severity, const char *name, const char *format,...)
 Log a message. More...
 
void rcutils_logging_console_output_handler (const rcutils_log_location_t *location, int severity, const char *name, rcutils_time_point_value_t timestamp, const char *format, va_list *args)
 The default output handler outputs log messages to the standard streams. More...
 

Variables

bool g_rcutils_logging_initialized
 The flag if the logging system has been initialized. More...
 
const char *const g_rcutils_log_severity_names [RCUTILS_LOG_SEVERITY_FATAL+1]
 The names of severity levels. More...
 
rcutils_logging_output_handler_t g_rcutils_logging_output_handler
 The function pointer of the current output handler. More...
 
int g_rcutils_logging_default_logger_level
 The default severity level for loggers. More...
 

Macro Definition Documentation

◆ RCUTILS_LOGGING_SEPARATOR_STRING

#define RCUTILS_LOGGING_SEPARATOR_STRING   "."

The separator used when logging node names.

◆ RCUTILS_DEFAULT_LOGGER_DEFAULT_LEVEL

#define RCUTILS_DEFAULT_LOGGER_DEFAULT_LEVEL   RCUTILS_LOG_SEVERITY_INFO

The default severity level of the default logger.

◆ RCUTILS_LOGGING_AUTOINIT

#define RCUTILS_LOGGING_AUTOINIT
Value:
do { \
RCUTILS_SAFE_FWRITE_TO_STDERR( \
"[rcutils|" __FILE__ ":" RCUTILS_STRINGIFY(__LINE__) \
"] error initializing logging: "); \
RCUTILS_SAFE_FWRITE_TO_STDERR(rcutils_get_error_string().str); \
RCUTILS_SAFE_FWRITE_TO_STDERR("\n"); \
rcutils_reset_error(); \
} \
} \
} while (0)

Initialize the rcl logging library. Usually it is unnecessary to call the macro directly. All logging macros ensure that this has been called once.

Typedef Documentation

◆ rcutils_log_location_t

The structure identifying the caller location in the source code.

◆ rcutils_logging_output_handler_t

typedef void(* rcutils_logging_output_handler_t) (const rcutils_log_location_t *, int, const char *, rcutils_time_point_value_t, const char *, va_list *)

The function signature to log messages.

Parameters
[in]locationThe location information about where the log came from
[in]severityThe severity of the log message expressed as an integer
[in]nameThe name of the logger that this message came from
[in]timestampThe time at which the log message was generated
[in]formatThe list of arguments to insert into the formatted log message
[in]argsThe variable argument list

Enumeration Type Documentation

◆ RCUTILS_LOG_SEVERITY

The severity levels of log messages / loggers.

Enumerator
RCUTILS_LOG_SEVERITY_UNSET 

The unset log level.

RCUTILS_LOG_SEVERITY_DEBUG 

The debug log level.

RCUTILS_LOG_SEVERITY_INFO 

The info log level.

RCUTILS_LOG_SEVERITY_WARN 

The warn log level.

RCUTILS_LOG_SEVERITY_ERROR 

The error log level.

RCUTILS_LOG_SEVERITY_FATAL 

The fatal log level.

Function Documentation

◆ rcutils_logging_initialize_with_allocator()

rcutils_ret_t rcutils_logging_initialize_with_allocator ( rcutils_allocator_t  allocator)

Initialize the logging system using the specified allocator.

Initialize the logging system only if it was not in an initialized state.

If an invalid allocator is passed, the initialization will fail. Otherwise, this function will still set the internal state to initialized even if an error occurs, to avoid repeated failing initialization attempts since this function is called automatically from logging macros. To re-attempt initialization, call rcutils_logging_shutdown() before re-calling this function.

If multiple errors occur, the error code of the last error will be returned.

The RCUTILS_CONSOLE_OUTPUT_FORMAT environment variable can be used to set the output format of messages logged to the console. Available tokens are:

  • file_name, the full file name of the caller including the path
  • function_name, the function name of the caller
  • line_number, the line number of the caller
  • message, the message string after it has been formatted
  • name, the full logger name
  • severity, the name of the severity level, e.g. INFO
  • time, the timestamp of log message in floating point seconds
  • time_as_nanoseconds, the timestamp of log message in integer nanoseconds

The RCUTILS_COLORIZED_OUTPUT environment variable allows configuring if colours are used or not. Available values are:

  • 1: Force using colours.
  • 0: Don't use colours. If it is unset, colours are used depending if the target stream is a terminal or not. See isatty documentation.

The format string can use these tokens by referencing them in curly brackets, e.g. "[{severity}] [{name}]: {message} ({function_name}() at {file_name}:{line_number})". Any number of tokens can be used. The limit of the format string is 2048 characters.


Attribute Adherence
Allocates Memory Yes
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]allocatorrcutils_allocator_t to be used.
Returns
RCUTILS_RET_OK if successful, or
RCUTILS_RET_INVALID_ARGUMENT if the allocator is invalid, in which case initialization will fail, or
RCUTILS_RET_INVALID_ARGUMENT if an error occurs reading the output format from the RCUTILS_CONSOLE_OUTPUT_FORMAT environment variable, in which case the default format will be used, or
RCUTILS_RET_LOGGING_SEVERITY_MAP_INVALID if the internal logger severity level map cannot be initialized, in which case logger severity levels will not be configurable.

◆ rcutils_logging_initialize()

rcutils_ret_t rcutils_logging_initialize ( void  )

Initialize the logging system.

Call rcutils_logging_initialize_with_allocator() using the default allocator. This function is called automatically when using the logging macros.


Attribute Adherence
Allocates Memory Yes
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Returns
RCUTILS_RET_OK if successful, or
RCUTILS_RET_INVALID_ARGUMENT if an error occurs reading the output format from the RCUTILS_CONSOLE_OUTPUT_FORMAT environment variable, in which case the default format will be used, or
RCUTILS_RET_LOGGING_SEVERITY_MAP_INVALID if the internal logger severity level map cannot be initialized, in which case logger levels will not be configurable.

◆ rcutils_logging_shutdown()

rcutils_ret_t rcutils_logging_shutdown ( void  )

Shutdown the logging system.

Free the resources allocated for the logging system. This puts the system into a state equivalent to being uninitialized.


Attribute Adherence
Allocates Memory No
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Returns
RCUTILS_RET_OK if successful, or
RCUTILS_RET_LOGGING_SEVERITY_MAP_INVALID if the internal logger severity level map cannot be finalized.

◆ rcutils_logging_severity_level_from_string()

rcutils_ret_t rcutils_logging_severity_level_from_string ( const char *  severity_string,
rcutils_allocator_t  allocator,
int *  severity 
)

Get a severity value from its string representation (e.g. DEBUG).

String representation must match one of the values in g_rcutils_log_severity_names, but is not case-sensitive. Examples: UNSET, DEBUG, INFO, WARN, Error, fatal.

Parameters
[in]severity_stringString representation of the severity, must be a null terminated c string
[in]allocatorrcutils_allocator_t to be used
[in,out]severityThe severity level as a represented by the RCUTILS_LOG_SEVERITY enum
Returns
RCUTILS_RET_OK if successful, or
RCUTILS_RET_INVALID_ARGUMENT on invalid arguments, or
RCUTILS_RET_LOGGING_SEVERITY_STRING_INVALID if unable to match string, or
RCUTILS_RET_ERROR if an unspecified error occured.

◆ rcutils_logging_get_output_handler()

rcutils_logging_output_handler_t rcutils_logging_get_output_handler ( )

Get the current output handler.


Attribute Adherence
Allocates Memory No, provided logging system is already initialized
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Returns
The function pointer of the current output handler.

◆ rcutils_logging_set_output_handler()

void rcutils_logging_set_output_handler ( rcutils_logging_output_handler_t  function)

Set the current output handler.


Attribute Adherence
Allocates Memory No, provided logging system is already initialized
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]functionThe function pointer of the output handler to be used.

◆ rcutils_logging_format_message()

rcutils_ret_t rcutils_logging_format_message ( const rcutils_log_location_t location,
int  severity,
const char *  name,
rcutils_time_point_value_t  timestamp,
const char *  msg,
rcutils_char_array_t logging_output 
)

Formats a log message according to RCUTILS_CONSOLE_OUTPUT_FORMAT.

A formatter that is meant to be used by an output handler to format a log message to the match the format specified in RCUTILS_CONSOLE_OUTPUT_FORMAT by performing token replacement.


Attribute Adherence
Allocates Memory Yes
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]locationThe location information about where the log came from
[in]severityThe severity of the log message expressed as an integer
[in]nameThe name of the logger that this message came from
[in]timestampThe time at which the log message was generated
[in]msgThe message being logged
[out]logging_outputAn output buffer for the formatted message
Returns
RCUTILS_RET_OK if successful.
RCUTILS_RET_BAD_ALLOC if memory allocation error occured

◆ rcutils_logging_get_default_logger_level()

int rcutils_logging_get_default_logger_level ( )

Get the default level for loggers.


Attribute Adherence
Allocates Memory No, provided logging system is already initialized
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Returns
The level.

◆ rcutils_logging_set_default_logger_level()

void rcutils_logging_set_default_logger_level ( int  level)

Set the default severity level for loggers.

If the severity level requested is RCUTILS_LOG_SEVERITY_UNSET, the default value for the default logger (RCUTILS_DEFAULT_LOGGER_DEFAULT_LEVEL) will be restored instead.


Attribute Adherence
Allocates Memory No, provided logging system is already initialized
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]levelThe level to be used.

◆ rcutils_logging_get_logger_level()

int rcutils_logging_get_logger_level ( const char *  name)

Get the severity level for a logger.

This considers the severity level of the specifed logger only. To get the effective level of a logger given the severity level of its ancestors, see rcutils_logging_get_logger_effective_level().


Attribute Adherence
Allocates Memory No, provided logging system is already initialized
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]nameThe name of the logger, must be null terminated c string
Returns
The level of the logger if it has been set, or
RCUTILS_LOG_SEVERITY_UNSET if unset, or
g_rcutils_logging_default_logger_level for an empty name, or
-1 on invalid arguments, or
-1 if an error occurred

◆ rcutils_logging_get_logger_leveln()

int rcutils_logging_get_logger_leveln ( const char *  name,
size_t  name_length 
)

Get the level for a logger and its name length.

Identical to rcutils_logging_get_logger_level() but without relying on the logger name to be a null terminated c string.


Attribute Adherence
Allocates Memory No, provided logging system is already initialized
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]nameThe name of the logger
[in]name_lengthLogger name length
Returns
The level of the logger if it has been set, or
RCUTILS_LOG_SEVERITY_UNSET if unset, or
g_rcutils_logging_default_logger_level for name_length of 0, or
-1 on invalid arguments, or
-1 if an error occurred

◆ rcutils_logging_set_logger_level()

rcutils_ret_t rcutils_logging_set_logger_level ( const char *  name,
int  level 
)

Set the severity level for a logger.

If an empty string is specified as the name, the g_rcutils_logging_default_logger_level will be set.


Attribute Adherence
Allocates Memory Yes
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]nameThe name of the logger, must be null terminated c string.
[in]levelThe level to be used.
Returns
RCUTILS_RET_OK if successful, or
RCUTILS_RET_INVALID_ARGUMENT on invalid arguments, or
RCUTILS_RET_LOGGING_SEVERITY_MAP_INVALID if severity map invalid, or
RCUTILS_RET_ERROR if an unspecified error occured

◆ rcutils_logging_logger_is_enabled_for()

bool rcutils_logging_logger_is_enabled_for ( const char *  name,
int  severity 
)

Determine if a logger is enabled for a severity level.


Attribute Adherence
Allocates Memory No, provided logging system is already initialized
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]nameThe name of the logger, must be null terminated c string or NULL.
[in]severityThe severity level.
Returns
true if the logger is enabled for the level, or
false otherwise.

◆ rcutils_logging_get_logger_effective_level()

int rcutils_logging_get_logger_effective_level ( const char *  name)

Determine the effective level for a logger.

The effective level is determined as the severity level of the logger if it is set, otherwise it is the first specified severity level of the logger's ancestors, starting with its closest ancestor. The ancestor hierarchy is signified by logger names being separated by dots: a logger named x is an ancestor of x.y, and both x and x.y are ancestors of x.y.z, etc. If the level has not been set for the logger nor any of its ancestors, the default level is used.


Attribute Adherence
Allocates Memory No, provided logging system is already initialized
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]nameThe name of the logger, must be null terminated c string.
Returns
The level, or
-1 on invalid arguments, or
-1 if an error occurred.

◆ rcutils_log()

void rcutils_log ( const rcutils_log_location_t location,
int  severity,
const char *  name,
const char *  format,
  ... 
)

Log a message.

The attributes of this function are also being influenced by the currently set output handler.


Attribute Adherence
Allocates Memory No, for formatted outputs <= 1023 characters

| Yes, for formatted outputs >= 1024 characters Thread-Safe | No Uses Atomics | No Lock-Free | Yes

Parameters
[in]locationThe pointer to the location struct or NULL
[in]severityThe severity level
[in]nameThe name of the logger, must be null terminated c string or NULL
[in]formatThe format string
[in]...The variable arguments

◆ rcutils_logging_console_output_handler()

void rcutils_logging_console_output_handler ( const rcutils_log_location_t location,
int  severity,
const char *  name,
rcutils_time_point_value_t  timestamp,
const char *  format,
va_list args 
)

The default output handler outputs log messages to the standard streams.

The messages with a severity level DEBUG and INFO are written to stdout. The messages with a severity level WARN, ERROR, and FATAL are written to stderr. The console output format of the logged message can be configured through the RCUTILS_CONSOLE_OUTPUT_FORMAT environment variable: see rcutils_logging_initialize_with_allocator() for details. For configuring if using colours or not, RCUTILS_COLORIZED_OUTPUT can be used: see rcutils_logging_initialize_with_allocator() for details.


Attribute Adherence
Allocates Memory No
Thread-Safe Yes, if the underlying *printf functions are
Uses Atomics No
Lock-Free Yes
Parameters
[in]locationThe pointer to the location struct or NULL
[in]severityThe severity level
[in]nameThe name of the logger, must be null terminated c string
[in]timestampThe timestamp for when the log message was made
[in]formatThe format string
[in]argsThe va_list used by the logger

Variable Documentation

◆ g_rcutils_logging_initialized

bool g_rcutils_logging_initialized

The flag if the logging system has been initialized.

◆ g_rcutils_log_severity_names

const char* const g_rcutils_log_severity_names[RCUTILS_LOG_SEVERITY_FATAL+1]

The names of severity levels.

◆ g_rcutils_logging_output_handler

rcutils_logging_output_handler_t g_rcutils_logging_output_handler

The function pointer of the current output handler.

◆ g_rcutils_logging_default_logger_level

int g_rcutils_logging_default_logger_level

The default severity level for loggers.

This level is used for (1) nameless log calls and (2) named log calls where the effective level of the logger name is unspecified.

See also
rcutils_logging_get_logger_effective_level()
rcutils_logging_initialize
rcutils_ret_t rcutils_logging_initialize(void)
Initialize the logging system.
rcutils_get_error_string
rcutils_error_string_t rcutils_get_error_string(void)
Return the error message followed by , at <file>:<line> if set, else "error not set".
g_rcutils_logging_initialized
bool g_rcutils_logging_initialized
The flag if the logging system has been initialized.
RCUTILS_RET_OK
#define RCUTILS_RET_OK
Successful operation.
Definition: rcutils_ret.h:29
RCUTILS_UNLIKELY
#define RCUTILS_UNLIKELY(x)
Definition: macros.h:131