| 1 | // SPDX-License-Identifier: GPL-3.0-or-later |
| 2 | |
| 3 | package prometheus |
| 4 | |
| 5 | import ( |
| 6 | "github.com/prometheus/common/model" |
| 7 | "github.com/prometheus/prometheus/model/labels" |
| 8 | ) |
| 9 | |
| 10 | // SampleKind classifies a streamed [Sample] by the role it plays in its typed |
| 11 | // family. The driver assigns it as it parses, so a consumer can re-assemble |
| 12 | // typed families (or relabel) without re-deriving the role from the name. |
| 13 | type SampleKind uint8 |
| 14 | |
| 15 | const ( |
| 16 | // SampleKindScalar is a plain sample (gauge, counter, untyped, or the base |
| 17 | // series of a summary/histogram). Interpret it together with FamilyType. |
| 18 | SampleKindScalar SampleKind = iota |
| 19 | SampleKindHistogramBucket |
| 20 | SampleKindHistogramSum |
| 21 | SampleKindHistogramCount |
| 22 | SampleKindSummaryQuantile |
| 23 | SampleKindSummarySum |
| 24 | SampleKindSummaryCount |
| 25 | ) |
| 26 | |
| 27 | // Sample is a single scraped series exposed before typed-family assembly. |
| 28 | // |
| 29 | // Name is the __name__ label value (found by lookup, not by position — do not |
| 30 | // assume label index 0). Labels holds every other label, including structural |
| 31 | // labels such as "le" (histogram buckets) and "quantile" (summary quantiles) — |
| 32 | // textparse canonicalizes these to floats (e.g. "1" -> "1.0") only when the family |
| 33 | // type is known from # TYPE, otherwise leaving them raw, so do not assume a fixed |
| 34 | // form when matching. Labels never contains __name__. Value is the sample value. |
| 35 | // Kind and FamilyType carry the classification the driver derived for this sample. |
| 36 | // |
| 37 | // Sample is the unit a Prometheus metric-relabeling step operates on. |
| 38 | type Sample struct { |
| 39 | Name string |
| 40 | Labels labels.Labels |
| 41 | Value float64 |
| 42 | Kind SampleKind |
| 43 | FamilyType model.MetricType |
| 44 | } |
| 45 | |
| 46 | // SampleTransform transforms or drops a single scraped Sample before typed-family |
| 47 | // assembly. Return (sample, true, nil) to keep it (optionally mutated — rewrite Name |
| 48 | // or mutate Labels in place), (_, false, nil) to drop it, or a non-nil error to abort |
| 49 | // the scrape. Each Sample owns its Labels, so in-place mutation is safe and does not |
| 50 | // affect other samples. It is the hook a Prometheus metric-relabeling step plugs into. |
| 51 | // |
| 52 | // Kind and FamilyType reflect the classification BEFORE the transform runs; rewriting |
| 53 | // Name, le, or quantile does NOT reclassify the sample (matching Prometheus, where |
| 54 | // relabeling cannot retype a series). |
| 55 | type SampleTransform func(Sample) (Sample, bool, error) |