Skip to content

Commit

Permalink
clearer & simpler API. move out single_label_provider as a separate case
Browse files Browse the repository at this point in the history 
Signed-off-by: Eugene <[email protected]>
  • Loading branch information
@amberpixels
amberpixels committed Sep 2, 2024
1 parent aa7e203 commit 80149ab
Show file tree
Hide file tree
Showing 2 changed files with 193 additions and 123 deletions.
256 changes: 160 additions & 96 deletions prometheus/promsafe/safe.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,140 +53,78 @@ func SetPromsafeTag(tag string) {
promsafeTag = tag
}

// labelProviderMarker is a marker interface for enforcing type-safety.
// With its help we can force our label-related functions to only accept SingleLabelProvider or StructLabelProvider.
type labelProviderMarker interface {
marker()
}

// SingleLabelProvider is a type used for declaring a single label.
// When used as labelProviderMarker it provides just a label name.
// It's meant to be used with single-label metrics only!
// Use StructLabelProvider for multi-label metrics.
type SingleLabelProvider string

var _ labelProviderMarker = SingleLabelProvider("")

func (s SingleLabelProvider) marker() {
panic("marker interface method should never be called")
// 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 _ labelProviderMarker = (*StructLabelProvider)(nil)

func (s StructLabelProvider) marker() {
panic("marker interface method should never be called")
}
var _ labelsProviderMarker = (*StructLabelProvider)(nil)

// handler is a helper struct that helps us to handle type-safe labels
// It holds a label name in case if it's the only label (when SingleLabelProvider is used).
type handler[T labelProviderMarker] struct {
theOnlyLabelName string
func (s StructLabelProvider) labelsProviderMarker() {
panic("labelsProviderMarker interface method should never be called")
}

func newHandler[T labelProviderMarker](labelProvider T) handler[T] {
var h handler[T]
if s, ok := any(labelProvider).(SingleLabelProvider); ok {
h.theOnlyLabelName = string(s)
}
return h
}
// 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

// extractLabelsWithValues extracts labels names+values from a given labelProviderMarker (SingleLabelProvider or StructLabelProvider)
func (h handler[T]) extractLabels(labelProvider T) []string {
if any(labelProvider) == nil {
return nil
}
if s, ok := any(labelProvider).(SingleLabelProvider); ok {
return []string{string(s)}
// Let's Support both Structs or Pointer to Structs given as T
val := reflect.ValueOf(&emptyLabels).Elem()
if val.Kind() == reflect.Ptr {
val.Set(reflect.New(val.Type().Elem()))
}

// Here, then, it can be only a struct, that is a parent of StructLabelProvider
labels := extractLabelFromStruct(labelProvider)
labelNames := make([]string, 0, len(labels))
for k := range labels {
labelNames = append(labelNames, k)
}
return labelNames
}

// extractLabelsWithValues extracts labels names+values from a given labelProviderMarker (SingleLabelProvider or StructLabelProvider)
func (h handler[T]) extractLabelsWithValues(labelProvider T) prometheus.Labels {
if any(labelProvider) == nil {
return nil
}

// TODO: let's handle defaults as well, why not?

if s, ok := any(labelProvider).(SingleLabelProvider); ok {
return prometheus.Labels{h.theOnlyLabelName: string(s)}
}

// Here, then, it can be only a struct, that is a parent of StructLabelProvider
return extractLabelFromStruct(labelProvider)
}

// extractLabelValues extracts label string values from a given labelProviderMarker (SingleLabelProvider or StructLabelProvider)
func (h handler[T]) extractLabelValues(labelProvider T) []string {
m := h.extractLabelsWithValues(labelProvider)

labelValues := make([]string, 0, len(m))
for _, v := range m {
labelValues = append(labelValues, v)
}
return labelValues
return emptyLabels
}

// NewCounterVecT creates a new CounterVecT with type-safe labels.
func NewCounterVecT[T labelProviderMarker](opts prometheus.CounterOpts, labels T) *CounterVecT[T] {
h := newHandler(labels)
func NewCounterVecT[T labelsProviderMarker](opts prometheus.CounterOpts) *CounterVecT[T] {
emptyLabels := newEmptyLabels[T]()

var inner *prometheus.CounterVec

if factory != nil {
inner = factory.NewCounterVec(opts, h.extractLabels(labels))
inner = factory.NewCounterVec(opts, extractLabelNames(emptyLabels))
} else {
inner = prometheus.NewCounterVec(opts, h.extractLabels(labels))
inner = prometheus.NewCounterVec(opts, extractLabelNames(emptyLabels))
}

return &CounterVecT[T]{
handler: h,
inner: inner,
}
return &CounterVecT[T]{inner: inner}
}

// CounterVecT is a wrapper around prometheus.CounterVecT that allows type-safe labels.
type CounterVecT[T labelProviderMarker] struct {
handler[T]
// CounterVecT is a wrapper around prometheus.CounterVec that allows type-safe labels.
type CounterVecT[T labelsProviderMarker] struct {
inner *prometheus.CounterVec
}

// GetMetricWithLabelValues behaves like prometheus.CounterVec.GetMetricWithLabelValues but with type-safe labels.
func (c *CounterVecT[T]) GetMetricWithLabelValues(labels T) (prometheus.Counter, error) {
return c.inner.GetMetricWithLabelValues(c.handler.extractLabelValues(labels)...)
return c.inner.GetMetricWithLabelValues(extractLabelValues(labels)...)
}

// GetMetricWith behaves like prometheus.CounterVec.GetMetricWith but with type-safe labels.
func (c *CounterVecT[T]) GetMetricWith(labels T) (prometheus.Counter, error) {
return c.inner.GetMetricWith(c.handler.extractLabelsWithValues(labels))
return c.inner.GetMetricWith(extractLabelsWithValues(labels))
}

// WithLabelValues behaves like prometheus.CounterVec.WithLabelValues but with type-safe labels.
func (c *CounterVecT[T]) WithLabelValues(labels T) prometheus.Counter {
return c.inner.WithLabelValues(c.handler.extractLabelValues(labels)...)
return c.inner.WithLabelValues(extractLabelValues(labels)...)
}

// With behaves like prometheus.CounterVec.With but with type-safe labels.
func (c *CounterVecT[T]) With(labels T) prometheus.Counter {
return c.inner.With(c.handler.extractLabelsWithValues(labels))
return c.inner.With(extractLabelsWithValues(labels))
}

// CurryWith behaves like prometheus.CounterVec.CurryWith but with type-safe labels.
// It still returns a CounterVecT, but it's inner prometheus.CounterVec is curried.
func (c *CounterVecT[T]) CurryWith(labels T) (*CounterVecT[T], error) {
curriedInner, err := c.inner.CurryWith(c.handler.extractLabelsWithValues(labels))
curriedInner, err := c.inner.CurryWith(extractLabelsWithValues(labels))
if err != nil {
return nil, err
}
Expand All @@ -197,7 +135,7 @@ func (c *CounterVecT[T]) CurryWith(labels T) (*CounterVecT[T], error) {
// MustCurryWith behaves like prometheus.CounterVec.MustCurryWith but with type-safe labels.
// It still returns a CounterVecT, but it's inner prometheus.CounterVec is curried.
func (c *CounterVecT[T]) MustCurryWith(labels T) *CounterVecT[T] {
c.inner = c.inner.MustCurryWith(c.handler.extractLabelsWithValues(labels))
c.inner = c.inner.MustCurryWith(extractLabelsWithValues(labels))
return c
}

Expand All @@ -221,24 +159,110 @@ func NewCounterFuncT(opts prometheus.CounterOpts, function func() float64) prome
return prometheus.NewCounterFunc(opts, function)
}

//
// Shorthand for Metrics with a single label
//

// singleLabelProviderMarker is a marker interface for enforcing type-safety of SingleLabelProvider.
type singleLabelProviderMarker interface {
singleLabelProviderMarker()
}

// SingleLabelProvider is a type used for declaring a single label only.
// When declaring a metric it's values used as a label name
// When calling With() it's values used as a label value
type SingleLabelProvider string

var _ singleLabelProviderMarker = SingleLabelProvider("")

func (s SingleLabelProvider) singleLabelProviderMarker() {
panic("singleLabelProviderMarker interface method should never be called")
}

// NewCounterVecT1 creates a new CounterVecT with the only single label
func NewCounterVecT1(opts prometheus.CounterOpts, singleLabelProvider singleLabelProviderMarker) *CounterVecT1 {
// labelName is the string itself
// and singleLabelProviderMarker here can ONLY be SingleLabelProvider
labelName := string(singleLabelProvider.(SingleLabelProvider))

var inner *prometheus.CounterVec
if factory != nil {
inner = factory.NewCounterVec(opts, []string{labelName})
} else {
inner = prometheus.NewCounterVec(opts, []string{labelName})
}

return &CounterVecT1{inner: inner, labelName: labelName}
}

// CounterVecT1 is a wrapper around prometheus.CounterVec that allows a single type-safe label.
type CounterVecT1 struct {
labelName string
inner *prometheus.CounterVec
}

// GetMetricWithLabelValues behaves like prometheus.CounterVec.GetMetricWithLabelValues but with type-safe labels.
func (c *CounterVecT1) GetMetricWithLabelValues(labelValue string) (prometheus.Counter, error) {
return c.inner.GetMetricWithLabelValues(labelValue)
}

// GetMetricWith behaves like prometheus.CounterVec.GetMetricWith but with type-safe labels.
func (c *CounterVecT1) GetMetricWith(labelValue string) (prometheus.Counter, error) {
return c.inner.GetMetricWith(prometheus.Labels{c.labelName: labelValue})
}

// WithLabelValues behaves like prometheus.CounterVec.WithLabelValues but with type-safe labels.
func (c *CounterVecT1) WithLabelValues(labelValue string) prometheus.Counter {
return c.inner.WithLabelValues(labelValue)
}

// With behaves like prometheus.CounterVec.With but with type-safe labels.
func (c *CounterVecT1) With(labelValue string) prometheus.Counter {
return c.inner.With(prometheus.Labels{c.labelName: labelValue})
}

// CurryWith behaves like prometheus.CounterVec.CurryWith but with type-safe labels.
// It still returns a CounterVecT, but it's inner prometheus.CounterVec is curried.
func (c *CounterVecT1) CurryWith(labelValue string) (*CounterVecT1, error) {
curriedInner, err := c.inner.CurryWith(prometheus.Labels{c.labelName: labelValue})
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 CounterVecT, but it's inner prometheus.CounterVec is curried.
func (c *CounterVecT1) MustCurryWith(labelValue string) *CounterVecT1 {
c.inner = c.inner.MustCurryWith(prometheus.Labels{c.labelName: labelValue})
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 *CounterVecT1) Unsafe() *prometheus.CounterVec {
return c.inner
}

//
// Promauto compatibility
//

// Factory is a promauto-like factory that allows type-safe labels.
// We have to duplicate promauto.Factory logic here, because promauto.Factory's registry is private.
type Factory[T labelProviderMarker] struct {
type Factory[T labelsProviderMarker] struct {
r prometheus.Registerer
}

// WithAuto is a helper function that allows to use promauto.With with promsafe.With
func WithAuto(r prometheus.Registerer) Factory[labelProviderMarker] {
return Factory[labelProviderMarker]{r: r}
func WithAuto[T labelsProviderMarker](r prometheus.Registerer) Factory[T] {
return Factory[T]{r: r}
}

// NewCounterVecT works like promauto.NewCounterVec but with type-safe labels
func (f Factory[T]) NewCounterVecT(opts prometheus.CounterOpts, labels T) *CounterVecT[T] {
c := NewCounterVecT(opts, labels)
func (f Factory[T]) NewCounterVecT(opts prometheus.CounterOpts) *CounterVecT[T] {
c := NewCounterVecT[T](opts)
if f.r != nil {
f.r.MustRegister(c.inner)
}
Expand All @@ -257,10 +281,50 @@ func (f Factory[T]) NewCounterFuncT(opts prometheus.CounterOpts, function func()
return promauto.With(f.r).NewCounterFunc(opts, function)
}

// TODO: we can't use Factory with NewCounterT1. If we need, then we need a new type-less Factory

//
// Helpers
//

// 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
}

// TODO: let's handle defaults as well, why not?

// Here, then, it can be only a struct, that is a parent of StructLabelProvider
return extractLabelFromStruct(labelProvider)
}

// extractLabelValues extracts label string values from a given labelsProviderMarker (parent instance of aStructLabelProvider)
func extractLabelValues(labelProvider labelsProviderMarker) []string {
m := extractLabelsWithValues(labelProvider)

labelValues := make([]string, 0, len(m))
for _, v := range m {
labelValues = append(labelValues, v)
}
return labelValues
}

// extractLabelNames extracts labels names from a given labelsProviderMarker (parent instance of aStructLabelProvider)
func extractLabelNames(labelProvider labelsProviderMarker) []string {
if any(labelProvider) == nil {
return nil
}

// Here, then, it can be only a struct, that is a parent of StructLabelProvider
labels := extractLabelFromStruct(labelProvider)
labelNames := make([]string, 0, len(labels))
for k := range labels {
labelNames = append(labelNames, k)
}
return labelNames
}

// extractLabelFromStruct extracts labels names+values from a given StructLabelProvider
func extractLabelFromStruct(structWithLabels any) prometheus.Labels {
labels := prometheus.Labels{}
Expand Down
Loading

0 comments on commit 80149ab

Please sign in to comment.