diff --git a/source/Releases/Release-Galactic-Geochelone.rst b/source/Releases/Release-Galactic-Geochelone.rst index 06f4c6d09b4..a84f4c00a16 100644 --- a/source/Releases/Release-Galactic-Geochelone.rst +++ b/source/Releases/Release-Galactic-Geochelone.rst @@ -36,6 +36,18 @@ It is now possible to specify different logging levels for different loggers on The above command sets a global log level of WARN, but sets the log level of the talker node messages to DEBUG. The ``--log-level`` command-line option can be passed an arbitrary number of times to set different log levels for each logger. +Ability to configure logging directory through environment variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It is now possible to configure the logging directory through two environment variables: ``ROS_LOG_DIR`` and ``ROS_HOME``. +The logic is as follows: + +* Use ``$ROS_LOG_DIR`` if ``ROS_LOG_DIR`` is set and not empty. +* Otherwise, use ``$ROS_HOME/log``, using ``~/.ros`` for ``ROS_HOME`` if not set or if empty. + +Thus the default value stays the same: ``~/.ros/log``. + +Related PRs: `ros2/rcl_logging#53 `_ and `ros2/launch#460 `_. Changes since the Foxy release ------------------------------ diff --git a/source/Tutorials/Logging-and-logger-configuration.rst b/source/Tutorials/Logging-and-logger-configuration.rst index 66959fdf535..dadbdfe976d 100644 --- a/source/Tutorials/Logging-and-logger-configuration.rst +++ b/source/Tutorials/Logging-and-logger-configuration.rst @@ -19,6 +19,76 @@ Over time you will see output from various log calls with different properties. To start with you will only see output from log calls with severity ``INFO`` and above (``WARN``, ``ERROR``, ``FATAL``). Note that the first message will only be logged once, though the line is reached on each iteration, as that is a property of the log call used for that message. +Logging directory configuration +------------------------------- + +.. note:: + + The logging directory can only be configured starting in Galactic. + +The logging directory can be configured through two environment variables: ``ROS_LOG_DIR`` and ``ROS_HOME``. +The logic is as follows: + +* Use ``$ROS_LOG_DIR`` if ``ROS_LOG_DIR`` is set and not empty. +* Otherwise, use ``$ROS_HOME/log``, using ``~/.ros`` for ``ROS_HOME`` if not set or if empty. + +For example, to set the logging directory to ``~/my_logs``: + +.. tabs:: + + .. group-tab:: Linux + + .. code-block:: bash + + export ROS_LOG_DIR=~/my_logs + ros2 run logging_demo logging_demo_main + + .. group-tab:: macOS + + .. code-block:: bash + + export ROS_LOG_DIR=~/my_logs + ros2 run logging_demo logging_demo_main + + .. group-tab:: Windows + + .. code-block:: bash + + set "ROS_LOG_DIR=~/my_logs" + ros2 run logging_demo logging_demo_main + +You will then find the logs under ``~/my_logs/``. + +Alternatively, you can set ``ROS_HOME`` and the logging directory will be relative to it (``$ROS_HOME/log``). +``ROS_HOME`` is intended to be used by anything that needs a base directory. +Note that ``ROS_LOG_DIR`` has to be either unset or empty. +For example, with ``ROS_HOME`` set to ``~/my_ros_home``: + +.. tabs:: + + .. group-tab:: Linux + + .. code-block:: bash + + export ROS_HOME=~/my_ros_home + ros2 run logging_demo logging_demo_main + + .. group-tab:: macOS + + .. code-block:: bash + + export ROS_HOME=~/my_ros_home + ros2 run logging_demo logging_demo_main + + .. group-tab:: Windows + + .. code-block:: bash + + set "ROS_HOME=~/my_ros_home" + ros2 run logging_demo logging_demo_main + +You will then find the logs under ``~/my_ros_home/log/``. + Logger level configuration: programmatically --------------------------------------------