metrics

type Bucket struct {
	// LE is the inclusive upper bound in seconds, following the Prometheus
	// convention so that a bridge can emit it unchanged.
	LE float64 `json:"le"`

	// Inf marks the final, unbounded bucket. It exists because JSON cannot
	// represent an infinity: encoding/json refuses to marshal one, and a
	// snapshot that cannot be serialised would defeat the point of the package.
	Inf bool `json:"inf,omitempty"`

	// Count is the number of observations at or below LE, including every
	// lower bucket.
	Count uint64 `json:"count"`
}

type CacheOp uint8

type CacheRecord struct {
	// Op is what happened.
	Op CacheOp

	// Entries is the number of entries the cache holds after the operation, or
	// zero if unknown.
	Entries int

	// Bytes is the cache's approximate memory footprint after the operation, or
	// zero if unknown.
	Bytes int
}

type CacheStat struct {
	// Ops is every operation counter indexed by [CacheOp], for a caller that
	// would rather range than name fields.
	Ops [numCacheOps]uint64 `json:"ops"`

	Hits        uint64 `json:"hits"`
	Misses      uint64 `json:"misses"`
	Inserts     uint64 `json:"inserts"`
	Evictions   uint64 `json:"evictions"`
	Expirations uint64 `json:"expirations"`
	StaleServes uint64 `json:"stale_serves"`

	// HitRatio is Hits/(Hits+Misses), or zero when neither has happened.
	HitRatio float64 `json:"hit_ratio"`

	// Entries and Bytes are gauges describing the cache after the most recent
	// operation that reported them, not totals.
	Entries int64 `json:"entries"`
	Bytes   int64 `json:"bytes"`

	// Invalid counts records with an undefined [CacheOp].
	Invalid uint64 `json:"invalid"`
}

type CardinalityStat struct {
	Devices    LimitStat `json:"devices"`
	Providers  LimitStat `json:"providers"`
	Transports LimitStat `json:"transports"`

	// OverflowKey repeats [OverflowKey] so that a consumer parsing the JSON
	// does not have to hard-code it.
	OverflowKey string `json:"overflow_key"`
}

type DeviceStat struct {
	Queries       uint64 `json:"queries"`
	Blocked       uint64 `json:"blocked"`
	Cached        uint64 `json:"cached"`
	Errors        uint64 `json:"errors"`
	ResponseBytes uint64 `json:"response_bytes"`
}

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

type HistogramSnapshot struct {
	// Buckets are cumulative and ascending; the last is the +Inf bucket.
	Buckets []Bucket `json:"buckets"`

	// Count is the total number of observations.
	Count uint64 `json:"count"`

	// Sum is the total of every observation. Sum/Count is the mean, and unlike
	// a quantile it is exact.
	Sum time.Duration `json:"sum_ns"`

	// Min and Max are exact, which is precisely what a bucketed quantile is
	// not. They are zero when Count is zero.
	Min time.Duration `json:"min_ns"`
	Max time.Duration `json:"max_ns"`
}

type LimitStat struct {
	// Limit is the cap. Zero means the dimension is not tracked per key at all.
	Limit int `json:"limit"`

	// Tracked is how many keys have their own entry.
	Tracked int `json:"tracked"`

	// FoldedRecords is how many records were attributed to [OverflowKey]
	// because their key did not fit. It is exact.
	FoldedRecords uint64 `json:"folded_records"`

	// FoldedKeys ESTIMATES how many distinct keys those records came from.
	// Folded keys are not stored — that is the point of folding them — so the
	// count comes from a fixed-size probabilistic sketch: accurate to a few per
	// cent in the thousands, and saturating around thirty thousand per shard,
	// beyond which it reads "a great many" rather than a number. Treat it as an
	// order of magnitude, which is all an operator needs to distinguish "a few
	// extra devices" from "someone is spraying identifiers at us".
	FoldedKeys uint64 `json:"folded_keys_estimate"`
}

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

type Options struct {
	// Clock supplies the time for uptime and for [Snapshot.Time]. Nil means the
	// system clock. Note that nothing on the query path reads it: the query
	// path never calls Now at all, because the caller already measured the
	// duration it passes in.
	Clock clock.Clock

	// Buckets are the latency histogram boundaries in seconds. Nil means
	// [DefaultBuckets]. See [NewHistogram] for how the slice is sanitised.
	Buckets []float64

	// MaxDevices caps how many distinct [QueryRecord.Device] values are tracked
	// individually. Zero means the default; a negative value disables
	// per-device tracking entirely, folding every device into [OverflowKey],
	// which is the right setting for a privacy-sensitive deployment.
	//
	// The cap exists because device identifiers are attacker-influenced: they
	// are usually derived from a client address, and anyone who can send a
	// packet can invent a new one. Without a cap, the per-device map is a
	// memory-exhaustion vector that looks like a feature.
	MaxDevices int

	// MaxProviders caps distinct provider names the same way. Providers are
	// normally configuration-derived and few, so the cap is a backstop against
	// a caller that derives the name from a response instead.
	MaxProviders int
}

type Outcome uint8

type ProviderStat struct {
	Queries  uint64            `json:"queries"`
	Attempts uint64            `json:"attempts"`
	Errors   uint64            `json:"errors"`
	Timeouts uint64            `json:"timeouts"`
	Latency  HistogramSnapshot `json:"latency"`
}

type QueryRecord struct {
	// Device identifies the client for per-device accounting. Empty means "not
	// attributed", and skips per-device work entirely, which is the right thing
	// for a deployment that does not care or must not know. Bear the cardinality
	// cap in mind when choosing what to put here; see [Options].
	Device string

	// Provider names the upstream that ultimately supplied the answer, empty
	// when nothing upstream was asked.
	Provider string

	// QType is the question's type. It is counted in a fixed array, so a flood
	// of unassigned types costs nothing.
	QType dnsmsg.Type

	// RCode is the response code actually sent to the client, recorded
	// alongside Outcome because the two answer different questions.
	RCode dnsmsg.RCode

	// Outcome is what the client effectively got.
	Outcome Outcome

	// Source is what produced the answer.
	Source Source

	// Duration is the whole client-visible latency, not just the upstream part.
	Duration time.Duration

	// ResponseBytes is the size of the message written to the client, which is
	// what a bandwidth graph and an amplification-ratio alert are built from.
	ResponseBytes int
}

type Recorder interface {
	// Query records one resolved query, start to finish, whatever answered it.
	Query(QueryRecord)

	// Upstream records one attempt against one upstream provider. A query that
	// retries or fans out produces several of these and one Query.
	Upstream(UpstreamRecord)

	// Cache records a cache operation that no single query is responsible for,
	// such as an eviction, an expiry or a background refresh. A query answered
	// from cache is reported by [Recorder.Query] with [SourceCache]; reporting
	// it here as well would double-count it.
	Cache(CacheRecord)
}

type Snapshot struct {
	// Time is when the snapshot was taken, from the configured clock.
	Time time.Time `json:"time"`

	// Uptime is how long the recorder has been counting, measured from
	// construction or from the last [Metrics.Reset].
	Uptime time.Duration `json:"uptime_ns"`

	// Queries is every query recorded, whatever answered it.
	Queries uint64 `json:"queries"`

	// ResponseBytes is the total size of responses written to clients.
	ResponseBytes uint64 `json:"response_bytes"`

	// InvalidRecords counts records whose Outcome or Source was outside the
	// defined set. Anything above zero is a caller bug.
	InvalidRecords uint64 `json:"invalid_records"`

	// Outcomes, Sources, QTypes and RCodes are keyed by mnemonic and omit
	// zeroes. QTypes and RCodes use "<other>" for values outside the range
	// counted individually.
	Outcomes map[string]uint64 `json:"outcomes"`
	Sources  map[string]uint64 `json:"sources"`
	QTypes   map[string]uint64 `json:"qtypes"`
	RCodes   map[string]uint64 `json:"rcodes"`

	// Devices and Providers are the capped dimensions. Read
	// [Snapshot.Cardinality] before trusting them to be complete; an
	// [OverflowKey] entry means they are not.
	Devices   map[string]DeviceStat   `json:"devices"`
	Providers map[string]ProviderStat `json:"providers"`

	// Transports is keyed by "udp", "tcp", "dot", "doh", "doq" or whatever the
	// caller passed.
	Transports map[string]TransportStat `json:"transports"`

	Cache    CacheStat    `json:"cache"`
	Upstream UpstreamStat `json:"upstream"`

	// QueryLatency is client-visible latency: what a user experiences.
	QueryLatency HistogramSnapshot `json:"query_latency"`

	// UpstreamLatency covers single attempts against providers, so a query that
	// retried contributes several observations here and one there.
	UpstreamLatency HistogramSnapshot `json:"upstream_latency"`

	Cardinality CardinalityStat `json:"cardinality"`
}

type Source uint8

type TransportStat struct {
	Attempts uint64 `json:"attempts"`
	Errors   uint64 `json:"errors"`
	Timeouts uint64 `json:"timeouts"`
}

type UpstreamRecord struct {
	// Provider names the upstream, subject to the same cardinality cap as
	// [QueryRecord.Device].
	Provider string

	// Transport is how it was reached: "udp", "tcp", "dot", "doh", "doq". It is
	// configuration-derived rather than client-derived, so it is tracked with a
	// small fixed cap rather than the configurable one.
	Transport string

	// Duration is the time this attempt took, successful or not. A timed-out
	// attempt records the time spent waiting, which is what makes a timeout
	// visible in the latency histogram rather than invisible.
	Duration time.Duration

	// Err is the failure, or nil. The recorder classifies it and does not
	// retain it: a counter must not keep a heap object alive per failure. Send
	// the detail to the events package or a log.
	Err error

	// Timeout distinguishes "no answer arrived" from "an answer arrived and it
	// was bad", because they have different causes and different fixes. Set it
	// alongside Err rather than instead of it.
	Timeout bool
}

type UpstreamStat struct {
	Attempts uint64 `json:"attempts"`

	// Errors counts attempts that failed for any reason, timeouts included, so
	// Timeouts is a subset of it.
	Errors   uint64 `json:"errors"`
	Timeouts uint64 `json:"timeouts"`

	// ErrorRatio is Errors/Attempts, or zero when nothing has been attempted.
	ErrorRatio float64 `json:"error_ratio"`
}