proposal: x/time/rate: expose number of available tokens for metrics/testing

[liggitt]

What version of Go are you using (go version)?

1.6

What operating system and processor architecture are you using (go env)?

darwin/amd64

What did you do?

Using golang.org/x/time/rate#Limiter in kubernetes, we have a need to monitor ratelimiters for saturation. To do that, we need the capacity (available via Burst()) and the current availability. The latter is not exposed in the Limiter API.

What did you expect to see?

A thread-safe Available() method that returns (but does not reserve) the number of currently available tokens.

Something like this, perhaps:

// Available returns the number of tokens currently available, but does not
// guarantee a subsequent call to AllowN, WaitN, or ReserveN will succeed.
// If consumers are waiting for tokens, the number can be negative.
// It is primarily for metrics reporting and debugging.
func (lim *Limiter) Available() int {
	lim.mu.Lock()
	defer lim.mu.Unlock()
	_, _, tokens := lim.advance(time.Now())
	return int(tokens)
}

What did you see instead?

No visibility to the number of available tokens at a given point in time

[krousey]

@liggitt see https://go-review.googlesource.com/#/c/29958/ for my attempt. The discussion on that change basically boils down to Kubernetes' queue saturation metric being a fundamentally broken calculation.

[liggitt]

ah, didn't know you'd already pursued that... I just opened https://go-review.googlesource.com/#/c/34112/

[bradfitz]

Sorry for letting this slip through the cracks. @dsnet, can you either own this or figure out who does own x/time/rate? And then have the owner review the CLs above?

[dsnet]

I'd like to re-open this issue. In addition to metrics, this is also useful for computing a time duration for a request to retry after.