cache: separate hit/miss metrics by level

We further break down the block cache metrics by level.

The level is plumbed through the level iterator. However, it is not
currently plumbed for the initial open of a file, and it is not
plumbed for blob value reads. I will investigate plumbing a level
through `LazyFetcher` separately.

The n/a level reflects accesses where the level is not known and any
accesses on flushable ingests.

Metrics after 30m of ycsb-A:
```
BLOCK CACHE: 592 entries (17MB)
                 miss rate [percentage of total misses] since start
 level |            |  background    sstdata       sstval      blobval       filter       index
-------+------------+------------------------------------------------------------------------------
   n/a | 2.3% [91%] | 9.6% [7.4%]                             4.1% [81%]               0.2% [3.3%]
    L0 | 22% [4.6%] |  36% [1.3%]    24% [2%]                                           15% [1.3%]
    L6 | 0% [4.1%]  |   0% [0%]     0% [2.8%]                                           0% [1.3%]
 total |    0.3%    |  10% [8.7%]   0% [4.8%]                 4.1% [81%]                0% [5.9%]
```

Benchmark (before = without the level AND the category changes). On a
GCE worker, `--benchtime=10s`:

```
name         old time/op  new time/op  delta
CacheGet-24  52.0ns ± 1%  44.0ns ± 1%  -15.40%  (p=0.008 n=5+5)
```

Author: RaduBerinde

compaction.go

@@ -2953,7 +2953,7 @@ func (d *DB) runCopyCompaction(
 			// TODO(radu): plumb a ReadEnv to CopySpan (it could use the buffer pool
 			// or update category stats).
 			wrote, err = sstable.CopySpan(ctx,
-				src, r, d.opts.MakeReaderOptions(),
+				src, r, c.startLevel.level,
 				w, d.opts.MakeWriterOptions(c.outputLevel.level, d.TableFormat()),
 				start, end,
 			)

db_test.go

@@ -858,7 +858,7 @@ func TestMemTableReservation(t *testing.T) {
 		t.Fatalf("expected 2 refs, but found %d", refs)
 	}
 	// Verify the memtable reservation has caused our test block to be evicted.
-	if cv := tmpHandle.Peek(base.DiskFileNum(0), 0, cache.CategoryBackground); cv != nil {
+	if cv := tmpHandle.Peek(base.DiskFileNum(0), 0, cache.MakeLevel(0), cache.CategoryBackground); cv != nil {
 		t.Fatalf("expected failure, but found success: %#v", cv)
 	}
 

file_cache.go

@@ -590,6 +590,9 @@ func (h *fileCacheHandle) newIters(
 	internalOpts.readEnv.Virtual = env.Virtual
 	internalOpts.readEnv.IsSharedIngested = env.IsSharedIngested
 	internalOpts.readEnv.InternalBounds = env.InternalBounds
+	if opts != nil && opts.layer.IsSet() && !opts.layer.IsFlushableIngests() {
+		internalOpts.readEnv.Block.Level = cache.MakeLevel(opts.layer.Level())
+	}
 
 	var iters iterSet
 	if kinds.RangeKey() && file.HasRangeKeys {

internal/cache/cache.go

@@ -252,19 +252,23 @@ func (c *Handle) Cache() *Cache {
 //
 // Peek supports the special CategoryHidden category, in which case the hit or
 // miss is not recorded in metrics.
-func (c *Handle) Peek(fileNum base.DiskFileNum, offset uint64, category Category) *Value {
+func (c *Handle) Peek(
+	fileNum base.DiskFileNum, offset uint64, level Level, category Category,
+) *Value {
 	k := makeKey(c.id, fileNum, offset)
-	return c.cache.getShard(k).get(k, category, true /* peekOnly */)
+	return c.cache.getShard(k).get(k, level, category, true /* peekOnly */)
 }
 
 // CategoryHidden can be used with Peek to avoid recording a cache hit or miss.
 const CategoryHidden Category = -1
 
 // Get retrieves the cache value for the specified file and offset, returning
 // nil if no value is present.
-func (c *Handle) Get(fileNum base.DiskFileNum, offset uint64, category Category) *Value {
+func (c *Handle) Get(
+	fileNum base.DiskFileNum, offset uint64, level Level, category Category,
+) *Value {
 	k := makeKey(c.id, fileNum, offset)
-	return c.cache.getShard(k).get(k, category, false /* peekOnly */)
+	return c.cache.getShard(k).get(k, level, category, false /* peekOnly */)
 }
 
 // GetWithReadHandle retrieves the cache value for the specified handleID, fileNum
@@ -291,7 +295,7 @@ func (c *Handle) Get(fileNum base.DiskFileNum, offset uint64, category Category)
 // While waiting, someone else may successfully read the value, which results
 // in a valid Handle being returned. This is a case where cacheHit=false.
 func (c *Handle) GetWithReadHandle(
-	ctx context.Context, fileNum base.DiskFileNum, offset uint64, category Category,
+	ctx context.Context, fileNum base.DiskFileNum, offset uint64, level Level, category Category,
 ) (
 	cv *Value,
 	rh ReadHandle,
@@ -301,7 +305,7 @@ func (c *Handle) GetWithReadHandle(
 	err error,
 ) {
 	k := makeKey(c.id, fileNum, offset)
-	cv, re := c.cache.getShard(k).getWithReadEntry(k, category)
+	cv, re := c.cache.getShard(k).getWithReadEntry(k, level, category)
 	if cv != nil {
 		return cv, ReadHandle{}, 0, 0, true, nil
 	}

internal/cache/cache_test.go

@@ -41,7 +41,7 @@ func TestCache(t *testing.T) {
 		wantHit := fields[1][0] == 'h'
 
 		var hit bool
-		cv := h.Get(base.DiskFileNum(key), 0, CategorySSTableData)
+		cv := h.Get(base.DiskFileNum(key), 0, MakeLevel(0), CategorySSTableData)
 		if cv == nil {
 			cv = Alloc(1)
 			cv.RawBuffer()[0] = fields[0][0]
@@ -81,14 +81,14 @@ func TestCachePeek(t *testing.T) {
 		setTestValue(h, 0, uint64(i), "a", 1)
 	}
 	for i := range size / 2 {
-		v := h.Get(base.DiskFileNum(0), uint64(i), CategoryBackground)
+		v := h.Get(base.DiskFileNum(0), uint64(i), MakeLevel(0), CategoryBackground)
 		if v == nil {
 			t.Fatalf("expected to find block %d", i)
 		}
 		v.Release()
 	}
 	for i := size / 2; i < size; i++ {
-		v := h.Peek(base.DiskFileNum(0), uint64(i), CategoryBackground)
+		v := h.Peek(base.DiskFileNum(0), uint64(i), MakeLevel(0), CategoryBackground)
 		if v == nil {
 			t.Fatalf("expected to find block %d", i)
 		}
@@ -100,7 +100,7 @@ func TestCachePeek(t *testing.T) {
 	}
 	// Verify that the Gets still find their values, despite the Peeks.
 	for i := range size / 2 {
-		v := h.Get(base.DiskFileNum(0), uint64(i), CategoryBackground)
+		v := h.Get(base.DiskFileNum(0), uint64(i), MakeLevel(0), CategoryBackground)
 		if v == nil {
 			t.Fatalf("expected to find block %d", i)
 		}
@@ -124,12 +124,12 @@ func TestCacheDelete(t *testing.T) {
 	if expected, size := int64(10), cache.Size(); expected != size {
 		t.Fatalf("expected cache size %d, but found %d", expected, size)
 	}
-	if v := h.Get(base.DiskFileNum(0), 0, CategorySSTableData); v == nil {
+	if v := h.Get(base.DiskFileNum(0), 0, MakeLevel(0), CategorySSTableData); v == nil {
 		t.Fatalf("expected to find block 0/0")
 	} else {
 		v.Release()
 	}
-	if v := h.Get(base.DiskFileNum(1), 0, CategorySSTableData); v != nil {
+	if v := h.Get(base.DiskFileNum(1), 0, MakeLevel(0), CategorySSTableData); v != nil {
 		t.Fatalf("expected to not find block 1/0")
 	}
 	// Deleting a non-existing block does nothing.
@@ -196,11 +196,11 @@ func TestMultipleDBs(t *testing.T) {
 	if expected, size := int64(5), cache.Size(); expected != size {
 		t.Fatalf("expected cache size %d, but found %d", expected, size)
 	}
-	v := h1.Get(base.DiskFileNum(0), 0, CategorySSTableData)
+	v := h1.Get(base.DiskFileNum(0), 0, MakeLevel(0), CategorySSTableData)
 	if v != nil {
 		t.Fatalf("expected not present, but found %#v", v)
 	}
-	v = h2.Get(base.DiskFileNum(0), 0, CategorySSTableData)
+	v = h2.Get(base.DiskFileNum(0), 0, MakeLevel(0), CategorySSTableData)
 	if v := v.RawBuffer(); string(v) != "bbbbb" {
 		t.Fatalf("expected bbbbb, but found %s", v)
 	}
@@ -308,8 +308,9 @@ func BenchmarkCacheGet(b *testing.B) {
 		for pb.Next() {
 			randVal := pcg.Uint64()
 			offset := randVal % size
-			category := Category((randVal >> 32) % uint64(NumCategories))
-			v := h.Get(base.DiskFileNum(0), offset, category)
+			level := Level{levelPlusOne: int8((randVal >> 32) % NumLevels)}
+			category := Category((randVal >> 48) % uint64(NumCategories))
+			v := h.Get(base.DiskFileNum(0), offset, level, category)
 			if v == nil {
 				b.Fatal("failed to look up value")
 			}

internal/cache/clockpro.go

@@ -76,7 +76,7 @@ func (k key) String() string {
 	return fmt.Sprintf("%d/%d/%d", k.id, k.fileNum, k.offset)
 }
 
-type counters [NumCategories]struct {
+type counters [NumLevels][NumCategories]struct {
 	hits   atomic.Int64
 	misses atomic.Int64
 }
@@ -138,7 +138,7 @@ func (c *shard) init(maxSize int64) {
 //
 // If peekOnly is true, the state of the cache is not modified to reflect the
 // access.
-func (c *shard) get(k key, category Category, peekOnly bool) *Value {
+func (c *shard) get(k key, level Level, category Category, peekOnly bool) *Value {
 	c.mu.RLock()
 	if e, _ := c.blocks.Get(k); e != nil {
 		if value := e.acquireValue(); value != nil {
@@ -148,14 +148,14 @@ func (c *shard) get(k key, category Category, peekOnly bool) *Value {
 			}
 			c.mu.RUnlock()
 			if category != CategoryHidden {
-				c.counters[category].hits.Add(1)
+				c.counters[level.index()][category].hits.Add(1)
 			}
 			return value
 		}
 	}
 	c.mu.RUnlock()
 	if category != CategoryHidden {
-		c.counters[category].misses.Add(1)
+		c.counters[level.index()][category].misses.Add(1)
 	}
 	return nil
 }
@@ -165,7 +165,7 @@ func (c *shard) get(k key, category Category, peekOnly bool) *Value {
 // is not in the cache (nil Value), a non-nil readEntry is returned (in which
 // case the caller is responsible to dereference the entry, via one of
 // unrefAndTryRemoveFromMap(), setReadValue(), setReadError()).
-func (c *shard) getWithReadEntry(k key, category Category) (*Value, *readEntry) {
+func (c *shard) getWithReadEntry(k key, level Level, category Category) (*Value, *readEntry) {
 	c.mu.RLock()
 	if e, _ := c.blocks.Get(k); e != nil {
 		if value := e.acquireValue(); value != nil {
@@ -174,13 +174,13 @@ func (c *shard) getWithReadEntry(k key, category Category) (*Value, *readEntry)
 				e.referenced.Store(true)
 			}
 			c.mu.RUnlock()
-			c.counters[category].hits.Add(1)
+			c.counters[level.index()][category].hits.Add(1)
 			return value, nil
 		}
 	}
 	re := c.readShard.acquireReadEntry(k)
 	c.mu.RUnlock()
-	c.counters[category].misses.Add(1)
+	c.counters[level.index()][category].misses.Add(1)
 	return nil, re
 }
 

internal/cache/metrics.go

@@ -6,10 +6,54 @@ package cache
 
 import (
 	"fmt"
+	"iter"
 
 	"github.com/cockroachdb/crlib/crtime"
+	"github.com/cockroachdb/errors"
+	"github.com/cockroachdb/pebble/internal/invariants"
 )
 
+// Level is the LSM level associated with an accessed block. Used to maintain
+// granular cache hit/miss statistics.
+//
+// The zero value indicates that there is no level (e.g. flushable ingests) or
+// it is unknown.
+type Level struct {
+	levelPlusOne int8
+}
+
+func (l Level) String() string {
+	if l.levelPlusOne <= 0 {
+		return "n/a"
+	}
+	return fmt.Sprintf("L%d", l.levelPlusOne-1)
+}
+
+// index returns a value between [0, NumLevels).
+func (l Level) index() int8 {
+	return l.levelPlusOne
+}
+
+func MakeLevel(l int) Level {
+	if invariants.Enabled && (l < 0 || l >= NumLevels-1) {
+		panic(errors.AssertionFailedf("invalid level: %d", l))
+	}
+	return Level{levelPlusOne: int8(l + 1)}
+}
+
+const NumLevels = 1 /* unknown level */ + 7
+
+// Levels is an iter.Seq[Level].
+func Levels(yield func(l Level) bool) {
+	for i := range NumLevels {
+		if !yield(Level{levelPlusOne: int8(i)}) {
+			return
+		}
+	}
+}
+
+var _ iter.Seq[Level] = Levels
+
 // Category is used to maintain granular cache hit/miss statistics.
 type Category int8
 
@@ -68,16 +112,51 @@ type Metrics struct {
 
 // HitsAndMisses contains the number of cache hits and misses across a period of
 // time.
-type HitsAndMisses [NumCategories]struct {
+type HitsAndMisses [NumLevels][NumCategories]struct {
 	Hits   int64
 	Misses int64
 }
 
-// Aggregate returns the total hits and misses across all categories.
+func (hm *HitsAndMisses) Get(level Level, category Category) (hits, misses int64) {
+	v := hm[level.index()][category]
+	return v.Hits, v.Misses
+}
+
+func (hm *HitsAndMisses) Hits(level Level, category Category) int64 {
+	return hm[level.index()][category].Hits
+}
+
+func (hm *HitsAndMisses) Misses(level Level, category Category) int64 {
+	return hm[level.index()][category].Misses
+}
+
+// Aggregate returns the total hits and misses across all categories and levels.
 func (hm *HitsAndMisses) Aggregate() (hits, misses int64) {
-	for i := range *hm {
-		hits += hm[i].Hits
-		misses += hm[i].Misses
+	for i := range hm {
+		for j := range hm[i] {
+			hits += hm[i][j].Hits
+			misses += hm[i][j].Misses
+		}
+	}
+	return hits, misses
+}
+
+// AggregateLevel returns the total hits and misses for a specific level (across
+// all categories).
+func (hm *HitsAndMisses) AggregateLevel(level Level) (hits, misses int64) {
+	for _, v := range hm[level.index()] {
+		hits += v.Hits
+		misses += v.Misses
+	}
+	return hits, misses
+}
+
+// AggregateCategory returns the total hits and misses for a specific category
+// (across all levels).
+func (hm *HitsAndMisses) AggregateCategory(category Category) (hits, misses int64) {
+	for i := range hm {
+		hits += hm[i][category].Hits
+		misses += hm[i][category].Misses
 	}
 	return hits, misses
 }
@@ -86,9 +165,11 @@ func (hm *HitsAndMisses) Aggregate() (hits, misses int64) {
 // current metrics.
 // At a high level, hm.ToRecent(current) means hm = current - hm.
 func (hm *HitsAndMisses) ToRecent(current *HitsAndMisses) {
-	for i := range *hm {
-		hm[i].Hits = current[i].Hits - hm[i].Hits
-		hm[i].Misses = current[i].Misses - hm[i].Misses
+	for i := range hm {
+		for j := range hm[i] {
+			hm[i][j].Hits = current[i][j].Hits - hm[i][j].Hits
+			hm[i][j].Misses = current[i][j].Misses - hm[i][j].Misses
+		}
 	}
 }
 
@@ -116,8 +197,10 @@ func (c *Cache) hitsAndMisses() HitsAndMisses {
 	for i := range c.shards {
 		shardCounters := &c.shards[i].counters
 		for j := range hm {
-			hm[j].Hits += shardCounters[j].hits.Load()
-			hm[j].Misses += shardCounters[j].misses.Load()
+			for k := range hm[j] {
+				hm[j][k].Hits += shardCounters[j][k].hits.Load()
+				hm[j][k].Misses += shardCounters[j][k].misses.Load()
+			}
 		}
 	}
 	return hm

internal/cache/read_shard_test.go

@@ -50,7 +50,7 @@ func newTestReader(
 }
 
 func (r *testReader) getAsync(shard *shard) *string {
-	v, re := shard.getWithReadEntry(r.key, CategorySSTableData)
+	v, re := shard.getWithReadEntry(r.key, MakeLevel(0), CategorySSTableData)
 	if v != nil {
 		str := string(v.RawBuffer())
 		v.Release()
@@ -285,7 +285,7 @@ func TestReadShardConcurrent(t *testing.T) {
 	for _, r := range differentReaders {
 		for j := 0; j < r.numReaders; j++ {
 			go func(r *testSyncReaders, index int) {
-				v, rh, _, _, _, err := r.handle.GetWithReadHandle(context.Background(), r.fileNum, r.offset, CategorySSTableData)
+				v, rh, _, _, _, err := r.handle.GetWithReadHandle(context.Background(), r.fileNum, r.offset, MakeLevel(0), CategorySSTableData)
 				require.NoError(t, err)
 				if v != nil {
 					require.Equal(t, r.val, v.RawBuffer())

level_checker.go

@@ -694,11 +694,15 @@ type valuesInfo struct {
 // each blob.BlockID's referenced blob.BlockValueID for the `i`th blob reference.
 func gatherBlobHandles(
 	ctx context.Context,
+	readEnv block.ReadEnv,
 	r *sstable.Reader,
 	blobRefs manifest.BlobReferences,
 	valueFetcher base.ValueFetcher,
 ) ([]map[blob.BlockID]valuesInfo, error) {
 	iter, err := r.NewPointIter(ctx, sstable.IterOptions{
+		Env: sstable.ReadEnv{
+			Block: readEnv,
+		},
 		BlobContext: sstable.TableBlobContext{
 			ValueFetcher: valueFetcher,
 			References:   &blobRefs,
@@ -797,7 +801,7 @@ func validateBlobValueLiveness(
 			// For this sstable, gather all the blob handles -- tracking
 			// each base.BlobReferenceID + blob.BlockID's referenced
 			// blob.BlockValueIDs.
-			referenced, err := gatherBlobHandles(ctx, r, t.BlobReferences, valueFetcher)
+			referenced, err := gatherBlobHandles(ctx, readEnv.Block, r, t.BlobReferences, valueFetcher)
 			if err != nil {
 				return err
 			}