ROS Console

http://wiki.ros.org/
Admin
ROS Console is a C++ logging library that provides macro-based console output and logging...
Tokens:6,282
Snippets:69
Trust Score:9.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Get default named logger name

Source: http://wiki.ros.org/rosconsole

Retrieve the default named logger string, which is typically 'ros.<package_name>'.

```c++
const char* logger_name = ROSCONSOLE_DEFAULT_NAME ".<name>"
```

--------------------------------

### Base ROS Logging Macros

Source: http://wiki.ros.org/rosconsole

Use these macros for general logging. They output to a logger named 'ros.<your_package_name>'.

```cpp
#include <ros/console.h>
ROS_DEBUG("Hello %s", "World");
ROS_DEBUG_STREAM("Hello " << "World");
```

--------------------------------

### Include custom rosconsole configuration in launch file

Source: http://wiki.ros.org/rosconsole

Specify a custom rosconsole configuration file using the ROSCONSOLE_CONFIG_FILE environment variable within a roslaunch file.

```xml
<launch>
  <env name="ROSCONSOLE_CONFIG_FILE" 
       value="$(find mypackage)/custom_rosconsole.conf"/>
  <node pkg="mypackage" type="mynode" name="mynode" output="screen"/>
</launch>
```

--------------------------------

### Base Logging Macros

Source: http://wiki.ros.org/rosconsole

These are the fundamental logging macros for different verbosity levels. They support both printf-style and stream-style formatting. The output is directed to a logger named 'ros.<your_package_name>'.

```APIDOC
## Base Logging Macros

### Description
Provides basic logging functionality at different verbosity levels (DEBUG, INFO, WARN, ERROR, FATAL).

### Macros
- `ROS_DEBUG(...)`
- `ROS_INFO(...)`
- `ROS_WARN(...)`
- `ROS_ERROR(...)`
- `ROS_FATAL(...)`
- `ROS_DEBUG_STREAM(args)`
- `ROS_INFO_STREAM(args)`
- `ROS_WARN_STREAM(args)`
- `ROS_ERROR_STREAM(args)`
- `ROS_FATAL_STREAM(args)`

### Example Usage
```cpp
#include <ros/console.h>

ROS_DEBUG("This is a debug message: %d", 123);
ROS_INFO_STREAM("This is an info message: " << 456);
```

### Output
Logs are directed to `ros.<your_package_name>`.
```

--------------------------------

### Customize console output format in launch file

Source: http://wiki.ros.org/rosconsole

Set the ROSCONSOLE_FORMAT environment variable within a roslaunch file to control the console output formatting for a specific node or the entire system.

```xml
<launch>
  <env name="ROSCONSOLE_FORMAT" value="[${severity}] [${time}] [${node}]: ${message}"/>
  <node pkg="mypackage" type="mynode" name="mynode" output="screen"/>
</launch>
```

--------------------------------

### Log Once ROS Macros

Source: http://wiki.ros.org/rosconsole

These macros ensure a message is logged only the first time the macro is encountered and enabled. Useful for first-time warnings or status messages.

```cpp
#include <ros/console.h>
for (int i = 0; i < 10; ++i)
{
  ROS_DEBUG_ONCE("This message will only print once");
}
```

--------------------------------

### Set Default Python ROS Console Format (Kinetic+)

Source: http://wiki.ros.org/rosconsole

Sets the default log format for Python to match C++ for compatibility. Use if you need the older Python format.

```bash
export ROSCONSOLE_FORMAT='[${severity}] [WallTime: ${time}]: ${message}'
```

--------------------------------

### Once Logging Macros

Source: http://wiki.ros.org/rosconsole

These macros ensure that a log message is printed only the first time the macro is encountered and enabled. This is useful for reporting infrequent events or initial states.

```APIDOC
## Once Logging Macros

### Description
Logs a message only the first time the macro is encountered and enabled. Subsequent calls within the same scope or program run will not produce output.

### Macros
- `ROS_DEBUG_ONCE(...)`
- `ROS_INFO_ONCE(...)`
- `ROS_WARN_ONCE(...)`
- `ROS_ERROR_ONCE(...)`
- `ROS_FATAL_ONCE(...)`
- `ROS_DEBUG_STREAM_ONCE(args)`
- `ROS_INFO_STREAM_ONCE(args)`
- `ROS_WARN_STREAM_ONCE(args)`
- `ROS_ERROR_STREAM_ONCE(args)`
- `ROS_FATAL_STREAM_ONCE(args)`
- `ROS_DEBUG_ONCE_NAMED(name, ...)`
- `ROS_INFO_ONCE_NAMED(name, ...)`
- `ROS_WARN_ONCE_NAMED(name, ...)`
- `ROS_ERROR_ONCE_NAMED(name, ...)`
- `ROS_FATAL_ONCE_NAMED(name, ...)`
- `ROS_DEBUG_STREAM_ONCE_NAMED(name, args)`
- `ROS_INFO_STREAM_ONCE_NAMED(name, args)`
- `ROS_WARN_STREAM_ONCE_NAMED(name, args)`
- `ROS_ERROR_STREAM_ONCE_NAMED(name, args)`
- `ROS_FATAL_STREAM_ONCE_NAMED(name, args)`

### Example Usage
```cpp
#include <ros/console.h>

for (int i = 0; i < 5; ++i) {
  ROS_WARN_ONCE("This warning will only appear once.");
}
```
```

--------------------------------

### Set default console output format

Source: http://wiki.ros.org/rosconsole

Define the environment variable ROSCONSOLE_FORMAT to customize the console output appearance. The default format includes severity, time, and message.

```shell
export ROSCONSOLE_FORMAT='[${severity}] [${time}]: ${message}'
```

--------------------------------

### Disable All ROS Logging with Configuration File

Source: http://wiki.ros.org/rosconsole

Create a log4j configuration file to completely disable ROS logging. Set the threshold to OFF.

```properties
log4j.threshold=OFF
```

--------------------------------

### Enable Line Buffering for ROS Console Output

Source: http://wiki.ros.org/rosconsole

Set this environment variable to 1 to force ROS loggers to flush output after every line. Useful when piping output.

```bash
export ROSCONSOLE_STDOUT_LINE_BUFFERED=1
```

--------------------------------

### Filtered ROS Logging Macros

Source: http://wiki.ros.org/rosconsole

These macros allow logging based on a user-defined filter that extends ros::console::FilterBase. The filter must be a pointer type.

```cpp
ROS_DEBUG_FILTER(filter, ...);
ROS_DEBUG_STREAM_FILTER(filter, args);
ROS_DEBUG_FILTER_NAMED(filter, name, ...);
ROS_DEBUG_STREAM_FILTER_NAMED(filter, name, args);
```

--------------------------------

### Named ROS Logging Macros

Source: http://wiki.ros.org/rosconsole

Use these macros to direct logs to a specific named logger, which is a child of the default logger. This allows for granular control over log output.

```cpp
#include <ros/console.h>
ROS_DEBUG_NAMED("test_only", "Hello %s", "World");
ROS_DEBUG_STREAM_NAMED("test_only", "Hello " << "World");
```

--------------------------------

### Configure rosconsole logger levels

Source: http://wiki.ros.org/rosconsole

Set default ros output to warning and higher, or override specific packages to debug. This configuration is compatible with log4j.

```config
# Set the default ros output to warning and higher
log4j.logger.ros=WARN
# Override my package to output everything
log4j.logger.ros.my_package_name=DEBUG
```

--------------------------------

### Filter Logging Macros

Source: http://wiki.ros.org/rosconsole

These macros allow logging based on a custom filter. Users can define their own filter logic by extending `ros::console::FilterBase` to control which messages are output.

```APIDOC
## Filter Logging Macros

### Description
Logs a message only if it passes a user-defined filter. The filter must be an instance of a class derived from `ros::console::FilterBase`.

### Macros
- `ROS_DEBUG_FILTER(filter, ...)`
- `ROS_INFO_FILTER(filter, ...)`
- `ROS_WARN_FILTER(filter, ...)`
- `ROS_ERROR_FILTER(filter, ...)`
- `ROS_FATAL_FILTER(filter, ...)`
- `ROS_DEBUG_STREAM_FILTER(filter, args)`
- `ROS_INFO_STREAM_FILTER(filter, args)`
- `ROS_WARN_STREAM_FILTER(filter, args)`
- `ROS_ERROR_STREAM_FILTER(filter, args)`
- `ROS_FATAL_STREAM_FILTER(filter, args)`
- `ROS_DEBUG_FILTER_NAMED(filter, name, ...)`
- `ROS_INFO_FILTER_NAMED(filter, name, ...)`
- `ROS_WARN_FILTER_NAMED(filter, name, ...)`
- `ROS_ERROR_FILTER_NAMED(filter, name, ...)`
- `ROS_FATAL_FILTER_NAMED(filter, name, ...)`
- `ROS_DEBUG_STREAM_FILTER_NAMED(filter, name, args)`
- `ROS_INFO_STREAM_FILTER_NAMED(filter, name, args)`
- `ROS_WARN_STREAM_FILTER_NAMED(filter, name, args)`
- `ROS_ERROR_STREAM_FILTER_NAMED(filter, name, args)`
- `ROS_FATAL_STREAM_FILTER_NAMED(filter, name, args)`

### Parameters
- `filter` (ros::console::FilterBase*): A pointer to a filter object that determines if the message should be logged.

### Example Usage
```cpp
#include <ros/console.h>

// Assume MyFilter is a class derived from ros::console::FilterBase
// MyFilter my_custom_filter;
// ROS_INFO_FILTER(&my_custom_filter, "This message will be logged if my_custom_filter allows it.");
```
```

--------------------------------

### Delayed Throttle Logging Macros

Source: http://wiki.ros.org/rosconsole

Similar to throttle macros, but with an added delay. The first message is not printed until the specified period has elapsed, ensuring that initial occurrences of an event do not immediately generate logs.

```APIDOC
## Delayed Throttle Logging Macros

### Description
Logs a message at most once per specified time period, with an initial delay. The first message will only appear after the `period` has elapsed.

### Macros
- `ROS_DEBUG_DELAYED_THROTTLE(period, ...)`
- `ROS_INFO_DELAYED_THROTTLE(period, ...)`
- `ROS_WARN_DELAYED_THROTTLE(period, ...)`
- `ROS_ERROR_DELAYED_THROTTLE(period, ...)`
- `ROS_FATAL_DELAYED_THROTTLE(period, ...)`
- `ROS_DEBUG_STREAM_DELAYED_THROTTLE(period, args)`
- `ROS_INFO_STREAM_DELAYED_THROTTLE(period, args)`
- `ROS_WARN_STREAM_DELAYED_THROTTLE(period, args)`
- `ROS_ERROR_STREAM_DELAYED_THROTTLE(period, args)`
- `ROS_FATAL_STREAM_DELAYED_THROTTLE(period, args)`
- `ROS_DEBUG_DELAYED_THROTTLE_NAMED(period, name, ...)`
- `ROS_INFO_DELAYED_THROTTLE_NAMED(period, name, ...)`
- `ROS_WARN_DELAYED_THROTTLE_NAMED(period, name, ...)`
- `ROS_ERROR_DELAYED_THROTTLE_NAMED(period, name, ...)`
- `ROS_FATAL_DELAYED_THROTTLE_NAMED(period, name, ...)`
- `ROS_DEBUG_STREAM_DELAYED_THROTTLE_NAMED(period, name, args)`
- `ROS_INFO_STREAM_DELAYED_THROTTLE_NAMED(period, name, args)`
- `ROS_WARN_STREAM_DELAYED_THROTTLE_NAMED(period, name, args)`
- `ROS_ERROR_STREAM_DELAYED_THROTTLE_NAMED(period, name, args)`
- `ROS_FATAL_STREAM_DELAYED_THROTTLE_NAMED(period, name, args)`

### Parameters
- `period` (ros::Duration): The minimum time interval between log messages, and the initial delay before the first message.

### Example Usage
```cpp
#include <ros/console.h>
#include <ros/duration.h>

while (!ros::service::waitForService("my_service", ros::Duration(0.1)) && ros::ok()) {
  // This message will print every 10 seconds, starting after 10 seconds.
  ROS_WARN_DELAYED_THROTTLE(ros::Duration(10.0), "Waiting for service 'my_service' to become available.");
}
```
```

--------------------------------

### Set Custom Time Format for ROS Console

Source: http://wiki.ros.org/rosconsole

Use this to control how timestamps are displayed in ROS logs. Supports strftime format specifiers.

```bash
export ROSCONSOLE_FORMAT='${time:format string}'
```

```bash
export ROSCONSOLE_FORMAT='${walltime:format string}'
```

--------------------------------

### Named Logging Macros

Source: http://wiki.ros.org/rosconsole

These macros allow logging to specific, named child loggers, enabling finer-grained control over log output configuration. The logger name is a string that is appended to the base logger name.

```APIDOC
## Named Logging Macros

### Description
Allows logging to a specific named logger, which is a child of the default logger. This enables custom configuration for different log sources.

### Macros
- `ROS_DEBUG_NAMED(name, ...)`
- `ROS_INFO_NAMED(name, ...)`
- `ROS_WARN_NAMED(name, ...)`
- `ROS_ERROR_NAMED(name, ...)`
- `ROS_FATAL_NAMED(name, ...)`
- `ROS_DEBUG_STREAM_NAMED(name, args)`
- `ROS_INFO_STREAM_NAMED(name, args)`
- `ROS_WARN_STREAM_NAMED(name, args)`
- `ROS_ERROR_STREAM_NAMED(name, args)`
- `ROS_FATAL_STREAM_NAMED(name, args)`

### Example Usage
```cpp
#include <ros/console.h>

ROS_DEBUG_NAMED("my_module", "Debug message from my_module.");
ROS_INFO_STREAM_NAMED("network", "Connection status: " << "OK");
```

### Output
Logs are directed to `ros.<your_package_name>.<name>`.
```

--------------------------------

### Conditional Named ROS Logging Macros

Source: http://wiki.ros.org/rosconsole

Combines named logging with conditional output. Logs are directed to a specific logger and only appear if the condition is met.

```cpp
#include <ros/console.h>
ROS_DEBUG_COND_NAMED(x < 0, "test_only", "Uh oh, x = %d, this is bad", x);
ROS_DEBUG_STREAM_COND_NAMED(x < 0, "test_only", "Uh oh, x = " << x << ", this is bad");
```

--------------------------------

### Throttled ROS Logging Macros

Source: http://wiki.ros.org/rosconsole

These macros limit log output to at most once per specified period. Ideal for preventing excessive logs during continuous events.

```cpp
while (true)
{
  ROS_DEBUG_THROTTLE(60, "This message will print every 60 seconds");
}
```

--------------------------------

### Delayed Throttled ROS Logging Macros

Source: http://wiki.ros.org/rosconsole

Similar to throttled logging, but ensures no message is printed until the specified period has elapsed. Useful for periodic status updates after an initial delay.

```cpp
while (!ros::service::waitForService("add_two_ints", ros::Duration(0.1)) && ros::ok())
{
  // This message will print every 10 seconds.
  // The macro will have no effect the first 10 seconds.
  // In other words, if the service is not available, the message will be
  // printed at times 10, 20, 30, ...
  ROS_DEBUG_DELAYED_THROTTLE(10, "Waiting for service 'add_two_ints'");
}
```

--------------------------------

### Conditional Named Logging Macros

Source: http://wiki.ros.org/rosconsole

Combines conditional logging with named loggers. Messages are logged only if the condition is true and directed to the specified named logger.

```APIDOC
## Conditional Named Logging Macros

### Description
Logs a message to a specific named logger only if the provided condition evaluates to true.

### Macros
- `ROS_DEBUG_COND_NAMED(cond, name, ...)`
- `ROS_INFO_COND_NAMED(cond, name, ...)`
- `ROS_WARN_COND_NAMED(cond, name, ...)`
- `ROS_ERROR_COND_NAMED(cond, name, ...)`
- `ROS_FATAL_COND_NAMED(cond, name, ...)`
- `ROS_DEBUG_STREAM_COND_NAMED(cond, name, args)`
- `ROS_INFO_STREAM_COND_NAMED(cond, name, args)`
- `ROS_WARN_STREAM_COND_NAMED(cond, name, args)`
- `ROS_ERROR_STREAM_COND_NAMED(cond, name, args)`
- `ROS_FATAL_STREAM_COND_NAMED(cond, name, args)`

### Example Usage
```cpp
#include <ros/console.h>

int y = 10;
ROS_DEBUG_COND_NAMED(y > 5, "high_values", "y is greater than 5: %d", y);
ROS_INFO_STREAM_COND_NAMED(y == 10, "exact_value", "y is exactly: " << y);
```
```

--------------------------------

### Conditional Logging Macros

Source: http://wiki.ros.org/rosconsole

These macros log messages only if a specified condition is true. The condition is evaluated only if the logging statement itself is enabled, providing an efficient way to log based on runtime state.

```APIDOC
## Conditional Logging Macros

### Description
Logs a message only if the provided condition evaluates to true. The condition is only checked if the logging level is enabled.

### Macros
- `ROS_DEBUG_COND(cond, ...)`
- `ROS_INFO_COND(cond, ...)`
- `ROS_WARN_COND(cond, ...)`
- `ROS_ERROR_COND(cond, ...)`
- `ROS_FATAL_COND(cond, ...)`
- `ROS_DEBUG_STREAM_COND(cond, args)`
- `ROS_INFO_STREAM_COND(cond, args)`
- `ROS_WARN_STREAM_COND(cond, args)`
- `ROS_ERROR_STREAM_COND(cond, args)`
- `ROS_FATAL_STREAM_COND(cond, args)`

### Example Usage
```cpp
#include <ros/console.h>

int x = -5;
ROS_DEBUG_COND(x < 0, "x is negative: %d", x);
ROS_INFO_STREAM_COND(x > 0, "x is positive: " << x);
```
```

--------------------------------

### Shut Down ROS Logging Subsystem in C++

Source: http://wiki.ros.org/rosconsole

Call this C++ function to immediately stop all ROS logging. This is useful for clean shutdowns.

```cpp
ros::console::shutdown();
```

--------------------------------

### Throttle Logging Macros

Source: http://wiki.ros.org/rosconsole

These macros limit the frequency of log messages. A message will be printed at most once per specified period, preventing excessive logging during high-frequency events.

```APIDOC
## Throttle Logging Macros

### Description
Logs a message at most once per specified time period. This is useful for preventing log spam from frequently occurring events.

### Macros
- `ROS_DEBUG_THROTTLE(period, ...)`
- `ROS_INFO_THROTTLE(period, ...)`
- `ROS_WARN_THROTTLE(period, ...)`
- `ROS_ERROR_THROTTLE(period, ...)`
- `ROS_FATAL_THROTTLE(period, ...)`
- `ROS_DEBUG_STREAM_THROTTLE(period, args)`
- `ROS_INFO_STREAM_THROTTLE(period, args)`
- `ROS_WARN_STREAM_THROTTLE(period, args)`
- `ROS_ERROR_STREAM_THROTTLE(period, args)`
- `ROS_FATAL_STREAM_THROTTLE(period, args)`
- `ROS_DEBUG_THROTTLE_NAMED(period, name, ...)`
- `ROS_INFO_THROTTLE_NAMED(period, name, ...)`
- `ROS_WARN_THROTTLE_NAMED(period, name, ...)`
- `ROS_ERROR_THROTTLE_NAMED(period, name, ...)`
- `ROS_FATAL_THROTTLE_NAMED(period, name, ...)`
- `ROS_DEBUG_STREAM_THROTTLE_NAMED(period, name, args)`
- `ROS_INFO_STREAM_THROTTLE_NAMED(period, name, args)`
- `ROS_WARN_STREAM_THROTTLE_NAMED(period, name, args)`
- `ROS_ERROR_STREAM_THROTTLE_NAMED(period, name, args)`
- `ROS_FATAL_STREAM_THROTTLE_NAMED(period, name, args)`

### Parameters
- `period` (ros::Duration): The minimum time interval between log messages.

### Example Usage
```cpp
#include <ros/console.h>
#include <ros/duration.h>

while (true) {
  ROS_INFO_THROTTLE(10.0, "This message prints every 10 seconds.");
}
```
```

--------------------------------

### Conditional ROS Logging Macros

Source: http://wiki.ros.org/rosconsole

These macros log messages only if a specified condition is true. The condition is evaluated only if the logging statement is enabled.

```cpp
#include <ros/console.h>
ROS_DEBUG_COND(x < 0, "Uh oh, x = %d, this is bad", x);
ROS_DEBUG_STREAM_COND(x < 0, "Uh oh, x = " << x << ", this is bad");
```

--------------------------------

### Change logger level dynamically in C++

Source: http://wiki.ros.org/rosconsole

Set the logger level for a specific logger name and notify listeners if the levels have changed. Ensure to call notifyLoggerLevelsChanged() if logger levels are modified after initialization.

```c++
#include <ros/console.h>
if( ros::console::set_logger_level(ROSCONSOLE_DEFAULT_NAME, ros::console::levels::Debug) ) {
   ros::console::notifyLoggerLevelsChanged();
}
```
Tokens:
Raw