metrics

package module

v0.1.0 Latest Latest Go to latest Published: May 16, 2026 License: MIT Imports: 8 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/algo2go/kite-mcp-metrics

Links

Open Source Insights

README ¶

kite-mcp-metrics

Telemetry primitives for the algo2go/* module family — Prometheus-exposition counters, histograms, and daily-bucket gauges. Pure stdlib at runtime (stretchr/testify is a test-only dependency).

Surface

metrics.Manager — the top-level container. Exposes counter + histogram + daily-gauge collection plus an HTTP handler that emits the Prometheus text format on /metrics.
metrics.Histogram — fixed-bucket histogram (latency-shaped buckets in milliseconds; configurable via WithBuckets). Emits <name>_bucket{le="..."} series + _count + _sum.
Daily-bucket gauges — per-day counters that roll over at midnight UTC, for tracking unique-users / login-count / per-day-tool-call shapes without time-series cardinality explosion.

Origin

Extracted 2026-05-16 from github.com/algo2go/kite-mcp-bootstrap/app/metrics as Phase 0 of the bootstrap-decomposition arc (see kite-mcp-bootstrap/.research/bootstrap-decomp-empirical-mapping.md). Zero behavior change at extraction; the only consumer (kite-mcp-bootstrap) imports this module via replace during the Phase A canary window, then via GOPROXY once Phase B canary deletion lands.

License

MIT — see LICENSE.

Documentation ¶

Constants ¶

View Source

const (
	DefaultServiceName          = "kite-mcp"
	DefaultHistoricalDays       = 7
	DefaultCleanupRetentionDays = 30
	DefaultCleanupHour          = 3 // 3 AM
	DefaultCleanupDay           = 6 // Saturday (0=Sunday, 6=Saturday)

	PrometheusContentType = "text/plain; version=0.0.4; charset=utf-8"
	AdminPathPrefix       = "/admin/"
	MetricsPathSuffix     = "/metrics"
)

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type Config ¶

type Config struct {
	ServiceName          string // defaults to DefaultServiceName
	AdminSecretPath      string // required for admin endpoint, empty = disabled
	HistoricalDays       int    // defaults to DefaultHistoricalDays
	CleanupRetentionDays int    // defaults to DefaultCleanupRetentionDays
	AutoCleanup          bool   // defaults to true
}

Config holds configuration for creating a metrics manager

type HistogramSource ¶

type HistogramSource func() ([]ToolHistogramSnapshot, error)

HistogramSource is invoked at scrape time to produce the per-tool latency histogram snapshots. Returning a non-nil error suppresses histogram emission for the scrape (counters and other metrics still emit). Nil source = no histograms emitted (back-compat default).

type Manager ¶

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

Manager handles metrics collection and export

func New ¶

func New(cfg Config) *Manager

New creates a new metrics manager with the given configuration

func (*Manager) AdminHTTPHandler ¶

func (m *Manager) AdminHTTPHandler() http.HandlerFunc

AdminHTTPHandler returns an HTTP handler with admin path protection

func (*Manager) CleanupOldData ¶

func (m *Manager) CleanupOldData() error

CleanupOldData removes user data older than the configured retention period

func (*Manager) GetAllCounters ¶

func (m *Manager) GetAllCounters() map[string]int64

GetAllCounters returns a snapshot of all counter values.

func (*Manager) GetCounterValue ¶

func (m *Manager) GetCounterValue(key string) int64

GetCounterValue returns the current value of a counter

func (*Manager) GetDailyUserCount ¶

func (m *Manager) GetDailyUserCount(date string) int64

GetDailyUserCount returns unique user count for a specific date

func (*Manager) GetTodayUserCount ¶

func (m *Manager) GetTodayUserCount() int64

GetTodayUserCount returns today's unique user count

func (*Manager) HTTPHandler ¶

func (m *Manager) HTTPHandler() http.HandlerFunc

HTTPHandler returns an HTTP handler for the metrics endpoint

func (*Manager) Increment ¶

func (m *Manager) Increment(key string)

Increment atomically increments a counter

func (*Manager) IncrementBy ¶

func (m *Manager) IncrementBy(key string, n int64)

IncrementBy atomically increments a counter by n

func (*Manager) IncrementDaily ¶

func (m *Manager) IncrementDaily(key string)

IncrementDaily atomically increments a daily counter for today

func (*Manager) IncrementDailyBy ¶

func (m *Manager) IncrementDailyBy(key string, n int64)

IncrementDailyBy atomically increments a daily counter by n for today

func (*Manager) SetHistogramSource ¶

func (m *Manager) SetHistogramSource(src HistogramSource)

SetHistogramSource registers (or replaces, or clears with nil) the histogram source. Safe to call concurrently with WritePrometheus — the source pointer is read once per scrape.

func (*Manager) Shutdown ¶

func (m *Manager) Shutdown()

Shutdown stops the cleanup routine

func (*Manager) TrackDailyUser ¶

func (m *Manager) TrackDailyUser(userID string)

TrackDailyUser tracks a unique user login for today

func (*Manager) WritePrometheus ¶

func (m *Manager) WritePrometheus(buf *bytes.Buffer)

WritePrometheus writes all metrics in Prometheus format

type ToolBucket ¶

type ToolBucket struct {
	LeMs  int64
	Count int
}

ToolBucket is a single Prometheus-style cumulative bucket. Mirrors kc/audit.ToolHistogramBucket but lives in this package so the metrics surface does not import kc/audit (would invert the layer graph). The wire-up site (app/wire.go) bridges the two shapes via a small adapter closure.

type ToolHistogramSnapshot ¶

type ToolHistogramSnapshot struct {
	ToolName  string
	CallCount int
	SumMs     float64
	Buckets   []ToolBucket
}

ToolHistogramSnapshot is the histogram-source row for a single tool. CallCount equals the +Inf bucket; SumMs is the sum of all duration_ms values in the window. Buckets must be cumulative non-decreasing per Prometheus convention.

Source Files ¶

View all Source files

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