feat(governance): add query metrics

Emit unsampled metrics for the governance query endpoint:
requests{namespace,direction,all_org_features},
customers_not_found{namespace}, and feature_access / customer_keys
histograms{namespace}. namespace is a per-tenant label (consistent with
ingest/sink/balanceworker); per-request counts are histogram values to
bound cardinality. Meter injected via Config like the tracer.

Author: gergely-kurucz-konghq

api/v3/handlers/governance/query.go

@@ -28,7 +28,6 @@ func (h *handler) QueryGovernanceAccess() QueryGovernanceAccessHandler {
 	return httptransport.NewHandlerWithArgs(
 		func(ctx context.Context, r *http.Request, params QueryGovernanceAccessParams) (governance.QueryAccessInput, error) {
 			ns, err := h.resolveNamespace(ctx)
-
 			if err != nil {
 				return governance.QueryAccessInput{}, err
 			}
@@ -61,7 +60,6 @@ func (h *handler) QueryGovernanceAccess() QueryGovernanceAccessHandler {
 		},
 		func(ctx context.Context, input governance.QueryAccessInput) (QueryGovernanceAccessResponse, error) {
 			res, err := h.governanceService.QueryAccess(ctx, input)
-
 			if err != nil {
 				return QueryGovernanceAccessResponse{}, err
 			}
@@ -130,7 +128,6 @@ func applyPaging(ctx context.Context, input *governance.QueryAccessInput, params
 
 func decodeCursorParam(ctx context.Context, field, raw string) (*pagination.Cursor, error) {
 	cursor, err := pagination.DecodeCursor(raw)
-
 	if err != nil {
 		return nil, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{{
 			Field:  field,

app/common/governance.go

@@ -2,6 +2,7 @@ package common
 
 import (
 	"github.com/google/wire"
+	"go.opentelemetry.io/otel/metric"
 	"go.opentelemetry.io/otel/trace"
 
 	"github.com/openmeterio/openmeter/openmeter/customer"
@@ -18,11 +19,13 @@ func NewGovernanceService(
 	customer customer.Service,
 	entitlementRegistry *registry.Entitlement,
 	tracer trace.Tracer,
+	meter metric.Meter,
 ) (governance.Service, error) {
 	return governanceservice.New(governanceservice.Config{
 		Customer:    customer,
 		Entitlement: entitlementRegistry.Entitlement,
 		Feature:     entitlementRegistry.Feature,
 		Tracer:      tracer,
+		Meter:       meter,
 	})
 }

cmd/server/wire_gen.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/samber/lo"
 	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/metric"
 	"go.opentelemetry.io/otel/trace"
 
 	"github.com/openmeterio/openmeter/openmeter/customer"
@@ -31,6 +32,7 @@ type Config struct {
 	Entitlement entitlement.Service
 	Feature     feature.FeatureConnector
 	Tracer      trace.Tracer
+	Meter       metric.Meter
 }
 
 func (c Config) Validate() error {
@@ -52,6 +54,10 @@ func (c Config) Validate() error {
 		errs = append(errs, errors.New("tracer is required"))
 	}
 
+	if c.Meter == nil {
+		errs = append(errs, errors.New("meter is required"))
+	}
+
 	return errors.Join(errs...)
 }
 
@@ -60,11 +66,17 @@ func New(config Config) (governance.Service, error) {
 		return nil, err
 	}
 
+	metrics, err := newMetrics(config.Meter)
+	if err != nil {
+		return nil, err
+	}
+
 	return &service{
 		customerService:    config.Customer,
 		entitlementService: config.Entitlement,
 		featureConnector:   config.Feature,
 		tracer:             config.Tracer,
+		metrics:            metrics,
 	}, nil
 }
 
@@ -73,6 +85,70 @@ type service struct {
 	entitlementService entitlement.Service
 	featureConnector   feature.FeatureConnector
 	tracer             trace.Tracer
+	metrics            queryMetrics
+}
+
+// queryMetrics holds the instruments for the governance query endpoint. These are unsampled
+// (unlike spans), so they back SLOs, alerting, and capacity dashboards. Per-request counts
+// are recorded as histogram observations rather than attributes to keep series cardinality
+// bounded; only low-cardinality enums are used as counter attributes.
+type queryMetrics struct {
+	// requests counts queries, broken down by pagination direction and whether the
+	// all-org-features (no filter) path was taken.
+	requests metric.Int64Counter
+	// customersNotFound counts input keys that did not resolve to a customer. These return
+	// HTTP 200 with a partial error, so they are invisible to HTTP-level metrics.
+	customersNotFound metric.Int64Counter
+	// featureAccess records the number of feature evaluations per query — the work unit that
+	// drives latency (~customers × features).
+	featureAccess metric.Int64Histogram
+	// customerKeys records the number of customer keys requested per query.
+	customerKeys metric.Int64Histogram
+}
+
+func newMetrics(meter metric.Meter) (queryMetrics, error) {
+	requests, err := meter.Int64Counter(
+		"openmeter.governance.query.requests",
+		metric.WithDescription("Number of governance access queries"),
+		metric.WithUnit("{request}"),
+	)
+	if err != nil {
+		return queryMetrics{}, fmt.Errorf("failed to create requests counter: %w", err)
+	}
+
+	customersNotFound, err := meter.Int64Counter(
+		"openmeter.governance.query.customers_not_found",
+		metric.WithDescription("Number of customer keys that did not resolve to a customer"),
+		metric.WithUnit("{customer}"),
+	)
+	if err != nil {
+		return queryMetrics{}, fmt.Errorf("failed to create customers_not_found counter: %w", err)
+	}
+
+	featureAccess, err := meter.Int64Histogram(
+		"openmeter.governance.query.feature_access",
+		metric.WithDescription("Number of feature evaluations per governance query"),
+		metric.WithUnit("{evaluation}"),
+	)
+	if err != nil {
+		return queryMetrics{}, fmt.Errorf("failed to create feature_access histogram: %w", err)
+	}
+
+	customerKeys, err := meter.Int64Histogram(
+		"openmeter.governance.query.customer_keys",
+		metric.WithDescription("Number of customer keys requested per governance query"),
+		metric.WithUnit("{key}"),
+	)
+	if err != nil {
+		return queryMetrics{}, fmt.Errorf("failed to create customer_keys histogram: %w", err)
+	}
+
+	return queryMetrics{
+		requests:          requests,
+		customersNotFound: customersNotFound,
+		featureAccess:     featureAccess,
+		customerKeys:      customerKeys,
+	}, nil
 }
 
 var _ governance.Service = (*service)(nil)
@@ -131,12 +207,38 @@ func (s *service) QueryAccess(ctx context.Context, input governance.QueryAccessI
 			out.Last = lo.ToPtr(cursorFor(sortedCustomers[len(sortedCustomers)-1]))
 		}
 
+		s.recordQueryMetrics(ctx, input, out, len(customers.queryErrors))
+
 		return out, nil
 	}
 
 	return tracex.Start[governance.QueryResult](ctx, s.tracer, "governance.QueryAccess").Wrap(fn)
 }
 
+// recordQueryMetrics emits the unsampled query metrics. namespace is a per-tenant label
+// (consistent with ingest/sink/balanceworker); per-request counts are histogram values, and
+// only low-cardinality enums (direction, all_org_features) are counter attributes.
+func (s *service) recordQueryMetrics(ctx context.Context, input governance.QueryAccessInput, out governance.QueryResult, notFound int) {
+	namespaceAttr := attribute.String("namespace", input.Namespace)
+
+	s.metrics.requests.Add(ctx, 1, metric.WithAttributes(
+		namespaceAttr,
+		attribute.String("direction", paginationDirection(input)),
+		attribute.Bool("all_org_features", len(input.FeatureKeys) == 0),
+	))
+
+	if notFound > 0 {
+		s.metrics.customersNotFound.Add(ctx, int64(notFound), metric.WithAttributes(namespaceAttr))
+	}
+
+	featureAccessTotal := lo.SumBy(out.Customers, func(c governance.CustomerAccess) int {
+		return len(c.Features)
+	})
+
+	s.metrics.featureAccess.Record(ctx, int64(featureAccessTotal), metric.WithAttributes(namespaceAttr))
+	s.metrics.customerKeys.Record(ctx, int64(len(input.CustomerKeys)), metric.WithAttributes(namespaceAttr))
+}
+
 // resolvedCustomer groups the matched input keys for a single customer.
 type resolvedCustomer struct {
 	customer customer.Customer

openmeter/governance/service/service.go

@@ -10,6 +10,7 @@ import (
 	"github.com/samber/lo"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	metricnoop "go.opentelemetry.io/otel/metric/noop"
 	"go.opentelemetry.io/otel/trace/noop"
 
 	"github.com/openmeterio/openmeter/app/config"
@@ -140,6 +141,7 @@ func newTestService(t *testing.T, deps *testDeps) governance.Service {
 		Entitlement: deps.registry.Entitlement,
 		Feature:     deps.registry.Feature,
 		Tracer:      noop.NewTracerProvider().Tracer("test"),
+		Meter:       metricnoop.NewMeterProvider().Meter("test"),
 	})
 	require.NoError(t, err)
 

openmeter/governance/service/service_test.go

@@ -17,6 +17,7 @@ import (
 	"github.com/samber/lo"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	metricnoop "go.opentelemetry.io/otel/metric/noop"
 	"go.opentelemetry.io/otel/trace/noop"
 
 	"github.com/openmeterio/openmeter/api"
@@ -751,6 +752,7 @@ func getTestServer(t *testing.T, opts ...func(*router.Config)) (*Server, *MockSt
 		Entitlement: &NoopEntitlementConnector{},
 		Feature:     featureService,
 		Tracer:      noop.NewTracerProvider().Tracer("test"),
+		Meter:       metricnoop.NewMeterProvider().Meter("test"),
 	})
 	assert.NoError(t, err, "failed to create governance service")