Promsafe introduced: Type Safe Labels. (Draft, Discussion is still required)
Signed-off-by: Eugene <eugene@amberpixels.io>
This commit is contained in:
Eugene
parent
f53c5ca1a8
commit
879c4741b0
|
|
@ -0,0 +1,161 @@
|
|||
// Copyright 2024 The Prometheus Authors
|
||||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||||
// you may not use this file except in compliance with the License.
|
||||
// You may obtain a copy of the License at
|
||||
//
|
||||
// http://www.apache.org/licenses/LICENSE-2.0
|
||||
//
|
||||
// Unless required by applicable law or agreed to in writing, software
|
||||
// distributed under the License is distributed on an "AS IS" BASIS,
|
||||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
// See the License for the specific language governing permissions and
|
||||
// limitations under the License.
|
||||
|
||||
package promsafe
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"reflect"
|
||||
"strings"
|
||||
|
||||
"github.com/prometheus/client_golang/prometheus"
|
||||
)
|
||||
|
||||
// LabelsProvider is an interface that allows to convert anything into prometheus.Labels
|
||||
// It allows to provide your own FAST implementation of Struct->prometheus.Labels conversion
|
||||
// without using reflection.
|
||||
type LabelsProvider interface {
|
||||
ToPrometheusLabels() prometheus.Labels
|
||||
ToLabelNames() []string
|
||||
}
|
||||
|
||||
// LabelsProviderMarker is a marker interface for enforcing type-safety of StructLabelProvider.
|
||||
type LabelsProviderMarker interface {
|
||||
labelsProviderMarker()
|
||||
}
|
||||
|
||||
// StructLabelProvider should be embedded in any struct that serves as a label provider.
|
||||
type StructLabelProvider struct{}
|
||||
|
||||
var _ LabelsProviderMarker = (*StructLabelProvider)(nil)
|
||||
|
||||
func (s StructLabelProvider) labelsProviderMarker() {
|
||||
panic("LabelsProviderMarker interface method should never be called")
|
||||
}
|
||||
|
||||
// NewEmptyLabels creates a new empty labels instance of type T
|
||||
// It's a bit tricky as we want to support both structs and pointers to structs
|
||||
// e.g. &MyLabels{StructLabelProvider} or MyLabels{StructLabelProvider}
|
||||
func NewEmptyLabels[T LabelsProviderMarker]() T {
|
||||
var emptyLabels T
|
||||
|
||||
val := reflect.ValueOf(&emptyLabels).Elem()
|
||||
if val.Kind() == reflect.Ptr {
|
||||
ptrType := val.Type().Elem()
|
||||
newValue := reflect.New(ptrType).Interface().(T)
|
||||
return newValue
|
||||
}
|
||||
|
||||
return emptyLabels
|
||||
}
|
||||
|
||||
//
|
||||
// Helpers
|
||||
//
|
||||
|
||||
// promsafeTag is the tag name used for promsafe labels inside structs.
|
||||
// The tag is optional, as if not present, field is used with snake_cased FieldName.
|
||||
// It's useful to use a tag when you want to override the default naming or exclude a field from the metric.
|
||||
var promsafeTag = "promsafe"
|
||||
|
||||
// SetPromsafeTag sets the tag name used for promsafe labels inside structs.
|
||||
func SetPromsafeTag(tag string) {
|
||||
promsafeTag = tag
|
||||
}
|
||||
|
||||
// iterateStructFields iterates over struct fields, calling the given function for each field.
|
||||
func iterateStructFields(structValue any, fn func(labelName string, fieldValue reflect.Value)) {
|
||||
val := reflect.Indirect(reflect.ValueOf(structValue))
|
||||
typ := val.Type()
|
||||
|
||||
for i := 0; i < typ.NumField(); i++ {
|
||||
field := typ.Field(i)
|
||||
if field.Anonymous {
|
||||
continue
|
||||
}
|
||||
|
||||
// Handle tag logic centrally
|
||||
var labelName string
|
||||
if ourTag := field.Tag.Get(promsafeTag); ourTag == "-" {
|
||||
continue // Skip field
|
||||
} else if ourTag != "" {
|
||||
labelName = ourTag
|
||||
} else {
|
||||
labelName = toSnakeCase(field.Name)
|
||||
}
|
||||
|
||||
fn(labelName, val.Field(i))
|
||||
}
|
||||
}
|
||||
|
||||
// extractLabelsWithValues extracts labels names+values from a given LabelsProviderMarker (parent instance of a StructLabelProvider)
|
||||
func extractLabelsWithValues(labelProvider LabelsProviderMarker) prometheus.Labels {
|
||||
if any(labelProvider) == nil {
|
||||
return nil
|
||||
}
|
||||
|
||||
if clp, ok := labelProvider.(LabelsProvider); ok {
|
||||
return clp.ToPrometheusLabels()
|
||||
}
|
||||
|
||||
// extracting labels from a struct
|
||||
labels := prometheus.Labels{}
|
||||
iterateStructFields(labelProvider, func(labelName string, fieldValue reflect.Value) {
|
||||
labels[labelName] = stringifyLabelValue(fieldValue)
|
||||
})
|
||||
return labels
|
||||
}
|
||||
|
||||
// extractLabelNames extracts labels names from a given LabelsProviderMarker (parent instance of aStructLabelProvider)
|
||||
func extractLabelNames(labelProvider LabelsProviderMarker) []string {
|
||||
if any(labelProvider) == nil {
|
||||
return nil
|
||||
}
|
||||
|
||||
// If custom implementation is done, just do it
|
||||
if lp, ok := labelProvider.(LabelsProvider); ok {
|
||||
return lp.ToLabelNames()
|
||||
}
|
||||
|
||||
// Fallback to slow implementation via reflect
|
||||
// Important! We return label names in order of fields in the struct
|
||||
labelNames := make([]string, 0)
|
||||
iterateStructFields(labelProvider, func(labelName string, fieldValue reflect.Value) {
|
||||
labelNames = append(labelNames, labelName)
|
||||
})
|
||||
|
||||
return labelNames
|
||||
}
|
||||
|
||||
// stringifyLabelValue makes up a valid string value from a given field's value
|
||||
// It's used ONLY in fallback reflect mode
|
||||
// Field value might be a pointer, that's why we do reflect.Indirect()
|
||||
// Note: in future we can handle default values here as well
|
||||
func stringifyLabelValue(v reflect.Value) string {
|
||||
// TODO: we probably want to handle custom type processing here
|
||||
// e.g. sometimes booleans need to be "on"/"off" instead of "true"/"false"
|
||||
return fmt.Sprintf("%v", reflect.Indirect(v).Interface())
|
||||
}
|
||||
|
||||
// Convert struct field names to snake_case for Prometheus label compliance.
|
||||
func toSnakeCase(s string) string {
|
||||
s = strings.TrimSpace(s)
|
||||
var result []rune
|
||||
for i, r := range s {
|
||||
if i > 0 && r >= 'A' && r <= 'Z' {
|
||||
result = append(result, '_')
|
||||
}
|
||||
result = append(result, r)
|
||||
}
|
||||
return strings.ToLower(string(result))
|
||||
}
|
||||
|
|
@ -0,0 +1,263 @@
|
|||
// Copyright 2024 The Prometheus Authors
|
||||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||||
// you may not use this file except in compliance with the License.
|
||||
// You may obtain a copy of the License at
|
||||
//
|
||||
// http://www.apache.org/licenses/LICENSE-2.0
|
||||
//
|
||||
// Unless required by applicable law or agreed to in writing, software
|
||||
// distributed under the License is distributed on an "AS IS" BASIS,
|
||||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
// See the License for the specific language governing permissions and
|
||||
// limitations under the License.
|
||||
|
||||
package promsafe
|
||||
|
||||
import (
|
||||
"reflect"
|
||||
"strconv"
|
||||
"testing"
|
||||
|
||||
"github.com/prometheus/client_golang/prometheus"
|
||||
)
|
||||
|
||||
type TestLabels struct {
|
||||
StructLabelProvider
|
||||
Field1 string
|
||||
Field2 int
|
||||
Field3 bool
|
||||
}
|
||||
|
||||
type TestLabelsWithTags struct {
|
||||
StructLabelProvider
|
||||
FieldA string `promsafe:"custom_a"`
|
||||
FieldB int `promsafe:"-"`
|
||||
FieldC bool // no promsafe tag, so default to snake_case of field_c
|
||||
}
|
||||
|
||||
type TestLabelsWithPointers struct {
|
||||
StructLabelProvider
|
||||
Field1 *string
|
||||
Field2 *int
|
||||
Field3 *bool
|
||||
}
|
||||
|
||||
type TestLabelsFast struct {
|
||||
StructLabelProvider
|
||||
Field1 string
|
||||
Field2 int
|
||||
Field3 bool
|
||||
}
|
||||
|
||||
func (t TestLabelsFast) ToPrometheusLabels() prometheus.Labels {
|
||||
return prometheus.Labels{
|
||||
"f1": t.Field1,
|
||||
"f2": strconv.Itoa(t.Field2),
|
||||
"f3": strconv.FormatBool(t.Field3),
|
||||
}
|
||||
}
|
||||
|
||||
func (t TestLabelsFast) ToLabelNames() []string {
|
||||
return []string{"f1", "f2", "f3"}
|
||||
}
|
||||
|
||||
func Test_extractLabelsWithValues(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
input LabelsProviderMarker
|
||||
expected prometheus.Labels
|
||||
shouldFail bool
|
||||
}{
|
||||
{
|
||||
name: "Basic struct without custom tags",
|
||||
input: TestLabels{
|
||||
Field1: "value1",
|
||||
Field2: 123,
|
||||
Field3: true,
|
||||
},
|
||||
expected: prometheus.Labels{
|
||||
"field1": "value1",
|
||||
"field2": "123",
|
||||
"field3": "true",
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "Struct with custom tags and exclusions",
|
||||
input: TestLabelsWithTags{
|
||||
FieldA: "customValue",
|
||||
FieldB: 456,
|
||||
FieldC: false,
|
||||
},
|
||||
expected: prometheus.Labels{
|
||||
"custom_a": "customValue",
|
||||
"field_c": "false",
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "Struct with pointers",
|
||||
input: TestLabelsWithPointers{
|
||||
Field1: ptr("ptrValue"),
|
||||
Field2: ptr(789),
|
||||
Field3: ptr(true),
|
||||
},
|
||||
expected: prometheus.Labels{
|
||||
"field1": "ptrValue",
|
||||
"field2": "789",
|
||||
"field3": "true",
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "Struct fast (with declared methods)",
|
||||
input: TestLabelsFast{
|
||||
Field1: "hello",
|
||||
Field2: 100,
|
||||
Field3: true,
|
||||
},
|
||||
expected: prometheus.Labels{
|
||||
"f1": "hello",
|
||||
"f2": "100",
|
||||
"f3": "true",
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "Nil will return empty result",
|
||||
input: nil,
|
||||
expected: nil,
|
||||
},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
defer func() {
|
||||
if r := recover(); r != nil {
|
||||
if !tt.shouldFail {
|
||||
t.Errorf("unexpected panic: %v", r)
|
||||
}
|
||||
}
|
||||
}()
|
||||
|
||||
// Call extractLabelsFromStruct
|
||||
got := extractLabelsWithValues(tt.input)
|
||||
|
||||
// Compare results
|
||||
if !reflect.DeepEqual(got, tt.expected) {
|
||||
t.Errorf("extractLabelFromStruct(%v) = %v; want %v", tt.input, got, tt.expected)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func Test_extractLabelNames(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
input LabelsProviderMarker
|
||||
expected []string
|
||||
shouldFail bool
|
||||
}{
|
||||
{
|
||||
name: "Basic struct without custom tags",
|
||||
input: TestLabels{
|
||||
Field1: "value1",
|
||||
Field2: 123,
|
||||
Field3: true,
|
||||
},
|
||||
expected: []string{"field1", "field2", "field3"},
|
||||
},
|
||||
{
|
||||
name: "Struct with custom tags and exclusions",
|
||||
input: TestLabelsWithTags{
|
||||
FieldA: "customValue",
|
||||
FieldB: 456,
|
||||
FieldC: false,
|
||||
},
|
||||
expected: []string{"custom_a", "field_c"},
|
||||
},
|
||||
{
|
||||
name: "Struct with pointers",
|
||||
input: TestLabelsWithPointers{
|
||||
Field1: ptr("ptrValue"),
|
||||
Field2: ptr(789),
|
||||
Field3: ptr(true),
|
||||
},
|
||||
expected: []string{"field1", "field2", "field3"},
|
||||
},
|
||||
{
|
||||
name: "Struct fast (with declared methods)",
|
||||
input: TestLabelsFast{
|
||||
Field1: "hello",
|
||||
Field2: 100,
|
||||
Field3: true,
|
||||
},
|
||||
expected: []string{"f1", "f2", "f3"},
|
||||
},
|
||||
{
|
||||
name: "Nil will return empty result",
|
||||
input: nil,
|
||||
expected: nil,
|
||||
},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
defer func() {
|
||||
if r := recover(); r != nil {
|
||||
if !tt.shouldFail {
|
||||
t.Errorf("unexpected panic: %v", r)
|
||||
}
|
||||
}
|
||||
}()
|
||||
|
||||
// Call extractLabelsFromStruct
|
||||
got := extractLabelNames(tt.input)
|
||||
|
||||
// Compare results
|
||||
if !reflect.DeepEqual(got, tt.expected) {
|
||||
t.Errorf("extractLabelFromStruct(%v) = %v; want %v", tt.input, got, tt.expected)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func Test_NewEmptyLabels(t *testing.T) {
|
||||
got1 := NewEmptyLabels[TestLabels]()
|
||||
if !reflect.DeepEqual(got1, TestLabels{}) {
|
||||
t.Errorf("NewEmptyLabels[%T] = %v; want %v", TestLabels{}, got1, TestLabels{})
|
||||
}
|
||||
got2 := NewEmptyLabels[TestLabelsWithTags]()
|
||||
if !reflect.DeepEqual(got2, TestLabelsWithTags{}) {
|
||||
t.Errorf("NewEmptyLabels[%T] = %v; want %v", TestLabelsWithTags{}, got1, TestLabelsWithTags{})
|
||||
}
|
||||
got3 := NewEmptyLabels[TestLabelsWithPointers]()
|
||||
if !reflect.DeepEqual(got3, TestLabelsWithPointers{}) {
|
||||
t.Errorf("NewEmptyLabels[%T] = %v; want %v", TestLabelsWithPointers{}, got1, TestLabelsWithPointers{})
|
||||
}
|
||||
got4 := NewEmptyLabels[*TestLabelsFast]()
|
||||
if !reflect.DeepEqual(*got4, TestLabelsFast{}) {
|
||||
t.Errorf("NewEmptyLabels[%T] = %v; want %v", TestLabelsFast{}, *got4, TestLabelsFast{})
|
||||
}
|
||||
}
|
||||
|
||||
func Test_SetPromsafeTag(t *testing.T) {
|
||||
SetPromsafeTag("prom")
|
||||
defer func() {
|
||||
SetPromsafeTag("")
|
||||
}()
|
||||
if promsafeTag != "prom" {
|
||||
t.Errorf("promsafeTag = %v; want %v", promsafeTag, "prom")
|
||||
}
|
||||
|
||||
type CustomTestLabels struct {
|
||||
StructLabelProvider
|
||||
FieldX string `prom:"x"`
|
||||
}
|
||||
|
||||
extractedLabelNames := extractLabelNames(CustomTestLabels{})
|
||||
if !reflect.DeepEqual(extractedLabelNames, []string{"x"}) {
|
||||
t.Errorf("Using custom promsafeTag: extractLabelNames(%v) = %v; want %v", CustomTestLabels{}, extractedLabelNames, []string{"x"})
|
||||
}
|
||||
}
|
||||
|
||||
// Helper functions to create pointers
|
||||
func ptr[T any](v T) *T {
|
||||
return &v
|
||||
}
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
// Copyright 2024 The Prometheus Authors
|
||||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||||
// you may not use this file except in compliance with the License.
|
||||
// You may obtain a copy of the License at
|
||||
//
|
||||
// http://www.apache.org/licenses/LICENSE-2.0
|
||||
//
|
||||
// Unless required by applicable law or agreed to in writing, software
|
||||
// distributed under the License is distributed on an "AS IS" BASIS,
|
||||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
// See the License for the specific language governing permissions and
|
||||
// limitations under the License.
|
||||
|
||||
// Package promauto_adapter provides compatibility adapter for migration of calls of promauto into promsafe
|
||||
package promauto_adapter
|
||||
|
||||
import (
|
||||
"github.com/prometheus/client_golang/prometheus"
|
||||
"github.com/prometheus/client_golang/prometheus/promauto"
|
||||
"github.com/prometheus/client_golang/prometheus/promsafe"
|
||||
)
|
||||
|
||||
// NewCounterVec behaves as adapter-promauto.NewCounterVec but with type-safe labels
|
||||
func NewCounterVec[T promsafe.LabelsProviderMarker](opts prometheus.CounterOpts) *promsafe.CounterVec[T] {
|
||||
//_ = promauto.NewCounterVec // keeping for reference
|
||||
|
||||
c := promsafe.NewCounterVec[T](opts)
|
||||
if prometheus.DefaultRegisterer != nil {
|
||||
prometheus.DefaultRegisterer.MustRegister(c.Unsafe())
|
||||
}
|
||||
return c
|
||||
}
|
||||
|
||||
// Factory is a promauto-like factory that allows type-safe labels.
|
||||
type Factory[T promsafe.LabelsProviderMarker] struct {
|
||||
r prometheus.Registerer
|
||||
}
|
||||
|
||||
// With behaves same as adapter-promauto.With but with type-safe labels
|
||||
func With[T promsafe.LabelsProviderMarker](r prometheus.Registerer) Factory[T] {
|
||||
return Factory[T]{r: r}
|
||||
}
|
||||
|
||||
// NewCounterVec behaves like adapter-promauto.NewCounterVec but with type-safe labels
|
||||
func (f Factory[T]) NewCounterVec(opts prometheus.CounterOpts) *promsafe.CounterVec[T] {
|
||||
c := NewCounterVec[T](opts)
|
||||
if f.r != nil {
|
||||
f.r.MustRegister(c.Unsafe())
|
||||
}
|
||||
return c
|
||||
}
|
||||
|
||||
// NewCounter wraps promauto.NewCounter.
|
||||
// As it doesn't require any labels, it's already type-safe, and we keep it for consistency.
|
||||
func (f Factory[T]) NewCounter(opts prometheus.CounterOpts) prometheus.Counter {
|
||||
return promauto.With(f.r).NewCounter(opts)
|
||||
}
|
||||
|
||||
// NewCounterFunc wraps promauto.NewCounterFunc.
|
||||
// As it doesn't require any labels, it's already type-safe, and we keep it for consistency.
|
||||
func (f Factory[T]) NewCounterFunc(opts prometheus.CounterOpts, function func() float64) prometheus.CounterFunc {
|
||||
return promauto.With(f.r).NewCounterFunc(opts, function)
|
||||
}
|
||||
|
|
@ -0,0 +1,58 @@
|
|||
// Copyright 2024 The Prometheus Authors
|
||||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||||
// you may not use this file except in compliance with the License.
|
||||
// You may obtain a copy of the License at
|
||||
//
|
||||
// http://www.apache.org/licenses/LICENSE-2.0
|
||||
//
|
||||
// Unless required by applicable law or agreed to in writing, software
|
||||
// distributed under the License is distributed on an "AS IS" BASIS,
|
||||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
// See the License for the specific language governing permissions and
|
||||
// limitations under the License.
|
||||
|
||||
package promauto_adapter_test
|
||||
|
||||
import (
|
||||
"github.com/prometheus/client_golang/prometheus"
|
||||
"github.com/prometheus/client_golang/prometheus/promsafe"
|
||||
|
||||
promauto "github.com/prometheus/client_golang/prometheus/promsafe/promauto_adapter"
|
||||
)
|
||||
|
||||
func ExampleNewCounterVec_promauto_adapted() {
|
||||
// Examples on how to migrate from promauto to promsafe gently
|
||||
//
|
||||
// Before:
|
||||
// import "github.com/prometheus/client_golang/prometheus/promauto"
|
||||
// func main() {
|
||||
// myReg := prometheus.NewRegistry()
|
||||
// counterOpts := prometheus.CounterOpts{Name:"..."}
|
||||
// promauto.With(myReg).NewCounterVec(counterOpts, []string{"event_type", "source"})
|
||||
// }
|
||||
//
|
||||
// After:
|
||||
//
|
||||
// import (
|
||||
// promauto "github.com/prometheus/client_golang/prometheus/promsafe/promauto_adapter"
|
||||
// )
|
||||
// ...
|
||||
|
||||
myReg := prometheus.NewRegistry()
|
||||
counterOpts := prometheus.CounterOpts{
|
||||
Name: "items_counted_detailed_auto",
|
||||
}
|
||||
|
||||
type MyLabels struct {
|
||||
promsafe.StructLabelProvider
|
||||
EventType string
|
||||
Source string
|
||||
}
|
||||
c := promauto.With[MyLabels](myReg).NewCounterVec(counterOpts)
|
||||
|
||||
c.With(MyLabels{
|
||||
EventType: "reservation", Source: "source1",
|
||||
}).Inc()
|
||||
|
||||
// Output:
|
||||
}
|
||||
|
|
@ -0,0 +1,186 @@
|
|||
// Copyright 2024 The Prometheus Authors
|
||||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||||
// you may not use this file except in compliance with the License.
|
||||
// You may obtain a copy of the License at
|
||||
//
|
||||
// http://www.apache.org/licenses/LICENSE-2.0
|
||||
//
|
||||
// Unless required by applicable law or agreed to in writing, software
|
||||
// distributed under the License is distributed on an "AS IS" BASIS,
|
||||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
// See the License for the specific language governing permissions and
|
||||
// limitations under the License.
|
||||
|
||||
// Package promsafe provides a layer of type-safety for label management in Prometheus metrics.
|
||||
//
|
||||
// Promsafe introduces type-safe labels, ensuring that the labels used with
|
||||
// Prometheus metrics are explicitly defined and validated at compile-time. This
|
||||
// eliminates common runtime errors caused by mislabeling, such as typos or
|
||||
// incorrect label orders.
|
||||
//
|
||||
// The following example demonstrates how to create and use a CounterVec with
|
||||
// type-safe labels (compared to how it's done in a regular way):
|
||||
//
|
||||
// package main
|
||||
//
|
||||
// import (
|
||||
// "strconv"
|
||||
//
|
||||
// "github.com/prometheus/client_golang/prometheus"
|
||||
// "github.com/prometheus/client_golang/prometheus/promsafe"
|
||||
// )
|
||||
//
|
||||
// // Original unsafe way (no type safety)
|
||||
//
|
||||
// func originalUnsafeWay() {
|
||||
// counterVec := prometheus.NewCounterVec(
|
||||
// prometheus.CounterOpts{
|
||||
// Name: "http_requests_total",
|
||||
// Help: "Total number of HTTP requests by status code and method.",
|
||||
// },
|
||||
// []string{"code", "method"}, // Labels defined as raw strings
|
||||
// )
|
||||
//
|
||||
// // No compile-time checks; label order and types must be correct
|
||||
// // You have to know which and how many labels are expected (in proper order)
|
||||
// counterVec.WithLabelValues("200", "GET").Inc()
|
||||
//
|
||||
// // or you can use map, that is even more fragile
|
||||
// counterVec.With(prometheus.Labels{"code": "200", "method": "GET"}).Inc()
|
||||
// }
|
||||
//
|
||||
// // Safe way (Quick implementation, reflect-based under-the-hood)
|
||||
//
|
||||
// type Labels1 struct {
|
||||
// promsafe.StructLabelProvider
|
||||
// Code int
|
||||
// Method string
|
||||
// }
|
||||
//
|
||||
// func safeReflectWay() {
|
||||
// counterVec := promsafe.NewCounterVec[Labels1](prometheus.CounterOpts{
|
||||
// Name: "http_requests_total_reflection",
|
||||
// Help: "Total number of HTTP requests by status code and method (reflection-based).",
|
||||
// })
|
||||
//
|
||||
// // Compile-time safe and readable; Will be converted into properly ordered list: "200", "GET"
|
||||
// counterVec.With(Labels1{Method: "GET", Code: 200}).Inc()
|
||||
// }
|
||||
//
|
||||
// // Safe way with manual implementation (no reflection overhead, as fast as original)
|
||||
//
|
||||
// type Labels2 struct {
|
||||
// promsafe.StructLabelProvider
|
||||
// Code int
|
||||
// Method string
|
||||
// }
|
||||
//
|
||||
// func (c Labels2) ToPrometheusLabels() prometheus.Labels {
|
||||
// return prometheus.Labels{
|
||||
// "code": strconv.Itoa(c.Code), // Convert int to string
|
||||
// "method": c.Method,
|
||||
// }
|
||||
// }
|
||||
//
|
||||
// func (c Labels2) ToLabelNames() []string {
|
||||
// return []string{"code", "method"}
|
||||
// }
|
||||
//
|
||||
// func safeManualWay() {
|
||||
// counterVec := promsafe.NewCounterVec[Labels2](prometheus.CounterOpts{
|
||||
// Name: "http_requests_total_custom",
|
||||
// Help: "Total number of HTTP requests by status code and method (manual implementation).",
|
||||
// })
|
||||
// counterVec.With(Labels2{Code: 404, Method: "POST"}).Inc()
|
||||
// }
|
||||
//
|
||||
// Package promsafe also provides compatibility adapter for integration with Prometheus's
|
||||
// `promauto` package, ensuring seamless adoption while preserving type-safety.
|
||||
// Methods that cannot guarantee type safety, such as those using raw `[]string`
|
||||
// label values, are explicitly deprecated and will raise runtime errors.
|
||||
//
|
||||
// A separate package allows conservative users to entirely ignore it. And
|
||||
// whoever wants to use it will do so explicitly, with an opportunity to read
|
||||
// this warning.
|
||||
//
|
||||
// Enjoy promsafe as it's safe!
|
||||
package promsafe
|
||||
|
||||
import (
|
||||
"github.com/prometheus/client_golang/prometheus"
|
||||
)
|
||||
|
||||
// NewCounterVec creates a new CounterVec with type-safe labels.
|
||||
func NewCounterVec[T LabelsProviderMarker](opts prometheus.CounterOpts) *CounterVec[T] {
|
||||
emptyLabels := NewEmptyLabels[T]()
|
||||
inner := prometheus.NewCounterVec(opts, extractLabelNames(emptyLabels))
|
||||
|
||||
return &CounterVec[T]{inner: inner}
|
||||
}
|
||||
|
||||
// CounterVec is a wrapper around prometheus.CounterVec that allows type-safe labels.
|
||||
type CounterVec[T LabelsProviderMarker] struct {
|
||||
inner *prometheus.CounterVec
|
||||
}
|
||||
|
||||
// GetMetricWithLabelValues covers prometheus.CounterVec.GetMetricWithLabelValues
|
||||
// Deprecated: Use GetMetricWith() instead. We can't provide a []string safe implementation in promsafe
|
||||
func (c *CounterVec[T]) GetMetricWithLabelValues(_ ...string) (prometheus.Counter, error) {
|
||||
panic("There can't be a SAFE GetMetricWithLabelValues(). Use GetMetricWith() instead")
|
||||
}
|
||||
|
||||
// GetMetricWith behaves like prometheus.CounterVec.GetMetricWith but with type-safe labels.
|
||||
func (c *CounterVec[T]) GetMetricWith(labels T) (prometheus.Counter, error) {
|
||||
return c.inner.GetMetricWith(extractLabelsWithValues(labels))
|
||||
}
|
||||
|
||||
// WithLabelValues covers like prometheus.CounterVec.WithLabelValues.
|
||||
// Deprecated: Use With() instead. We can't provide a []string safe implementation in promsafe
|
||||
func (c *CounterVec[T]) WithLabelValues(_ ...string) prometheus.Counter {
|
||||
panic("There can't be a SAFE WithLabelValues(). Use With() instead")
|
||||
}
|
||||
|
||||
// With behaves like prometheus.CounterVec.With but with type-safe labels.
|
||||
func (c *CounterVec[T]) With(labels T) prometheus.Counter {
|
||||
return c.inner.With(extractLabelsWithValues(labels))
|
||||
}
|
||||
|
||||
// CurryWith behaves like prometheus.CounterVec.CurryWith but with type-safe labels.
|
||||
// It still returns a CounterVec, but it's inner prometheus.CounterVec is curried.
|
||||
func (c *CounterVec[T]) CurryWith(labels T) (*CounterVec[T], error) {
|
||||
curriedInner, err := c.inner.CurryWith(extractLabelsWithValues(labels))
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
c.inner = curriedInner
|
||||
return c, nil
|
||||
}
|
||||
|
||||
// MustCurryWith behaves like prometheus.CounterVec.MustCurryWith but with type-safe labels.
|
||||
// It still returns a CounterVec, but it's inner prometheus.CounterVec is curried.
|
||||
func (c *CounterVec[T]) MustCurryWith(labels T) *CounterVec[T] {
|
||||
c.inner = c.inner.MustCurryWith(extractLabelsWithValues(labels))
|
||||
return c
|
||||
}
|
||||
|
||||
// Unsafe returns the underlying prometheus.CounterVec
|
||||
// it's used to call any other method of prometheus.CounterVec that doesn't require type-safe labels
|
||||
func (c *CounterVec[T]) Unsafe() *prometheus.CounterVec {
|
||||
return c.inner
|
||||
}
|
||||
|
||||
// NewCounter simply creates a new prometheus.Counter.
|
||||
// As it doesn't have any labels, it's already type-safe.
|
||||
// We keep this method just for consistency and interface fulfillment.
|
||||
func NewCounter(opts prometheus.CounterOpts) prometheus.Counter {
|
||||
return prometheus.NewCounter(opts)
|
||||
}
|
||||
|
||||
// NewCounterFunc wraps a new prometheus.CounterFunc.
|
||||
// As it doesn't have any labels, it's already type-safe.
|
||||
// We keep this method just for consistency and interface fulfillment.
|
||||
func NewCounterFunc(opts prometheus.CounterOpts, function func() float64) prometheus.CounterFunc {
|
||||
return prometheus.NewCounterFunc(opts, function)
|
||||
}
|
||||
|
||||
// TODO: other methods (Gauge, Histogram, Summary, etc.)
|
||||
|
|
@ -0,0 +1,162 @@
|
|||
// Copyright 2024 The Prometheus Authors
|
||||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||||
// you may not use this file except in compliance with the License.
|
||||
// You may obtain a copy of the License at
|
||||
//
|
||||
// http://www.apache.org/licenses/LICENSE-2.0
|
||||
//
|
||||
// Unless required by applicable law or agreed to in writing, software
|
||||
// distributed under the License is distributed on an "AS IS" BASIS,
|
||||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
// See the License for the specific language governing permissions and
|
||||
// limitations under the License.
|
||||
|
||||
package promsafe_test
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"log"
|
||||
"strconv"
|
||||
"testing"
|
||||
|
||||
"github.com/prometheus/client_golang/prometheus"
|
||||
"github.com/prometheus/client_golang/prometheus/promsafe"
|
||||
)
|
||||
|
||||
// These are Examples that can be treated as basic smoke tests
|
||||
|
||||
func ExampleNewCounterVec_multiple_labels_manual() {
|
||||
// Manually registering with multiple labels
|
||||
|
||||
type MyCounterLabels struct {
|
||||
promsafe.StructLabelProvider
|
||||
EventType string
|
||||
Success bool
|
||||
Position uint8 // yes, it's a number, but be careful with high-cardinality labels
|
||||
|
||||
ShouldNotBeUsed string `promsafe:"-"`
|
||||
}
|
||||
|
||||
c := promsafe.NewCounterVec[MyCounterLabels](prometheus.CounterOpts{
|
||||
Name: "items_counted_detailed",
|
||||
})
|
||||
|
||||
// Manually register the counter
|
||||
if err := prometheus.Register(c.Unsafe()); err != nil {
|
||||
log.Fatal("could not register: ", err.Error())
|
||||
}
|
||||
|
||||
// and now, because of generics we can call Inc() with filled struct of labels:
|
||||
counter := c.With(MyCounterLabels{
|
||||
EventType: "reservation", Success: true, Position: 1,
|
||||
})
|
||||
counter.Inc()
|
||||
|
||||
// Output:
|
||||
}
|
||||
|
||||
// FastMyLabels is a struct that will have a custom method that converts to prometheus.Labels
|
||||
type FastMyLabels struct {
|
||||
promsafe.StructLabelProvider
|
||||
EventType string
|
||||
Source string
|
||||
}
|
||||
|
||||
// ToPrometheusLabels does a superfast conversion to labels. So no reflection is involved.
|
||||
func (f FastMyLabels) ToPrometheusLabels() prometheus.Labels {
|
||||
return prometheus.Labels{"event_type": f.EventType, "source": f.Source}
|
||||
}
|
||||
|
||||
// ToLabelNames does a superfast label names list. So no reflection is involved.
|
||||
func (f FastMyLabels) ToLabelNames() []string {
|
||||
return []string{"event_type", "source"}
|
||||
}
|
||||
|
||||
func ExampleNewCounterVec_fast_safe_labels_provider() {
|
||||
// Note: fast labels provider has a drawback: they can't be declared as inline structs
|
||||
// as we need methods
|
||||
|
||||
c := promsafe.NewCounterVec[FastMyLabels](prometheus.CounterOpts{
|
||||
Name: "items_counted_detailed_fast",
|
||||
})
|
||||
|
||||
// Manually register the counter
|
||||
if err := prometheus.Register(c.Unsafe()); err != nil {
|
||||
log.Fatal("could not register: ", err.Error())
|
||||
}
|
||||
|
||||
counter := c.With(FastMyLabels{
|
||||
EventType: "reservation", Source: "source1",
|
||||
})
|
||||
counter.Inc()
|
||||
|
||||
// Output:
|
||||
}
|
||||
|
||||
// ====================
|
||||
// Benchmark Tests
|
||||
// ====================
|
||||
|
||||
type TestLabels struct {
|
||||
promsafe.StructLabelProvider
|
||||
Label1 string
|
||||
Label2 int
|
||||
Label3 bool
|
||||
}
|
||||
|
||||
type TestLabelsFast struct {
|
||||
promsafe.StructLabelProvider
|
||||
Label1 string
|
||||
Label2 int
|
||||
Label3 bool
|
||||
}
|
||||
|
||||
func (t TestLabelsFast) ToPrometheusLabels() prometheus.Labels {
|
||||
return prometheus.Labels{
|
||||
"label1": t.Label1,
|
||||
"label2": strconv.Itoa(t.Label2),
|
||||
"label3": strconv.FormatBool(t.Label3),
|
||||
}
|
||||
}
|
||||
|
||||
func (t TestLabelsFast) ToLabelNames() []string {
|
||||
return []string{"label1", "label2", "label3"}
|
||||
}
|
||||
|
||||
func BenchmarkCompareCreatingMetric(b *testing.B) {
|
||||
// Note: on stage of creation metrics, Unique metric names are not required,
|
||||
// but let it be for consistency
|
||||
|
||||
b.Run("Prometheus NewCounterVec", func(b *testing.B) {
|
||||
for i := 0; i < b.N; i++ {
|
||||
uniqueMetricName := fmt.Sprintf("test_counter_prometheus_%d_%d", b.N, i)
|
||||
|
||||
_ = prometheus.NewCounterVec(prometheus.CounterOpts{
|
||||
Name: uniqueMetricName,
|
||||
Help: "A test counter created just using prometheus.NewCounterVec",
|
||||
}, []string{"label1", "label2", "label3"})
|
||||
}
|
||||
})
|
||||
|
||||
b.Run("Promsafe (reflect) NewCounterVec", func(b *testing.B) {
|
||||
for i := 0; i < b.N; i++ {
|
||||
uniqueMetricName := fmt.Sprintf("test_counter_promsafe_%d_%d", b.N, i)
|
||||
|
||||
_ = promsafe.NewCounterVec[TestLabels](prometheus.CounterOpts{
|
||||
Name: uniqueMetricName,
|
||||
Help: "A test counter created using promauto.NewCounterVec",
|
||||
})
|
||||
}
|
||||
})
|
||||
|
||||
b.Run("Promsafe (fast) NewCounterVec", func(b *testing.B) {
|
||||
for i := 0; i < b.N; i++ {
|
||||
uniqueMetricName := fmt.Sprintf("test_counter_promsafe_fast_%d_%d", b.N, i)
|
||||
|
||||
_ = promsafe.NewCounterVec[TestLabelsFast](prometheus.CounterOpts{
|
||||
Name: uniqueMetricName,
|
||||
Help: "A test counter created using promauto.NewCounterVec",
|
||||
})
|
||||
}
|
||||
})
|
||||
}
|
||||
Loading…
Reference in New Issue