Documentation update and expand example

Signed-off-by: Jason Bos <[email protected]>

doc/TAM/Granular-Counter-Subscription.md

@@ -14,16 +14,18 @@
 
 This spec enhances the existing TAM (Telemetry and Monitoring) spec to add granular counter subscription.
 
-The TAM API previously allowed for predefined telemetry groups, like SAI_TAM_TELEMETRY_TYPE_SWITCH or SAI_TAM_TELEMETRY_TYPE_PORT. This provides extensibility to the API only to define new fixed collections. When collecting counters, all counters for the objects are reported.
+The TAM API  allows for predefined telemetry groups, like SAI_TAM_TELEMETRY_TYPE_SWITCH or SAI_TAM_TELEMETRY_TYPE_PORT. This provides extensibility to the API only to define new fixed collections. When collecting counters, all supported counters for the relevant objects are reported.
 
-However, the user may need enable telemetry for specific counters at runtime. For example, a user may wish to receive only port byte counters, or queue watermarks. Filtering the telemetry permits a device to generate counters samples faster than possible when all counters are collected.
+However, the user may wish to enable telemetry for a more limited set of counters, selected at runtime. For example, a user may wish to receive only port byte counters, or queue watermarks. Limiting the scope of the telemetry collection permits a device to generate counters samples faster than possible when all counters are collected, and fit many more samples into each network packet, allowing a higher rate of delivery.
 
-Additionally, to provide a meaningful identifier for a counter. The meaning will depend on the report type. For intance, an implementation may use this to label the counter in .proto file, as data in a json report, or as an enterprise-specific identifer in an IPFIX template.
+In this mode, the collector may require a meaningful identifier for a counter, which identifies both the object as well as the specific counter on the object.
+Depending on the report type, this may be carried directly in the report itself. Or it may be delivered separately, for example as an enterprise-specific
+information element ID in an IPFIX template set.
 
 ## 2.0 Configuration
 
-
 The subscription is represented by an object of SAI_TAM_COUNTER_SUBSCRIPTION. The creation of this object will indicate that a specific counter should be monitored.
+
 ```c
 typedef enum _sai_tam_counter_subscription_attr_t
 {
@@ -60,14 +62,13 @@ typedef enum _sai_tam_counter_subscription_attr_t
      /**
      * @brief Telemetry label
      *
-     * Label to identify this counter in telemetry reports.
+     * Label to identify the subscribed counter in telemetry reports.
      *
      * @type sai_uint64_t
      * @flags CREATE_ONLY
      * @default 0
      */
     SAI_TAM_COUNTER_SUBSCRIPTION_ATTR_LABEL,
-
 ```
 
 The attribute SAI_TAM_COUNTER_SUBSCRIPTION_ATTR_LABEL may be used to provide the NOS-specific counter ID.
@@ -76,41 +77,79 @@ The attribute SAI_TAM_COUNTER_SUBSCRIPTION_ATTR_LABEL may be used to provide the
 ## 3 Configuration example
 
 ```c
+
+// Example: Create a bulk report object
+sai_attr_list[0].id = SAI_TAM_REPORT_ATTR_TYPE;
+sai_attr_list[0].value.s32 = SAI_TAM_REPORT_TYPE_PROTO;
+
+sai_attr_list[1].id = SAI_TAM_REPORT_ATTR_REPORT_MODE;
+sai_attr_list[1].value.s32 = SAI_TAM_REPORT_MODE_BULK;
+
+attr_count = 2;
+
+sai_create_tam_report_fn(
+   &sai_tam_report_obj,
+   switch_id,
+   attr_count,
+   sai_attr_list);
+
+// Example: Create telemetry type object to collect object stats
 sai_attr_list[0].id = SAI_TAM_TEL_TYPE_ATTR_TAM_TELEMETRY_TYPE;
 sai_attr_list[0].value.u32 = SAI_TAM_TELEMETRY_TYPE_OBJECT_STAT;
 
-attr_count = 1;
+sai_attr_list[1].id = SAI_TAM_TEL_TYPE_ATTR_REPORT_ID;
+sai_attr_list[1].value.oid = sai_tam_report_obj;
+
+attr_count = 2;
 sai_create_tam_tel_type_fn(
     &sai_tam_tel_type_obj,
     switch_id,
     attr_count,
     sai_attr_list);
 
-// Example: Create counter subscription(s)
+// Example: Create counter subscription(s) to collect queue length and watermark
 sai_attr_list[0].id = SAI_TAM_COUNTER_SUBSCRIPTION_ATTR_TEL_TYPE;
 sai_attr_list[0].value.u32 = sai_tam_tel_type_obj;
 
 sai_attr_list[1].id = SAI_TAM_COUNTER_SUBSCRIPTION_ATTR_OBJECT_ID;
-sai_attr_list[1].value.oid = sai_ipg1_obj;
+sai_attr_list[1].value.oid = sai_queue_obj;
 
 sai_attr_list[2].id = SAI_TAM_COUNTER_SUBSCRIPTION_ATTR_STAT_ID;
-sai_attr_list[2].value.u32 = SAI_INGRESS_PRIORITY_GROUP_STAT_CURR_OCCUPANCY_BYTES;
+sai_attr_list[2].value.u32 = SAI_QUEUE_STAT_CURR_OCCUPANCY_BYTES;
 
 sai_attr_list[3].id = SAI_TAM_COUNTER_SUBSCRIPTION_ATTR_LABEL;
-sai_attr_list[3].value.u64 = 47;  // NOS-provided label
+sai_attr_list[3].value.u64 = 1;
 
 attr_count = 4;
 sai_create_tam_counter_subscription_fn(
-    &sai_tam_subscription_obj,
+    &sai_tam_subscription_obj1,
     switch_id,
     attr_count,
     sai_attr_list);
 
-// Repeat as needed for desired counters
+sai_attr_list[0].id = SAI_TAM_COUNTER_SUBSCRIPTION_ATTR_TEL_TYPE;
+sai_attr_list[0].value.u32 = sai_tam_tel_type_obj;
+
+sai_attr_list[1].id = SAI_TAM_COUNTER_SUBSCRIPTION_ATTR_OBJECT_ID;
+sai_attr_list[1].value.oid = sai_queue_obj;
+
+sai_attr_list[2].id = SAI_TAM_COUNTER_SUBSCRIPTION_ATTR_STAT_ID;
+sai_attr_list[2].value.u32 = SAI_QUEUE_STAT_WATERMARK_BYTES;
+
+sai_attr_list[3].id = SAI_TAM_COUNTER_SUBSCRIPTION_ATTR_LABEL;
+sai_attr_list[3].value.u64 = 2;
+
+attr_count = 4;
+sai_create_tam_counter_subscription_fn(
+    &sai_tam_subscription_obj2,
+    switch_id,
+    attr_count,
+    sai_attr_list);
 
 // Example: Create Telemetry object
 sai_attr_list[0].id = SAI_TAM_TELEMETRY_ATTR_TAM_TYPE_LIST;
-sai_attr_list[0].value.oid = sai_tam_tel_type_obj;
+sai_attr_list[0].value.objlist.count = 1
+sai_attr_list[0].value.objlist.list[0] = sai_tam_tel_type_obj;
 
 sai_attr_list[1].id = SAI_TAM_TELEMETRY_ATTR_COLLECTOR_LIST
 sai_attr_list[1].value.objlist.count = 1;
@@ -125,29 +164,43 @@ sai_create_tam_telemetry_fn(
 
 // Example: Create TAM object and bind to monitored objects:
 
-sai_attr_list[1].id = SAI_TAM_ATTR_TAM_TELEMETRY_OBJECTS_LIST;
-sai_attr_list[1].value.objlist.count = 1;
-sai_attr_list[1].value.objlist.list[0] = sai_tam_telemetry_obj;
+sai_attr_list[0].id = SAI_TAM_ATTR_TAM_TELEMETRY_OBJECTS_LIST;
+sai_attr_list[0].value.objlist.count = 1;
+sai_attr_list[0].value.objlist.list[0] = sai_tam_telemetry_obj;
 
-sai_attr_list[2].id = SAI_TAM_ATTR_TAM_BIND_POINT_TYPE_LIST;
-sai_attr_list[2].value.objlist.count = 1;
-sai_attr_list[2].value.objlist.list[0] = SAI_TAM_BIND_POINT_TYPE_IPG;
+sai_attr_list[1].id = SAI_TAM_ATTR_TAM_BIND_POINT_TYPE_LIST;
+sai_attr_list[1].value.objlist.count = 1;
+sai_attr_list[1].value.objlist.list[0] = SAI_TAM_BIND_POINT_TYPE_QUEUE;
 
-attr_count = 3;
+attr_count = 2;
 sai_create_tam_fn(
     &sai_tam_obj,
     switch_id,
     attr_count,
     sai_attr_list);
 
-sai_attr.id = SAI_INGRESS_PRIORITY_GROUP_ATTR_TAM;
-sai_attr.value.oid = sai_tam_obj;
+// Example: Attach the TAM to a queue
 
-sai_set_ingress_priority_group_attribute_fn(
-    sai_ipg1_obj,
-    sai_attr);
+sai_attr.id = SAI_QUEUE_ATTR_TAM;
+sai_attr.value.oid = sai_tam_obj;
 
-sai_set_ingress_priority_group_attribute_fn(
-    sai_ipg2_obj,
+sai_set_queue_attribute_fn(
+    sai_queue,
     sai_attr);
 ```
+
+## 4 Sample data export format
+
+Counter subscription is independent of a specific report format. The actual format of the report is determined by the report object. In case of GPB, a possible report format is:
+
+message CounterSubscriptionSample {
+    required uint64 timestamp = 1 [(telemetry_options).is_timestamp = true];
+    repeated uint64 counter_values = 2;
+}
+
+message CounterSubscriptionReport {
+    // Counter labels in the order the values will appear in each sample
+    repeated uint64 counter_labels = 1;
+    repeated CounterSubscriptionSample samples = 2;
+}
+

inc/saitam.h

@@ -1060,7 +1060,7 @@ typedef enum _sai_tam_tel_type_attr_t
     SAI_TAM_TEL_TYPE_ATTR_REPORT_ID,
 
     /**
-     * @brief List of Tam counter subscriptions
+     * @brief List of Tam counter subscription objects
      *
      * @type sai_object_list_t
      * @flags READ_ONLY