Better inline docs for stat name / object / suffix terminology

ambuc · ambuc · commit 732af4f5bc92 · 2018-07-10T13:46:53.000-04:00
Signed-off-by: James Buckland &lt;jbuckland@google.com&gt;
diff --git a/include/envoy/stats/stats.h b/include/envoy/stats/stats.h
@@ -29,6 +29,18 @@ namespace Stats {
  * maximum stat suffix length of a stat. These have defaults in StatsOptionsImpl, and the maximum
  * object name length can be overridden. The default initialization is used in IsolatedStatImpl, and
  * the user-overridden struct is stored in Options.
+ *
+ *  As noted in the comment above StatsOptionsImpl in source/common/stats/stats_impl.h, a stat name
+ * often contains both a string whose length is user-defined (cluster_name in the below example),
+ * and a specific statistic name generated by Envoy, which are often as long as
+ * `upstream_cx_connect_attempts_exceeded`. To make room for growth on both fronts, we limit the max
+ * allowed length of each separately.
+ *
+ *                           name / stat name
+ *  |----------------------------------------------------------------|
+ *  cluster.<cluster_name>.outlier_detection.ejections_consecutive_5xx
+ *  |--------------------------------------| |-----------------------|
+ *                object name                         suffix
  */
 class StatsOptions {
 public:
