relayer

var (
	// RelaysTotal is a Counter metric for the total requests processed by the relay miner.
	// It increments to track proxy requests and is labeled by 'service_id',
	// essential for monitoring load and traffic on different proxies and services.
	//
	// Usage:
	// - Monitor total request load.
	// - Compare requests across services or proxies.
	RelaysTotal = prometheus.NewCounterFrom(stdprometheus.CounterOpts{
		Subsystem: relayMinerProcess,
		Name:      requestsTotal,
		Help:      "Total number of requests processed, labeled by service ID.",
	}, []string{"service_id", "supplier_operator_address"})

	// RelaysErrorsTotal is a Counter for total error events in the relay miner.
	// It increments with each error, labeled by 'service_id',
	// crucial for pinpointing error-prone areas for reliability improvement.
	//
	// Usage:
	// - Track and analyze error types and distribution.
	// - Compare error rates for reliability analysis.
	RelaysErrorsTotal = prometheus.NewCounterFrom(stdprometheus.CounterOpts{
		Subsystem: relayMinerProcess,
		Name:      requestsErrorsTotal,
		Help:      "Total number of error events.",
	}, []string{"service_id"})

	// RelaysSuccessTotal is a Counter metric for successful requests in the relay miner.
	// It increments with each successful request, labeled by 'service_id'.
	RelaysSuccessTotal = prometheus.NewCounterFrom(stdprometheus.CounterOpts{
		Subsystem: relayMinerProcess,
		Name:      requestsSuccessTotal,
		Help:      "Total number of successful requests processed, labeled by service ID.",
	}, []string{"service_id"})

	// RelaysDurationSeconds observes the end-to-end duration of the request in the relay miner.
	//
	// It includes the duration of the request to the backend service/data node AS WELL AS
	// the duration of the RelayMiner's internal overhead.
	//
	// Usage:
	// - Analyze typical response times and long-tail latency issues.
	// - Compare performance across services or environments.
	RelaysDurationSeconds = prometheus.NewHistogramFrom(stdprometheus.HistogramOpts{
		Subsystem: relayMinerProcess,
		Name:      relayDurationSeconds,
		Help:      "Histogram of request durations for performance analysis.",
		Buckets:   defaultBuckets,
	}, []string{"service_id", "status_code"})

	// ServiceDurationSeconds observes the duration of the request to the backend service/data node outside of the RelayMiner.
	//
	// This histogram, labeled by 'service_id' and 'status_code', measures response times,
	// vital for performance analysis under different loads.
	//
	// It is a complementary metric to RelaysDurationSeconds allowing to isolate the
	// performance of the data node and the overhead of the RelayMiner's internal processing.
	//
	// Usage:
	// - Analyze typical response times and long-tail latency issues.
	// - Compare performance across services or environments.
	ServiceDurationSeconds = prometheus.NewHistogramFrom(stdprometheus.HistogramOpts{
		Subsystem: relayMinerProcess,
		Name:      serviceDurationSeconds,
		Help:      "Histogram of service call durations for performance analysis.",
		Buckets:   defaultBuckets,
	}, []string{"service_id", "status_code"})

	// TODO_TECHDEBT: Remove those metrics once the session rollover issue is resolved.
	// RelayRequestPreparationDurationSeconds observes the duration of preparing
	// a relay request from an HTTP request.
	//
	// This histogram, labeled by 'service_id', measures the time taken to prepare
	// a relay request, which includes unmarshaling the request body and preparing
	// the RelayRequest structure.
	// Usage:
	// - Analyze the time taken to prepare relay requests.
	// - Identify potential bottlenecks in request preparation.
	RelayRequestPreparationDurationSeconds = prometheus.NewHistogramFrom(stdprometheus.HistogramOpts{
		Subsystem: relayMinerProcess,
		Name:      requestPreparationDurationSeconds,
		Help:      "Histogram of relay request preparation durations in seconds.",
		Buckets:   defaultBuckets,
	}, []string{"service_id"})

	// TODO_TECHDEBT: Remove those metrics once the session rollover issue is resolved.
	// RelayResponsePreparationDurationSeconds observes the duration of preparing
	// a relay response from the the service's HTTP response.
	//
	// This histogram, labeled by 'service_id', measures the time taken to prepare
	// a relay response, which includes marshaling the response body and preparing
	// the RelayResponse structure.
	// Usage:
	// - Analyze the time taken to prepare relay responses.
	// - Identify potential bottlenecks in response preparation.
	RelayResponsePreparationDurationSeconds = prometheus.NewHistogramFrom(stdprometheus.HistogramOpts{
		Subsystem: relayMinerProcess,
		Name:      responsePreparationDurationSeconds,
		Help:      "Histogram of relay response preparation durations in seconds.",
		Buckets:   defaultBuckets,
	}, []string{"service_id"})

	// FullNodeGRPCCallDurationSeconds is a histogram metric for measuring the duration of gRPC calls.
	//
	// It is labeled by 'component' (e.g., miner, proxy) and 'method', capturing the time taken for each call.
	// This metric is essential for performance monitoring and analysis of gRPC interactions.
	// Usage:
	// - Monitor gRPC call performance.
	// - Identify slow or problematic calls.
	FullNodeGRPCCallDurationSeconds = prometheus.NewHistogramFrom(stdprometheus.HistogramOpts{
		Subsystem: relayMinerProcess,
		Name:      fullNodeGRPCCallDurationSeconds,
		Help:      "Histogram of gRPC call durations for performance analysis.",
		Buckets:   defaultBuckets,
	}, []string{"component", "method"})

	// RelayResponseSizeBytes is a histogram metric for observing response size distribution.
	// It counts responses in bytes, with buckets:
	// - 100 bytes to 50,000 bytes, capturing a range from small to large responses.
	// This data helps in accurately representing response size distribution and is vital
	// for performance tuning.
	//
	// TODO_TECHDEBT: Consider configuring bucket sizes externally for flexible adjustments
	// in response to different data patterns or deployment scenarios.
	RelayResponseSizeBytes = prometheus.NewHistogramFrom(stdprometheus.HistogramOpts{
		Subsystem: relayMinerProcess,
		Name:      responseSizeBytes,
		Help:      "Histogram of response sizes in bytes for performance analysis.",
		Buckets:   []float64{100, 500, 1000, 5000, 10000, 50000},
	}, []string{"service_id"})

	// RelayRequestSizeBytes is a histogram metric for observing request size distribution.
	// It counts requests in bytes, with buckets:
	// - 100 bytes to 50,000 bytes, capturing a range from small to large requests.
	// This data helps in accurately representing request size distribution and is vital
	// for performance tuning.
	RelayRequestSizeBytes = prometheus.NewHistogramFrom(stdprometheus.HistogramOpts{
		Subsystem: relayMinerProcess,
		Name:      requestSizeBytes,
		Help:      "Histogram of request sizes in bytes for performance analysis.",
		Buckets:   []float64{100, 500, 1000, 5000, 10000, 50000},
	}, []string{"service_id"})

	// DelayedRelayRequestValidationTotal is a Counter metric for tracking delayed validation occurrences.
	// It increments when relay requests are validated after being served (late validation)
	// rather than being validated upfront. This indicates sessions that weren't known at
	// request time and required deferred validation.
	DelayedRelayRequestValidationTotal = prometheus.NewCounterFrom(stdprometheus.CounterOpts{
		Subsystem: relayMinerProcess,
		Name:      delayedRelayRequestValidationTotal,
		Help:      "Total number of delayed validation occurrences, labeled by service ID.",
	}, []string{"service_id", "supplier_operator_address"})

	// DelayedRelayRequestValidationFailuresTotal is a Counter metric for tracking delayed validation failures.
	// It increments when relay requests fail validation during the delayed validation process.
	// This typically occurs when the relay request signature is invalid or session validation
	// fails after the relay has already been served.
	DelayedRelayRequestValidationFailuresTotal = prometheus.NewCounterFrom(stdprometheus.CounterOpts{
		Subsystem: relayMinerProcess,
		Name:      delayedRelayRequestValidationFailuresTotal,
		Help:      "Total number of delayed validation failures, labeled by service ID.",
	}, []string{"service_id", "supplier_operator_address"})

	// DelayedRelayRequestRateLimitingCheckTotal is a Counter metric for tracking rate limiting during delayed validation.
	// It increments when, during late (deferred) validation, the application is found to have
	// exceeded its allocated stake and the relay is rate limited.
	//
	// User/payment impact:
	// - The relay becomes reward-ineligible (no on-chain payment to the supplier for this relay).
	// - Signals potential fee leakage and helps rate-limit thresholds.
	DelayedRelayRequestRateLimitingCheckTotal = prometheus.NewCounterFrom(stdprometheus.CounterOpts{
		Subsystem: relayMinerProcess,
		Name:      delayedRelayRequestRateLimitingCheckTotal,
		Help:      "Total number of delayed validation rate limiting events, labeled by service ID.",
	}, []string{"service_id", "supplier_operator_address"})

	// BlockHeightCurrent is a Gauge metric for tracking the current block height.
	// It is updated each time a new block is received by the RelayMiner.
	// This metric enables monitoring of block progression over time and detecting
	// when block updates have stalled.
	//
	// Usage:
	// - Monitor block height progression over time in Grafana
	// - Detect block update stalls by checking for flat lines
	// - Alert when block height hasn't updated in expected timeframe
	BlockHeightCurrent = prometheus.NewGaugeFrom(stdprometheus.GaugeOpts{
		Subsystem: relayMinerProcess,
		Name:      blockHeightCurrent,
		Help:      "Current block height observed by the RelayMiner.",
	}, []string{})

	// InstructionTimeSeconds is a Histogram metric for tracking the duration of individual
	// instructions during relay processing. It measures the time between consecutive
	// instruction steps to identify performance bottlenecks and optimize relay handling.
	// The metric is labeled by instruction name to provide granular timing analysis.
	InstructionTimeSeconds = prometheus.NewHistogramFrom(stdprometheus.HistogramOpts{
		Subsystem: relayMinerProcess,
		Name:      instructionTimeSeconds,
		Help:      "Histogram of request instruction times in milliseconds for performance analysis.",
		Buckets:   defaultBuckets,
	}, []string{"instruction"})

	// RelaysDroppedTotal is a Counter metric for relays that were served to the
	// client but DROPPED from the mining pipeline (never added to the session tree).
	//
	// A dropped relay is permanently lost reward: the supplier did the work but will
	// not be compensated on-chain because no evidence enters the SMST.
	// It is labeled by 'service_id', 'supplier_operator_address', and 'reason'
	// (e.g. "mining_channel_full") to quantify and localize reward leakage under load.
	//
	// Usage:
	// - Alert when nonzero: it directly measures unpaid work.
	// - Correlate with throughput to size mining pipeline buffers/workers.
	RelaysDroppedTotal = prometheus.NewCounterFrom(stdprometheus.CounterOpts{
		Subsystem: relayMinerProcess,
		Name:      relaysDroppedTotal,
		Help:      "Total number of served relays dropped from the mining pipeline (lost reward), labeled by service ID, supplier, and reason.",
	}, []string{"service_id", "supplier_operator_address", "reason"})
)