-
Notifications
You must be signed in to change notification settings - Fork 1.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Promsafe: Strongly-typed safe labels #1598
base: main
Are you sure you want to change the base?
Conversation
14250ae
to
b783c16
Compare
c064fc4
to
83aba46
Compare
Signed-off-by: Eugene <[email protected]>
83aba46
to
5d421be
Compare
Signed-off-by: Eugene <[email protected]>
091995d
to
aa7e203
Compare
Signed-off-by: Eugene <[email protected]>
011822d
to
80149ab
Compare
Hi! Thanks for innovating here 💪🏽 I presume this is about using generics for label values type safety -- in the relation to defined label names.
Can you share exactly the requirements behind For example, how often you see those Generally, what's recommended is hardcoding label values in Thus, let's circle back to barebone requirements we want here 🤗 e.g. generally you should avoid using Additionally, performance is important for this increment flow, so it would be nice to check how this applies. |
Hey. Thanks for a feedback. Let me share details on my motivation behind the provided By // Counter registration: we're fine with possible panic here :)
myCounter := promauto.NewCounterVec(prometheus.CounterOpts{
Name: "items_counted",
}, []string{"event_type", "success", "slot" /* 1/2/3/.../9 */})
// But using counter: where there motivation comes from:
// Using .GetMetricWith*() methods will error if labels are messed up
myCounterWithValues, err := myCounter.GetMetricWith(prometheus.Labels{
"event_type": "reservation",
"success": "true",
"slot": "1",
})
if err != nil {
// TODO: handle error
}
// Same error can happen if using *WithLabelValues version:
// myCounterWithValues, err := myCounter.GetMetricWithLabelValues("reservation", "true", "1")
// To avoid error-handling we can use .With/.WithLabelValues, but it will just panic for the same reasons:
myCounter.WithLabelValues("reservation", "true", "2").Inc() 💡 So here and further i call "panic" both panicing of Why Panic? why it matters?Here are several reasons:
All these reasons are possible ways to break code because of panicking in .With() or .WithLabelValues(). Let's not spend time and efforts on code-reviews to ensure that new usage of "counter inc" is not breaking everything. Also, one more reason is not about failing but about consistency: How it's solved by promsafe?// Promsafe example:
// Registering a metric with simply providing the type containing labels
type MyCounterLabels struct {
promsafe.StructLabelProvider
EventType string
Success bool
Slot uint8 // yes, it's a number, still should be careful with high-cardinality labels
}
myCounterSafe := promsafe.NewCounterVecT[MyCounterLabels](prometheus.CounterOpts{
Name: "items_counted_detailed",
})
// Calling counter is simple: just provide the filled struct of the dedicated type.
//
// Neither of 5 reasons can panic here. You simply can't mess up the struct.
// With() accepts ONLY this type of struct, you can't send any other struct.
// You don't need to remember the fields and their order. IDE will show you them.
// You can't send more fields.
// You can send less fields (but it can easily fill up with default values, or other custom non-panicy logic).
// You can't mess up types.
// You're consistent with types.
myCounterSafe.With(MyCounterLabels{
EventType: "reservation", Success: true, Slot: 1,
}).Inc() P.S. issue with inconsistency of promsafe-version of WithLabelValues() method// One thing that I need to specify here is the inconsistency with promsafe-version of WithLabelValues()
// WithLabelValues() excepts ordered raw strings, that unfortunately breaks the "safety" concept.
// We can't control the order of given strings and even the length of it
// That's why in promsafe, .WithLavelValues() and .GetMetricWithLabelValues() are disabled:
// They are marked deprecated and panic (so they are strongly considered not to be used) |
This API is really nice, would love to see this merged. I've already ran into a few of the failure modes @amberpixels mentioned in my first few weeks of using this library. |
… a metric Signed-off-by: Eugene <[email protected]>
Signed-off-by: Eugene <[email protected]>
Signed-off-by: Eugene <[email protected]>
…Names Signed-off-by: Eugene <[email protected]>
Small update. I've pushed some improvements in API, so it's more consistent and stable. |
Promsafe
Introducing
promsafe
lib (optional helper lib, similar topromauto
) that allows to use type-safe labels.Motivation
This PR only covers
Counter
functionality as an example. If idea is fine for community, I'll push further commits expanding logic toGauge
,Histogram
, etcFor detailed motivation see my comment below
Fixes #1599
Why?
Currently having unsafe labels lead to several problems: either err-handling nightmare, either panicing (in case if you use "promauto")
Having unsafe labels can lead to following issues:
As of state of art of modern Go version, we can use Go Generics to solve these issues.
Examples of how to use it
1. Multi-label mode (safe structs)
2. (Experimental, syntax sugar) Single-label mode (Pure string, no structs)
Compatibility with
promauto
1.
promauto.With
call migrationNote:
All non-string value types will be automatically converted to string. Here we can add a reasonable type-validation, so we can make it only to work with fields that are strings/bools/ints
2. Global
promauto
setup (allNew*
calls will behave same aspromauto.New*
)