callstats

package
v0.71.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 17, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package callstats keeps a rolling, in-memory record of per-server tool-call outcomes so the health calculator can report a server whose calls mostly fail as degraded even though its connection looks fine (Spec 113-d).

The window is bucketed (30 buckets of 10 s = 5 min) so Record and Snapshot are O(buckets) with no per-call allocation. Nothing here is persisted.

Index

Constants

View Source
const (
	// BucketSize is the width of one counter bucket.
	BucketSize = 10 * time.Second
	// NumBuckets is the number of buckets kept.
	NumBuckets = 30
	// WindowSize is the rolling window length (NumBuckets * BucketSize).
	WindowSize = NumBuckets * BucketSize
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Kind

type Kind uint8

Kind is the dominant class of a failed call.

const (
	// KindNone means no failure (or no data).
	KindNone Kind = iota
	// KindNetwork is a connection-level failure (refused, reset, closed, EOF).
	KindNetwork
	// KindTimeout is a timeout or deadline after the call was dispatched.
	KindTimeout
	// KindHTTP is an HTTP status failure from the upstream.
	KindHTTP
	// KindJSONRPC is a JSON-RPC protocol error from the upstream.
	KindJSONRPC
	// KindSession is a terminated MCP session.
	KindSession
	// KindOther is any other counted failure.
	KindOther
)

func Classify

func Classify(ctx context.Context, result *mcp.CallToolResult, err error) (counted, failed bool, kind Kind)

Classify decides how one dispatched tool call affects the failure-rate window. ctx is the caller's dispatch context (nil is allowed). It is a denylist over typed proxy-side outcomes (Spec 113 FR-061):

  • isError:true results are tool-level answers, not transport failures: uncounted.
  • limiter rejections, connection-generation refusals, caller cancellation and auth-required errors are not the upstream's fault: uncounted.
  • every other error from the dispatch is a counted failure.
  • a nil error with a normal result is a counted success.

Profile/quarantine refusals and argument validation happen before dispatch and never reach this predicate.

func (Kind) String

func (k Kind) String() string

String returns a short human-readable label used in health detail text.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry holds one Window per server name.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty registry using the wall clock.

func (*Registry) Drop

func (r *Registry) Drop(server string)

Drop discards a server's window (server removed or renamed).

func (*Registry) Record

func (r *Registry) Record(server string, counted, failed bool, kind Kind)

Record adds an outcome for server.

func (*Registry) SetClock

func (r *Registry) SetClock(now func() time.Time)

SetClock replaces the registry clock. Intended for tests.

func (*Registry) Snapshot

func (r *Registry) Snapshot(server string) (calls, failures int, dominant Kind)

Snapshot returns the current window counts for server (zeros if unknown).

type Window

type Window struct {
	// contains filtered or unexported fields
}

Window is a rolling per-server outcome counter. The zero value is ready to use and safe for concurrent use.

func (*Window) Record

func (w *Window) Record(now time.Time, counted, failed bool, kind Kind)

Record adds one outcome. Uncounted outcomes (counted == false) are ignored: they are in neither the numerator nor the denominator.

func (*Window) Snapshot

func (w *Window) Snapshot(now time.Time) (calls, failures int, dominant Kind)

Snapshot returns the counted calls, failures and the most frequent failure kind inside the window ending at now.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL