metrics

type AggregationPusher interface {
	// PushCount returns the count of metric records matching the given criteria.
	// The labels parameter is optional — if non-nil, only records with those labels are counted.
	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", "entity.popularity").
	MetricName string

	// Value is the numeric measurement.
	Value float64

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

	// RecordID is the entity's primary key (stringified). Empty for type-level metrics.
	RecordID string
}

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

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

	// RecordID is the primary key of the entity, stringified.
	// Empty for type-level metrics (e.g. list counts).
	RecordID string `json:"record_id" db:"record_id" bson:"record_id"`

	// MetricName identifies the metric (e.g. "crud.action", "entity.popularity").
	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 key-value dimensions for slicing metrics.
	// Stored as a JSON blob in SQL databases via JSONColumn.
	Labels r3.JSONColumn[Labels] `json:"labels" db:"labels" bson:"labels"`

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

	// CreatedAt is the timestamp 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 CRUD operation took.
	Duration time.Duration

	// Entity is the result entity (after mutation for create/update/patch,
	// before deletion for delete, fetched entity for get).
	// For list operations, this is the zero value — use Entities instead.
	Entity T

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

	// OldEntity is the entity state before mutation (for update/patch/delete).
	// Zero value for create/get/list.
	OldEntity T

	// HasOld indicates whether OldEntity is valid.
	HasOld bool

	// ID is the entity primary key (for get/delete). Zero value for create/list.
	EntityID ID

	// TotalCount is the total matching count from List (before pagination). Zero for other ops.
	TotalCount int64

	// Query is the r3.Query passed to Get or List. Empty for mutations.
	Query r3.Query

	// Fields is the field list passed to Patch. Nil for other operations.
	Fields r3.Fields

	// Err is the error returned by the inner CRUD operation (nil on success).
	// Most collectors only fire on success, but ErrorCollector uses this.
	Err error
}

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

type Options[T any, ID comparable] struct {
	// RecordType is the name used to identify this entity type in metric records.
	// If empty, it is derived automatically from the struct type T
	// (e.g. Order -> "orders", CampaignAdset -> "campaign_adsets").
	RecordType string

	// IDFunc extracts the primary key from an entity.
	// Required for entity-level metrics (popularity, per-entity counters).
	IDFunc IDFunc[T, ID]

	// Collectors defines what metrics to emit for CRUD operations.
	// Multiple collectors are composed — all are called on every operation.
	Collectors []Collector[T, ID]

	// Labelers extract dimension labels from entities.
	// Applied to every metric record where an entity is available.
	Labelers []Labeler[T]

	// ContextLabelers extract dimension labels from request context.
	// Applied to every metric record.
	ContextLabelers []ContextLabeler

	// BucketSize controls the time granularity for metric bucketing.
	// Default: BucketDaily.
	BucketSize BucketSize

	// Async when true records metrics in a background goroutine.
	// The CRUD operation returns immediately; metric recording errors are logged
	// but do not affect the CRUD result. Default: false (synchronous).
	Async bool

	// ErrorHandler is called when metric persistence fails.
	// If nil, errors are logged via 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 is the maximum age of metric records. Records older than this
	// are deleted during enforcement. Zero means no age-based retention.
	MaxAge time.Duration

	// MaxRecords is the maximum number of metric records to keep per entity type.
	// When exceeded, the oldest records are deleted first. Zero means no 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.
	// It describes the original granularity of the compacted records
	// (e.g. BucketMinutely, BucketHourly).
	SourceBucket BucketSize

	// TargetBucket is the coarser bucket size to roll up into
	// (e.g. BucketHourly, BucketDaily).
	TargetBucket BucketSize

	// MinAge is the minimum age of records before they become eligible for rollup.
	// Only records older than this are compacted. Zero means all records.
	MinAge time.Duration
}

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