/* * (c) Copyright, Real-Time Innovations, 2002-2024. * All rights reserved. * * No duplications, whole or partial, manual or electronic, may be made * without express written permission. Any such copies, or * revisions thereof, must display this notice unaltered. * This code contains trade secrets of Real-Time Innovations, Inc. */ #ifndef routingservice_monitoring_h #define routingservice_monitoring_h #include "routingservice/routingservice_dll.h" #include "routingservice/routingservice_service.h" #include "apputils/apputils_resource_identifier_impl.h" #ifdef __cplusplus extern "C" { #endif #include "routingservice/ServiceCommon.h" #include "routingservice/ServiceCommonPlugin.h" #include "routingservice/ServiceCommonSupport.h" /* * --- StatisticsCalculator --------------------------------------------------- */ /*i * StatisticsCalculator * * @brief Utility for computing historical statistics based on a moving * average within several window sizes. * * The are two concepts: the "value" and the "unit". The value is the raw * counter of the magnitude we are measuring (eg. total number of samples or * total seconds of latency), the "unit" is the magnitude to calculate the * mean (eg. time for the "value" total number of samples or number of * samples for the "value" total seconds of latency). * * There are two main functions: update and takeSnapshots. * * Every call to update provides the total value and the total unit until * that moment. For example, the total number of samples sent and the total * number of seconds since the beginning. * * There are serveral statistics: last period, five-minute, one-hour * and since the beginning. Each category includes a mean, a maximum value, * a mininum value and the standard deviation. * * Last period computes the mean (and the rest of stats) for the values * provided with update between one call to takeSnapshot and the next one: * * For example: * Update(2, 1), Update(3, 2), Update(8, 4), TakeSnapshot [a], * Update(10, 5), Update(10, 6), Update(11, 8), TakeSnapshot [b] * In [a] The mean would be 8/4 = 2, the maximum would be 2.5, * the minimum would be 1 * In [b] The mean would be 1/3, the maximum would be 1/2, * the miminum would be 0. * * The stats for five-minute correspond to the values provided with update() * from the last call to update before takeSnapshot to the call to update * that happened 5 minutes before. * For all this calculations, we assume that update is called (approx.) with * the frequency stated in the sampling period that is passed to the * constructor */ typedef struct ROUTERStatisticsCalculator RTI_RoutingServiceStatsCalculator; #define RTI_RoutingServiceStatsCalculatorProperty_INITIALIZER { \ {0,0}, \ 0, \ RTI_FALSE, \ {0,0} \ } #define RTI_SERVICE_MONITORING_CONFIG_DISTRIBUTION_TOPIC RTI_Service_Monitoring_DistributionTopicKind_CONFIG #define RTI_SERVICE_MONITORING_EVENT_DISTRIBUTION_TOPIC RTI_Service_Monitoring_DistributionTopicKind_EVENT #define RTI_SERVICE_MONITORING_PERIODIC_DISTRIBUTION_TOPIC RTI_Service_Monitoring_DistributionTopicKind_PERIODIC #define RTI_ROUTING_SERVICE_MONITORING_SERVICE_RESOURCE RTI_Service_Monitoring_ResourceKind_ROUTING_SERVICE #define RTI_ROUTING_SERVICE_MONITORING_DOMAIN_ROUTE_RESOURCE RTI_Service_Monitoring_ResourceKind_ROUTING_DOMAIN_ROUTE #define RTI_ROUTING_SERVICE_MONITORING_SESSION_RESOURCE RTI_Service_Monitoring_ResourceKind_ROUTING_SESSION #define RTI_ROUTING_SERVICE_MONITORING_AUTO_ROUTE_RESOURCE RTI_Service_Monitoring_ResourceKind_ROUTING_AUTO_ROUTE #define RTI_ROUTING_SERVICE_MONITORING_ROUTE_RESOURCE RTI_Service_Monitoring_ResourceKind_ROUTING_ROUTE #define RTI_ROUTING_SERVICE_MONITORING_INPUT_RESOURCE RTI_Service_Monitoring_ResourceKind_ROUTING_INPUT #define RTI_ROUTING_SERVICE_MONITORING_OUTPUT_RESOURCE RTI_Service_Monitoring_ResourceKind_ROUTING_OUTPUT #if defined(RTI_LINUX) || defined(RTI_WIN32) #define RTI_SERVICE_MONITORING_PROCESS_MEMORY_USAGE_SUPPORTED (1) #define RTI_SERVICE_MONITORING_PROCESS_CPU_USAGE_SUPPORTED (1) #define RTI_SERVICE_MONITORING_PROCESS_UPTIME_SUPPORTED (1) #define RTI_SERVICE_MONITORING_HOST_CPU_USAGE_SUPPORTED (1) #define RTI_SERVICE_MONITORING_HOST_MEMORY_USAGE_SUPPORTED (1) #define RTI_SERVICE_MONITORING_HOST_UPTIME_SUPPORTED (1) #elif defined(RTI_QNX) #define RTI_SERVICE_MONITORING_PROCESS_MEMORY_USAGE_SUPPORTED (1) #define RTI_SERVICE_MONITORING_PROCESS_CPU_USAGE_SUPPORTED (1) #define RTI_SERVICE_MONITORING_PROCESS_UPTIME_SUPPORTED (0) #define RTI_SERVICE_MONITORING_HOST_CPU_USAGE_SUPPORTED (0) #define RTI_SERVICE_MONITORING_HOST_MEMORY_USAGE_SUPPORTED (0) #define RTI_SERVICE_MONITORING_HOST_UPTIME_SUPPORTED (0) #elif defined (RTI_DARWIN) #define RTI_SERVICE_MONITORING_PROCESS_CPU_USAGE_SUPPORTED (1) #define RTI_SERVICE_MONITORING_PROCESS_MEMORY_USAGE_SUPPORTED (1) #define RTI_SERVICE_MONITORING_PROCESS_UPTIME_SUPPORTED (0) #define RTI_SERVICE_MONITORING_HOST_CPU_USAGE_SUPPORTED (1) #define RTI_SERVICE_MONITORING_HOST_MEMORY_USAGE_SUPPORTED (1) #define RTI_SERVICE_MONITORING_HOST_UPTIME_SUPPORTED (1) #else #define RTI_SERVICE_MONITORING_PROCESS_MEMORY_USAGE_SUPPORTED (0) #define RTI_SERVICE_MONITORING_PROCESS_CPU_USAGE_SUPPORTED (0) #define RTI_SERVICE_MONITORING_PROCESS_UPTIME_SUPPORTED (0) #define RTI_SERVICE_MONITORING_HOST_CPU_USAGE_SUPPORTED (0) #define RTI_SERVICE_MONITORING_HOST_MEMORY_USAGE_SUPPORTED (0) #define RTI_SERVICE_MONITORING_HOST_UPTIME_SUPPORTED (0) #endif struct RTI_RoutingServiceStatsCalculatorProperty { struct DDS_Duration_t sampling_period; DDS_UnsignedLongLong initial_unit; DDS_Boolean use_accumulated_values; struct DDS_Duration_t start_time; }; extern ROUTERDllExport void RTI_RoutingServiceStatsCalculator_update( RTI_RoutingServiceStatsCalculator *self, DDS_LongLong value, DDS_UnsignedLongLong unit); extern ROUTERDllExport void RTI_RoutingServiceStatsCalculator_take_snapshot( RTI_RoutingServiceStatsCalculator *self, struct RTI_Service_Monitoring_StatisticVariable *variable_out, DDS_UnsignedLong slot, const struct DDS_Duration_t *snapshot_period); extern ROUTERDllExport void RTI_RoutingServiceStatsCalculator_aggregate( struct RTI_Service_Monitoring_StatisticVariable *variable_out, const struct RTI_Service_Monitoring_StatisticVariable *variable_in); extern ROUTERDllExport void RTI_RoutingServiceStatsCalculator_reset_variable( struct RTI_Service_Monitoring_StatisticVariable *variable); extern ROUTERDllExport RTI_RoutingServiceStatsCalculator * RTI_RoutingServiceStatsCalculator_new( const struct RTI_RoutingServiceStatsCalculatorProperty *property); extern ROUTERDllExport void RTI_RoutingServiceStatsCalculator_delete( RTI_RoutingServiceStatsCalculator *self); /******************** Remote monitoring infrastructure ************************/ /* Forward declarations for monitoring */ /** * \ingroup RTI_RoutingServiceLibModule * @brief An opaque structure used to publish external monitoring information */ struct RTI_RoutingServiceMonitoringTopicHandle; /** * \ingroup RTI_RoutingServiceLibModule * @brief Callback to implement when the monitoring service requires to publish * data */ typedef void (*RTI_RoutingServiceMonitorable_PublishStatusCallback)( void *monitorableData, const struct RTINtpTime *now); /** * \ingroup RTI_RoutingServiceLibModule * @brief Callback to implement when the monitoring service requires to sample * statistics data */ typedef void (*RTI_RoutingServiceMonitorable_SampleStatusCallback)( void *monitorableData, const struct RTINtpTime *now); /** * \ingroup RTI_RoutingServiceLibModule * @brief Callback to implement when the monitoring service requires to sample * statistics data */ struct RTI_RoutingServiceMonitorable { /*i @brief Sample status callback */ RTI_RoutingServiceMonitorable_SampleStatusCallback sample_status; /*i @brief publish status callback */ RTI_RoutingServiceMonitorable_PublishStatusCallback publish_status; /*i @brief Implementation data */ void * monitorable_data; }; /** * \ingroup RTI_RoutingServiceLibModule * @brief Registers a monitoring topic in Routing Service * @returns A monitoring topic hanlde */ extern ROUTERDllExport struct RTI_RoutingServiceMonitoringTopicHandle * RTI_RoutingService_register_monitoring_topic( struct RTI_RoutingService *service, const char *topic_name, const char *type_name, void *plugin); /** * \ingroup RTI_RoutingServiceLibModule * @brief Unregisters a monitoring topic in Routing Service * @param self The service * @param handle The monitoring topic handle */ extern ROUTERDllExport void RTI_RoutingService_unregister_monitoring_topic( struct RTI_RoutingService *self, struct RTI_RoutingServiceMonitoringTopicHandle *handle); /** * \ingroup RTI_RoutingServiceLibModule * @brief Registers a monitorable entity in Routing Service * * @param self The service * @param monitorable The monitoring topic handle * @param sampling_period The sampling period * @param publishing_period The monitoring data publication period * * @returns 0 on success. Negative value on failure */ extern ROUTERDllExport int RTI_RoutingService_register_monitorable( struct RTI_RoutingService *self, struct RTI_RoutingServiceMonitorable *monitorable, struct DDS_Duration_t *sampling_period, struct DDS_Duration_t *publishing_period); /** * \ingroup RTI_RoutingServiceLibModule * @brief Unregisters a monitorable entity in Routing Service * * @param self The service * @param monitorable The monitoring topic handle */ extern ROUTERDllExport void RTI_RoutingService_unregister_monitorable( struct RTI_RoutingService *self, struct RTI_RoutingServiceMonitorable *monitorable); /** * \ingroup RTI_RoutingServiceLibModule * @brief Publishes monitoring data * * @param self The service * @param handle The monitoring topic handle * @param data The monitoring data * * @returns 0 on success. Negative value on failure */ extern ROUTERDllExport int RTI_RoutingService_publish_monitoring_data( struct RTI_RoutingService *self, struct RTI_RoutingServiceMonitoringTopicHandle *handle, const void *data); /** * \ingroup RTI_RoutingServiceLibModule * @brief Disposes monitoring data * * @param self The service * @param handle The monitoring topic handle * @param data The monitoring data * * @returns 0 on success. Negative value on failure */ extern ROUTERDllExport int RTI_RoutingService_dispose_monitoring_data( struct RTI_RoutingService *self, struct RTI_RoutingServiceMonitoringTopicHandle *handle, const void *data); /** * \ingroup RTI_RoutingServiceLibModule * @brief Initializes the built-in MonitorableApplication instance * * If the object is already initialized, this is a no-op and the object is * returned. * * @param self The service * @param host_config Output result containing the host data * @param process_config Output result containing the process data * * @returns The MonitorableApplication */ extern ROUTERDllExport struct RTI_RoutingServiceMonitorable * RTI_RoutingService_initialize_monitorable_application( struct RTI_RoutingService *self, struct RTI_Service_Monitoring_HostConfig *host_config, struct RTI_Service_Monitoring_ProcessConfig *process_config); /** * \ingroup RTI_RoutingServiceLibModule * @brief Resets the statistic counters of the built-in MonitorableApplication * object. * * @param self The service * @param sampling_period Period at which the metrics are sampled * * @returns The MonitorableApplication */ extern ROUTERDllExport DDS_Boolean RTI_RoutingService_reset_monitorable_application_statistics( struct RTI_RoutingService *self, const struct DDS_Duration_t *sampling_period); /** * \ingroup RTI_RoutingServiceLibModule * @brief Finalizes the built-in MonitorableApplication instance * * If the object is already initialized, this is a no-op . * * @param self The service */ extern ROUTERDllExport void RTI_RoutingService_finalize_monitorable_application( struct RTI_RoutingService *self); /** * \ingroup RTI_RoutingServiceLibModule * @brief Returns a snapshot of the statistics collected by the enabled * built-in MonitorableApplication. * * @param self The service * @param process_periodic Output Process statistics * @param host_periodic Output Host statistics * @param snapshot_period Period at which the statistics metrics are collected * @param now Current time */ extern ROUTERDllExport void RTI_RoutingService_collect_application_stats( struct RTI_RoutingService *self, struct RTI_Service_Monitoring_ProcessPeriodic *process_periodic, struct RTI_Service_Monitoring_HostPeriodic *host_periodic, const struct DDS_Duration_t *snapshot_period, const struct DDS_Duration_t *now); /** * \ingroup RTI_RoutingServiceLibModule * * @brief Creates a Monitorable object to track common metrics of a Session, * such as per-thread cpu usage. * * @param self The service * @param[in] session_fully_qualified_name Fully qualified name of the Sesssion */ extern ROUTERDllExport struct RTI_RoutingServiceMonitorable * RTI_RoutingService_create_monitorable_session( struct RTI_RoutingService *self, const char *session_fully_qualified_name); /** * \ingroup RTI_RoutingServiceLibModule * * @brief Deletes a monitorable session * * @param self The service * @param[inout] monitorable_session Object to be deleted */ extern ROUTERDllExport void RTI_RoutingService_delete_monitorable_session( struct RTI_RoutingService *self, struct RTI_RoutingServiceMonitorable *monitorable_session); /** * \ingroup RTI_RoutingServiceLibModule * * @brief Returns a snapshot of the statistics collected for the specified * MonitorableSession * */ extern ROUTERDllExport void RTI_RoutingService_collect_monitorable_session_stats( void *monitorable_data, struct RTI_Service_Monitoring_ThreadPoolPeriodic *thread_pool_periodic, const struct DDS_Duration_t *snapshot_period, const struct DDS_Duration_t *now); /** * \ingroup RTI_RoutingServiceLibModule * * @brief Enters the critical section of the monitorable. * * After this operation returns, the current context is within a critical * section that can be leveraged for safe modification and access to * monitorable data shared between sampling and publication threads. * * @param self The service */ extern ROUTERDllExport void RTI_RoutingService_begin_monitorable_access( struct RTI_RoutingService *self); /** * \ingroup RTI_RoutingServiceLibModule * * @brief Leaves the critical section of the monitorable. * * After this operation returns, the current contexts leaves the critical * section entered with RTI_RoutingService_begin_monitorable_access. * * @param self The service */ extern ROUTERDllExport void RTI_RoutingService_end_monitorable_access( struct RTI_RoutingService *self); /** * \ingroup RTI_RoutingServiceLibModule * * @brief Returns the monitoring timestamp of the current time * * @param self The service * @param[out] now The output time */ extern ROUTERDllExport void RTI_RoutingService_get_time( struct RTI_RoutingService *self, struct RTINtpTime *now); #ifdef __cplusplus } /* extern "C" */ #endif #endif /* routingservice_monitoring_h */