Update documentation to show how to use per-logger configuration. (#819)

This functionality was added in ros2/rcl#664 . While we are in here, revamp the logging documentation to be more correct as of Foxy. Also remove a bunch of redundant information in Logging.rst that is already in Logging-and-logger-configuration. Signed-off-by: Chris Lalancette <[email protected]>
ros2 · Jul 15, 2020 · d78edcc · d78edcc
1 parent 46533e8
commit d78edcc
Show file tree

Hide file tree

Showing 5 changed files with 98 additions and 68 deletions.
diff --git a/source/Concepts/Logging.rst b/source/Concepts/Logging.rst
@@ -59,63 +59,3 @@ Logging usage
 
     * See the `rclpy examples <https://github.com/ros2/examples/blob/master/rclpy/services/minimal_client/examples_rclpy_minimal_client/client.py>`__ for example usage of a node's logger.
     * See the `rclpy tests <https://github.com/ros2/rclpy/blob/master/rclpy/test/test_logging.py>`__ for example usage of keyword arguments (e.g. ``skip_first``, ``once``).
-
-Logger configuration
---------------------
-
-.. _logging-command-line-configuration-of-the-default-severity-level:
-
-Command line configuration of the default severity level
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-As of the Bouncy ROS 2 release, the default severity level for loggers can be configured from the command line with the following, for example (the level string is not case sensitive):
-
-.. tabs::
-
-  .. group-tab:: Bouncy+
-
-    .. code-block:: bash
-
-      ros2 run demo_nodes_cpp listener __log_level:=debug
-
-  .. group-tab:: Eloquent+
-
-    .. code-block:: bash
-
-      ros2 run demo_nodes_cpp listener --ros-args --log-level DEBUG
-
-This will affect all loggers that have not explicitly been configured to use a particular severity level.
-Configuration of specific loggers from the command line is forthcoming.
-
-Programmatic configuration of individual loggers
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Logger configuration is still under development.
-For now, the severity level of individual loggers can be configured programmatically with, e.g.:
-
-.. tabs::
-
-  .. group-tab:: C++
-
-    .. code-block:: bash
-
-       rcutils_logging_set_logger_level("logger_name", RCUTILS_LOG_SEVERITY_DEBUG);
-
-  .. group-tab:: Python
-
-    .. code-block:: bash
-
-       logger.set_level(rclpy.logging.LoggingSeverity.DEBUG)
-       rclpy.logging.set_logger_level('logger_name', rclpy.logging.LoggingSeverity.DEBUG)
-
-The `logging demo <../Tutorials/Logging-and-logger-configuration>` provides an example of manually exposing a service so that loggers can be configured externally; in the future we expect runtime configuration capabilities of loggers to be exposed automatically.
-
-.. _logging-console-output-configuration:
-
-Console output configuration
-----------------------------
-
-By default, console output will be formatted to include the message severity, logger name, and the message.
-Information such as the file name, function name and line number of the log call are also available.
-Custom console output format can be configured with the ``RCUTILS_CONSOLE_OUTPUT_FORMAT`` environment variable: see the `rcutils documentation for details <https://docs.ros2.org/latest/api/rcutils/logging_8h.html#a27340ac73188b1cf8d9cb96d86c76694>`__.
-As ``rclpy`` and ``rclcpp`` both use ``rcutils`` for logging, this will affect all Python and C++ nodes.
diff --git a/source/Releases/Release-Galactic-Geochelone.rst b/source/Releases/Release-Galactic-Geochelone.rst
@@ -20,7 +20,18 @@ TBD
 New features in this ROS 2 release
 ----------------------------------
 
-TBD
+Ability to specify per-logger log levels
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is now possible to specify different logging levels for different loggers on the command line:
+
+.. code-block:: bash
+
+   ros2 run demo_nodes_cpp talker --ros-args --log-level WARN --log-level talker:=DEBUG
+
+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.
+
 
 Changes since the Foxy release
 ------------------------------

diff --git a/source/Tutorials/Creating-Your-First-ROS2-Package.rst b/source/Tutorials/Creating-Your-First-ROS2-Package.rst
@@ -17,7 +17,7 @@ Background
 ----------
 
 1 What is a ROS 2 package?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 A package can be considered a container for your ROS 2 code.
 If you want to be able to install your code or share it with others, then you’ll need it organized in a package.

diff --git a/source/Tutorials/Logging-and-logger-configuration.rst b/source/Tutorials/Logging-and-logger-configuration.rst
@@ -113,12 +113,22 @@ Restart the demo including the following command line argument:
 This configures the default severity for any unset logger to the debug severity level.
 You should see debug output from loggers from the demo itself and from the ROS 2 core.
 
-The ability to configure specific loggers from the command line is forthcoming.
+As of the Galactic ROS 2 release, the severity level for individual loggers can be configured from the command-line.
+Restart the demo including the following command line arguments:
+
+.. tabs::
+
+  .. group-tab:: Galactic and newer
+
+    .. code-block:: bash
+
+       ros2 run logging_demo logging_demo_main --ros-args --log-level logger_usage_demo:=debug
+
 
 Console output formatting
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you would like more or less verbose formatting, you can use `the RCUTILS_CONSOLE_OUTPUT_FORMAT environment variable <logging-console-output-configuration>`.
+If you would like more or less verbose formatting, you can use RCUTILS_CONSOLE_OUTPUT_FORMAT environment variable.
 For example, to additionally get the timestamp and location of the log calls, stop the demo and restart it with the environment variable set:
 
 .. tabs::
@@ -182,10 +192,41 @@ You should see that debug, warn, error and fatal logs aren't colorized now.
    If it is forced you will get a new warning saying that colorization failed.
    The default behavior already checks if the output is a console or not, so forcing colorization is not recommended.
 
+Default stream for console output
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In Dashing and Eloquent, the output from DEBUG and INFO severity are printed out to stdout, and the output from WARN, ERROR, and FATAL are printed to stderr.
+In Foxy and later, the output from all debug levels goes to stderr by default.  It is possible to force all output to go to stdout by setting the ``RCUTILS_LOGGING_USE_STDOUT`` environment variable to ``1``.
+For example:
+
+.. tabs::
+
+  .. group-tab:: Linux
+
+    .. code-block:: bash
+
+      export RCUTILS_LOGGING_USE_STDOUT=1
+
+  .. group-tab:: macOS
+
+    .. code-block:: bash
+
+      export RCUTILS_LOGGING_USE_STDOUT=1
+
+  .. group-tab:: Windows
+
+    .. code-block:: bash
+
+      set "RCUTILS_LOGGING_USE_STDOUT=1"
+
+
 Line buffered console output
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-By default, info and debug log calls aren't line buffered.
+Dashing and Eloquent
+""""""""""""""""""""
+
+By default, INFO and DEBUG log calls aren't line buffered.
 You can force it using ``RCUTILS_CONSOLE_STDOUT_LINE_BUFFERED`` environment variable.
 For example:
 
@@ -207,8 +248,46 @@ For example:
 
     .. code-block:: bash
 
-       # set "RCUTILS_CONSOLE_STDOUT_LINE_BUFFERED=1"
-       ros2 run logging_demo logging_demo_main
+      set "RCUTILS_CONSOLE_STDOUT_LINE_BUFFERED=1"
+
+Then run:
+
+.. code-block:: bash
+
+    ros2 run logging_demo logging_demo_main
 
 The output should look as before.
 For details about I/O buffering, see `buffering concepts <https://www.gnu.org/software/libc/manual/html_node/Buffering-Concepts.html>`_.
+
+Foxy
+""""
+
+By default, all logging output is unbuffered.
+You can force it to be buffered by setting the ``RCUTILS_LOGGING_BUFFERED_STREAM`` environment variable to 1.
+For example:
+
+.. tabs::
+
+  .. group-tab:: Linux
+
+    .. code-block:: bash
+
+      export RCUTILS_LOGGING_BUFFERED_STREAM=1
+
+  .. group-tab:: macOS
+
+    .. code-block:: bash
+
+      export RCUTILS_LOGGING_BUFFERED_STREAM=1
+
+  .. group-tab:: Windows
+
+    .. code-block:: bash
+
+      set "RCUTILS_LOGGING_BUFFERED_STREAM=1"
+
+Then run:
+
+.. code-block:: bash
+
+    ros2 run logging_demo logging_demo_main
diff --git a/source/Tutorials/Node-arguments.rst b/source/Tutorials/Node-arguments.rst
@@ -110,7 +110,7 @@ The following example will both change the node name and remap a topic (node and
 Logger configuration
 --------------------
 
-See ``--log-level`` argument usage in `the logging page <logging-command-line-configuration-of-the-default-severity-level>`.
+See ``--log-level`` argument usage in `the logging page <Logging-and-logger-configuration>`.
 
 Parameters
 ----------