registry: add a multiplier option to convert values to base units (#2774)

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>

internal/multiplier/multiplier.go

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 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 multiplier applies the optional multiplier of a user-defined metric
+// of the wmi, performancecounter and registry collectors. It converts values
+// to base units, for example milliseconds to seconds with 0.001.
+package multiplier
+
+import (
+	"fmt"
+	"math"
+)
+
+// maxExactInteger is the largest integer up to which every integer has an
+// exact float64 representation.
+const maxExactInteger = 1 << 53
+
+// Multiplier scales values. The zero value leaves them unchanged.
+type Multiplier struct {
+	factor  float64
+	divisor float64
+}
+
+// New validates the multiplier of the configuration; nil means none. It must
+// be a positive finite number, so that counters stay monotonic.
+func New(multiplier *float64) (Multiplier, error) {
+	if multiplier == nil {
+		return Multiplier{}, nil
+	}
+
+	m := *multiplier
+
+	if math.IsNaN(m) || math.IsInf(m, 0) || m <= 0 {
+		return Multiplier{}, fmt.Errorf("multiplier must be a positive finite number, got %v", m)
+	}
+
+	if m == 1 {
+		return Multiplier{}, nil
+	}
+
+	// x * 0.001 is not always the correctly rounded x / 1000, because 0.001
+	// has no exact binary representation: 9 * 0.001 is 0.009000000000000001.
+	// Divide by the reciprocal instead when it is an integer.
+	if m < 1 {
+		if d := math.Round(1 / m); d <= maxExactInteger && 1/d == m {
+			return Multiplier{divisor: d}, nil
+		}
+	}
+
+	return Multiplier{factor: m}, nil
+}
+
+// Apply returns v scaled by the multiplier.
+func (m Multiplier) Apply(v float64) float64 {
+	switch {
+	case m.divisor != 0:
+		return v / m.divisor
+	case m.factor != 0:
+		return v * m.factor
+	default:
+		return v
+	}
+}

internal/multiplier/multiplier_test.go

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Copyright 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 multiplier_test
+
+import (
+	"math"
+	"testing"
+
+	"github.com/prometheus-community/windows_exporter/internal/multiplier"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNew(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name       string
+		multiplier *float64
+		value      float64
+		want       float64
+	}{
+		{"unset", nil, 42, 42},
+		{"one", new(1.0), 42, 42},
+		{"hours to seconds", new(3600.0), 2, 7200},
+		{"megabytes to bytes", new(1048576.0), 3, 3145728},
+		{"milliseconds to seconds", new(0.001), 9, 0.009},
+		{"percent to ratio", new(0.01), 7, 0.07},
+		{"ticks to seconds", new(1e-7), 115960642, 11.5960642},
+		{"non-integer reciprocal", new(0.4), 5, 2},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			m, err := multiplier.New(tc.multiplier)
+			require.NoError(t, err)
+			require.Equal(t, tc.want, m.Apply(tc.value)) //nolint:testifylint // The result must be exact.
+		})
+	}
+}
+
+func TestNewInvalid(t *testing.T) {
+	t.Parallel()
+
+	for _, m := range []float64{0, -1, math.NaN(), math.Inf(1), math.Inf(-1)} {
+		_, err := multiplier.New(&m)
+		require.Error(t, err, "multiplier %v", m)
+	}
+}
+
+// TestApplyDividesExactly checks that a multiplier that is the reciprocal of
+// an integer gives the correctly rounded quotient, which a plain
+// multiplication misses for about one in seven values.
+func TestApplyDividesExactly(t *testing.T) {
+	t.Parallel()
+
+	for _, divisor := range []float64{10, 100, 1000, 1024, 1e6, 1e7, 1e9} {
+		m, err := multiplier.New(new(1 / divisor))
+		require.NoError(t, err)
+
+		for i := range 100000 {
+			v := float64(i)
+			if got := m.Apply(v); got != v/divisor {
+				t.Fatalf("Apply(%v) with multiplier 1/%v = %v, want %v", v, divisor, got, v/divisor)
+			}
+		}
+	}
+}