libindex: layer metrics

go.mod

@@ -20,6 +20,7 @@ require (
 	github.com/spdx/tools-golang v0.5.7
 	github.com/ulikunitz/xz v0.5.15
 	go.opentelemetry.io/otel v1.42.0
+	go.opentelemetry.io/otel/metric v1.42.0
 	go.opentelemetry.io/otel/trace v1.42.0
 	go.uber.org/mock v0.6.0
 	golang.org/x/crypto v0.48.0
@@ -52,7 +53,6 @@ require (
 	github.com/prometheus/procfs v0.16.1 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
-	go.opentelemetry.io/otel/metric v1.42.0 // indirect
 	go.yaml.in/yaml/v2 v2.4.2 // indirect
 	golang.org/x/mod v0.33.0 // indirect
 	google.golang.org/protobuf v1.36.8 // indirect

internal/cache/live.go

@@ -94,3 +94,18 @@ func (c *Live[K, V]) Get(ctx context.Context, key K, create CreateFunc[K, V]) (*
 // No additional calls are made for individual values; the cache simply drops
 // any references it has.
 func (c *Live[K, V]) Clear() { c.m.Clear() }
+
+// Len reports the approximate number of entries in the cache.
+//
+// The count is approximate because concurrent removals and additions may not be
+// seen. If a caller wants an accurate count, it must arrange to prevent
+// concurrent modifications.
+func (c *Live[K, V]) Len() (n int) {
+	c.m.Range(func(_, value any) bool {
+		if v := value.(weak.Pointer[V]).Value(); v != nil {
+			n++
+		}
+		return true
+	})
+	return n
+}

internal/units/doc.go

@@ -0,0 +1,25 @@
+// Package units provides a common spot for [OTel units].
+//
+// Units should follow the [Unified Code for Units of Measure] (UCUM).
+//
+//   - Instruments for utilization metrics (that measure the fraction out of a
+//     total) are dimensionless and SHOULD use the default unit 1 (the unity).
+//   - All non-units that use curly braces to annotate a quantity need to match
+//     the grammatical number of the quantity it represent. For example, if
+//     measuring the number of individual requests to a process the unit would be
+//     "{request}", not "{requests}".
+//   - Instruments that measure an integer count of something SHOULD only use
+//     annotations with curly braces to give additional meaning without the
+//     leading default unit (1). For example, use "{packet}", "{error}",
+//     "{fault}", etc.
+//   - Instrument units other than 1 and those that use annotations SHOULD be
+//     specified using the UCUM case sensitive ("c/s") variant. For example, "Cel"
+//     for the unit with full name "degree Celsius".
+//   - Instruments SHOULD use non-prefixed units (i.e. "By" instead of "MiBy")
+//     unless there is good technical reason to not do so.
+//   - When instruments are measuring durations, seconds (i.e. "s") SHOULD be
+//     used.
+//
+// [Unified Code for Units of Measure]: https://ucum.org/ucum
+// [OTel units]: https://opentelemetry.io/docs/specs/semconv/general/metrics/#instrument-units
+package units

internal/units/histogram.go

@@ -0,0 +1,72 @@
+package units
+
+import (
+	"math/big"
+	"slices"
+
+	"go.opentelemetry.io/otel/metric"
+)
+
+// Buckets as suggested for [request durations].
+//
+// [request durations]: https://opentelemetry.io/docs/specs/semconv/http/http-metrics/#metric-httpserverrequestduration
+var Buckets metric.HistogramOption
+
+// LargeBuckets is a 10x multiple of [Buckets].
+var LargeBuckets metric.HistogramOption
+
+// VeryLargeBuckets is a 20x multiple [Buckets].
+var VeryLargeBuckets metric.HistogramOption
+
+func init() {
+	Buckets = metric.WithExplicitBucketBoundaries(BucketBoundaries(0.005, 14)...)
+	LargeBuckets = metric.WithExplicitBucketBoundaries(BucketBoundaries(0.05, 14)...)
+	VeryLargeBuckets = metric.WithExplicitBucketBoundaries(BucketBoundaries(0.1, 14)...)
+}
+
+// BucketBoundaries returns "count" bucket boundaries in the same pattern as the
+// semconv suggested bucket boundaries.
+func BucketBoundaries(start float64, count int) []float64 {
+	// This uses [big.Rat], which is probably not strictly necessary, but avoids
+	// needing to do rounding shenanigans. The overhead of the math is also just
+	// paid once at setup.
+	ten := big.NewRat(10, 1)
+	rat := big.NewRat(1, 4)
+	steps := []*big.Rat{
+		big.NewRat(1, 1),
+		big.NewRat(2, 1),
+		big.NewRat(3, 1),
+	}
+
+	n := new(big.Rat).SetFloat64(start)
+	seq := func(yield func(float64) bool) {
+		// Yield wrapper: convert the [big.Rat] and check the number of values
+		// we're supposed to produce.
+		y := func(n *big.Rat) bool {
+			v, _ := n.Float64()
+			count--
+			return yield(v) && count > 0
+		}
+		if !y(n) {
+			return
+		}
+		n.Mul(n, big.NewRat(2, 1))
+		v, incr := new(big.Rat), new(big.Rat)
+		for {
+			if !y(n) {
+				return
+			}
+
+			n.Mul(n, ten)
+			incr.Mul(n, rat)
+
+			for _, step := range steps {
+				v.Mul(incr, step)
+				if !y(v) {
+					return
+				}
+			}
+		}
+	}
+	return slices.Collect(seq)
+}

internal/units/histogram_test.go

@@ -0,0 +1,37 @@
+package units
+
+import (
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+)
+
+func TestBucketSeq(t *testing.T) {
+	tt := []struct {
+		Name string
+		Want []float64
+	}{
+		{
+			"Buckets",
+			[]float64{0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10},
+		},
+		{
+			"LargeBuckets",
+			[]float64{0.05, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10, 25, 50, 75, 100},
+		},
+		{
+			"VeryLargeBuckets",
+			[]float64{0.1, 0.2, 0.5, 1, 1.5, 2, 5, 10, 15, 20, 50, 100, 150, 200},
+		},
+	}
+	for _, tc := range tt {
+		t.Run(tc.Name, func(t *testing.T) {
+			want := tc.Want
+			got := BucketBoundaries(want[0], len(want))
+
+			if !cmp.Equal(got, want) {
+				t.Error(cmp.Diff(got, want))
+			}
+		})
+	}
+}