1 files changed, 46 insertions, 1 deletions
diff --git a/src/core/lib/debug/stats_data.yaml b/src/core/lib/debug/stats_data.yaml
index 4e0bc5de58..ddf1294a78 100644
--- a/src/core/lib/debug/stats_data.yaml
+++ b/src/core/lib/debug/stats_data.yaml
@@ -17,63 +17,108 @@
 
 # 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
 - histogram: call_initial_size
   max: 262144
   buckets: 64
+  doc: Initial size of the grpc_call arena created at call start
 # 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
 - histogram: poll_events_returned
   max: 1024
   buckets: 128
+  doc: How many events are called for each syscall_poll
 - counter: pollset_kick
+  doc: How many polling wakeups were performed by the process
 - counter: pollset_kicked_without_poller
+  doc: How many times was a polling wakeup requested without an active poller
 - counter: pollset_kicked_again
+  doc: How many times was the same polling worker awoken repeatedly before
+       waking up
 - counter: pollset_kick_wakeup_fd
+  doc: How many times was an eventfd used as the wakeup vector for a polling
+       wakeup
 - counter: pollset_kick_wakeup_cv
+  doc: How many times was a condition variable used as the wakeup vector for a
+       polling wakeup
 - counter: pollset_kick_own_thread
+  doc: How many times could a polling wakeup be satisfied by keeping the waking
+       thread awake?
 # 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