types

const (
	// None represents an uninitialized or invalid metric type.
	//
	// This value should not be used for actual metrics. It exists as a zero value
	// for the MetricType enum and can be used to detect uninitialized metrics.
	//
	// Any attempt to register a metric with type None will fail.
	None MetricType = iota

	// Counter represents a cumulative metric that only increases.
	//
	// A counter is a monotonically increasing value that starts at zero and can only
	// increase (or be reset to zero on restart). Counters are ideal for tracking
	// cumulative counts of events.
	//
	// Common uses:
	//   - Total number of HTTP requests
	//   - Total number of errors
	//   - Total bytes transferred
	//   - Total number of tasks processed
	//
	// Operations:
	//   - Inc(): Increment by 1
	//   - Add(n): Increment by n (n must be positive)
	//
	// PromQL patterns:
	//   - rate(metric[5m]): Requests per second
	//   - increase(metric[1h]): Total increase over 1 hour
	//   - irate(metric[5m]): Instantaneous rate
	//
	// Example:
	//   http_requests_total{method="GET",status="200"} 12345
	Counter

	// Gauge represents a metric that can arbitrarily go up or down.
	//
	// A gauge represents a single numerical value that can increase or decrease.
	// Gauges are typically used for measured values that can fluctuate.
	//
	// Common uses:
	//   - Current memory usage
	//   - Number of active connections
	//   - Queue depth
	//   - Temperature readings
	//   - CPU usage percentage
	//
	// Operations:
	//   - Set(v): Set to specific value
	//   - Inc(): Increment by 1
	//   - Dec(): Decrement by 1
	//   - Add(v): Add v (can be negative)
	//   - Sub(v): Subtract v
	//
	// PromQL patterns:
	//   - metric: Current value
	//   - avg_over_time(metric[5m]): Average value
	//   - max_over_time(metric[1h]): Maximum value
	//   - min_over_time(metric[1h]): Minimum value
	//
	// Example:
	//   active_connections{server="web-1"} 42
	Gauge

	// Histogram represents a distribution of values with predefined buckets.
	//
	// A histogram samples observations (usually request durations or response sizes)
	// and counts them in configurable buckets. It also provides a sum of all observed
	// values and a total count.
	//
	// Metrics generated:
	//   - <name>_bucket{le="X"}: Cumulative count of observations <= X
	//   - <name>_sum: Sum of all observed values
	//   - <name>_count: Total number of observations
	//
	// Common uses:
	//   - HTTP request duration
	//   - Response size distribution
	//   - Query execution time
	//   - Job processing duration
	//
	// Operations:
	//   - Observe(v): Record an observation
	//
	// PromQL patterns:
	//   - histogram_quantile(0.95, rate(metric_bucket[5m])): 95th percentile
	//   - rate(metric_sum[5m]) / rate(metric_count[5m]): Average value
	//   - rate(metric_count[5m]): Operations per second
	//
	// Bucket configuration:
	//   Buckets must be defined when creating the metric:
	//   metric.AddBuckets(0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10)
	//
	// Advantages:
	//   - Can calculate quantiles across multiple instances
	//   - Efficient storage and computation
	//   - Aggregatable
	//
	// Example:
	//   http_request_duration_seconds_bucket{le="0.1"} 95000
	//   http_request_duration_seconds_bucket{le="0.5"} 99500
	//   http_request_duration_seconds_bucket{le="+Inf"} 100000
	//   http_request_duration_seconds_sum 28000
	//   http_request_duration_seconds_count 100000
	Histogram

	// Summary represents a distribution with streaming quantiles.
	//
	// A summary samples observations and calculates configurable quantiles over
	// a sliding time window. It's similar to a histogram but computes quantiles
	// on the client side.
	//
	// Metrics generated:
	//   - <name>{quantile="X"}: Pre-calculated quantile value
	//   - <name>_sum: Sum of all observed values
	//   - <name>_count: Total number of observations
	//
	// Common uses:
	//   - Request latencies (when precise quantiles needed)
	//   - Response sizes (when bucket ranges unknown)
	//
	// Operations:
	//   - Observe(v): Record an observation
	//
	// PromQL patterns:
	//   - metric{quantile="0.95"}: Pre-calculated 95th percentile
	//   - rate(metric_sum[5m]) / rate(metric_count[5m]): Average value
	//
	// Objectives configuration:
	//   Quantiles and their error margins must be defined:
	//   metric.SetObjectives(map[float64]float64{
	//       0.5: 0.05,   // median with ±5% error
	//       0.9: 0.01,   // 90th percentile with ±1% error
	//       0.99: 0.001, // 99th percentile with ±0.1% error
	//   })
	//
	// Disadvantages:
	//   - Cannot aggregate quantiles across instances
	//   - More computationally expensive than histograms
	//   - Quantiles are calculated per instance
	//
	// Recommendation:
	//   Prefer Histogram over Summary in most cases. Use Summary only when:
	//     - You cannot define buckets upfront
	//     - You need very precise quantiles for a single instance
	//     - Cross-instance aggregation is not needed
	//
	// Example:
	//   http_request_duration_seconds{quantile="0.5"} 0.15
	//   http_request_duration_seconds{quantile="0.9"} 0.35
	//   http_request_duration_seconds{quantile="0.99"} 0.75
	//   http_request_duration_seconds_sum 28000
	//   http_request_duration_seconds_count 100000
	Summary
)