Add a documentation field to stats, enforce its usage

4 files changed, 96 insertions, 19 deletions

diff --git a/src/core/lib/debug/stats_data.c b/src/core/lib/debug/stats_data.c
index f4ac2ddbd2..15ccaf21c4 100644
--- a/src/core/lib/debug/stats_data.c
+++ b/src/core/lib/debug/stats_data.c
@@ -49,9 +49,46 @@ const char *grpc_stats_counter_name[GRPC_STATS_COUNTER_COUNT] = {
     "executor_wakeup_initiated",
     "executor_queue_drained",
 };
+const char *grpc_stats_counter_doc[GRPC_STATS_COUNTER_COUNT] = {
+    "Number of client side calls created by this process",
+    "Number of server side calls created by this process",
+    "Number of polling syscalls (epoll_wait, poll, etc) made by this process",
+    "Number of sleeping syscalls made by this process",
+    "Number of times histogram increments went through the slow (binary "
+    "search) path",
+    "Number of write syscalls (or equivalent - eg sendmsg) made by this "
+    "process",
+    "Number of read syscalls (or equivalent - eg recvmsg) made by this process",
+    "Number of batches received by HTTP2 transport",
+    "Number of cancelations received by HTTP2 transport",
+    "Number of batches containing send initial metadata",
+    "Number of batches containing send message",
+    "Number of batches containing send trailing metadata",
+    "Number of batches containing receive initial metadata",
+    "Number of batches containing receive message",
+    "Number of batches containing receive trailing metadata",
+    "Number of HTTP2 pings sent by process", "Number of HTTP2 writes initiated",
+    "Number of combiner lock entries by process (first items queued to a "
+    "combiner)",
+    "Number of items scheduled against combiner locks",
+    "Number of final items scheduled against combiner locks",
+    "Number of combiner locks offloaded to different threads",
+    "Number of closures scheduled against the executor (gRPC thread pool)",
+    "Number of closures scheduled by the executor to the executor",
+    "Number of thread wakeups initiated within the executor",
+    "Number of times an executor queue was drained",
+};
 const char *grpc_stats_histogram_name[GRPC_STATS_HISTOGRAM_COUNT] = {
-    "tcp_write_size", "tcp_write_iov_size", "tcp_read_size",
-    "tcp_read_offer", "tcp_read_iov_size",  "http2_send_message_size",
+    "tcp_write_size", "tcp_write_iov_size",      "tcp_read_size",
+    "tcp_read_offer", "tcp_read_offer_iov_size", "http2_send_message_size",
+};
+const char *grpc_stats_histogram_doc[GRPC_STATS_HISTOGRAM_COUNT] = {
+    "Number of bytes offered to each syscall_write",
+    "Number of byte segments offered to each syscall_write",
+    "Number of bytes received by each syscall_read",
+    "Number of bytes offered to each syscall_read",
+    "Number of byte segments offered to each syscall_read",
+    "Size of messages received by HTTP2 transport",
 };
 const int grpc_stats_table_0[65] = {
     0,       1,       2,       3,       4,       6,       8,        11,
@@ -182,11 +219,12 @@ void grpc_stats_inc_tcp_read_offer(grpc_exec_ctx *exec_ctx, int value) {
                            grpc_stats_histo_find_bucket_slow(
                                (exec_ctx), value, grpc_stats_table_0, 64));
 }
-void grpc_stats_inc_tcp_read_iov_size(grpc_exec_ctx *exec_ctx, int value) {
+void grpc_stats_inc_tcp_read_offer_iov_size(grpc_exec_ctx *exec_ctx,
+                                            int value) {
   value = GPR_CLAMP(value, 0, 1024);
   if (value < 13) {
-    GRPC_STATS_INC_HISTOGRAM((exec_ctx), GRPC_STATS_HISTOGRAM_TCP_READ_IOV_SIZE,
-                             value);
+    GRPC_STATS_INC_HISTOGRAM(
+        (exec_ctx), GRPC_STATS_HISTOGRAM_TCP_READ_OFFER_IOV_SIZE, value);
     return;
   }
   union {
@@ -199,11 +237,12 @@ void grpc_stats_inc_tcp_read_iov_size(grpc_exec_ctx *exec_ctx, int value) {
         grpc_stats_table_3[((_val.uint - 4623507967449235456ull) >> 48)] + 13;
     _bkt.dbl = grpc_stats_table_2[bucket];
     bucket -= (_val.uint < _bkt.uint);
-    GRPC_STATS_INC_HISTOGRAM((exec_ctx), GRPC_STATS_HISTOGRAM_TCP_READ_IOV_SIZE,
-                             bucket);
+    GRPC_STATS_INC_HISTOGRAM(
+        (exec_ctx), GRPC_STATS_HISTOGRAM_TCP_READ_OFFER_IOV_SIZE, bucket);
     return;
   }
-  GRPC_STATS_INC_HISTOGRAM((exec_ctx), GRPC_STATS_HISTOGRAM_TCP_READ_IOV_SIZE,
+  GRPC_STATS_INC_HISTOGRAM((exec_ctx),
+                           GRPC_STATS_HISTOGRAM_TCP_READ_OFFER_IOV_SIZE,
                            grpc_stats_histo_find_bucket_slow(
                                (exec_ctx), value, grpc_stats_table_2, 64));
 }
@@ -240,6 +279,9 @@ const int *const grpc_stats_histo_bucket_boundaries[6] = {
     grpc_stats_table_0, grpc_stats_table_2, grpc_stats_table_0,
     grpc_stats_table_0, grpc_stats_table_2, grpc_stats_table_0};
 void (*const grpc_stats_inc_histogram[6])(grpc_exec_ctx *exec_ctx, int x) = {
-    grpc_stats_inc_tcp_write_size,    grpc_stats_inc_tcp_write_iov_size,
-    grpc_stats_inc_tcp_read_size,     grpc_stats_inc_tcp_read_offer,
-    grpc_stats_inc_tcp_read_iov_size, grpc_stats_inc_http2_send_message_size};
+    grpc_stats_inc_tcp_write_size,
+    grpc_stats_inc_tcp_write_iov_size,
+    grpc_stats_inc_tcp_read_size,
+    grpc_stats_inc_tcp_read_offer,
+    grpc_stats_inc_tcp_read_offer_iov_size,
+    grpc_stats_inc_http2_send_message_size};
diff --git a/src/core/lib/debug/stats_data.h b/src/core/lib/debug/stats_data.h
index 9b2d43a03c..3151e5ab5c 100644
--- a/src/core/lib/debug/stats_data.h
+++ b/src/core/lib/debug/stats_data.h
@@ -53,16 +53,18 @@ typedef enum {
   GRPC_STATS_COUNTER_COUNT
 } grpc_stats_counters;
 extern const char *grpc_stats_counter_name[GRPC_STATS_COUNTER_COUNT];
+extern const char *grpc_stats_counter_doc[GRPC_STATS_COUNTER_COUNT];
 typedef enum {
   GRPC_STATS_HISTOGRAM_TCP_WRITE_SIZE,
   GRPC_STATS_HISTOGRAM_TCP_WRITE_IOV_SIZE,
   GRPC_STATS_HISTOGRAM_TCP_READ_SIZE,
   GRPC_STATS_HISTOGRAM_TCP_READ_OFFER,
-  GRPC_STATS_HISTOGRAM_TCP_READ_IOV_SIZE,
+  GRPC_STATS_HISTOGRAM_TCP_READ_OFFER_IOV_SIZE,
   GRPC_STATS_HISTOGRAM_HTTP2_SEND_MESSAGE_SIZE,
   GRPC_STATS_HISTOGRAM_COUNT
 } grpc_stats_histograms;
 extern const char *grpc_stats_histogram_name[GRPC_STATS_HISTOGRAM_COUNT];
+extern const char *grpc_stats_histogram_doc[GRPC_STATS_HISTOGRAM_COUNT];
 typedef enum {
   GRPC_STATS_HISTOGRAM_TCP_WRITE_SIZE_FIRST_SLOT = 0,
   GRPC_STATS_HISTOGRAM_TCP_WRITE_SIZE_BUCKETS = 64,
@@ -72,8 +74,8 @@ typedef enum {
   GRPC_STATS_HISTOGRAM_TCP_READ_SIZE_BUCKETS = 64,
   GRPC_STATS_HISTOGRAM_TCP_READ_OFFER_FIRST_SLOT = 192,
   GRPC_STATS_HISTOGRAM_TCP_READ_OFFER_BUCKETS = 64,
-  GRPC_STATS_HISTOGRAM_TCP_READ_IOV_SIZE_FIRST_SLOT = 256,
-  GRPC_STATS_HISTOGRAM_TCP_READ_IOV_SIZE_BUCKETS = 64,
+  GRPC_STATS_HISTOGRAM_TCP_READ_OFFER_IOV_SIZE_FIRST_SLOT = 256,
+  GRPC_STATS_HISTOGRAM_TCP_READ_OFFER_IOV_SIZE_BUCKETS = 64,
   GRPC_STATS_HISTOGRAM_HTTP2_SEND_MESSAGE_SIZE_FIRST_SLOT = 320,
   GRPC_STATS_HISTOGRAM_HTTP2_SEND_MESSAGE_SIZE_BUCKETS = 64,
   GRPC_STATS_HISTOGRAM_BUCKETS = 384
@@ -151,9 +153,9 @@ void grpc_stats_inc_tcp_read_size(grpc_exec_ctx *exec_ctx, int x);
 #define GRPC_STATS_INC_TCP_READ_OFFER(exec_ctx, value) \
   grpc_stats_inc_tcp_read_offer((exec_ctx), (int)(value))
 void grpc_stats_inc_tcp_read_offer(grpc_exec_ctx *exec_ctx, int x);
-#define GRPC_STATS_INC_TCP_READ_IOV_SIZE(exec_ctx, value) \
-  grpc_stats_inc_tcp_read_iov_size((exec_ctx), (int)(value))
-void grpc_stats_inc_tcp_read_iov_size(grpc_exec_ctx *exec_ctx, int x);
+#define GRPC_STATS_INC_TCP_READ_OFFER_IOV_SIZE(exec_ctx, value) \
+  grpc_stats_inc_tcp_read_offer_iov_size((exec_ctx), (int)(value))
+void grpc_stats_inc_tcp_read_offer_iov_size(grpc_exec_ctx *exec_ctx, int x);
 #define GRPC_STATS_INC_HTTP2_SEND_MESSAGE_SIZE(exec_ctx, value) \
   grpc_stats_inc_http2_send_message_size((exec_ctx), (int)(value))
 void grpc_stats_inc_http2_send_message_size(grpc_exec_ctx *exec_ctx, int x);
diff --git a/src/core/lib/debug/stats_data.yaml b/src/core/lib/debug/stats_data.yaml
index a0d042a688..53f6ff0074 100644
--- a/src/core/lib/debug/stats_data.yaml
+++ b/src/core/lib/debug/stats_data.yaml
@@ -17,51 +17,84 @@
 
 # overall
 - counter: client_calls_created
+  doc: Number of client side calls created by this process
 - counter: server_calls_created
+  doc: Number of server side calls created by this process
 # polling
 - counter: syscall_poll
+  doc: Number of polling syscalls (epoll_wait, poll, etc) made by this process
 - counter: syscall_wait
+  doc: Number of sleeping syscalls made by this process
 # stats system
 - counter: histogram_slow_lookups
+  doc: Number of times histogram increments went through the slow
+       (binary search) path
 # tcp
 - counter: syscall_write
+  doc: Number of write syscalls (or equivalent - eg sendmsg) made by this process
 - counter: syscall_read
+  doc: Number of read syscalls (or equivalent - eg recvmsg) made by this process
 - histogram: tcp_write_size
   max: 16777216 # 16 meg max write tracked
   buckets: 64
+  doc: Number of bytes offered to each syscall_write
 - histogram: tcp_write_iov_size
   max: 1024
   buckets: 64
+  doc: Number of byte segments offered to each syscall_write
 - histogram: tcp_read_size
   max: 16777216
   buckets: 64
+  doc: Number of bytes received by each syscall_read
 - histogram: tcp_read_offer
   max: 16777216
   buckets: 64
-- histogram: tcp_read_iov_size
+  doc: Number of bytes offered to each syscall_read
+- histogram: tcp_read_offer_iov_size
   max: 1024
   buckets: 64
+  doc: Number of byte segments offered to each syscall_read
 # chttp2
 - counter: http2_op_batches
+  doc: Number of batches received by HTTP2 transport
 - counter: http2_op_cancel
+  doc: Number of cancelations received by HTTP2 transport
 - counter: http2_op_send_initial_metadata
+  doc: Number of batches containing send initial metadata
 - counter: http2_op_send_message
+  doc: Number of batches containing send message
 - counter: http2_op_send_trailing_metadata
+  doc: Number of batches containing send trailing metadata
 - counter: http2_op_recv_initial_metadata
+  doc: Number of batches containing receive initial metadata
 - counter: http2_op_recv_message
+  doc: Number of batches containing receive message
 - counter: http2_op_recv_trailing_metadata
+  doc: Number of batches containing receive trailing metadata
 - histogram: http2_send_message_size
   max: 16777216
   buckets: 64
+  doc: Size of messages received by HTTP2 transport
 - counter: http2_pings_sent
+  doc: Number of HTTP2 pings sent by process
 - counter: http2_writes_begun
+  doc: Number of HTTP2 writes initiated
 # combiner locks
 - counter: combiner_locks_initiated
+  doc: Number of combiner lock entries by process
+       (first items queued to a combiner)
 - counter: combiner_locks_scheduled_items
+  doc: Number of items scheduled against combiner locks
 - counter: combiner_locks_scheduled_final_items
+  doc: Number of final items scheduled against combiner locks
 - counter: combiner_locks_offloaded
+  doc: Number of combiner locks offloaded to different threads
 # executor
 - counter: executor_scheduled_items
+  doc: Number of closures scheduled against the executor (gRPC thread pool)
 - counter: executor_scheduled_to_self
+  doc: Number of closures scheduled by the executor to the executor
 - counter: executor_wakeup_initiated
+  doc: Number of thread wakeups initiated within the executor
 - counter: executor_queue_drained
+  doc: Number of times an executor queue was drained
diff --git a/src/core/lib/iomgr/tcp_posix.c b/src/core/lib/iomgr/tcp_posix.c
index 98a2afd78b..3372e14eef 100644
--- a/src/core/lib/iomgr/tcp_posix.c
+++ b/src/core/lib/iomgr/tcp_posix.c
@@ -256,7 +256,7 @@ static void tcp_do_read(grpc_exec_ctx *exec_ctx, grpc_tcp *tcp) {
   msg.msg_flags = 0;
 
   GRPC_STATS_INC_TCP_READ_OFFER(exec_ctx, tcp->incoming_buffer->length);
-  GRPC_STATS_INC_TCP_READ_IOV_SIZE(exec_ctx, tcp->incoming_buffer->count);
+  GRPC_STATS_INC_TCP_READ_OFFER_IOV_SIZE(exec_ctx, tcp->incoming_buffer->count);
 
   GPR_TIMER_BEGIN("recvmsg", 0);
   do {