metrics

type Backend interface {
	// NewCounter must return a thread-safe Counter implementation native to the backend.
	NewCounter(name, help string, labels []string) Counter

	// NewGauge must return a thread-safe Gauge implementation native to the backend.
	NewGauge(name, help string, labels []string) Gauge

	// NewHistogram must return a thread-safe Histogram implementation native to the backend.
	// The implementation should map the provided bucket boundaries to the backend's native
	// histogram structure.
	NewHistogram(name, help string, buckets []float64, labels []string) Histogram

	// Push should implement the logic to push metrics to a remote aggregator.
	// If the backend operates on a purely pull-based model,
	// this can safely be implemented as a no-op returning nil.
	Push(ctx context.Context) error

	// Close should gracefully flush any in-memory buffers, stop background synchronization loops (if any),
	// and close open connections to the metrics sink (if any).
	Close(ctx context.Context) error
}

type Counter interface {
	// Inc increase the counter by 1.
	Inc(labelValues ...string)

	// Add adds the given value to the counter. It panics if the value is < 0.
	Add(val float64, labelValues ...string)
}

type Gauge interface {
	// Set forces the Gauge to a specific value.
	Set(val float64, labelValues ...string)

	// Add applies a relative adjustment to the Gauge.
	// Unlike Counter, Gauge allows negative value to be passed to Add.
	Add(val float64, labelValues ...string)
}

type Histogram interface {
	// Observe records a single data point (e.g., the time taken to process
	// a request) into the histogram's underlying buckets.
	Observe(val float64, labelValues ...string)
}

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

type Provider interface {
	// NewCounter creates a new metric that strictly increases (e.g., number of requests served,
	// errors encountered, or tasks completed).
	NewCounter(name, help string, labels []string) Counter

	// NewGauge creates a new metric that can arbitrarily go up and down (e.g., current memory usage,
	// number of active connections, or queue size).
	NewGauge(name, help string, labels []string) Gauge

	// NewHistogram creates a new metric that samples observations (usually request durations or response sizes)
	// and counts them in configurable buckets.
	NewHistogram(name, help string, buckets []float64, labels []string) Histogram

	// NewTimer creates a specialized component specifically designed for measuring durations.
	// It wraps an underlying Histogram and provides a convenient Stop() method to record elapsed time.
	NewTimer(name, help string, buckets []float64, labels []string) *Timer

	// Push forces the underlying metrics to be sent to the remote backend immediately.
	// This is typically used in batch jobs, ephemeral processes, or when using a push-based
	// architecture.
	Push(ctx context.Context) error

	// Close flushes pending metrics.
	Close(ctx context.Context) error
}

type ProviderFactory func(enabled bool) Provider

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