Logging Data

The Stretch software stack uses a combination of standard python loggers and ros2 logging infrastructure. A global logging configuration is saved in stretch4_body.core.robot_params.RobotParams. Any object derived from Device will inherit this configuration, and the logs can be reviewed using the stretch_body_server interface. Monitoring the output of stretch4_body is useful for debugging robot motion and identifying underlying hardware faults. Standard ROS 2 tooling can be used for debugging higher-level ROS 2 node behaviors.

High-Level Design Summary

• Configuration via DictConfig: The logger's configuration is managed centrally within stretch4_body.core.robot_params.RobotParams. At initialization, RobotParams loads the system defaults (defined in nominal_system_params), which dictate logger formats, handlers, and save paths.
• Handlers:

  • Console Handler: Configured via HelloLoggerScreen, providing color-coded, human-readable logging to the terminal/IDE.
  • Rotating File Handler: Writing to stretch_body_server.log by default (formatted using HelloLoggerFile). It implements automatic rotation when logs exceed 10MB, retaining up to 10 historical backups to prevent logs from overtaking disk space.
• Log Locations: Logs are saved inside the stretch_user directory inside the stretch_user/log directory. Stretch_body_server logs from an active session are recorded in stretch_user/log/stretch_body_logger/stretch_body_server.log. Archived logs from previous sessions are saved to stretch_user/log/stretch_body_logger/stretch_body_server_archived/.
• Component Loggers: Subsystem and module components are subclasses of stretch4_body.core.device.Device. The base Device class orchestrates the logging.config.dictConfig(...) initialization and exposes self.logger = logging.getLogger(self.name) automatically to all subclasses.
• Throttling Filter: To prevent spamming (such as missed loop warnings occurring extremely rapidly), standard device loggers initialize with a custom LoggerThrottleFilter instance. You can throttle any log message by passing extra={'throttle_s': <seconds>} during the log call. The filter tracks log frequency using a combination of the calling file name and the exact line number to accurately throttle specific messages without affecting others.

Understanding Stretch Behavior using Logs

Inspecting the main log (stretch_body_server.log) helps unravel mysterious behavior or failures on the robot:

1. Startup Procedures: Device initialization attempts logs parameters that could not be loaded or hardware subsystems that could not be reached. Error messages indicating "Parameters for device [xxx] not found" typically mean YAML configurations are out of sync or corrupted.
2. Loop Iterations and Control Rates: Tools like LoopStats will log WARNING level messages directly to the logger if they cannot maintain their target refresh rate (e.g., due to CPU spikes).
3. Deprecation/Configuration Drift: Core utilities log errors and force-quit if they detect deprecated settings (such as outdated collision/contact force thresholds or outdated URDF kinematic tree joint names).
4. Behavior Analysis: Since every sub-component (e.g., pimu, arm, lift) is uniquely named, it is straightforward to grep the log file for specific subsystems to see exactly when they fault, hit limits, or drop communication.

How to Add New Logs

Because stretch4_body handles the logging.config execution for you globally, adding new logs is seamless.

Inside a Device subclass

If your class derives from stretch4_body.core.device.Device, you already have a pre-configured logger:

class MyNewSensor(Device):
    def __init__(self):
        super().__init__('my_sensor')
        self.logger.info("Initializing MyNewSensor")

    def poll_data(self):
        try:
            # Polling hardware...
            self.logger.debug("Successfully polled hardware.")
        except Exception as e:
            # Logs the error at most once every 5.0 seconds
            self.logger.error(f"Failed pulling data: {e}", extra={'throttle_s': 5.0})

In a standalone script or module

If you're writing a utility script or an isolated class, you can setup logging to integrate into stretch4_body with the following example:

import logging
from stretch4_body.core.robot_params import RobotParams

def setup_logging():
    try:
        _, robot_params = RobotParams.get_params()
        logging_params = robot_params['logging'].copy()
        # Update filename to be specific to this tool
        if 'file_handler' in logging_params['handlers']:
            logging_params['handlers']['file_handler']['filename'] = hello_utils.get_stretch_directory('log/stretch_body_logger/') + 'stretch4_urdf.log'
        logging.config.dictConfig(logging_params)
    except:
        # Fallback to basic configuration if robot_params cannot be loaded
        logging.basicConfig(
            level=logging.INFO,
            format="[%(asctime)s] [%(name)s] [%(levelname)s]: %(message)s",
            datefmt="%m/%d/%Y %H:%M:%S"
        )

Modifying Log Verbosity Dynamically

During testing or debugging, you can elevate the verbosity for the console handler to include deeper DEBUG traces:

from stretch4_body.core.robot_params import RobotParams
RobotParams.set_logging_level('DEBUG', handler='console_handler')

Interacting with Server Logs

You can easily launch the server and view its logs directly using the stretch_body_server command line tool:

• stretch_body_server --print: Use this command to live-tail the server's active log. It will gracefully track internal file rotation boundaries and print using native color coding to distinguish INFO (white), WARNING (yellow), and ERROR (red). If no active server is detected locally, it will intelligently extract and print the final 10 lines of the most recent .tar.gz archived log instead to provide immediate context on what just happened.
• stretch_body_server --launch: This command spins up the Stretch Body Server directly in the terminal. It maintains the same logging and log aggregation behavior as the background process, but will additionally surface standard print statements.