stats: Correct the documentation around tag extraction (#22378)

Commit Message: The documentation in the protobuf comments for stats tag extractors has been stale since 2018. This corrects the documentation to match the current behavior.
Additional Description: This documents a change that was done in Feb 2018: #2515 -- obviously we should've fixed the doc then but it was overlooked.
Risk Level: low
Testing: none
Docs Changes: this is a doc change only, to reflect current reality
Release Notes: n/a
Platform Specific Features: n/a

Signed-off-by: Joshua Marantz <jmarantz@google.com>

Mirrored from https://github.com/envoyproxy/envoy @ 076bc515b3e6fca54592174928fc7ab06763b812

envoy/config/metrics/v3/stats.proto

@@ -48,10 +48,11 @@ message StatsConfig {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.metrics.v2.StatsConfig";
 
-  // Each stat name is iteratively processed through these tag specifiers.
-  // When a tag is matched, the first capture group is removed from the name so
-  // later :ref:`TagSpecifiers <envoy_v3_api_msg_config.metrics.v3.TagSpecifier>` cannot match that
-  // same portion of the match.
+  // Each stat name is independently processed through these tag specifiers. When a tag is
+  // matched, the first capture group is not immediately removed from the name, so later
+  // :ref:`TagSpecifiers <envoy_v3_api_msg_config.metrics.v3.TagSpecifier>` can also match that
+  // same portion of the match. After all tag matching is complete, a tag-extracted version of
+  // the name is produced and is used in stats sinks that represent tags, such as Prometheus.
   repeated TagSpecifier stats_tags = 1;
 
   // Use all default tag regexes specified in Envoy. These can be combined with
@@ -265,18 +266,18 @@ message TagSpecifier {
     //     }
     //   ]
     //
-    // The two regexes of the specifiers will be processed in the definition order.
+    // The two regexes of the specifiers will be processed from the elaborated
+    // stat name.
     //
-    // The first regex will remove ``ios.``, leaving the tag extracted name
-    // ``http.connection_manager_1.user_agent.downstream_cx_total``. The tag
-    // ``envoy.http_user_agent`` will be added with tag value ``ios``.
+    // The first regex will save ``ios.`` as the tag value for ``envoy.http_user_agent``. It will
+    // leave it in the name for potential matching with additional tag specifiers. After all tag
+    // specifiers are processed the tags will be removed from the name.
     //
-    // The second regex will remove ``connection_manager_1.`` from the tag
-    // extracted name produced by the first regex
-    // ``http.connection_manager_1.user_agent.downstream_cx_total``, leaving
-    // ``http.user_agent.downstream_cx_total`` as the tag extracted name. The tag
-    // ``envoy.http_conn_manager_prefix`` will be added with the tag value
-    // ``connection_manager_1``.
+    // The second regex will populate tag ``envoy.http_conn_manager_prefix`` with value
+    // ``connection_manager_1.``, based on the original stat name.
+    //
+    // As a final step, the matched tags are removed, leaving
+    // ``http.user_agent.downstream_cx_total`` as the tag extracted name.
     string regex = 2 [(validate.rules).string = {max_bytes: 1024}];
 
     // Specifies a fixed tag value for the ``tag_name``.