feat(metrics): add instrumentation for Check method (#430)

Extends the existing metrics pattern (already covering WhoCanAccess and
WhatCanTargetAccess) to the Check method, recording cache hit/miss,
candidates sent to SDK, and result size per call.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: yosiharan

internal/services/authz.go

@@ -102,6 +102,7 @@ func (a *authzCache) DeleteFGARelations(ctx context.Context, relations []*descop
 }
 
 func (a *authzCache) Check(ctx context.Context, relations []*descope.FGARelation) ([]*descope.FGACheck, error) {
+	start := time.Now()
 	// get cache and mgmt sdk
 	projectCache, mgmtSDK, err := a.getOrCreateProjectCache(ctx)
 	if err != nil {
@@ -111,6 +112,8 @@ func (a *authzCache) Check(ctx context.Context, relations []*descope.FGARelation
 	cachedChecks, toCheckViaSDK, indexToCachedChecks := projectCache.CheckRelations(ctx, relations)
 	// if all relations were found in cache, return
 	if len(toCheckViaSDK) == 0 {
+		// candidatesCount = 0 (nothing sent to SDK); filteredCount = 0 (Check doesn't filter, every relation gets an answer)
+		a.recordMetric(ctx, metrics.APICheck, true, 0, 0, len(cachedChecks), start)
 		return cachedChecks, nil
 	}
 	// fetch missing relations from sdk
@@ -131,6 +134,8 @@ func (a *authzCache) Check(ctx context.Context, relations []*descope.FGARelation
 			j++
 		}
 	}
+	// candidatesCount = relations sent to SDK (not in cache); filteredCount = 0 (Check doesn't filter, every relation gets an answer)
+	a.recordMetric(ctx, metrics.APICheck, false, len(toCheckViaSDK), 0, len(result), start)
 	return result, nil
 }
 

internal/services/authz_test.go

@@ -661,6 +661,98 @@ func TestWhatCanTargetAccess_MetricsRecorded_CacheHit(t *testing.T) {
 	require.Equal(t, int64(2), agg.SumResultSize)
 }
 
+func TestCheck_MetricsRecorded_FullCacheHit(t *testing.T) {
+	ac, mockSDK, mockCache, collector := injectAuthzMocksWithCollector(t)
+	ctx := cctx.AddProjectID(context.TODO(), "proj1")
+	relations := []*descope.FGARelation{
+		{Resource: "mario", Target: "luigi", Relation: "bigBro"},
+		{Resource: "luigi", Target: "mario", Relation: "bigBro"},
+	}
+	mockSDK.MockFGA.CheckAssert = func(_ []*descope.FGARelation) {
+		require.Fail(t, "should not be called on full cache hit")
+	}
+	mockCache.CheckRelationFunc = func(_ context.Context, _ *descope.FGARelation) (bool, bool, bool) {
+		return true, true, true
+	}
+	mockCache.UpdateCacheWithChecksFunc = func(_ context.Context, _ []*descope.FGACheck) {
+		require.Fail(t, "should not be called on full cache hit")
+	}
+	_, err := ac.Check(ctx, relations)
+	require.NoError(t, err)
+	snapshot := collector.SnapshotAndReset()
+	require.Contains(t, snapshot, "proj1")
+	agg := snapshot["proj1"][metrics.APICheck]
+	require.NotNil(t, agg)
+	require.Equal(t, int64(1), agg.TotalCalls)
+	require.Equal(t, int64(1), agg.HitCount)
+	require.Equal(t, int64(0), agg.MissCount)
+	require.Equal(t, int64(0), agg.SumCandidates) // full hit: nothing sent to SDK
+	require.Equal(t, int64(2), agg.SumResultSize)
+}
+
+func TestCheck_MetricsRecorded_FullCacheMiss(t *testing.T) {
+	ac, mockSDK, mockCache, collector := injectAuthzMocksWithCollector(t)
+	ctx := cctx.AddProjectID(context.TODO(), "proj1")
+	relations := []*descope.FGARelation{
+		{Resource: "mario", Target: "luigi", Relation: "bigBro"},
+		{Resource: "luigi", Target: "mario", Relation: "bigBro"},
+	}
+	sdkResponse := []*descope.FGACheck{
+		{Allowed: true, Relation: relations[0], Info: &descope.FGACheckInfo{Direct: true}},
+		{Allowed: false, Relation: relations[1], Info: &descope.FGACheckInfo{Direct: true}},
+	}
+	mockCache.CheckRelationFunc = func(_ context.Context, _ *descope.FGARelation) (bool, bool, bool) {
+		return false, false, false
+	}
+	mockSDK.MockFGA.CheckResponse = sdkResponse
+	mockCache.UpdateCacheWithChecksFunc = func(_ context.Context, _ []*descope.FGACheck) {}
+	_, err := ac.Check(ctx, relations)
+	require.NoError(t, err)
+	snapshot := collector.SnapshotAndReset()
+	require.Contains(t, snapshot, "proj1")
+	agg := snapshot["proj1"][metrics.APICheck]
+	require.NotNil(t, agg)
+	require.Equal(t, int64(1), agg.TotalCalls)
+	require.Equal(t, int64(0), agg.HitCount)
+	require.Equal(t, int64(1), agg.MissCount)
+	require.Equal(t, int64(2), agg.SumCandidates) // full miss: all 2 relations sent to SDK
+	require.Equal(t, int64(2), agg.SumResultSize)
+}
+
+func TestCheck_MetricsRecorded_PartialHit(t *testing.T) {
+	ac, mockSDK, mockCache, collector := injectAuthzMocksWithCollector(t)
+	ctx := cctx.AddProjectID(context.TODO(), "proj1")
+	relations := []*descope.FGARelation{
+		{Resource: "mario", Target: "luigi", Relation: "bigBro"},
+		{Resource: "luigi", Target: "mario", Relation: "bigBro"}, // only this one in cache
+		{Resource: "mario", Target: "bowser", Relation: "enemy"},
+	}
+	sdkResponse := []*descope.FGACheck{
+		{Allowed: true, Relation: relations[0], Info: &descope.FGACheckInfo{Direct: true}},
+		{Allowed: true, Relation: relations[2], Info: &descope.FGACheckInfo{Direct: true}},
+	}
+	mockCache.CheckRelationFunc = func(_ context.Context, r *descope.FGARelation) (bool, bool, bool) {
+		if r.Resource == "luigi" && r.Target == "mario" {
+			return false, true, true // cached
+		}
+		return false, false, false // not cached
+	}
+	mockSDK.MockFGA.CheckResponse = sdkResponse
+	mockCache.UpdateCacheWithChecksFunc = func(_ context.Context, _ []*descope.FGACheck) {}
+	_, err := ac.Check(ctx, relations)
+	require.NoError(t, err)
+	snapshot := collector.SnapshotAndReset()
+	require.Contains(t, snapshot, "proj1")
+	agg := snapshot["proj1"][metrics.APICheck]
+	require.NotNil(t, agg)
+	require.Equal(t, int64(1), agg.TotalCalls)
+	require.Equal(t, int64(0), agg.HitCount)
+	require.Equal(t, int64(1), agg.MissCount)
+	require.Equal(t, int64(2), agg.SumCandidates) // 2 relations sent to SDK (1 was cached)
+	require.Equal(t, int64(0), agg.SumFiltered)
+	require.Equal(t, int64(3), agg.SumResultSize)
+}
+
 func BenchmarkCheck(b *testing.B) {
 	for _, numRelations := range []int{500, 1000, 5000} {
 		name := fmt.Sprintf("relations=%d", numRelations)

internal/services/metrics/collector.go

@@ -8,6 +8,7 @@ import (
 type APIName string
 
 const (
+	APICheck               APIName = "Check"
 	APIWhoCanAccess        APIName = "WhoCanAccess"
 	APIWhatCanTargetAccess APIName = "WhatCanTargetAccess"
 )