Documentation
¶
Overview ¶
Package metrics provides a generic timeseries store for recording and querying (timestamp, value) points behind a thin Timeseries interface.
The root package ships an in-process implementation (NewMemory) with no external dependencies, suitable for CLIs, tests, and single-process servers. A cross-process, persistent implementation backed by valkey/redis sorted sets lives in the sibling submodule github.com/flanksource/clicky/valkey, which depends on valkey-go so the root module stays dependency-free.
Both implementations share the same wire format (see codec.go) so a metric recorded by one can be queried by the other, and RegisterRoutes serves either over HTTP without knowing which backend it holds.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EncodeMember ¶
EncodeMember renders a Point as a sorted-set member string of the form "<unixMillis>:<value>". The millisecond timestamp prefix doubles as the sorted-set score, and including it in the member keeps members unique even when two observations share a value. The value is formatted with -1 precision so it round-trips losslessly through ParseMember.
func Handler ¶
func Handler(ts Timeseries, prefix string) http.Handler
Handler returns the metrics endpoint as a standalone http.Handler for callers that compose their own mux. It expects to be mounted such that request paths look like {prefix}/metrics/{id}.
func RegisterRoutes ¶
func RegisterRoutes(mux *http.ServeMux, ts Timeseries, prefix string)
RegisterRoutes mounts the metrics read endpoint on mux under prefix:
GET {prefix}/metrics/{id}?since=&until=
The handler owns all request parsing, querying, and JSON encoding — callers supply only a Timeseries. prefix is the leading path segment shared with the rest of the API (e.g. "/api/v1"); it is used verbatim, so pass it without a trailing slash.
Types ¶
type MemoryConfig ¶
type MemoryConfig struct {
// Retention drops points older than this on each Record. Zero -> 1h.
Retention time.Duration
// MaxPoints caps the points kept per metric ID; the oldest are dropped
// first on overflow. Zero -> 4096.
MaxPoints int
}
MemoryConfig tunes the in-process Timeseries. Zero fields fall back to defaults: Retention 1h, MaxPoints 4096.
type Point ¶
Point is a single observation in a timeseries.
func ParseMember ¶
ParseMember reverses EncodeMember. It returns an error for any member that does not match the "<unixMillis>:<value>" shape so a corrupt entry surfaces loudly rather than decoding to a zero Point.
type QueryRequest ¶
QueryRequest reads the points for metric ID whose timestamps fall in [Since, Until]. The HTTP handler resolves zero bounds to a default window (Until = now, Since = now-1h); implementations treat a zero bound as unbounded on that side.
type RecordRequest ¶
RecordRequest records one Point for metric ID. A zero At is resolved to the current time by the implementation.
type Timeseries ¶
type Timeseries interface {
// Record appends a point. Recording is best-effort instrumentation: an
// implementation backed by an unavailable store may return an error, but
// callers are expected to log-and-continue rather than fail the producer.
Record(req RecordRequest) error
// Query returns the points in the requested range, ascending by time.
Query(req QueryRequest) ([]Point, error)
}
Timeseries stores and retrieves timeseries points. Implementations must be safe for concurrent use.
func NewMemory ¶
func NewMemory(cfg MemoryConfig) Timeseries
NewMemory returns an in-process Timeseries. It needs no backend and is the zero-config default for CLIs, tests, and single-process servers.
Source Files