Add broker and web throughput diagnostics

src/session_broker.h

@@ -49,6 +49,11 @@ typedef struct {
     session_broker_client_id_t writer_id;
 } session_broker_event_t;
 
+/*
+ * Active-client counters cover this connection (or the last counter clear).
+ * They become unavailable on disconnect and reset on slot/generation reuse;
+ * global totals retain disconnected clients' traffic until explicitly cleared.
+ */
 typedef struct {
     /* UART bytes considered for delivery while this client was connected. */
     uint64_t uart_rx_bytes;
@@ -67,13 +72,18 @@ typedef struct {
     uint64_t events_queued;
     uint64_t events_popped;
     uint64_t event_drops;
+    /* Peak output occupancy, <= SESSION_BROKER_OUTPUT_SIZE; clear seeds pending. */
+    size_t output_high_water_bytes;
 } session_broker_client_counters_t;
 
 typedef struct {
     uint64_t uart_rx_bytes;
     /* UART RX drained when there were no connected observers. */
     uint64_t unobserved_rx_bytes;
-    /* Queue/read/drop totals count one copy per client observer. */
+    /* Queue/read/drop totals count one copy per client observer.
+     * Drops include full-buffer losses and unread output discarded on disconnect.
+     * Read means handed to a transport, not confirmed delivery to its peer.
+     */
     uint64_t output_queued_bytes;
     uint64_t output_read_bytes;
     uint64_t output_dropped_bytes;
@@ -158,7 +168,9 @@ esp_err_t session_broker_get_global_snapshot(session_broker_global_snapshot_t *s
 size_t session_broker_list_clients(session_broker_client_snapshot_t *clients,
                                    size_t capacity);
 
-/* Counter clearing does not reset client IDs, queued data, or event sequence. */
+/* Counter clearing does not reset client IDs, queued data, or event sequence.
+ * Client output high-water marks restart at current queued occupancy, not zero.
+ */
 esp_err_t session_broker_clear_counters(void);
 esp_err_t session_broker_clear_client_counters(session_broker_client_id_t client_id);