feat: add env variable to configure flushing interval

[Achllle]

Description

Adds the option to configure the logging interval to file using an environment variable RCL_LOGGING_SPDLOG_FLUSH_PERIOD_SECONDS. Previously this was hardcoded to 5s, which is the default to maintain backwards compatibility. This allows the user to change the interval to a different value, notably including 0, which means unbuffered writes. An example where this is useful is on discourse
Added documentation for the experimental behavior env flag that was not documented yet.

Testing steps

Save the below Dockerfile

FROM ros:rolling

# Install dependencies
RUN apt-get update && apt-get install -y \
    ros-rolling-demo-nodes-cpp \
    multitail \
    git \
    python3-colcon-common-extensions \
    python3-rosdep \
    && rm -rf /var/lib/apt/lists/*

# Create workspace
WORKDIR /ros2_ws

# Clone the fork with configurable flush period
RUN git clone --branch configurable_flush_period \
    https://github.com/Achllle/rcl_logging.git src/rcl_logging

RUN apt-get update && rosdep install --from-paths src --ignore-src -r -y

# Build rcl_logging overlay
RUN . /opt/ros/rolling/setup.sh && \
    colcon build --packages-up-to rcl_logging_spdlog

# Create launch file
RUN mkdir -p /ros2_ws/launch
COPY <<EOF /ros2_ws/launch/demo.launch.py
from launch import LaunchDescription
from launch_ros.actions import Node

def generate_launch_description():
    return LaunchDescription([
        Node(
            package='demo_nodes_cpp',
            executable='talker',
            name='my_talker_node',
            output='screen',
            emulate_tty=True,
        ),
        Node(
            package='demo_nodes_cpp',
            executable='listener',
            name='my_listener_node',
            output='screen',
            emulate_tty=True,
        )
    ])
EOF

# Create entrypoint script
COPY <<EOF /ros2_ws/entrypoint.sh
#!/bin/bash
set -e

# Source the overlay
source /ros2_ws/install/setup.bash

# Set log directory
export ROS_LOG_DIR=\${ROS_LOG_DIR:-/tmp/ros_logs}
mkdir -p "\$ROS_LOG_DIR"

# Print configuration
echo "=== RCL Logging Demo ==="
echo "RCL_LOGGING_SPDLOG_FLUSH_PERIOD_SECONDS=\${RCL_LOGGING_SPDLOG_FLUSH_PERIOD_SECONDS:-not set (default 5s)}"
echo "ROS_LOG_DIR=\$ROS_LOG_DIR"
echo "========================"
echo ""

# Launch nodes in background, redirect output to /dev/null
ros2 launch /ros2_ws/launch/demo.launch.py > /dev/null 2>&1 &
LAUNCH_PID=\$!

# Wait for log files to appear
sleep 2

# Use multitail to follow all log files in ROS_LOG_DIR
exec multitail -Q 1 "\$ROS_LOG_DIR/*.log"
EOF

RUN chmod +x /ros2_ws/entrypoint.sh

# Default environment
ENV ROS_LOG_DIR=/tmp/ros_logs

ENTRYPOINT ["/ros2_ws/entrypoint.sh"]

then docker build -t rcl-logging-demo .

• default behavior: docker run -it --rm rcl-logging-demo:latest: logs are buffered for 5s
• try other interval: docker run -it --rm -e RCL_LOGGING_SPDLOG_FLUSH_PERIOD_SECONDS=0 rcl-logging-demo:latest: logs are unbuffered

Did you use Generative AI?

yes, Claude Opus 4.5

Additional Information

relevant issue about config file: #92

[fujitatomoya]

There have been several issues and discussions around configuring the logging implementation. The original plan (see #92) was to use the config file argument as a generic ROS 2 logging configuration layer that would translate settings to the specific backend implementation. However, that work was never implemented, and as far as I can tell, no one is actively working on it. Given that, I think this spdlog-specific configuration via an environment variable is a practical and useful addition for ROS 2 applications that depend on the spdlog backend today.

CC: @wjwwood @ahcorde @mjcarroll

[fujitatomoya]

@Achllle thanks for the fix. i am good to go with this, but i would like to have another approval from other maintainers before merge. i will go ahead to start the CI.

[fujitatomoya]

Pulls: #139
Gist: https://gist.githubusercontent.com/fujitatomoya/d6865b43fee22387bf04ec21ac5fb6d8/raw/f7bff7e897e32b5cc7f1541ee14bcb4b5f42ffae/ros2.repos
BUILD args: --packages-above-and-dependencies rcl_logging_spdlog
TEST args: --packages-above rcl_logging_spdlog
ROS Distro: rolling
Job: ci_launcher
ci_launcher ran: https://ci.ros2.org/job/ci_launcher/18146

• Linux
• Linux-aarch64
• Linux-rhel
• Windows

[ahcorde]

Pulls: #139
Gist: https://gist.githubusercontent.com/ahcorde/e998924c08ca7fdd03e851c12795665b/raw/f7bff7e897e32b5cc7f1541ee14bcb4b5f42ffae/ros2.repos
BUILD args: --packages-above-and-dependencies rcl_logging_spdlog
TEST args: --packages-above rcl_logging_spdlog
ROS Distro: rolling
Job: ci_launcher
ci_launcher ran: https://ci.ros2.org/job/ci_launcher/18151

• Linux
• Linux-aarch64
• Linux-rhel
• Windows

[wjwwood]

There have been several issues and discussions around configuring the logging implementation. The original plan (see #92) was to use the config file argument as a generic ROS 2 logging configuration layer that would translate settings to the specific backend implementation. However, that work was never implemented, and as far as I can tell, no one is actively working on it. Given that, I think this spdlog-specific configuration via an environment variable is a practical and useful addition for ROS 2 applications that depend on the spdlog backend today.

CC: @wjwwood @ahcorde @mjcarroll

Works for me. While I would like to see us have the logging config, I think I would be more concerned with a larger feature revolving around logging than this. Pragmatically, this is a reasonable compromise.

[ahcorde]

Test are failing

• rcl_logging_spdlog.LoggingTest.init_with_invalid_flush_period_non_integer
• rcl_logging_spdlog.LoggingTest.init_with_invalid_flush_period_trailing_chars

[Achllle]

Apologies, that's on me - the failures went unnoticed because I saw linter and copyright test failures which I knew were related to building without installing. Addressed in f2efa39.

[fujitatomoya]

lgtm with green CI.

[fujitatomoya]

Pulls: #139
Gist: https://gist.githubusercontent.com/fujitatomoya/08079122c6f6beb237318946fdc27af2/raw/f7bff7e897e32b5cc7f1541ee14bcb4b5f42ffae/ros2.repos
BUILD args: --packages-above-and-dependencies rcl_logging_spdlog
TEST args: --packages-above rcl_logging_spdlog
ROS Distro: rolling
Job: ci_launcher
ci_launcher ran: https://ci.ros2.org/job/ci_launcher/18359

• Linux
• Linux-aarch64
• Linux-rhel
• Windows

[fujitatomoya]

@Achllle can you take a look at ros2/ros2_documentation#6276?

[Achllle]

Thanks for updating the docs - I should have realized to do so.