General information about this repository, including legal information and known issues/limitations, are given in README.md in the repository root.

The diagnostic_aggregator package

This package contains the aggregator_node. It listens to the diagnostic_msgs/DiagnosticArray messages on the /diagnostics topic and aggregates and published them on the /diagnostics_agg topic.

One use case for this package is to aggregate the diagnostics of a robot. Aggregation means that the diagnostics of the robot are grouped by various aspects, like their location on the robot, their type, etc. This will allow you to easily see which part of the robot is causing problems.

Example

In our example, we are looking at a robot with arms and legs. The robot has two of each, one on each side. The robot also 4 camera sensors, one left and one right and one in the front and one in the back. These are all the available diagnostic sources:

/arms/left/motor
/arms/right/motor
/legs/left/motor
/legs/right/motor
/sensors/left/cam
/sensors/right/cam
/sensors/front/cam
/sensors/rear/cam

We want to group the diagnostics by

• all sensors
• all motors
• left side of the robot
• right side of the robot

We can achieve that by creating a configuration file that looks like this (see example_analyzers.yaml):

analyzers:
  ros__parameters:
    path: Aggregation
    arms:
      type: diagnostic_aggregator/GenericAnalyzer
      path: Arms
      startswith: [ '/arms' ]
    legs:
      type: diagnostic_aggregator/GenericAnalyzer
      path: Legs
      startswith: [ '/legs' ]
    sensors:
      type: diagnostic_aggregator/GenericAnalyzer
      path: Sensors
      startswith: [ '/sensors' ]
    motors:
      type: diagnostic_aggregator/GenericAnalyzer
      path: Motors
      contains: [ '/motor' ]
    topology:
      type: 'diagnostic_aggregator/AnalyzerGroup'
      path: Topology
      analyzers:
        left:
          type: diagnostic_aggregator/GenericAnalyzer
          path: Left
          contains: [ '/left' ]
        right:
          type: diagnostic_aggregator/GenericAnalyzer
          path: Right
          contains: [ '/right' ]

Based on this configuration, the rqt_robot_monitor will display the diagnostics information in a well-arranged manner as follows:

Note that it will also display the highest state per group to allow you to see at a glance which part of the robot is not working properly. For example in the above image, the left side of the robot is not working properly, because the left camera is in the ERROR state.

Analyzers

The aggregator_node will load analyzers to process the diagnostics data. An analyzer is a plugin that inherits from the diagnostic_aggregator::Analyzer class. Analyzers must be implemented in packages that directly depend on pluginlib and diagnostic_aggregator.

The diagnostic_aggregator::Analyzer class is purely virtual and derived classes must implement the following methods:

• init() - Analyzer is initialized with base path and namespace
• match() - Returns true if the analyzer is interested in the status message
• analyze() - Returns true if the analyzer will analyze the status message
• report() - Returns results of analysis as vector of status messages
• getPath() - Returns the prefix path of the analyzer (e.g., “/robot/motors/”)
• getName() - Returns the name of the analyzer (e.g., “Motors”)

Analyzers can choose the value of the error level of their output. Usually, the error level of the output is the highest error level of the input. The analyzers are responsible for setting the name of each item in the output correctly.

Using the aggregator_node

Configuration

The aggregator_node can be configured at launch time like in this example:

pub_rate: 1.0 # Optional, defaults to 1.0
base_path: 'PRE' # Optional, defaults to ""
analyzers:
  motors:
    type: PR2MotorsAnalyzer
  joints:
    type: GenericAnalyzer
    path: 'Joints'
    regex: 'Joint*'

The pub_rate parameter is the rate at which the aggregated diagnostics will be published. The base_path parameter is the prefix that will be added to the name of each item in the output.

Under the analyzers key, you can specify the analyzers that you want to use. Each analyzer must have a unique name. Under the name, you must specify the type of the analyzer. This must be the name of the class that implements the analyzer. Additional parameters depend on the type of the analyzer.

Any diagnostic item that is not matched by any analyzer will be published by an “Other” analyzer. Items created by the “Other” analyzer will go stale after 5 seconds.

The critical parameter makes the aggregator react immediately to a degradation in diagnostic state. This is useful if the toplevel state is parsed by a watchdog for example.

Launching

You can launch the aggregator_node like this (see example.launch.py.in):

    aggregator = launch_ros.actions.Node(
        package='diagnostic_aggregator',
        executable='aggregator_node',
        output='screen',
        parameters=[analyzer_params_filepath])
    return launch.LaunchDescription([
        aggregator,
    ])

You can add analyzers at runtime using the add_analyzer node like this (see example.launch.py.in):

    add_analyzer = launch_ros.actions.Node(
        package='diagnostic_aggregator',
        executable='add_analyzer',
        output='screen',
        parameters=[add_analyzer_params_filepath])
    return launch.LaunchDescription([
        add_analyzer,
    ])

This node updates the parameters of the aggregator_node by calling the service /analyzers/set_parameters_atomically. The aggregator_node will detect when a parameter-event has introduced new parameters to it. When this happens the aggregator_node will reload all analyzers based on its new set of parameters. Adding analyzers this way can be done at runtime and can be made conditional.

In the example, add_analyzer will add an analyzer for diagnostics that are marked optional:

/**:
  ros__parameters:
    optional:
      type: diagnostic_aggregator/GenericAnalyzer
      path: Optional
      startswith: [ '/optional' ]

This will move the /optional/runtime/analyzer diagnostic from the “Other” to “Aggregation” where it will not go stale after 5 seconds and will be taken into account for the toplevel state.

Basic analyzers

The diagnostic_aggregator package provides a few basic analyzers that you can use to aggregate your diagnostics.

GenericAnalyzer

The diagnostic_aggregator::GenericAnalyzer class is a basic analyzer that can be configured to match diagnostics based on their name. By defining a path parameter, you can specify the prefix that will be added to the name of each item in the output. This way you can group diagnostics by their location or other aspects as demonstrated in the example.

AnalyzerGroup

The diagnostic_aggregator::AnalyzerGroup class is a basic analyzer that can be configured to group other analyzers. It has itself an analyzers parameter that can be filled with other analyzers to group them.

An example of this is (see example_analyzers.yaml):

    topology:
      type: 'diagnostic_aggregator/AnalyzerGroup'
      path: Topology
      analyzers:
        left:
          type: diagnostic_aggregator/GenericAnalyzer
          path: Left
          contains: [ '/left' ]
        right:
          type: diagnostic_aggregator/GenericAnalyzer
          path: Right
          contains: [ '/right' ]

DiscardAnalyzer

The diagnostic_aggregator::DiscardAnalyzer class is a basic analyzer that discards all diagnostics that match it. This can be useful if you want to ignore some diagnostics.

IgnoreAnalyzer

The diagnostic_aggregator::IgnoreAnalyzer will ignore all parameters in its namespace and not match anything.

The difference between the DiscardAnalyzer and the IgnoreAnalyzer is that the DiscardAnalyzer will match diagnostics and discard them, while the IgnoreAnalyzer will not match anything. This means that things that are ignored by the IgnoreAnalyzer will still be published in the “Other” analyzer, while things that are discarded by the DiscardAnalyzer will not be published at all.

ROS API

## aggregator_node

Subscribed Topics

• diagnostics (diagnostic_msgs/DiagnosticArray) - The diagnostics to be aggregated

Published Topics

• diagnostics_agg (diagnostic_msgs/DiagnosticArray) - The aggregated diagnostics
• diagnostics_toplevel_state (diagnostic_msgs/DiagnosticStatus) - The highest state of the aggregated diagnostics

Parameters

• pub_rate (double, default: 1.0) - The rate at which the aggregated diagnostics will be published
• base_path (string, default: “”) - The prefix that will be added to the name of each item in the output
• analyzers (map, default: {}) - The analyzers that will be used to aggregate the diagnostics

Tutorials

TODO: Port tutorials #contributions-welcome

Changelog for package diagnostic_aggregator

4.3.1 (2024-07-30)

3.2.1 (2024-06-27)

• Add add_analyzer functionality (#329)
• Aggregator: publish diagnostics_toplevel_state immediately on every degradation (#324)
• Contributors: MartinCornelis2, Tim Clephas

3.2.0 (2024-03-22)

• Avoid rolling up an ERROR state when empty GenericAnalyzer blocks are marked discard_stale, or when all of their items are STALE. (#315)
• formatting fixes from PR324 (#327)
• Debugging instability introduced by #317 (#323)
• feat: publish top level msg when error is received (#317)
• Empty default aggregator base_path (#305)
• using defined state for stale (#298)
• Contributors: Andrew Symington, Christian Henkel, outrider-jhulas

3.1.2 (2023-03-24)

3.1.1 (2023-03-16)

• exporting dependency on pluginlib fixes #293 (#294)
• Secretly supporting galactic (#295)
• Linting additional package (#268)
• Fix code-analyser bug
• Maintainer update
• Contributors: Austin, Christian Henkel, Ralph Lange, Tim Clephas

3.1.0 (2023-01-26)

• Merge of foxy and humble history into rolling for future maintenance from one branch only.
• Adding READMEs to the repo (#270)
• License fixes (#263)
• Fix/cleanup ros1 (#257)
• Use regex to search AnalyzerGroup
• Contributors: Alberto Soragna, Austin, Christian Henkel, Keisuke Shima, Ralph Lange

3.0.0 (2022-06-10)

• Use node clock for diagnostic_aggregator and diagnostic_updater (#210)
• Contributors: Kenji Miyake

2.1.3 (2021-08-03)

2.1.2 (2021-03-03)

• Adapt new launch file syntax. (#190)
• Introduce history depth parameter for subscription. (#168)
• Contributors: Karsten Knese, Ryohsuke Mitsudome

2.1.1 (2021-01-28)

• Move Aggregator publishing to timer to allow subscription callback more processing time. (#180)
• Contributors: cdbierl

2.1.0 (2021-01-12)

• Update to latest ros2 rolling. (#177)
• Fix installation of diagnostic aggregator example. (#159)
• Restore alphabetical order. (#148)
• Aggregator bugfix, tests, and nicer example. (#147)

* Contributors: Arne Nordmann, Georg Bartels, Karsten Knese 2.0.9 (2022-11-12) ------------------

2.0.8 (2021-08-03)

2.0.7 (2021-03-04)

2.0.6 (2021-01-28)

• Move Aggregator publishing to timer to allow subscription callback more processing time. (#179)
• Contributors: cdbierl

2.0.5 (2021-01-06)

• Set aggregator subscription history depth to 1000. (#174)
• Contributors: cdbierl

2.0.4 (2020-08-05)

• Fix installation of diagnostic aggregator example. (#159) (#160)
• Contributors: Georg Bartels

2.0.3 (2020-07-09)

• restore alphabetical order (#148) (#150) Signed-off-by: Karsten Knese <<karsten.knese@us.bosch.com>>
• Fixes toplevel diagnostic status calculation (#149) See https://github.com/ros/diagnostics/issues/146 Signed-off-by: Arne Nordmann <<arne.nordmann@de.bosch.com>>
• Contributors: Arne Nordmann, Karsten Knese

2.0.2 (2020-06-03)

• 2.0.2
• Ros2 migrate diagnostic aggregator (#118) Co-authored-by: Arne Nordmann <<arne.nordmann@de.bosch.com>> Co-authored-by: Robin Vanhove <<1r0b1n0@gmail.com>>
• Contributors: Karsten Knese, Arne Nordmann, Robin Vanhove

2.0.1 (2020-06-03)

• Ros2 migrate diagnostic aggregator (#118)
• Contributors: Arne Nordmann, Robin Vanhove, Karsten Knese

1.9.3 (2018-05-02)

• Merge pull request #79 from nlamprian/indigo-devel Fixed base_path handling
• Merge pull request #82 from moriarty/fix-pluginlib-deprecated-headers [Aggregator] Fixes C++ Warnings (pluginlib)
• [Aggregator] Fixes C++ Warnings (pluginlib) This fixes the following warnings: warning: Including header <pluginlib/class_list_macros.h> is deprecated,include <pluginlib/class_list_macros.hpp> instead. [-Wcpp] warning: Including header <pluginlib/class_loader.h> is deprecated, include <pluginlib/class_loader.hpp> instead. [-Wcpp] The .hpp files have been backported to indigo
• Fixed base_path handling
• Upstream missing changes to add_analyzers
• Contributors: Alexander Moriarty, Austin, Nick Lamprianidis, trainman419

1.9.2 (2017-07-15)

1.9.1 (2017-07-15)

• Add queue size parameters on Publishers
• add_analyzers improvements
  • Warning message when bond is broken
  • Per-bond topics to avoid queue length issues
• Option to make diagnostics in Other an error
• Contributors: trainman419

1.9.0 (2017-04-25)

• Longer settling time
• Fix race condition in unload
• Fix cmake warnings
• make rostest in CMakeLists optional (ros/rosdistro#3010)
• Changed all deprecated PLUGINLIB_DECLARE_CLASS to PLUGINLIB_EXPORT_CLASS macros
• Contributors: Aris Synodinos, Lukas Bulwahn, trainman419

1.8.10 (2016-06-14)

• Start bond after add_diagnostics service is available
• Contributors: Mustafa Safri

1.8.9 (2016-03-02)

• Add version dependencies in package.xml
• Add version check in cmake
• Add functionality for dynamically adding analyzers
• Contributors: Michal Staniaszek, trainman419

1.8.8 (2015-08-06)

• Fix #17
• Contributors: trainman419

1.8.7 (2015-01-09)

• Upgrade to gtest 1.7.0
• Contributors: trainman419

1.8.6 (2014-12-10)

1.8.5 (2014-07-29)

• Include gtest source directly
• Contributors: trainman419

1.8.4 (2014-07-24 20:51)

• Install analyzer_loader. Fixes #24
• Add dependency on message generation
• Remove stray architechture_independent flags This flag should be used for package which do not contain architecture-specific files. Compiled binaries are such a file, and these packages contain them.
• Contributors: Jon Binney, Scott K Logan, trainman419

1.8.3 (2014-04-23)

• Fix stale aggregation bug
• Clean up stale check Fixes #21
• Contributors: Austin Hendrix

1.8.2 (2014-04-08)

• Fix linking. All tests pass. Fixes #12
• Most tests pass
• Contributors: Austin Hendrix

1.8.1 (2014-04-07)

• Add myself as maintainer
• check for CATKIN_ENABLE_TESTING
• Contributors: Austin Hendrix, Lukas Bulwahn

1.8.0 (2013-04-03)

1.7.11 (2014-07-24 20:24)

• Install analyzer_loader
• diagnostic_aggregator) Removed redundancy in package.xml.
• Contributors: Isaac Saito, trainman419

1.7.10 (2013-02-22)

• Changed package.xml version number before releasing
• diagnostic_aggregator) Maintainer added.
• Contributors: Brice Rebsamen, Isaac Saito

1.7.9 (2012-12-14)

• add missing dep to catkin
• Contributors: Dirk Thomas

1.7.8 (2012-12-06)

• fix issue #1
• missing includedirs from roscpp cause compile errors. diagnostic_aggregator/include/diagnostic_aggregator/status_item.h:45:21: fatal error: ros/ros.h: No such file or directory diagnostics/diagnostic_updater/include/diagnostic_updater/diagnostic_updater.h:42:29: fatal error: ros/node_handle.h: No such file or directory compilation terminated.
• Contributors: Thibault Kruse, Vincent Rabaud

1.7.7 (2012-11-10)

• install missing entities
• Contributors: Vincent Rabaud

1.7.6 (2012-11-07 23:32)

1.7.5 (2012-11-07 21:53)

1.7.4 (2012-11-07 20:18)

1.7.3 (2012-11-04)

1.7.2 (2012-10-30 22:31)

1.7.1 (2012-10-30 15:30)

• fix a few things after the first release
• fix a few things all over
• Contributors: Vincent Rabaud

1.7.0 (2012-10-29)

• catkinize the stack
• use the proper gtest macro
• fixed regression of last change in diagnostics
• added separate publisher for toplevel state in diagnostic_aggregator (#5187)
• Allowing analyzer_loader to build on 'all' target. WG-ROS-PKG 4935
• Error message for bad regex. #4416
• Fixed string literal to avoid warning
• Changed all analyzer load names to pkg/Analyzer for new pluginlib call. #4117
• Using new pluginlib macro for Analyzer classes. #4117
• Added support for taking GenericAnalyzer params as string or list in regression test. #3199
• StatusItem no longer prepends extra / to output name if not needed
• GenericAnalyzer doesnt report anything for num_items = 0, #4052
• Ignore analyzer ignores all parameters. #3733
• Added discard analyzer. #3733
• Added Ubuntu platform tags to manifest
• Fixed no items message for GenericAnalyzer. #3199
• rename forearm camera's on hw
• Error checking in getParamVals(). #3846
• Replaced boost assert with ros assert
• Aggregator now warns when message timestamp isn't set, #3823
• Check that we're always publishing names starting with / in diagnostic aggregator. #3199
• Added test for testing that diagnositc items that have been matched by >1 analyzer show up in aggregated diagnostic output. #3840
• AnalyzerGroup can now handle multiple analyzers matching and analyzing a single status name properly. #3691
• AnalyzerGroup now will have a correctly named DiagnosticStatus name if no analyzers are created. #3807
• Adding '/' to all output diagnostic status names, #3743
• Changing header message for GenericAnalyzerBase when no items found
• Correct corner case of GenericAnalyzer discarding expected items that were stale
• diagnostic_aggregator/diagnostic_analysis doc reviewed
• Tested fixes for not discarding stale items if they are expected in GenericAnalzyer, #3616. Needs formal regression test.
• GenericAnalyzer won't discard items if they're expected. #3616. Needs regression test, further verification
• Fixed a typo.
• Corrected typo in manifest.
• Updating error message of Analyzer::match const function
• aggregator node will now catch all exceptions in aggregator, and ROS_FATAL/ROS_BREAK. This will put all exceptions to the rosconsole
• AnalyzerGroup now reports that it failed to initialize if any sub analyzers failed to initialize. AnalyzerGroup will still be able to correctly match(), analyze() and report() even if all sub-analyzers failed to initialized
• Adding Analyzer load test #3474
• Allowed users to set and get the level/message of a StatusItem
• Dox update for generic analyzer, other analyzer, aggregator files. Updated mainpage to get correct information
• Updated aggregator documentation in manifest
• Added documentation, warnings for incorrect initialization to diagnostic_aggregator
• Fixed Other analyzer to correctly initialize GenericAnalyzerBase
• discard_stale parameters to generic analyzer will cause it to discard any items that haven't been updated within timeout
• Corrected reporting of stale items in analyzer group
• Adding analyzer group to allow diagnostic analyzers to be grouped together. Used internally by diagnostic aggregator. #3461
• Remove use of deprecated rosbuild macros
• Adding xmlrpcpp back into manifest for ros-pkg #3121
• Adding message header, stamp in aggregator, robot/runtime monitor test scripts for ROS 0.10 compatibility
• Other analyzer will no longer report anything if no 'Other' items in diagnostic aggregator. #3263
• Fixing diagnostic aggregator for ROS 0.10 message header stamp change
• Fixed demo in diagnostic aggregator
• Adding all changes from API review on 11/2
• Adding all changes from API review on 11/2
• Added regex support to diagnostic aggregator, made GenericAnalyzer subclassable
• Diagnostic aggregator upgrades after 10/15 API review.
• Minor fixes before API review
• Added unit test for component analyzer to diagnostic aggregator
• Added checking or warn, error conditions to generic analyzer test
• Changes from Josh's API review
• Adding diagnostic aggregator for components, things that can be broken into sub categories. Used for motors and sensors
• Adds hasKey/getValue functions to status item, removing old toStatusMsg defn
• Fixed '/' v '' in dox, updated demo launch file
• Forgot to make the test node a <test> for diagnostic aggregator
• Moved everything to correct class names, fixed parameter ~, and added unit test
• Renamed classes to avoid diagnostic prefix, renamed files. Removed use of ~ in param names
• Removing dependency on xmlrpc++ for #3121
• Changed diagnostic aggregator to use boost::shared_ptr
• Added boost linkage necessary for OS X
• Minor doc fix
• diagnostics 0.1 commit. Removed diagnostic_analyzer/generic_analyzer and integrated into diagnostic_aggregator.
• Merging the new version of pluginlib back into trunk r31894@att (orig r22146): eitanme | 2009-08-18 10:30:37 -0700 Creating a branch to work on pluginlib and get things changed r31896@att (orig r22148): eitanme | 2009-08-18 10:32:35 -0700 Starting rework... need to commit so that I can move some files around r31942@att (orig r22182): eitanme | 2009-08-18 16:36:37 -0700 Commit because Scott is moving into the office and I have to shut down my computer r31978@att (orig r22216): eitanme | 2009-08-18 19:20:47 -0700 Working on changing things over to work with the new pluginlib r31980@att (orig r22218): eitanme | 2009-08-18 19:24:54 -0700 Converted pluginlib tutorials to new pluginlib code r31982@att (orig r22220): eitanme | 2009-08-18 19:28:34 -0700 Moving joint qualification controllers over to the new pluginlib model r31985@att (orig r22223): eitanme | 2009-08-18 19:40:36 -0700 Moving people_aware_nav to new pluginlib interface r31986@att (orig r22224): eitanme | 2009-08-18 19:43:09 -0700 Moving diagnostic aggregator to the pluginlib interface r31987@att (orig r22225): eitanme | 2009-08-18 19:43:51 -0700 Moving generic analyzer to the new pluginlib interface r31988@att (orig r22226): eitanme | 2009-08-18 19:44:21 -0700 Moving carrot planner to the new pluginlib interface r31992@att (orig r22230): eitanme | 2009-08-18 19:54:15 -0700 Changing REGISTER_CLASS to PLUGINLIB_REGISTER_CLASS r31996@att (orig r22234): eitanme | 2009-08-18 20:19:30 -0700 Fixing a plugin .xml file r31998@att (orig r22236): eitanme | 2009-08-18 20:25:05 -0700 Fixing more incorrect tags
• Removing Python aggregator node, has been replaced by C++ version
• Correct function names to camelCase, added documentation
• Added C++ diagnostic_aggregator
• Display child status levels in parent status for generic analyzer
• Updated documentation, fixed copy-paste error
• diagnostic_aggregator package to filter and analyze robot diagnostics
• Contributors: Vincent Rabaud, blaise, dthomas, eitanme, gerkey, kwc, vrabaud, watts, wattsk, wheeler, wim