MONITORING QosPolicy (DDS Extension)

43.4 MONITORING QosPolicy (DDS Extension)

This QoS policy configures RTI Monitoring Library 2.0, which is used by the RTI Connext Observability Framework. See Chapter 60 RTI Monitoring Library 2.0 for more information.

Note: This QoS policy configures the RTI Monitoring Library 2.0, not the Chapter 59 RTI Monitoring Library.

This QoS policy can be configured programmatically or via XML. You can also find information about it, including its minimum setup, in the API Reference HTML documentation and in Monitoring Library 2.0, in the RTI Observability Framework documentation.

This QoS policy has the members described in the following tables.

Table 43.4 DDS_MonitoringQosPolicy
Type	Field Name	Description
DDS_Boolean	enable	Enables the collection and distribution of telemetry data for a Connext application using Monitoring Library 2.0. Note: Enabling and disabling Monitoring Library 2.0 while DDS Entities are being created or deleted is not a safe operation. The entities created while Monitoring Library 2.0 is being enabled may not be monitored. In that case, children entities from that entity (invisible to the library) will not be monitored, either. Default: FALSE
char *	application_name	Name of the resource that represents your Connext application. When this member is set to a value other than NULL, the resource identifier representing this application will be: /applications/<application_name> This is the resource identifier that will be used to send commands to this application from the RTI Observability Dashboards. The application_name should be unique across the Connext system; however, Monitoring Library 2.0 does not currently enforce uniqueness. When application_name is set to NULL, Monitoring Library 2.0 will automatically assign a resource identifier with this format: /applications/<host_name:process_id:uuid> Default: NULL
DDS_MonitoringDistributionSettings	distribution_settings	This structure configures the distribution of telemetry data. It includes the fields in Table 43.5 DDS_MonitoringDistributionSettings.
DDS_MonitoringTelemetryData	telemetry_data	This structure configures the telemetry data that will be distributed (logs and metrics). It includes the fields in Table 43.10 DDS_MonitoringTelemetryData.

Table 43.5 DDS_MonitoringDistributionSettings

Type	Field Name	Description
DDS_MonitoringDedicatedParticipantSettings	dedicated_participant	Configures the use of a dedicated DomainParticipant to distribute the Connext application telemetry data. It includes the fields in Table 43.6 DDS_MonitoringDedicatedParticipantSettings.
char *	publisher_qos_profile_name	Fully qualified name of the profile used to configure the Publishers that distribute telemetry data. There is one Publisher for each telemetry data Topic: RTI_MONITORING_PERIODIC_TOPIC_NAME RTI_MONITORING_EVENT_TOPIC_NAME RTI_MONITORING_LOGGING_TOPIC_NAME If NULL (the default value) then Monitoring Library 2.0 uses DDS_PROFILE_GENERIC_MONITORING2. Default: NULL
DDS_MonitoringEventDistributionSettings	event_settings	Configures the distribution of event metrics. Event metrics are provided to Monitoring Library 2.0 when they change. For example, if the liveliness of a DataWriter is lost, a matching DataReader will push the new value of 40.7.4 LIVELINESS_CHANGED Status to Monitoring Library 2.0 so that the liveliness status change can be distributed. There are three kinds of event metrics: Configuration metrics: Provided to Monitoring Library 2.0 by pushing changes to QoS policies. Status metrics: Provided to Monitoring Library 2.0 by pushing changes to the event statuses such as 40.7.4 LIVELINESS_CHANGED Status. Resource metrics: Provided to Monitoring Library 2.0 when a resource (such as a DataWriter) is created or deleted. See Table 43.7 DDS_MonitoringEventDistributionSettings.
DDS_MonitoringPeriodicDistributionSettings	periodic_settings	Configures the distribution of periodic metrics. Periodic metrics change often, and they are polled and published periodically by a thread created by Monitoring Library 2.0. Monitoring Library 2.0 obtains periodic metrics by polling the current value of periodic statuses such as the 31.6.3 DATA_WRITER_PROTOCOL_STATUS. See Table 43.8 DDS_MonitoringPeriodicDistributionSettings.
DDS_MonitoringLoggingDistributionSettings	logging_settings	Configures the distribution of logging messages. Log messages are pushed into Monitoring Library 2.0 and published by the logging thread. The logging thread only publishes a log message with a Syslog level smaller than or equal to the forwarding level of the NDDS_Config_LogFacility associated with the log message. The default value of the forwarding level for all facilities is NDDS_CONFIG_SYSLOG_VERBOSITY_WARNING. This value can be changed with the Table 43.11 DDS_MonitoringLoggingForwardingSettings or by sending a command to Monitoring Library 2.0. Currently, commands can only be sent from the Observability Dashboards. Monitoring Library 2.0 can be configured to keep a history of log messages for later distribution when a log snapshot is requested by an Observability Collector Service. The log messages maintained in the history are the last ‘n’ messages published by the logging thread (where ‘n’ is the value of max_historical_logs). See Table 43.9 DDS_MonitoringLoggingDistributionSettings.

Table 43.6 DDS_MonitoringDedicatedParticipantSettings

Type	Field Name	Description
DDS_Boolean	enable	Enables the use of a dedicated DomainParticipant to distribute the Connext application telemetry data. Setting this value to FALSE is not currently supported. Default: TRUE
int	domain_id	Domain ID used in the creation of Monitoring Library 2.0 DomainParticipant. Default: 2
char *	participant_qos_profile_name	Fully qualified name of the profile used to configure the DomainParticipant that will be used to distribute telemetry data. If NULL (the default value), then Monitoring Library 2.0 uses DDS_PROFILE_GENERIC_MONITORING2. Default: NULL
DDS_StringSeq	collector_initial_peers	Determines the initial list of peers that the discovery process will contact to send announcements about the presence of the dedicated DomainParticipant. These initial peers should correspond with the RTI Observability Collector Service with which Monitoring Library 2.0 has to communicate. The collector_initial_peers works the same as initial_peers for other DomainParticipants, except that it allows you to easily specify the initial peer(s) for the Monitoring Library 2.0 DomainParticipant, which usually has different initial peer(s) than those used by your application. See Monitoring Library 2.0, in the RTI Observability Framework documentation for more context. If no collector_initial_peers are specified, or if it is explicitly set to an empty list, the initial_peers list of the QoS profile specified in participant_qos_profile_name will be used as the initial peers of the dedicated DomainParticipant. Default: An empty sequence

Table 43.7 DDS_MonitoringEventDistributionSettings

Type	Field Name	Description
DDS_UnsignedLong	concurrency_level	Defines how concurrent the push is of event metrics to Monitoring Library 2.0. With a concurrency_level of one, all the event metrics pushed to Monitoring Library 2.0 will be stored in a single queue protected by a single mutex. With a concurrency_level of 'n', Monitoring Library 2.0 will create 'n' queues for event metrics, each queue protected by its own mutex. Each resource (e.g,, a DataReader) will be associated with one of the queues when the resource is registered with Monitoring Library 2.0. Therefore, all the event metrics for a single resource always go to the same queue. The event metrics for two resources associated with different event queues can be pushed in parallel. This is why a higher concurrency_level provides more concurrency. The event metrics added to the event queues are processed by a single thread configured using the thread field. Range: [1, 100] Default: 5
char *	datawriter_qos_profile_name	Fully qualified name of the profile used to configure the DataWriter that distributes event metrics. The DataWriter Topic is RTI_MONITORING_EVENT_TOPIC_NAME. If NULL (the default value), then Monitoring Library 2.0 uses DDS_PROFILE_GENERIC_MONITORING2. Default: NULL
DDS_ThreadSettings_t	thread	Settings of the event metric thread. The event metric thread periodically publishes the event metrics pushed into Monitoring Library 2.0 event metric queues after they change their values. The thread runs at the period configured using the publication_period. See also 50.4.7 Thread Settings. Default: DDS_THREAD_SETTINGS_DEFAULT
DDS_Duration_t	publication_period	Period at which the event metric thread publishes the event metrics that have changed since the last time they were published. With a period of 0 seconds, changes to event metrics will be published immediately after they are pushed into Monitoring Library 2.0. Default: 1 second

Table 43.8 DDS_MonitoringPeriodicDistributionSettings

Type	Field Name	Description
char *	datawriter_qos_profile_name	Fully qualified name of the profile used to configure the DataWriter that distributes periodic metrics. The DataWriter Topic is RTI_MONITORING_PERIODIC_TOPIC_NAME. If NULL (the default value), then Monitoring Library 2.0 uses DDS_PROFILE_GENERIC_MONITORING2. Default: NULL
DDS_ThreadSettings_t	thread	Settings of the periodic metric thread. The periodic metric thread periodically polls and publishes periodic event metrics. The thread runs at the period configured using the polling_period. See also 50.4.7 Thread Settings. Default: DDS_THREAD_SETTINGS_DEFAULT
DDS_Duration_t	polling_period	Period at which the periodic metric thread polls and publishes the periodic metrics. Range: > 0 seconds Default: 5 seconds

Type

Field Name

Description

char *

datawriter_qos_profile_name

Fully qualified name of the profile used to configure the DataWriter that distributes periodic metrics. The DataWriter Topic is RTI_MONITORING_PERIODIC_TOPIC_NAME.

If NULL (the default value), then Monitoring Library 2.0 uses DDS_PROFILE_GENERIC_MONITORING2.

Default: NULL

DDS_ThreadSettings_t

thread

Settings of the periodic metric thread. The periodic metric thread periodically polls and publishes periodic event metrics. The thread runs at the period configured using the polling_period. See also 50.4.7 Thread Settings.

Default: DDS_THREAD_SETTINGS_DEFAULT

DDS_Duration_t

polling_period

Period at which the periodic metric thread polls and publishes the periodic metrics.

Range: > 0 seconds

Default: 5 seconds

Table 43.9 DDS_MonitoringLoggingDistributionSettings

Type	Field Name	Description
DDS_UnsignedLong	concurrency_level	Defines how concurrent the push of log messages to Monitoring Library 2.0 is. With a concurrency_level of one, all the log messages pushed to Monitoring Library 2.0 will be stored in a single queue protected by a single mutex. With a concurrency_level of 'n', Monitoring Library 2.0 will create 'n' queues for log messages, each queue protected by its own mutex. The log messages generated by a single thread will always be pushed to the same queue. The log messages for two threads associated with different log queues can be pushed in parallel. This is why a higher concurrency_level provides more concurrency. The log messages added to the log queues are processed and published by a single thread configured using the thread field. Range: [1, 100] Default: 5
DDS_UnsignedLong	max_historical_logs	Number of log messages that Monitoring Library 2.0 will keep as history. Monitoring Library 2.0 will keep as history the last max_historical_logs published messages. A value of 0 means that Monitoring Library 2.0 should not keep any history. Default: 128
char *	datawriter_qos_profile_name	Fully qualified name of the profile used to configure the DataWriter that distributes log messages. The DataWriter Topic is RTI_MONITORING_LOGGING_TOPIC_NAME. If NULL (the default value), then Monitoring Library 2.0 uses DDS_PROFILE_GENERIC_MONITORING2. Default: NULL
DDS_ThreadSettings_t	thread	Settings of the logging thread. The logging thread periodically publishes the log messages pushed into Monitoring Library 2.0 log message queues after they are generated. The thread runs at the period configured using publication_period. See also 50.4.7 Thread Settings. Default: DDS_THREAD_SETTINGS_DEFAULT
DDS_Duration_t	publication_period	Period at which the logging thread publishes log messages. With a period of 0 seconds, log messages will be published immediately after they are pushed into Monitoring Library 2.0. Default: 1 second

Table 43.10 DDS_MonitoringTelemetryData

Type	Field Name	Description
DDS_MonitoringMetricSelectionSeq	metrics	There are many metrics that Observability Framework can collect and forward for a given set of observable resources (for a DomainParticipant, Publisher, DataReader, etc.). The metrics field enables you to specify the initial set of metrics you want to collect. For example, when a DataWriter is created in your application, the metrics you define here are forwarded to Observability Collector Service, which distributes them to observability backends. If you decide later that you want more/fewer metrics to be forwarded, you can easily add/remove them via a remote command. See the RTI Observability Framework documentation for more details. The metrics field is a sequence of DDS_MonitoringMetricSelection elements, each containing three fields: resource_selection: An expression pattern that selects a subset of resources by matching the pattern to the resource names. The enabled_metric_selection and disabled_metric_selection fields are applied to this subset of resources. enabled_metric_selection: A sequence of patterns that match the names of the metrics that should be collected and distributed for the observable resources selected by resource_selection. disabled_metric_selection: A sequence of patterns that match the names of the metrics that should not be collected and distributed for the observable resources selected by resource_selection. For information about how to build the patterns in these fields, see the Metrics section in the RTI Observability Framework documentation. See the API Reference HTML documentation (for example, see here for Modern C++) for further details on these fields, including examples. Every DDS_MonitoringMetricSelection in the sequence is evaluated in order: enabled_metric_selection is evaluated first and disabled_metric_selection after. Therefore, if the same metric is enabled and disabled at the same time, the disablement will be the final result. Attention: By default, no metrics will be enabled for any resource unless you specify them here.
DDS_MonitoringLoggingForwardingSettings	logs	This structure configures the NDDS_Config_SyslogVerbosity levels that will be forwarded for the different NDDS_Config_LogFacility levels. See Table 43.11 DDS_MonitoringLoggingForwardingSettings.

Type

Field Name

Description

DDS_MonitoringMetricSelectionSeq

metrics

There are many metrics that Observability Framework can collect and forward for a given set of observable resources (for a DomainParticipant, Publisher, DataReader, etc.). The metrics field enables you to specify the initial set of metrics you want to collect. For example, when a DataWriter is created in your application, the metrics you define here are forwarded to Observability Collector Service, which distributes them to observability backends. If you decide later that you want more/fewer metrics to be forwarded, you can easily add/remove them via a remote command. See the RTI Observability Framework documentation for more details.

The metrics field is a sequence of DDS_MonitoringMetricSelection elements, each containing three fields:

resource_selection: An expression pattern that selects a subset of resources by matching the pattern to the resource names. The enabled_metric_selection and disabled_metric_selection fields are applied to this subset of resources.
enabled_metric_selection: A sequence of patterns that match the names of the metrics that should be collected and distributed for the observable resources selected by resource_selection.
disabled_metric_selection: A sequence of patterns that match the names of the metrics that should not be collected and distributed for the observable resources selected by resource_selection.

For information about how to build the patterns in these fields, see the Metrics section in the RTI Observability Framework documentation. See the API Reference HTML documentation (for example, see here for Modern C++) for further details on these fields, including examples.

Every DDS_MonitoringMetricSelection in the sequence is evaluated in order: enabled_metric_selection is evaluated first and disabled_metric_selection after. Therefore, if the same metric is enabled and disabled at the same time, the disablement will be the final result.

Attention: By default, no metrics will be enabled for any resource unless you specify them here.

DDS_MonitoringLoggingForwardingSettings

logs

This structure configures the NDDS_Config_SyslogVerbosity levels that will be forwarded for the different NDDS_Config_LogFacility levels. See Table 43.11 DDS_MonitoringLoggingForwardingSettings.

Table 43.11 DDS_MonitoringLoggingForwardingSettings

Type	Field Name	Description
NDDS_Config_SyslogVerbosity	middleware_forwarding_level	Log messages with NDDS_CONFIG_LOG_FACILITY_MIDDLEWARE and a log level more verbose than this value will not be distributed by Monitoring Library 2.0. See 54.2 Configuring Connext Logging for more information on the NDDS_CONFIG_LOG_FACILITY_* and NDDS_CONFIG_SYSLOG_* settings. Note: Setting this field to a value more verbose than WARNING if your application's verbosity is greater than NDDS_CONFIG_LOG_VERBOSITY_WARNING, may affect performance due to the large amount of messages produced. Default: NDDS_CONFIG_SYSLOG_VERBOSITY_WARNING
NDDS_Config_SyslogVerbosity	security_event_forwarding_level	Log messages with NDDS_CONFIG_LOG_FACILITY_SECURITY_EVENT and a log level more verbose than this value will not be distributed by Monitoring Library 2.0. See 54.2 Configuring Connext Logging for more information on the NDDS_CONFIG_LOG_FACILITY_* and NDDS_CONFIG_SYSLOG_* settings. Note: Setting this field to a value more verbose than WARNING if your application's verbosity is greater than NDDS_CONFIG_LOG_VERBOSITY_WARNING, may affect performance due to the large amount of messages produced. Default: NDDS_CONFIG_SYSLOG_VERBOSITY_WARNING
NDDS_Config_SyslogVerbosity	service_forwarding_level	Log messages with NDDS_CONFIG_LOG_FACILITY_SERVICE and a log level more verbose than this value will not be distributed by Monitoring Library 2.0. See 54.2 Configuring Connext Logging for more information on the NDDS_CONFIG_LOG_FACILITY_* and NDDS_CONFIG_SYSLOG_* settings. Note: Setting this field to a value more verbose than WARNING if your application's verbosity is greater than NDDS_CONFIG_LOG_VERBOSITY_WARNING, may affect performance due to the large amount of messages produced. Default: NDDS_CONFIG_SYSLOG_VERBOSITY_WARNING
NDDS_Config_SyslogVerbosity	user_forwarding_level	Log messages with NDDS_CONFIG_LOG_FACILITY_USER and a log level more verbose than this value will not be distributed by Monitoring Library 2.0. See 54.2 Configuring Connext Logging for more information on the NDDS_CONFIG_LOG_FACILITY_* and NDDS_CONFIG_SYSLOG_* settings. Note: Setting this field to a value more verbose than WARNING if your application's verbosity is greater than NDDS_CONFIG_LOG_VERBOSITY_WARNING, may affect performance due to the large amount of messages produced. Default: NDDS_CONFIG_SYSLOG_VERBOSITY_WARNING

43.4.1 Properties

This QosPolicy can be changed at any time.

There are no compatibility restrictions for how it is set on the publishing and subscribing sides.

43.4.2 Related QoS Policies

None

43.4.3 Applicable DDS Entities

16.2 DomainParticipantFactory

43.4.4 System Resource Considerations

Enabling Monitoring Library 2.0 by setting monitoring.enable (that is, enable in the DDS_MonitoringQosPolicy) to TRUE will allocate additional resources to collect and distribute the telemetry data. These resources include:

An additional DomainParticipant if monitoring.distribution_settings.dedicated_participant.enable is set to TRUE (default behavior)
A Publisher and a DataWriter to publish periodic metrics
A Publisher and a DataWriter to publish event metrics
A Publisher and a DataWriter to publish logging messages

By default, these entities are created using the builtin profile BuiltinQosLib::Generic.Monitoring2, which configures those entities' QoS, including minimizing their memory usage if desired. You can change the QoSs of the entities by setting the following fields; in these fields, you can provide a different profile (name), which contains your own modifications to Monitoring Qos Policy.

monitoring.distribution_settings.publisher_qos_profile_name (apply to all Publishers)
monitoring.distribution_settings.dedicated_participant.participant_qos_profile_name
monitoring.distribution_settings.periodic_settings.datawriter_qos_profile_name
monitoring.distribution_settings.event_settings.datawriter_qos_profile_name
monitoring.distribution_settings.logging_settings.datawriter_qos_profile_name

See Monitoring Library 2.0, in the RTI Observability Framework documentation for notes about the BuiltinQosLib::Generic.Monitoring2 profile, including examples in XML for changing the settings.