diff --git a/doc/TAM/SAI-Proposal-TAM-stream-telemetry.md b/doc/TAM/SAI-Proposal-TAM-stream-telemetry.md index 8181c3b16..14377ab71 100644 --- a/doc/TAM/SAI-Proposal-TAM-stream-telemetry.md +++ b/doc/TAM/SAI-Proposal-TAM-stream-telemetry.md @@ -77,10 +77,12 @@ The existing telemetry solution relies on a process to proactively query stats a - The vendor SDK should support querying the minimal polling interval for each counter. - When reconfiguring any stream settings, whether it is the polling interval or the stats list, the existing stream will be interrupted and regenerated. - If any of monitored objects is deleted, the existing stream will be interrupted and regenerated. +- The collector is designed to handle single-cycle counter rollovers; however, vendors must ensure that the data does not roll over twice between two collection intervals. ### Phase 2 - Supports updating configuration without interrupting the telemetry stream +- Support stats of tam telemetry for debugging purpose ## Architecture Design @@ -971,6 +973,13 @@ typedef struct _sai_stat_st_capability_t */ uint64_t minimal_polling_interval; +/** + * @brief Maximal polling interval in nanoseconds + * + * If polling interval is more than this value, it will be unacceptable. + */ + uint64_t maximal_polling_interval; + } sai_stat_st_capability_t; typedef struct _sai_stat_st_capability_list_t @@ -1007,3 +1016,62 @@ sai_s32_list_t tel_type_mode[2] = {-1, -1}; sai_query_attribute_enum_values_capability(switch_id, SAI_OBJECT_TYPE_TAM_TEL_TYPE, SAI_TAM_TEL_TYPE_ATTR_MODE, tel_type_mode) ``` + +#### Stats for TAM telemetry + +```c++ + +/** + * @brief TAM telemetry counter IDs in sai_get_tam_telemetry_stats_ext() call + * + * @flags ranges + */ +typedef enum _sai_tam_telemetry_stat_t +{ + /** Tam telemetry stat range start */ + SAI_TAM_TELEMETRY_STAT_START, + + /** + * @brief Total number of telemetry records successfully ingested + * + * Indicates the cumulative count of telemetry messages received and accepted + * into the telemetry system. + * Unit: Count [uint64_t] + */ + SAI_TAM_TELEMETRY_STAT_INGESTED_RECORDS = SAI_TAM_TELEMETRY_STAT_START, + + /** + * @brief Number of telemetry records pending read or processing + * + * Represents current backlog or pending messages awaiting processing. + * This is a gauge-type value rather than a monotonically increasing counter. + * Unit: Count [uint64_t] + */ + SAI_TAM_TELEMETRY_STAT_PENDING_READ_RECORDS, + + /** + * @brief Total number of telemetry records successfully consumed + * + * Indicates the cumulative count of telemetry records that have been processed + * by the consumer. + * Unit: Count [uint64_t] + */ + SAI_TAM_TELEMETRY_STAT_CONSUMED_RECORDS, + + /** + * @brief Total number of telemetry records dropped + * + * Represents the cumulative number of telemetry messages discarded due to + * buffer overflow, timeout, or internal error. + * Unit: Count [uint64_t] + */ + SAI_TAM_TELEMETRY_STAT_DROPPED_RECORDS, + + /** Tam telemetry stat range end */ + SAI_TAM_TELEMETRY_STAT_END, + + SAI_TAM_TELEMETRY_STAT_CUSTOM_RANGE_BASE = 0x10000000, + +} sai_tam_telemetry_stat_t; + +``` diff --git a/inc/saitam.h b/inc/saitam.h index 3e16ab418..03edd3120 100644 --- a/inc/saitam.h +++ b/inc/saitam.h @@ -1607,6 +1607,59 @@ typedef enum _sai_tam_telemetry_attr_t } sai_tam_telemetry_attr_t; +/** + * @brief TAM telemetry counter IDs in sai_get_tam_telemetry_stats_ext() call + * + * @flags ranges + */ +typedef enum _sai_tam_telemetry_stat_t +{ + /** Tam telemetry stat range start */ + SAI_TAM_TELEMETRY_STAT_START, + + /** + * @brief Total number of telemetry records successfully ingested + * + * Indicates the cumulative count of telemetry messages received and accepted + * into the telemetry system. + * Unit: Count [uint64_t] + */ + SAI_TAM_TELEMETRY_STAT_INGESTED_RECORDS = SAI_TAM_TELEMETRY_STAT_START, + + /** + * @brief Number of telemetry records pending read or processing + * + * Represents current backlog or pending messages awaiting processing. + * This is a gauge-type value rather than a monotonically increasing counter. + * Unit: Count [uint64_t] + */ + SAI_TAM_TELEMETRY_STAT_PENDING_READ_RECORDS, + + /** + * @brief Total number of telemetry records successfully consumed + * + * Indicates the cumulative count of telemetry records that have been processed + * by the consumer. + * Unit: Count [uint64_t] + */ + SAI_TAM_TELEMETRY_STAT_CONSUMED_RECORDS, + + /** + * @brief Total number of telemetry records dropped + * + * Represents the cumulative number of telemetry messages discarded due to + * buffer overflow, timeout, or internal error. + * Unit: Count [uint64_t] + */ + SAI_TAM_TELEMETRY_STAT_DROPPED_RECORDS, + + /** Tam telemetry stat range end */ + SAI_TAM_TELEMETRY_STAT_END, + + SAI_TAM_TELEMETRY_STAT_CUSTOM_RANGE_BASE = 0x10000000, + +} sai_tam_telemetry_stat_t; + /** * @brief Create and return a telemetry object * @@ -2484,6 +2537,54 @@ sai_status_t sai_tam_telemetry_get_data( _Inout_ sai_size_t *buffer_size, _Out_ void *buffer); +/** + * @brief Get TAM telemetry statistics counters. Deprecated for backward compatibility. + * + * @param[in] tam_telemetry_id TAM telemetry id + * @param[in] number_of_counters Number of counters in the array + * @param[in] counter_ids Specifies the array of counter ids + * @param[out] counters Array of resulting counter values. + * + * @return #SAI_STATUS_SUCCESS on success, failure status code on error + */ +typedef sai_status_t (*sai_get_tam_telemetry_stats_fn)( + _In_ sai_object_id_t tam_telemetry_id, + _In_ uint32_t number_of_counters, + _In_ const sai_stat_id_t *counter_ids, + _Out_ uint64_t *counters); + +/** + * @brief Get TAM telemetry statistics counters extended. + * + * @param[in] tam_telemetry_id TAM telemetry id + * @param[in] number_of_counters Number of counters in the array + * @param[in] counter_ids Specifies the array of counter ids + * @param[in] mode Statistics mode + * @param[out] counters Array of resulting counter values. + * + * @return #SAI_STATUS_SUCCESS on success, failure status code on error + */ +typedef sai_status_t (*sai_get_tam_telemetry_stats_ext_fn)( + _In_ sai_object_id_t tam_telemetry_id, + _In_ uint32_t number_of_counters, + _In_ const sai_stat_id_t *counter_ids, + _In_ sai_stats_mode_t mode, + _Out_ uint64_t *counters); + +/** + * @brief Clear tam_telemetry statistics counters. + * + * @param[in] tam_telemetry_id TAM telemetry id + * @param[in] number_of_counters Number of counters in the array + * @param[in] counter_ids Specifies the array of counter ids + * + * @return #SAI_STATUS_SUCCESS on success, failure status code on error + */ +typedef sai_status_t (*sai_clear_tam_telemetry_stats_fn)( + _In_ sai_object_id_t tam_telemetry_id, + _In_ uint32_t number_of_counters, + _In_ const sai_stat_id_t *counter_ids); + /** * @brief SAI TAM API set */ @@ -2531,6 +2632,9 @@ typedef struct _sai_tam_api_t sai_remove_tam_telemetry_fn remove_tam_telemetry; sai_set_tam_telemetry_attribute_fn set_tam_telemetry_attribute; sai_get_tam_telemetry_attribute_fn get_tam_telemetry_attribute; + sai_get_tam_telemetry_stats_fn get_tam_telemetry_stats; + sai_get_tam_telemetry_stats_ext_fn get_tam_telemetry_stats_ext; + sai_clear_tam_telemetry_stats_fn clear_tam_telemetry_stats; sai_create_tam_collector_fn create_tam_collector; sai_remove_tam_collector_fn remove_tam_collector; diff --git a/inc/saitypes.h b/inc/saitypes.h index a32ba25da..7da623817 100644 --- a/inc/saitypes.h +++ b/inc/saitypes.h @@ -1909,6 +1909,12 @@ typedef struct _sai_stat_st_capability_t */ uint64_t minimal_polling_interval; + /** + * @brief Maximal polling interval in nanoseconds + * + * If polling interval is more than this value, it will be unacceptable. + */ + uint64_t maximal_polling_interval; } sai_stat_st_capability_t; typedef struct _sai_stat_st_capability_list_t