N1: the bus module's nats_consumers lists consumers by delivered-rate or created

The flow per consumer is measured within one call, so a busy bus says with what.

Builds: design 47 H2 §813 (5), §819
This commit is contained in:
2026-11-21 23:04:31 +01:00
parent 32e1ed6c55
commit c5a593eb05
3 changed files with 139 additions and 2 deletions
+99 -1
View File
@@ -11,6 +11,7 @@ import (
"encoding/json"
"errors"
"fmt"
"sort"
"strings"
"time"
@@ -254,7 +255,7 @@ func decodeStored(b []byte) (*Stored, error) {
return &Stored{Seq: doc.Message.Seq, Subject: doc.Message.Subject, Time: doc.Message.Time, Data: doc.Message.Data}, nil
}
// readTools are the two reads that locate a lost event.
// readTools are the reads that locate a lost event, and the consumers' flow.
func readTools(jsz func() ([]byte, error), open MsgOpen) []stdio.Tool {
return []stdio.Tool{
{Name: "nats_consumer",
@@ -270,6 +271,7 @@ func readTools(jsz func() ([]byte, error), open MsgOpen) []stdio.Tool {
}
return Consumer(doc, arg(a, "stream"), arg(a, "consumer"))
}},
flowTool(jsz, time.Sleep),
{Name: "nats_stream_messages",
Description: "The messages a stream keeps for one subject (a filter with * or > is allowed), newest first: sequence, subject, time and size of each, and the body only when asked for, no larger than 4 KiB, and only on the stream EVENTS (every kept event is there); on every other stream (kept events, asks, calls and replies, mail, dead letters, records, logs) only sequence, subject, time and size. Bounded by count (default 20, at most 200) and bytes (default 1 MiB); says when it stopped before the oldest the stream keeps. Read on the bus module's own credential. Refuses the streams of a module's kept state (KV_*, OBJ_*): their values are read through their owners' tools; this tool is for lost events.",
Input: map[string]any{"stream": str("the stream, e.g. EVENTS"), "subject": str("a subject or filter, e.g. mesh.mod.mesh-delivery-indexer.event.view-changed"),
@@ -313,3 +315,99 @@ func readTools(jsz func() ([]byte, error), open MsgOpen) []stdio.Tool {
}},
}
}
// defaultRateWindow is how long nats_consumers measures each consumer's deliveries when the call names no rate-window
// (design 47 H2 §813 (5)).
const defaultRateWindow = 10 * time.Second
// ConsumerFlow is one consumer's flow: how many messages a second it was delivered over the window, and when it was made.
type ConsumerFlow struct {
Stream string `json:"stream"`
Consumer string `json:"consumer"`
Created string `json:"created"`
DeliveredRate float64 `json:"delivered-rate"`
Delivered int64 `json:"delivered"`
Pending int64 `json:"pending"`
Unacknowledged int64 `json:"unacknowledged"`
}
// ConsumerFlows is every consumer of every stream, its delivered-rate the deliveries between the two monitoring documents
// before and after, read window apart, a second; sorted by delivered-rate, the fastest first, or by created, the newest
// first (design 47 H2 §813 (5)). A consumer the second document does not hold is left out: it was removed meanwhile.
func ConsumerFlows(before, after []byte, window time.Duration, by string) (map[string]any, error) {
if by == "" {
by = "delivered-rate"
}
if by != "delivered-rate" && by != "created" {
return nil, fmt.Errorf("sort is delivered-rate or created, not %q", by)
}
var a, b jszDoc
if err := json.Unmarshal(before, &b); err != nil {
return nil, err
}
if err := json.Unmarshal(after, &a); err != nil {
return nil, err
}
was := map[string]int64{}
for _, acc := range b.Accounts {
for _, s := range acc.Streams {
for _, c := range s.Consumers {
was[s.Name+"\x00"+c.Name] = c.Delivered.Consumer
}
}
}
rows := []ConsumerFlow{}
for _, acc := range a.Accounts {
for _, s := range acc.Streams {
for _, c := range s.Consumers {
rate := 0.0
if start, ok := was[s.Name+"\x00"+c.Name]; ok && window > 0 && c.Delivered.Consumer > start {
rate = float64(c.Delivered.Consumer-start) / window.Seconds()
}
rows = append(rows, ConsumerFlow{Stream: s.Name, Consumer: c.Name, Created: c.Created, DeliveredRate: rate,
Delivered: c.Delivered.Consumer, Pending: c.NumPending, Unacknowledged: c.NumAckPending})
}
}
}
sort.SliceStable(rows, func(i, j int) bool {
if by == "created" {
return createdAt(rows[i].Created).After(createdAt(rows[j].Created))
}
return rows[i].DeliveredRate > rows[j].DeliveredRate
})
return map[string]any{"sort": by, "rate-window-seconds": window.Seconds(), "consumers": rows}, nil
}
func createdAt(s string) time.Time { t, _ := time.Parse(time.RFC3339Nano, s); return t }
// flowTool is nats_consumers: the monitoring document read twice, rate-window apart, within the one call; wait is how the
// window passes (time.Sleep live, a stand-in in a test).
func flowTool(jsz func() ([]byte, error), wait func(time.Duration)) stdio.Tool {
return stdio.Tool{Name: "nats_consumers",
Description: "Every consumer of every stream with its flow: delivered-rate (messages delivered a second, measured over rate-window within this one call), delivered, pending and unacknowledged, and when it was created; sorted by delivered-rate (the fastest first, the default) or by created (the newest first). The question behind a bus that is busy and no one knows with what.",
Input: map[string]any{"sort": str("delivered-rate (default) or created"),
"rate-window": num("seconds the deliveries are measured over, within this call (default 10)")},
Run: func(a map[string]any) (any, error) {
window := defaultRateWindow
if v, ok := a["rate-window"].(float64); ok {
if v <= 0 {
return nil, errors.New("rate-window is a number of seconds above 0")
}
window = time.Duration(v * float64(time.Second))
}
by := arg(a, "sort")
if by != "" && by != "delivered-rate" && by != "created" {
return nil, fmt.Errorf("sort is delivered-rate or created, not %q", by)
}
before, err := jsz()
if err != nil {
return nil, err
}
wait(window)
after, err := jsz()
if err != nil {
return nil, err
}
return ConsumerFlows(before, after, window, by)
}}
}
+39 -1
View File
@@ -47,6 +47,42 @@ func TestAConsumerIsReadWithItsConfigAndItsState(t *testing.T) {
t.Fatalf("%v answered", c)
}
}
t.Run("nats_consumers measures the flow within the call and sorts it", consumersFlow)
}
// consumersFlow: design 47 H2 §813 (5). Two consumers, the older delivered 40 messages over the 4 s window, the newer
// 4; the window passes through the stand-in wait, never a real sleep.
func consumersFlow(t *testing.T) {
doc := func(oldSeq, newSeq int) []byte {
return []byte(fmt.Sprintf(`{"account_details":[{"stream_detail":[{"name":"EVENTS","consumer_detail":[
{"name":"old","created":"2026-11-01T10:00:00Z","delivered":{"consumer_seq":%d},"num_pending":7},
{"name":"new","created":"2026-11-21T10:00:00Z","delivered":{"consumer_seq":%d}}]}]}]}`, oldSeq, newSeq))
}
reads, waited := 0, time.Duration(0)
tool := flowTool(func() ([]byte, error) {
reads++
if reads%2 == 1 {
return doc(100, 10), nil
}
return doc(140, 14), nil
}, func(d time.Duration) { waited += d })
out, err := tool.Run(map[string]any{"rate-window": float64(4)})
if err != nil {
t.Fatal(err)
}
rows := out.(map[string]any)["consumers"].([]ConsumerFlow)
if waited != 4*time.Second || len(rows) != 2 || rows[0].Consumer != "old" || rows[0].DeliveredRate != 10 || rows[1].DeliveredRate != 1 || rows[0].Pending != 7 {
t.Fatalf("waited %s: %+v", waited, rows)
}
out, _ = tool.Run(map[string]any{"sort": "created"})
if rows := out.(map[string]any)["consumers"].([]ConsumerFlow); waited != 14*time.Second || rows[0].Consumer != "new" {
t.Fatalf("the default window or the sort by created: waited %s, %+v", waited, rows)
}
for _, bad := range []map[string]any{{"sort": "name"}, {"rate-window": float64(0)}} {
if _, err := tool.Run(bad); err == nil {
t.Fatalf("%v answered", bad)
}
}
}
func TestMessagesComeNewestFirstBoundedAndBodiesOnlyWhenAsked(t *testing.T) {
@@ -82,9 +118,11 @@ func TestMessagesComeNewestFirstBoundedAndBodiesOnlyWhenAsked(t *testing.T) {
if r := got["messages"].([]MessageRow)[0]; r.Body != "" || r.BodyOmitted == "" {
t.Fatalf("%+v", r)
}
t.Run("messages scan back across blocks and say an unanswered read", messagesScanBack)
}
func TestMessagesScanBackAcrossBlocksAndSayAnUnansweredRead(t *testing.T) {
// messagesScanBack is run by TestMessagesComeNewestFirstBoundedAndBodiesOnlyWhenAsked (design 47 H2 §819: fewer tests).
func messagesScanBack(t *testing.T) {
ctx := context.Background()
got, _ := NewestMessages(ctx, func(_ context.Context, _ string, seq uint64, _ string) (*Stored, error) {
if seq <= 3 {
+1
View File
@@ -164,6 +164,7 @@
"nats_streams",
"nats_backlog",
"nats_consumer",
"nats_consumers",
"nats_stream_messages",
"nats_buckets",
"nats_users",