| 1 | // SPDX-License-Identifier: GPL-3.0-or-later |
| 2 | |
| 3 | package metrix |
| 4 | |
| 5 | // CollectorStore is the collector-facing metrics container. |
| 6 | // Writes are cycle-scoped and reads are snapshot-bound. |
| 7 | type CollectorStore interface { |
| 8 | Read(opts ...ReadOption) Reader |
| 9 | Write() Writer |
| 10 | } |
| 11 | |
| 12 | // RuntimeStore is reserved for out-of-cycle internal instrumentation. |
| 13 | // It is intentionally stateful-only on the write side. |
| 14 | type RuntimeStore interface { |
| 15 | Read(opts ...ReadOption) Reader |
| 16 | Write() RuntimeWriter |
| 17 | } |
| 18 | |
| 19 | // CycleController owns collect-cycle transitions for a cycle-managed store. |
| 20 | // Collector code does not call these methods directly. |
| 21 | type CycleController interface { |
| 22 | BeginCycle() |
| 23 | CommitCycleSuccess() error |
| 24 | AbortCycle() |
| 25 | } |
| 26 | |
| 27 | // CycleManagedStore extends CollectorStore with runtime-only cycle control. |
| 28 | type CycleManagedStore interface { |
| 29 | CollectorStore |
| 30 | CycleController() CycleController |
| 31 | } |
| 32 | |
| 33 | // Reader exposes immutable snapshot reads. |
| 34 | // Read() defaults to freshness-filtered visibility; raw visibility is enabled via read options. |
| 35 | type Reader interface { |
| 36 | Value(name string, labels Labels) (SampleValue, bool) |
| 37 | Delta(name string, labels Labels) (SampleValue, bool) |
| 38 | Histogram(name string, labels Labels) (HistogramPoint, bool) |
| 39 | Summary(name string, labels Labels) (SummaryPoint, bool) |
| 40 | StateSet(name string, labels Labels) (StateSetPoint, bool) |
| 41 | MeasureSet(name string, labels Labels) (MeasureSetPoint, bool) |
| 42 | SeriesMeta(name string, labels Labels) (SeriesMeta, bool) |
| 43 | // MetricMeta resolves metadata by metric name in the active reader view. |
| 44 | // With Read(ReadFlatten()), lookups use flattened scalar series names. |
| 45 | // Example: histogram families resolve via *_bucket/*_count/*_sum names. |
| 46 | MetricMeta(name string) (MetricMeta, bool) |
| 47 | CollectMeta() CollectMeta |
| 48 | // HostScopes returns all host scopes present in the snapshot, including the |
| 49 | // default scope when it has series. The result is not filtered by the |
| 50 | // reader's active scope. |
| 51 | HostScopes() []HostScope |
| 52 | // Family returns a scalar-only view. For non-scalar families use Histogram/Summary/StateSet, |
| 53 | // or use Read(ReadFlatten()) at reader acquisition time. |
| 54 | Family(name string) (FamilyView, bool) |
| 55 | // ForEachByName iterates scalar series only. For non-scalar families use typed getters |
| 56 | // or Read(ReadFlatten()). |
| 57 | ForEachByName(name string, fn func(labels LabelView, v SampleValue)) |
| 58 | // ForEachSeries iterates scalar series only. For non-scalar families use typed getters |
| 59 | // or Read(ReadFlatten()). |
| 60 | ForEachSeries(fn func(name string, labels LabelView, v SampleValue)) |
| 61 | // ForEachSeriesIdentity iterates scalar series and includes stable identity/hash. |
| 62 | // For non-scalar families use typed getters or Read(ReadFlatten()). |
| 63 | ForEachSeriesIdentity(fn func(identity SeriesIdentity, meta SeriesMeta, name string, labels LabelView, v SampleValue)) |
| 64 | // ForEachMatch iterates scalar series only. For non-scalar families use typed getters |
| 65 | // or Read(ReadFlatten()). |
| 66 | ForEachMatch(name string, match func(labels LabelView) bool, fn func(labels LabelView, v SampleValue)) |
| 67 | } |
| 68 | |
| 69 | // SeriesIdentityRawIterator is an optional reader fast path that exposes |
| 70 | // raw canonical label slices to avoid per-series LabelView interface wrapping |
| 71 | // in hot iteration paths. |
| 72 | // |
| 73 | // Labels are snapshot-owned and immutable for the lifetime of that reader. |
| 74 | // Callers must not mutate returned label slices. |
| 75 | type SeriesIdentityRawIterator interface { |
| 76 | ForEachSeriesIdentityRaw(fn func(identity SeriesIdentity, meta SeriesMeta, name string, labels []Label, v SampleValue)) |
| 77 | } |
| 78 | |
| 79 | // Writer is the declaration/write entrypoint for collection stores. |
| 80 | // Metric mode is selected via SnapshotMeter or StatefulMeter. |
| 81 | type Writer interface { |
| 82 | SnapshotMeter(prefix string) SnapshotMeter |
| 83 | StatefulMeter(prefix string) StatefulMeter |
| 84 | } |
| 85 | |
| 86 | // RuntimeWriter is stateful-only by design. |
| 87 | type RuntimeWriter interface { |
| 88 | StatefulMeter(prefix string) StatefulMeter |
| 89 | } |
| 90 | |
| 91 | // SnapshotMeter declares snapshot-mode instruments under a metric-name prefix. |
| 92 | type SnapshotMeter interface { |
| 93 | WithHostScope(scope HostScope) SnapshotMeter |
| 94 | WithLabels(labels ...Label) SnapshotMeter |
| 95 | WithLabelSet(labels ...LabelSet) SnapshotMeter |
| 96 | // Vec binds a reusable vec label-key schema for multiple vector instruments. |
| 97 | Vec(labelKeys ...string) SnapshotVecMeter |
| 98 | Gauge(name string, opts ...InstrumentOption) SnapshotGauge |
| 99 | Counter(name string, opts ...InstrumentOption) SnapshotCounter |
| 100 | Histogram(name string, opts ...InstrumentOption) SnapshotHistogram |
| 101 | Summary(name string, opts ...InstrumentOption) SnapshotSummary |
| 102 | StateSet(name string, opts ...InstrumentOption) StateSetInstrument |
| 103 | MeasureSetGauge(name string, opts ...InstrumentOption) SnapshotMeasureSetGauge |
| 104 | MeasureSetCounter(name string, opts ...InstrumentOption) SnapshotMeasureSetCounter |
| 105 | LabelSet(labels ...Label) LabelSet |
| 106 | } |
| 107 | |
| 108 | // SnapshotVecMeter declares snapshot vec instruments sharing one label-key schema. |
| 109 | type SnapshotVecMeter interface { |
| 110 | WithHostScope(scope HostScope) SnapshotVecMeter |
| 111 | Gauge(name string, opts ...InstrumentOption) SnapshotGaugeVec |
| 112 | Counter(name string, opts ...InstrumentOption) SnapshotCounterVec |
| 113 | Histogram(name string, opts ...InstrumentOption) SnapshotHistogramVec |
| 114 | Summary(name string, opts ...InstrumentOption) SnapshotSummaryVec |
| 115 | StateSet(name string, opts ...InstrumentOption) SnapshotStateSetVec |
| 116 | MeasureSetGauge(name string, opts ...InstrumentOption) SnapshotMeasureSetGaugeVec |
| 117 | MeasureSetCounter(name string, opts ...InstrumentOption) SnapshotMeasureSetCounterVec |
| 118 | } |
| 119 | |
| 120 | // StatefulMeter declares stateful-mode instruments under a metric-name prefix. |
| 121 | type StatefulMeter interface { |
| 122 | WithHostScope(scope HostScope) StatefulMeter |
| 123 | WithLabels(labels ...Label) StatefulMeter |
| 124 | WithLabelSet(labels ...LabelSet) StatefulMeter |
| 125 | // Vec binds a reusable vec label-key schema for multiple vector instruments. |
| 126 | Vec(labelKeys ...string) StatefulVecMeter |
| 127 | Gauge(name string, opts ...InstrumentOption) StatefulGauge |
| 128 | Counter(name string, opts ...InstrumentOption) StatefulCounter |
| 129 | Histogram(name string, opts ...InstrumentOption) StatefulHistogram |
| 130 | Summary(name string, opts ...InstrumentOption) StatefulSummary |
| 131 | StateSet(name string, opts ...InstrumentOption) StateSetInstrument |
| 132 | MeasureSetGauge(name string, opts ...InstrumentOption) StatefulMeasureSetGauge |
| 133 | MeasureSetCounter(name string, opts ...InstrumentOption) StatefulMeasureSetCounter |
| 134 | LabelSet(labels ...Label) LabelSet |
| 135 | } |
| 136 | |
| 137 | // StatefulVecMeter declares stateful vec instruments sharing one label-key schema. |
| 138 | type StatefulVecMeter interface { |
| 139 | WithHostScope(scope HostScope) StatefulVecMeter |
| 140 | Gauge(name string, opts ...InstrumentOption) StatefulGaugeVec |
| 141 | Counter(name string, opts ...InstrumentOption) StatefulCounterVec |
| 142 | Histogram(name string, opts ...InstrumentOption) StatefulHistogramVec |
| 143 | Summary(name string, opts ...InstrumentOption) StatefulSummaryVec |
| 144 | StateSet(name string, opts ...InstrumentOption) StatefulStateSetVec |
| 145 | MeasureSetGauge(name string, opts ...InstrumentOption) StatefulMeasureSetGaugeVec |
| 146 | MeasureSetCounter(name string, opts ...InstrumentOption) StatefulMeasureSetCounterVec |
| 147 | } |
| 148 | |
| 149 | // SnapshotGauge writes sampled absolute values; last write wins in a cycle. |
| 150 | type SnapshotGauge interface { |
| 151 | Observe(v SampleValue, labels ...LabelSet) |
| 152 | } |
| 153 | |
| 154 | // SnapshotGaugeVec provides labeled series handles for snapshot gauges. |
| 155 | // It follows the Prometheus vec pattern: |
| 156 | // - GetWithLabelValues returns (metric, error) |
| 157 | // - WithLabelValues panics on invalid label values |
| 158 | type SnapshotGaugeVec interface { |
| 159 | WithHostScope(scope HostScope) SnapshotGaugeVec |
| 160 | GetWithLabelValues(labelValues ...string) (SnapshotGauge, error) |
| 161 | WithLabelValues(labelValues ...string) SnapshotGauge |
| 162 | } |
| 163 | |
| 164 | // StatefulGauge writes maintained values: |
| 165 | // Set overwrites staged value, Add accumulates from committed baseline. |
| 166 | type StatefulGauge interface { |
| 167 | Set(v SampleValue, labels ...LabelSet) |
| 168 | Add(delta SampleValue, labels ...LabelSet) |
| 169 | } |
| 170 | |
| 171 | // StatefulGaugeVec provides labeled series handles for stateful gauges. |
| 172 | type StatefulGaugeVec interface { |
| 173 | WithHostScope(scope HostScope) StatefulGaugeVec |
| 174 | GetWithLabelValues(labelValues ...string) (StatefulGauge, error) |
| 175 | WithLabelValues(labelValues ...string) StatefulGauge |
| 176 | } |
| 177 | |
| 178 | type SnapshotCounter interface { |
| 179 | ObserveTotal(v SampleValue, labels ...LabelSet) |
| 180 | } |
| 181 | |
| 182 | // SnapshotCounterVec provides labeled series handles for snapshot counters. |
| 183 | type SnapshotCounterVec interface { |
| 184 | WithHostScope(scope HostScope) SnapshotCounterVec |
| 185 | GetWithLabelValues(labelValues ...string) (SnapshotCounter, error) |
| 186 | WithLabelValues(labelValues ...string) SnapshotCounter |
| 187 | } |
| 188 | |
| 189 | type StatefulCounter interface { |
| 190 | Add(delta SampleValue, labels ...LabelSet) |
| 191 | } |
| 192 | |
| 193 | // StatefulCounterVec provides labeled series handles for stateful counters. |
| 194 | type StatefulCounterVec interface { |
| 195 | WithHostScope(scope HostScope) StatefulCounterVec |
| 196 | GetWithLabelValues(labelValues ...string) (StatefulCounter, error) |
| 197 | WithLabelValues(labelValues ...string) StatefulCounter |
| 198 | } |
| 199 | |
| 200 | type SnapshotHistogram interface { |
| 201 | ObservePoint(p HistogramPoint, labels ...LabelSet) |
| 202 | } |
| 203 | |
| 204 | // SnapshotHistogramVec provides labeled series handles for snapshot histograms. |
| 205 | type SnapshotHistogramVec interface { |
| 206 | WithHostScope(scope HostScope) SnapshotHistogramVec |
| 207 | GetWithLabelValues(labelValues ...string) (SnapshotHistogram, error) |
| 208 | WithLabelValues(labelValues ...string) SnapshotHistogram |
| 209 | } |
| 210 | |
| 211 | type StatefulHistogram interface { |
| 212 | Observe(v SampleValue, labels ...LabelSet) |
| 213 | } |
| 214 | |
| 215 | // StatefulHistogramVec provides labeled series handles for stateful histograms. |
| 216 | type StatefulHistogramVec interface { |
| 217 | WithHostScope(scope HostScope) StatefulHistogramVec |
| 218 | GetWithLabelValues(labelValues ...string) (StatefulHistogram, error) |
| 219 | WithLabelValues(labelValues ...string) StatefulHistogram |
| 220 | } |
| 221 | |
| 222 | type SnapshotSummary interface { |
| 223 | ObservePoint(p SummaryPoint, labels ...LabelSet) |
| 224 | } |
| 225 | |
| 226 | // SnapshotSummaryVec provides labeled series handles for snapshot summaries. |
| 227 | type SnapshotSummaryVec interface { |
| 228 | WithHostScope(scope HostScope) SnapshotSummaryVec |
| 229 | GetWithLabelValues(labelValues ...string) (SnapshotSummary, error) |
| 230 | WithLabelValues(labelValues ...string) SnapshotSummary |
| 231 | } |
| 232 | |
| 233 | type StatefulSummary interface { |
| 234 | Observe(v SampleValue, labels ...LabelSet) |
| 235 | } |
| 236 | |
| 237 | // StatefulSummaryVec provides labeled series handles for stateful summaries. |
| 238 | type StatefulSummaryVec interface { |
| 239 | WithHostScope(scope HostScope) StatefulSummaryVec |
| 240 | GetWithLabelValues(labelValues ...string) (StatefulSummary, error) |
| 241 | WithLabelValues(labelValues ...string) StatefulSummary |
| 242 | } |
| 243 | |
| 244 | type StateSetInstrument interface { |
| 245 | ObserveStateSet(p StateSetPoint, labels ...LabelSet) |
| 246 | Enable(actives ...string) |
| 247 | } |
| 248 | |
| 249 | type SnapshotMeasureSetGauge interface { |
| 250 | ObservePoint(p MeasureSetPoint, labels ...LabelSet) |
| 251 | ObserveFields(fields map[string]SampleValue, labels ...LabelSet) |
| 252 | } |
| 253 | |
| 254 | type SnapshotMeasureSetGaugeVec interface { |
| 255 | WithHostScope(scope HostScope) SnapshotMeasureSetGaugeVec |
| 256 | GetWithLabelValues(labelValues ...string) (SnapshotMeasureSetGauge, error) |
| 257 | WithLabelValues(labelValues ...string) SnapshotMeasureSetGauge |
| 258 | } |
| 259 | |
| 260 | type SnapshotMeasureSetCounter interface { |
| 261 | ObserveTotalPoint(p MeasureSetPoint, labels ...LabelSet) |
| 262 | ObserveTotalFields(fields map[string]SampleValue, labels ...LabelSet) |
| 263 | } |
| 264 | |
| 265 | type SnapshotMeasureSetCounterVec interface { |
| 266 | WithHostScope(scope HostScope) SnapshotMeasureSetCounterVec |
| 267 | GetWithLabelValues(labelValues ...string) (SnapshotMeasureSetCounter, error) |
| 268 | WithLabelValues(labelValues ...string) SnapshotMeasureSetCounter |
| 269 | } |
| 270 | |
| 271 | type StatefulMeasureSetGauge interface { |
| 272 | SetPoint(p MeasureSetPoint, labels ...LabelSet) |
| 273 | SetFields(fields map[string]SampleValue, labels ...LabelSet) |
| 274 | SetField(field string, value SampleValue, labels ...LabelSet) |
| 275 | AddPoint(delta MeasureSetPoint, labels ...LabelSet) |
| 276 | AddFields(delta map[string]SampleValue, labels ...LabelSet) |
| 277 | AddField(field string, delta SampleValue, labels ...LabelSet) |
| 278 | } |
| 279 | |
| 280 | type StatefulMeasureSetGaugeVec interface { |
| 281 | WithHostScope(scope HostScope) StatefulMeasureSetGaugeVec |
| 282 | GetWithLabelValues(labelValues ...string) (StatefulMeasureSetGauge, error) |
| 283 | WithLabelValues(labelValues ...string) StatefulMeasureSetGauge |
| 284 | } |
| 285 | |
| 286 | type StatefulMeasureSetCounter interface { |
| 287 | AddPoint(delta MeasureSetPoint, labels ...LabelSet) |
| 288 | AddFields(delta map[string]SampleValue, labels ...LabelSet) |
| 289 | AddField(field string, delta SampleValue, labels ...LabelSet) |
| 290 | } |
| 291 | |
| 292 | type StatefulMeasureSetCounterVec interface { |
| 293 | WithHostScope(scope HostScope) StatefulMeasureSetCounterVec |
| 294 | GetWithLabelValues(labelValues ...string) (StatefulMeasureSetCounter, error) |
| 295 | WithLabelValues(labelValues ...string) StatefulMeasureSetCounter |
| 296 | } |
| 297 | |
| 298 | // SnapshotStateSetVec provides labeled series handles for snapshot statesets. |
| 299 | type SnapshotStateSetVec interface { |
| 300 | WithHostScope(scope HostScope) SnapshotStateSetVec |
| 301 | GetWithLabelValues(labelValues ...string) (StateSetInstrument, error) |
| 302 | WithLabelValues(labelValues ...string) StateSetInstrument |
| 303 | } |
| 304 | |
| 305 | // StatefulStateSetVec provides labeled series handles for stateful statesets. |
| 306 | type StatefulStateSetVec interface { |
| 307 | WithHostScope(scope HostScope) StatefulStateSetVec |
| 308 | GetWithLabelValues(labelValues ...string) (StateSetInstrument, error) |
| 309 | WithLabelValues(labelValues ...string) StateSetInstrument |
| 310 | } |