metrics

type AggregationPusher interface {
	// PushCount returns the count of matching records. A non-nil labels filters
	// to records carrying those labels.
	PushCount(ctx context.Context, recordType, metricName string, tr TimeRange, labels Labels) (int64, error)

	// PushSum returns the sum of metric values matching the given criteria.
	PushSum(ctx context.Context, recordType, metricName string, tr TimeRange, labels Labels) (float64, error)

	// PushAvg returns the average of metric values matching the given criteria.
	PushAvg(ctx context.Context, recordType, metricName string, tr TimeRange, labels Labels) (float64, error)

	// PushTopN returns the top N entities by summed metric value.
	PushTopN(
		ctx context.Context,
		recordType, metricName string,
		tr TimeRange,
		n int,
		labels Labels,
	) ([]RankedEntity, error)

	// PushTimeSeries returns metric values grouped by time bucket.
	PushTimeSeries(
		ctx context.Context,
		recordType, metricName string,
		tr TimeRange,
		bucket BucketSize,
		labels Labels,
	) ([]BucketValue, error)

	// PushGroupBy returns metric values grouped by a label key.
	PushGroupBy(
		ctx context.Context,
		recordType, metricName string,
		tr TimeRange,
		labelKey string,
		labels Labels,
	) (map[string]float64, error)
}

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

type BucketSize string

type BucketValue struct {
	Bucket string
	Value  float64
}

type CRUD[T any, ID comparable] struct {
	// contains filtered or unexported fields
}

type Collector[T any, ID comparable] interface {
	Collect(ctx context.Context, opCtx OperationContext[T, ID]) []MetricEntry
}

type CollectorFunc[T any, ID comparable] func(ctx context.Context, opCtx OperationContext[T, ID]) []MetricEntry

type ContextLabeler func(ctx context.Context) Labels

type IDFunc[T any, ID comparable] func(entity T) ID

type Labeler[T any] func(entity T) Labels

type Labels map[string]string

type MetricEntry struct {
	// MetricName identifies the metric (e.g. "crud.action").
	MetricName string

	// Value is the numeric measurement.
	Value float64

	// Labels are collector-specific, merged with global/context/core labels by
	// the decorator.
	Labels Labels

	// RecordID is the stringified entity key; empty for type-level metrics.
	RecordID string
}

type MetricRecord struct {
	// ID is the unique identifier for this record.
	ID string `json:"id" db:"id,pk" bson:"_id"`

	// RecordType is the entity type name (e.g. "users"), derived from the struct
	// type or set via options.
	RecordType string `json:"record_type" db:"record_type" bson:"record_type"`

	// RecordID is the stringified entity key; empty for type-level metrics.
	RecordID string `json:"record_id" db:"record_id" bson:"record_id"`

	// MetricName identifies the metric (e.g. "crud.action").
	MetricName string `json:"metric_name" db:"metric_name" bson:"metric_name"`

	// Value is the numeric measurement (1 for counters, ms for latency, etc.).
	Value float64 `json:"value" db:"value" bson:"value"`

	// Labels carries arbitrary dimensions, stored as a JSON blob in SQL.
	Labels r3.JSONColumn[Labels] `json:"labels" db:"labels" bson:"labels"`

	// Bucket is the pre-computed time bucket for efficient aggregation: RFC3339
	// truncated to the boundary (e.g. "2026-02-16T00:00:00Z" for daily).
	Bucket string `json:"bucket" db:"bucket" bson:"bucket"`

	// CreatedAt is when this metric was recorded.
	CreatedAt time.Time `json:"created_at" db:"created_at" bson:"created_at"`
}

type Operation string

type OperationContext[T any, ID comparable] struct {
	// Operation is the CRUD method that was invoked.
	Operation Operation

	// Duration is the wall-clock time the inner operation took.
	Duration time.Duration

	// Entity is the result: post-mutation for create/update/patch, pre-deletion
	// for delete, fetched for get. Zero for list - use Entities.
	Entity T

	// Entities is the result set for List. Nil otherwise.
	Entities []T

	// OldEntity is the state before mutation (update/patch/delete).
	OldEntity T

	// HasOld reports whether OldEntity is valid.
	HasOld bool

	// EntityID is the primary key (get/delete).
	EntityID ID

	// TotalCount is List's total match count before pagination.
	TotalCount int64

	// Query is the r3.Query passed to Get or List.
	Query r3.Query

	// Fields is the field list passed to Patch.
	Fields r3.Fields

	// Err is the inner operation's error, nil on success. Most collectors fire
	// only on success; ErrorCollector uses this.
	Err error
}

type Option[T any, ID comparable] func(*Options[T, ID])

type Options[T any, ID comparable] struct {
	// RecordType names this entity type in metric records. If empty, derived from
	// T as snake_case plural (e.g. Order -> "orders").
	RecordType string

	// IDFunc extracts the primary key; required for entity-level metrics.
	IDFunc IDFunc[T, ID]

	// Collectors are the metrics emitted per operation; all run on every op.
	Collectors []Collector[T, ID]

	// Labelers extract labels from entities, applied wherever an entity is available.
	Labelers []Labeler[T]

	// ContextLabelers extract labels from request context, applied to every record.
	ContextLabelers []ContextLabeler

	// BucketSize is the time bucketing granularity. Default: BucketDaily.
	BucketSize BucketSize

	// Async records metrics in a background goroutine: the CRUD op returns
	// immediately and recording errors are logged, not surfaced. Default: false.
	Async bool

	// ErrorHandler is called on persistence failure; if nil, errors go to slog.
	ErrorHandler func(error)
}

type QueryOption func(*queryConfig)

type RankedEntity struct {
	RecordID string
	Value    float64
}

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

type RetentionPolicy struct {
	// MaxAge deletes records older than this. Zero disables age-based retention.
	MaxAge time.Duration

	// MaxRecords caps records kept per entity type, deleting the oldest first.
	// Zero disables the count-based limit.
	MaxRecords int64
}

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

type RollupPolicy struct {
	// SourceBucket is recorded in the summary's _rollup_source label for
	// provenance only; it does not filter which records are compacted.
	SourceBucket BucketSize

	// TargetBucket is the coarser bucket size to roll up into.
	TargetBucket BucketSize

	// MinAge compacts only records older than this. Zero means all records.
	MinAge time.Duration
}

type TimeRange struct {
	From time.Time
	To   time.Time
}