dynamic_modules: test stats sink tag callbacks end to end and fix a doc comment

Signed-off-by: Basundhara Chakrabarty <basundhara17061996@gmail.com>

Author: basundhara-c

source/extensions/dynamic_modules/sdk/rust/src/lib_test.rs

@@ -6742,6 +6742,14 @@ const STUB_COUNTER_TAG_EXTRACTED_NAMES: [&str; 2] = ["cluster.rq_total", "counte
 const STUB_COUNTER_TAGS: [&[(&str, &str)]; 2] =
   [&[("envoy.cluster_name", "foo"), ("envoy.response_code", "200")], &[]];
 
+// Tag data for the single stub gauge and text readout, matching STUB_GAUGES / STUB_TEXT_READOUTS.
+// Both carry one tag so the gauge and text-readout tag wrappers are exercised distinctly from the
+// counter ones, guarding against a wrapper wired to the wrong ABI callback.
+const STUB_GAUGE_TAG_EXTRACTED_NAMES: [&str; 1] = ["cluster.cx_active"];
+const STUB_GAUGE_TAGS: [&[(&str, &str)]; 1] = [&[("envoy.cluster_name", "bar")]];
+const STUB_TEXT_READOUT_TAG_EXTRACTED_NAMES: [&str; 1] = ["control_plane.identifier"];
+const STUB_TEXT_READOUT_TAGS: [&[(&str, &str)]; 1] = [&[("envoy.control_plane", "xds")]];
+
 // Counts stub_write invocations on the calling thread so tests can assert the grow-and-retry
 // behavior (each ABI getter call writes its name once, plus a value for text readouts). It is
 // thread-local so it stays correct even if tests run in parallel.
@@ -6866,9 +6874,8 @@ pub extern "C" fn envoy_dynamic_module_callback_stat_sink_snapshot_get_counter_t
   true
 }
 
-// Gauge and text-readout tag callbacks share the counter tag code paths, so the harness stubs
-// them as empty (no tags) purely to satisfy linkage; the counter stubs above carry the tag data
-// the tests exercise.
+// The gauge and text-readout tag callbacks share the counter tag code paths, but each stub serves
+// its own canned data so the corresponding SDK wrappers are exercised distinctly.
 #[no_mangle]
 pub extern "C" fn envoy_dynamic_module_callback_stat_sink_snapshot_get_gauge_tag_extracted_name(
   _snapshot: abi::envoy_dynamic_module_type_stat_sink_snapshot_envoy_ptr,
@@ -6877,10 +6884,17 @@ pub extern "C" fn envoy_dynamic_module_callback_stat_sink_snapshot_get_gauge_tag
   name_buffer_capacity: usize,
   name_size: *mut usize,
 ) -> bool {
-  if index >= STUB_GAUGES.len() {
+  if index >= STUB_GAUGE_TAG_EXTRACTED_NAMES.len() {
     return false;
   }
-  unsafe { stub_write(STUB_GAUGES[index].0, name_buffer, name_buffer_capacity, name_size) };
+  unsafe {
+    stub_write(
+      STUB_GAUGE_TAG_EXTRACTED_NAMES[index],
+      name_buffer,
+      name_buffer_capacity,
+      name_size,
+    );
+  }
   true
 }
 
@@ -6890,26 +6904,34 @@ pub extern "C" fn envoy_dynamic_module_callback_stat_sink_snapshot_get_gauge_tag
   index: usize,
   tag_count: *mut usize,
 ) -> bool {
-  if index >= STUB_GAUGES.len() {
+  if index >= STUB_GAUGE_TAGS.len() {
     return false;
   }
-  unsafe { *tag_count = 0 };
+  unsafe { *tag_count = STUB_GAUGE_TAGS[index].len() };
   true
 }
 
 #[no_mangle]
 pub extern "C" fn envoy_dynamic_module_callback_stat_sink_snapshot_get_gauge_tag(
   _snapshot: abi::envoy_dynamic_module_type_stat_sink_snapshot_envoy_ptr,
-  _index: usize,
-  _tag_index: usize,
-  _name_buffer: *mut std::ffi::c_char,
-  _name_buffer_capacity: usize,
-  _name_size: *mut usize,
-  _value_buffer: *mut std::ffi::c_char,
-  _value_buffer_capacity: usize,
-  _value_size: *mut usize,
+  index: usize,
+  tag_index: usize,
+  name_buffer: *mut std::ffi::c_char,
+  name_buffer_capacity: usize,
+  name_size: *mut usize,
+  value_buffer: *mut std::ffi::c_char,
+  value_buffer_capacity: usize,
+  value_size: *mut usize,
 ) -> bool {
-  false
+  if index >= STUB_GAUGE_TAGS.len() || tag_index >= STUB_GAUGE_TAGS[index].len() {
+    return false;
+  }
+  let (name, value) = STUB_GAUGE_TAGS[index][tag_index];
+  unsafe {
+    stub_write(name, name_buffer, name_buffer_capacity, name_size);
+    stub_write(value, value_buffer, value_buffer_capacity, value_size);
+  }
+  true
 }
 
 #[no_mangle]
@@ -6920,10 +6942,17 @@ pub extern "C" fn envoy_dynamic_module_callback_stat_sink_snapshot_get_text_read
   name_buffer_capacity: usize,
   name_size: *mut usize,
 ) -> bool {
-  if index >= STUB_TEXT_READOUTS.len() {
+  if index >= STUB_TEXT_READOUT_TAG_EXTRACTED_NAMES.len() {
     return false;
   }
-  unsafe { stub_write(STUB_TEXT_READOUTS[index].0, name_buffer, name_buffer_capacity, name_size) };
+  unsafe {
+    stub_write(
+      STUB_TEXT_READOUT_TAG_EXTRACTED_NAMES[index],
+      name_buffer,
+      name_buffer_capacity,
+      name_size,
+    );
+  }
   true
 }
 
@@ -6933,26 +6962,34 @@ pub extern "C" fn envoy_dynamic_module_callback_stat_sink_snapshot_get_text_read
   index: usize,
   tag_count: *mut usize,
 ) -> bool {
-  if index >= STUB_TEXT_READOUTS.len() {
+  if index >= STUB_TEXT_READOUT_TAGS.len() {
     return false;
   }
-  unsafe { *tag_count = 0 };
+  unsafe { *tag_count = STUB_TEXT_READOUT_TAGS[index].len() };
   true
 }
 
 #[no_mangle]
 pub extern "C" fn envoy_dynamic_module_callback_stat_sink_snapshot_get_text_readout_tag(
   _snapshot: abi::envoy_dynamic_module_type_stat_sink_snapshot_envoy_ptr,
-  _index: usize,
-  _tag_index: usize,
-  _name_buffer: *mut std::ffi::c_char,
-  _name_buffer_capacity: usize,
-  _name_size: *mut usize,
-  _value_buffer: *mut std::ffi::c_char,
-  _value_buffer_capacity: usize,
-  _value_size: *mut usize,
+  index: usize,
+  tag_index: usize,
+  name_buffer: *mut std::ffi::c_char,
+  name_buffer_capacity: usize,
+  name_size: *mut usize,
+  value_buffer: *mut std::ffi::c_char,
+  value_buffer_capacity: usize,
+  value_size: *mut usize,
 ) -> bool {
-  false
+  if index >= STUB_TEXT_READOUT_TAGS.len() || tag_index >= STUB_TEXT_READOUT_TAGS[index].len() {
+    return false;
+  }
+  let (name, value) = STUB_TEXT_READOUT_TAGS[index][tag_index];
+  unsafe {
+    stub_write(name, name_buffer, name_buffer_capacity, name_size);
+    stub_write(value, value_buffer, value_buffer_capacity, value_size);
+  }
+  true
 }
 
 #[no_mangle]
@@ -7139,6 +7176,27 @@ fn test_metric_snapshot_reads_tags() {
   assert_eq!(snapshot.counter_tag_count(2), None);
   assert!(!snapshot.counter_tag(0, 2, &mut name, &mut value));
   assert!(!snapshot.counter_tag(2, 0, &mut name, &mut value));
+
+  // gauge_0: one tag. Exercises the gauge tag wrappers, which are distinct entry points from the
+  // counter ones.
+  assert!(snapshot.gauge_tag_extracted_name(0, &mut name));
+  assert_eq!(name.as_slice(), b"cluster.cx_active");
+  assert_eq!(snapshot.gauge_tag_count(0), Some(1));
+  assert!(snapshot.gauge_tag(0, 0, &mut name, &mut value));
+  assert_eq!(name.as_slice(), b"envoy.cluster_name");
+  assert_eq!(value.as_slice(), b"bar");
+  assert_eq!(snapshot.gauge_tag_count(1), None);
+  assert!(!snapshot.gauge_tag(0, 1, &mut name, &mut value));
+
+  // text_0: one tag. Exercises the text-readout tag wrappers.
+  assert!(snapshot.text_readout_tag_extracted_name(0, &mut name));
+  assert_eq!(name.as_slice(), b"control_plane.identifier");
+  assert_eq!(snapshot.text_readout_tag_count(0), Some(1));
+  assert!(snapshot.text_readout_tag(0, 0, &mut name, &mut value));
+  assert_eq!(name.as_slice(), b"envoy.control_plane");
+  assert_eq!(value.as_slice(), b"xds");
+  assert_eq!(snapshot.text_readout_tag_count(1), None);
+  assert!(!snapshot.text_readout_tag(0, 1, &mut name, &mut value));
 }
 
 #[test]

source/extensions/dynamic_modules/sdk/rust/src/stats_sink.rs

@@ -120,7 +120,7 @@ impl<'a> MetricSnapshot<'a> {
   }
 
   /// Reads the tag-extracted name of the counter at `index` into `name` (the stat name with tag
-  /// values removed). Returns `None` and leaves `name` unchanged when the index is out of range.
+  /// values removed). Returns `false` and leaves `name` unchanged when the index is out of range.
   pub fn counter_tag_extracted_name(&self, index: usize, name: &mut Vec<u8>) -> bool {
     fill_buffer(name, |ptr, capacity, size| unsafe {
       abi::envoy_dynamic_module_callback_stat_sink_snapshot_get_counter_tag_extracted_name(

test/extensions/dynamic_modules/stat_sink/abi_impl_test.cc

@@ -262,8 +262,8 @@ TEST_F(DynamicModuleStatsSinkAbiTest, GetGaugeTagExtractedNameAndTags) {
   EXPECT_EQ("cluster.cx_active", written(name_buffer, name_size, sizeof(name_buffer)));
 
   size_t tag_count = 0;
-  EXPECT_TRUE(envoy_dynamic_module_callback_stat_sink_snapshot_get_gauge_tag_count(
-      snapshotHandle(), 0, &tag_count));
+  EXPECT_TRUE(envoy_dynamic_module_callback_stat_sink_snapshot_get_gauge_tag_count(snapshotHandle(),
+                                                                                   0, &tag_count));
   EXPECT_EQ(1u, tag_count);
 
   char tag_name[256];
@@ -277,6 +277,36 @@ TEST_F(DynamicModuleStatsSinkAbiTest, GetGaugeTagExtractedNameAndTags) {
   EXPECT_EQ("bar", written(tag_value, tag_value_size, sizeof(tag_value)));
 }
 
+// The text-readout tag callbacks reach the third snapshot collection; a spot check confirms the
+// wiring, mirroring the gauge check above.
+TEST_F(DynamicModuleStatsSinkAbiTest, GetTextReadoutTagExtractedNameAndTags) {
+  t0_.name_ = "control_plane.foo.identifier";
+  t0_.setTagExtractedName("control_plane.identifier");
+  t0_.setTags({{"envoy.control_plane", "foo"}});
+  snapshot_.text_readouts_.push_back(t0_);
+
+  char name_buffer[256];
+  size_t name_size = 0;
+  EXPECT_TRUE(envoy_dynamic_module_callback_stat_sink_snapshot_get_text_readout_tag_extracted_name(
+      snapshotHandle(), 0, name_buffer, sizeof(name_buffer), &name_size));
+  EXPECT_EQ("control_plane.identifier", written(name_buffer, name_size, sizeof(name_buffer)));
+
+  size_t tag_count = 0;
+  EXPECT_TRUE(envoy_dynamic_module_callback_stat_sink_snapshot_get_text_readout_tag_count(
+      snapshotHandle(), 0, &tag_count));
+  EXPECT_EQ(1u, tag_count);
+
+  char tag_name[256];
+  char tag_value[256];
+  size_t tag_name_size = 0;
+  size_t tag_value_size = 0;
+  ASSERT_TRUE(envoy_dynamic_module_callback_stat_sink_snapshot_get_text_readout_tag(
+      snapshotHandle(), 0, 0, tag_name, sizeof(tag_name), &tag_name_size, tag_value,
+      sizeof(tag_value), &tag_value_size));
+  EXPECT_EQ("envoy.control_plane", written(tag_name, tag_name_size, sizeof(tag_name)));
+  EXPECT_EQ("foo", written(tag_value, tag_value_size, sizeof(tag_value)));
+}
+
 // =============================================================================
 // Gauge callbacks
 // =============================================================================

test/extensions/dynamic_modules/stat_sink/integration_test.cc

@@ -88,16 +88,23 @@ INSTANTIATE_TEST_SUITE_P(
 TEST_P(DynamicModulesStatsSinkIntegrationTest, BasicFlush) {
   // The "found gauge server.uptime" marker proves the module decoded a gauge name through the
   // buffer-based snapshot API.
-  EXPECT_LOG_CONTAINS_ALL_OF(Envoy::ExpectedLogMessages({
-                                 {"info", "stat sink integration test: config_new called"},
-                                 {"info", "stat sink integration test: flush called"},
-                                 {"info", "stat sink integration test: found gauge server.uptime"},
-                             }),
-                             {
-                               addStatSinkAndInitialize();
-                               timeSystem().realSleepDoNotUseWithoutScrutiny(
-                                   std::chrono::milliseconds(500));
-                             });
+  Envoy::ExpectedLogMessages expected{
+      {"info", "stat sink integration test: config_new called"},
+      {"info", "stat sink integration test: flush called"},
+      {"info", "stat sink integration test: found gauge server.uptime"},
+  };
+  if (language() == "rust") {
+    // Only the Rust SDK exposes the tag callbacks. The "reconstructed tagged gauge" marker proves
+    // the module read the tag-extracted name and the "envoy.cluster_name" tag of the always-present
+    // cluster.membership_total gauge and rebuilt the dimensional name a Prometheus-style sink would
+    // emit.
+    expected.push_back({"info", "stat sink integration test: reconstructed tagged gauge "
+                                "cluster.membership_total envoy.cluster_name=cluster_0"});
+  }
+  EXPECT_LOG_CONTAINS_ALL_OF(expected, {
+    addStatSinkAndInitialize();
+    timeSystem().realSleepDoNotUseWithoutScrutiny(std::chrono::milliseconds(500));
+  });
 }
 
 TEST_P(DynamicModulesStatsSinkIntegrationTest, FlushAfterTraffic) {

test/extensions/dynamic_modules/test_data/rust/stat_sink_integration_test.rs

@@ -63,23 +63,61 @@ impl StatSink for TestStatSink {
     // pattern the API enables (for example writing each name to a socket).
     let mut name = Vec::new();
     let mut value = Vec::new();
+    let mut tag_name = Vec::new();
+    let mut tag_value = Vec::new();
+    // Exercise the counter tag callbacks against every counter in the live snapshot. Every tag
+    // index the count reports must resolve; a mismatch means the count and the per-tag reader
+    // disagree.
+    let mut counter_tags_consistent = true;
     for index in 0..snapshot.counter_count() {
       let _ = snapshot.counter(index, &mut name);
+      if !snapshot.counter_tag_extracted_name(index, &mut name) {
+        counter_tags_consistent = false;
+        continue;
+      }
+      let Some(tag_count) = snapshot.counter_tag_count(index) else {
+        counter_tags_consistent = false;
+        continue;
+      };
+      for tag_index in 0..tag_count {
+        if !snapshot.counter_tag(index, tag_index, &mut tag_name, &mut tag_value) {
+          counter_tags_consistent = false;
+        }
+      }
     }
     // Decode every gauge name and look for the always-present "server.uptime" gauge, which proves a
     // name round-trips byte-for-byte through the buffer API end to end.
     let mut found_uptime = false;
+    // Reconstruct the dimensional name of a tagged gauge from its tag-extracted name and tags, the
+    // way a Prometheus-style sink would. "cluster.cluster_0.membership_total" carries a single
+    // "envoy.cluster_name" tag whose value is the cluster name, so the tag callbacks must yield
+    // tag-extracted name "cluster.membership_total" and tag ("envoy.cluster_name", "cluster_0").
+    let mut found_tagged_gauge = false;
     for index in 0..snapshot.gauge_count() {
       if snapshot.gauge(index, &mut name).is_some() && name.as_slice() == b"server.uptime" {
         found_uptime = true;
       }
+      if snapshot.gauge_tag_extracted_name(index, &mut name)
+        && name.as_slice() == b"cluster.membership_total"
+        && snapshot.gauge_tag_count(index) == Some(1)
+        && snapshot.gauge_tag(index, 0, &mut tag_name, &mut tag_value)
+        && tag_name.as_slice() == b"envoy.cluster_name"
+        && tag_value.as_slice() == b"cluster_0"
+      {
+        found_tagged_gauge = true;
+      }
     }
     for index in 0..snapshot.text_readout_count() {
       let _ = snapshot.text_readout(index, &mut name, &mut value);
     }
     if found_uptime {
       envoy_log_info!("stat sink integration test: found gauge server.uptime");
     }
+    // A tagged gauge reconstructed from the tag callbacks, and every counter's tag count agreed
+    // with its per-tag reads: the tag ABI round-trips end to end against a live snapshot.
+    if found_tagged_gauge && counter_tags_consistent {
+      envoy_log_info!("stat sink integration test: reconstructed tagged gauge cluster.membership_total envoy.cluster_name=cluster_0");
+    }
     envoy_log_info!(
       "stat sink integration test: flush called counters={} gauges={}",
       snapshot.counter_count(),