Add new messages for topic statistics

statistics_msgs/CMakeLists.txt

@@ -0,0 +1,28 @@
+cmake_minimum_required(VERSION 3.5)
+
+project(statistics_msgs)
+
+# Default to C++14
+if(NOT CMAKE_CXX_STANDARD)
+  set(CMAKE_CXX_STANDARD 14)
+endif()
+if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+  add_compile_options(-Wall -Wextra -Wpedantic)
+endif()
+
+# Find dependencies
+find_package(ament_cmake REQUIRED)
+find_package(builtin_interfaces REQUIRED)
+find_package(rosidl_default_generators REQUIRED)
+
+# Generate added messages with dependencies listed here
+rosidl_generate_interfaces(${PROJECT_NAME}
+  "msg/MetricsMessage.msg"
+  "msg/StatisticDataPoint.msg"
+  "msg/StatisticDataType.msg"
+  DEPENDENCIES builtin_interfaces
+)
+
+ament_export_dependencies(rosidl_default_runtime)
+
+ament_package()

statistics_msgs/README.md

@@ -0,0 +1,37 @@
+# metrics_statistics_msgs
+
+Package containing ROS 2 message definitions for reporting
+statistics for topics and system resources.
+
+## Messages defined in this package
+
+1. StatisticDataType
+
+   A message that represent the types of statistics reported.
+   This defines the following data types that can be used to represent
+   individual metric data points.
+   * `average`
+   * `minimum`
+   * `maximum`
+   * `stddev`
+   * `sample_count`
+
+1. StatisticDataPoint
+
+   A message that represents a single statistic value.
+   This includes:
+   * `data_type`: Type of the metric data point, as defined in `StatisticDataType`.
+   * `data`: Value of the metric data point.
+
+1. MetricsMessage
+
+   A message that represents statistic data measured from a source
+   within a time window.
+   This includes:
+   * `measurement_source_name`: Source from where the measurement or statistic originates.
+   * `metrics_source`: Name of the metric.
+   * `unit`: Unit representing the metric.
+   * `window_start`: Start time of the metric measurement window.
+   * `window_stop`: End time of the metric measurement window.
+   * `statistics`: A list of `StatisticDataPoint` representing the values
+   of collected metrics.

statistics_msgs/msg/MetricsMessage.msg

@@ -0,0 +1,30 @@
+#############################################
+# A generic metrics message providing statistics for measurements from different sources. For example,
+# measure a system's CPU % for a given window yields the following data points over a window of time:
+#
+#   - average cpu %
+#   - std deviation
+#   - min
+#   - max
+#   - sample count
+#
+# These are all represented as different 'StatisticDataPoint's.
+#############################################
+
+# Name metric measurement source, e.g., node, topic, or process name
+string measurement_source_name
+
+# Name of the metric being measured, e.g. cpu_percentage, free_memory_mb, message_age, etc.
+string metrics_source
+
+# Unit of measure of the metric, e.g. percent, mb, seconds, etc.
+string unit
+
+# Measurement window start time
+builtin_interfaces/Time window_start
+
+# Measurement window end time
+builtin_interfaces/Time window_stop
+
+# A list of statistics data point, defined in StatisticDataPoint.msg
+StatisticDataPoint[] statistics

statistics_msgs/msg/StatisticDataPoint.msg

@@ -0,0 +1,23 @@
+#############################################
+# This holds the structure of a single data point of a StatisticDataType.
+#
+# This message is used in MetricsStatisticsMessage, defined in MetricsStatisticsMessage.msg.
+#
+# Examples of the value of data point are
+# - average size of messages received
+# - standard deviation of the period of messages published
+# - maximum age of messages published
+#
+# A value of nan represents no data is available.
+# One example is that standard deviation is only available when there are two or more data points but there is only one,
+# and in this case the value would be nan.
+# +inf and -inf are not allowed.
+#
+#############################################
+
+# The statistic type of this data point, defined in StatisticDataType.msg
+# Default value should be StatisticDataType.STATISTICS_DATA_TYPE_UNINITIALIZED (0).
+uint8 data_type
+
+# The value of the data point
+float64 data

statistics_msgs/msg/StatisticDataType.msg

@@ -0,0 +1,18 @@
+#############################################
+# This file contains the commonly used constants for the statistics data type.
+#
+# The value 0 is reserved for unitialized statistic message data type.
+# Range of values: [0, 255].
+# Unallowed values: any value that is not specified in this file.
+#
+#############################################
+
+# Constant for uninitialized
+uint8 STATISTICS_DATA_TYPE_UNINITIALIZED = 0
+
+# Allowed values
+uint8 STATISTICS_DATA_TYPE_AVERAGE = 1
+uint8 STATISTICS_DATA_TYPE_MINIMUM = 2
+uint8 STATISTICS_DATA_TYPE_MAXIMUM = 3
+uint8 STATISTICS_DATA_TYPE_STDDEV = 4
+uint8 STATISTICS_DATA_TYPE_SAMPLE_COUNT = 5

statistics_msgs/package.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0"?>
+<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
+<package format="3">
+  <name>statistics_msgs</name>
+  <version>0.8.0</version>
+  <description>Message definitions for reporting statistics for topics and system resources.</description>
+  <maintainer email="ros-tooling@googlegroups.com">ROS Tooling Working Group</maintainer>
+  <license>Apache License 2.0</license>
+
+  <buildtool_depend>ament_cmake</buildtool_depend>
+  <buildtool_depend>rosidl_default_generators</buildtool_depend>
+
+  <build_depend>builtin_interfaces</build_depend>
+
+  <build_export_depend>builtin_interfaces</build_export_depend>
+
+  <exec_depend>builtin_interfaces</exec_depend>
+  <exec_depend>rosidl_default_runtime</exec_depend>
+
+  <test_depend>ament_lint_common</test_depend>
+
+  <member_of_group>rosidl_interface_packages</member_of_group>
+
+  <export>
+    <build_type>ament_cmake</build_type>
+  </export>
+</package>