problemspans: add data structure

Package problemspans provides functionality for tracking and managing
key spans that have been identified as problematic. It allows users to
add spans with associated expiration times, check if a given key range
overlaps any active (non-expired) spans, and remove spans when issues
are resolved.

Author: RaduBerinde

go.mod

@@ -3,6 +3,7 @@ module github.com/cockroachdb/pebble
 require (
 	github.com/DataDog/zstd v1.5.7
 	github.com/HdrHistogram/hdrhistogram-go v1.1.2
+	github.com/RaduBerinde/axisds v0.0.0-20250405232732-ecb85bedf677
 	github.com/cespare/xxhash/v2 v2.2.0
 	github.com/cockroachdb/crlib v0.0.0-20241112164430-1264a2edc35b
 	github.com/cockroachdb/datadriven v1.0.3-0.20250407164829-2945557346d5
@@ -38,6 +39,7 @@ require (
 	github.com/getsentry/sentry-go v0.27.0 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
 	github.com/golang/protobuf v1.5.3 // indirect
+	github.com/google/btree v1.1.3 // indirect
 	github.com/inconshreveable/mousetrap v1.0.0 // indirect
 	github.com/kr/text v0.2.0 // indirect
 	github.com/mattn/go-runewidth v0.0.9 // indirect

go.sum

@@ -10,6 +10,8 @@ github.com/GoogleCloudPlatform/cloudsql-proxy v0.0.0-20190129172621-c8b1d7a94ddf
 github.com/HdrHistogram/hdrhistogram-go v1.1.2 h1:5IcZpTvzydCQeHzK4Ef/D5rrSqwxob0t8PQPMybUNFM=
 github.com/HdrHistogram/hdrhistogram-go v1.1.2/go.mod h1:yDgFjdqOqDEKOvasDdhWNXYg9BVp4O+o5f6V/ehm6Oo=
 github.com/OneOfOne/xxhash v1.2.2/go.mod h1:HSdplMjZKSmBqAxg5vPj2TmRDmfkzw+cTzAElWljhcU=
+github.com/RaduBerinde/axisds v0.0.0-20250405232732-ecb85bedf677 h1:NofOMIO/Z3301wDc9gIM/M0/+YjvOYSvUe7+30bkxkA=
+github.com/RaduBerinde/axisds v0.0.0-20250405232732-ecb85bedf677/go.mod h1:YO26VdZg1RVVjEhjmeEJE/4bLnD2mowj5eDiZQSLtlE=
 github.com/aclements/go-gg v0.0.0-20170118225347-6dbb4e4fefb0/go.mod h1:55qNq4vcpkIuHowELi5C8e+1yUHtoLoOUR9QU5j7Tes=
 github.com/aclements/go-moremath v0.0.0-20210112150236-f10218a38794 h1:xlwdaKcTNVW4PtpQb8aKA4Pjy0CdJHEqvFbAnvR5m2g=
 github.com/aclements/go-moremath v0.0.0-20210112150236-f10218a38794/go.mod h1:7e+I0LQFUI9AXWxOfsQROs9xPhoJtbsyWcjJqDd4KPY=
@@ -104,6 +106,8 @@ github.com/gonum/internal v0.0.0-20181124074243-f884aa714029/go.mod h1:Pu4dmpkhS
 github.com/gonum/lapack v0.0.0-20181123203213-e4cdc5a0bff9/go.mod h1:XA3DeT6rxh2EAE789SSiSJNqxPaC0aE9J8NTOI0Jo/A=
 github.com/gonum/matrix v0.0.0-20181209220409-c518dec07be9/go.mod h1:0EXg4mc1CNP0HCqCz+K4ts155PXIlUywf0wqN+GfPZw=
 github.com/google/btree v1.0.0/go.mod h1:lNA+9X1NB3Zf8V7Ke586lFgjr2dZNuvo3lPJSGZ5JPQ=
+github.com/google/btree v1.1.3 h1:CVpQJjYgC4VbzxeGVHfvZrv1ctoYCAI8vbl07Fcxlyg=
+github.com/google/btree v1.1.3/go.mod h1:qOPhT0dTNdNzV6Z/lhRX0YXUafgPLFUh+gZMl761Gm4=
 github.com/google/go-cmp v0.2.0/go.mod h1:oXzfMopK8JAjlY9xF4vHSVASa0yLyX7SntLO5aqRK0M=
 github.com/google/go-cmp v0.5.4/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=

internal/problemspans/by_level.go

@@ -0,0 +1,117 @@
+// Copyright 2025 The LevelDB-Go and Pebble Authors. All rights reserved. Use
+// of this source code is governed by a BSD-style license that can be found in
+// the LICENSE file.
+
+package problemspans
+
+import (
+	"fmt"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/cockroachdb/crlib/crstrings"
+	"github.com/cockroachdb/crlib/crtime"
+	"github.com/cockroachdb/pebble/internal/base"
+)
+
+// ByLevel maintains a set of spans (separated by LSM level) with expiration
+// times and allows checking for overlap against active (non-expired) spans.
+//
+// When the spans added to the set are not overlapping, all operations are
+// logarithmic.
+//
+// ByLevel is safe for concurrent use.
+type ByLevel struct {
+	empty  atomic.Bool
+	mu     sync.Mutex
+	levels []Set
+}
+
+// Init must be called before using the ByLevel.
+func (bl *ByLevel) Init(numLevels int, cmp base.Compare) {
+	bl.empty.Store(false)
+	bl.levels = make([]Set, numLevels)
+	for i := range bl.levels {
+		bl.levels[i].Init(cmp)
+	}
+}
+
+// InitForTesting is used by tests which mock the time source.
+func (bl *ByLevel) InitForTesting(numLevels int, cmp base.Compare, nowFn func() crtime.Mono) {
+	bl.empty.Store(false)
+	bl.levels = make([]Set, numLevels)
+	for i := range bl.levels {
+		bl.levels[i].init(cmp, nowFn)
+	}
+}
+
+// IsEmpty returns true if there are no problem spans (the "normal" case). It
+// can be used in fast paths to avoid checking for specific overlaps.
+func (bl *ByLevel) IsEmpty() bool {
+	if bl.empty.Load() {
+		// Fast path.
+		return true
+	}
+	bl.mu.Lock()
+	defer bl.mu.Unlock()
+	for i := range bl.levels {
+		if !bl.levels[i].IsEmpty() {
+			return false
+		}
+	}
+	bl.empty.Store(true)
+	return true
+}
+
+// Add a span on a specific level. The span automatically expires after the
+// given duration.
+func (bl *ByLevel) Add(level int, bounds base.UserKeyBounds, expiration time.Duration) {
+	bl.mu.Lock()
+	defer bl.mu.Unlock()
+	bl.empty.Store(false)
+	bl.levels[level].Add(bounds, expiration)
+}
+
+// Overlaps returns true if any active (non-expired) span on the given level
+// overlaps the given bounds.
+func (bl *ByLevel) Overlaps(level int, bounds base.UserKeyBounds) bool {
+	if bl.empty.Load() {
+		// Fast path.
+		return false
+	}
+	bl.mu.Lock()
+	defer bl.mu.Unlock()
+	return bl.levels[level].Overlaps(bounds)
+}
+
+// Excise a span from all levels. Any overlapping active (non-expired) spans are
+// split or trimmed accordingly.
+func (bl *ByLevel) Excise(bounds base.UserKeyBounds) {
+	bl.mu.Lock()
+	defer bl.mu.Unlock()
+	for i := range bl.levels {
+		bl.levels[i].Excise(bounds)
+	}
+}
+
+// String prints all active (non-expired) span fragments.
+func (bl *ByLevel) String() string {
+	bl.mu.Lock()
+	defer bl.mu.Unlock()
+	var buf strings.Builder
+
+	for i := range bl.levels {
+		if !bl.levels[i].IsEmpty() {
+			fmt.Fprintf(&buf, "L%d:\n", i)
+			for _, line := range crstrings.Lines(bl.levels[i].String()) {
+				fmt.Fprintf(&buf, "  %s\n", line)
+			}
+		}
+	}
+	if buf.Len() == 0 {
+		return "<empty>"
+	}
+	return buf.String()
+}

internal/problemspans/by_level_test.go

@@ -0,0 +1,93 @@
+// Copyright 2025 The LevelDB-Go and Pebble Authors. All rights reserved. Use
+// of this source code is governed by a BSD-style license that can be found in
+// the LICENSE file.
+
+package problemspans
+
+import (
+	"bytes"
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/cockroachdb/crlib/crstrings"
+	"github.com/cockroachdb/crlib/crtime"
+	"github.com/cockroachdb/datadriven"
+	"github.com/cockroachdb/pebble/internal/base"
+	"github.com/stretchr/testify/require"
+)
+
+func TestByLevel(t *testing.T) {
+	const numLevels = 7
+	now := crtime.Mono(0)
+	nowFn := func() crtime.Mono { return now }
+	var byLevel ByLevel
+	byLevel.InitForTesting(numLevels, base.DefaultComparer.Compare, nowFn)
+
+	datadriven.RunTest(t, "testdata/by_level", func(t *testing.T, td *datadriven.TestData) string {
+		var nowStr string
+		if td.MaybeScanArgs(t, "now", &nowStr) {
+			var nowVal int
+			if n, err := fmt.Sscanf(nowStr, "%ds", &nowVal); err != nil || n != 1 {
+				td.Fatalf(t, "error parsing now %q: %v", nowStr, err)
+			}
+			v := crtime.Mono(time.Duration(nowVal) * time.Second)
+			if v < now {
+				td.Fatalf(t, "now cannot go backwards")
+			}
+			now = v
+		}
+
+		var out bytes.Buffer
+		switch td.Cmd {
+
+		case "add":
+			for _, line := range crstrings.Lines(td.Input) {
+				parts := strings.SplitN(line, " ", 2)
+				require.Equalf(t, 2, len(parts), "%s", line)
+				var level int
+				_, err := fmt.Sscanf(parts[0], "L%d", &level)
+				require.NoError(t, err)
+				bounds, expiration := parseSetLine(parts[1], true /* withTime */)
+				// The test uses absolute expiration times.
+				byLevel.Add(level, bounds, expiration.Sub(now))
+			}
+
+		case "excise":
+			for _, line := range crstrings.Lines(td.Input) {
+				bounds, _ := parseSetLine(line, false /* withTime */)
+				byLevel.Excise(bounds)
+			}
+
+		case "overlap":
+			for _, line := range crstrings.Lines(td.Input) {
+				parts := strings.SplitN(line, " ", 2)
+				require.Equal(t, 2, len(parts))
+				var level int
+				_, err := fmt.Sscanf(parts[0], "L%d", &level)
+				require.NoError(t, err)
+				bounds, _ := parseSetLine(parts[1], false /* withTime */)
+				res := "overlap"
+				if !byLevel.Overlaps(level, bounds) {
+					res = "no overlap"
+				}
+				fmt.Fprintf(&out, "%s: %s\n", bounds, res)
+			}
+
+		case "is-empty":
+			if byLevel.IsEmpty() {
+				out.WriteString("empty\n")
+			} else {
+				out.WriteString("not empty\n")
+			}
+		default:
+			td.Fatalf(t, "unknown command %q", td.Cmd)
+		}
+		out.WriteString("ByLevel:\n")
+		for _, l := range crstrings.Lines(byLevel.String()) {
+			fmt.Fprintf(&out, "  %s\n", l)
+		}
+		return out.String()
+	})
+}

internal/problemspans/doc.go

@@ -0,0 +1,28 @@
+// Copyright 2025 The LevelDB-Go and Pebble Authors. All rights reserved. Use
+// of this source code is governed by a BSD-style license that can be found in
+// the LICENSE file.
+
+// Package problemspans provides functionality for tracking and managing key
+// spans that have been identified as problematic. It allows users to add spans
+// with associated expiration times, check if a given key range overlaps any
+// active (non-expired) spans, and remove spans when issues are resolved.
+//
+// This package is designed for efficiently tracking key ranges that may need
+// special handling.
+//
+// Key Features:
+//
+//   - **Span Registration:**
+//     Add spans with specified expiration times so that they automatically
+//     become inactive after a set duration.
+//
+//   - **Overlap Detection:**
+//     Quickly check if a key range overlaps with any active problematic spans.
+//
+//   - **Span Excise:**
+//     Remove or adjust spans to reflect changes as issues are resolved.
+//
+//   - **Level-Based Organization:**
+//     The package offers a structure to organize and manage problematic spans
+//     per level, with built-in support for concurrent operations.
+package problemspans

internal/problemspans/set.go

@@ -0,0 +1,122 @@
+// Copyright 2025 The LevelDB-Go and Pebble Authors. All rights reserved. Use
+// of this source code is governed by a BSD-style license that can be found in
+// the LICENSE file.
+
+package problemspans
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/RaduBerinde/axisds"
+	"github.com/RaduBerinde/axisds/regiontree"
+	"github.com/cockroachdb/crlib/crtime"
+	"github.com/cockroachdb/pebble/internal/base"
+)
+
+// Set maintains a set of spans with expiration times and allows checking for
+// overlap against non-expired spans.
+//
+// When the spans added to the set are not overlapping, all operations are
+// logarithmic.
+//
+// Set is not safe for concurrent use.
+type Set struct {
+	cmp   base.Compare
+	nowFn func() crtime.Mono
+
+	now crtime.Mono
+
+	// We use a region tree with key boundaries and the expirationTime as a
+	// property.
+	rt regiontree.T[axisds.Endpoint[[]byte], expirationTime]
+}
+
+// expirationTime of a problem span. 0 means that there is no problem span in a
+// region. Expiration times <= Set.now are equivalent to 0.
+type expirationTime crtime.Mono
+
+// Init must be called before a Set can be used.
+func (s *Set) Init(cmp base.Compare) {
+	s.init(cmp, crtime.NowMono)
+}
+
+func (s *Set) init(cmp base.Compare, nowFn func() crtime.Mono) {
+	*s = Set{}
+	s.cmp = cmp
+	s.nowFn = nowFn
+	// The region tree supports a property equality function that "evolves" over
+	// time, in that some properties that used to not be equal become equal. In
+	// our case expired properties become equal to 0.
+	//
+	// Note that the region tree automatically removes boundaries between two
+	// regions that have expired, even during enumeration.
+	propEqFn := func(a, b expirationTime) bool {
+		return a == b ||
+			crtime.Mono(a) <= s.now && crtime.Mono(b) <= s.now // Both are expired or 0.
+	}
+	endpointCmp := axisds.EndpointCompareFn(axisds.CompareFn[[]byte](cmp))
+	s.rt = regiontree.Make(endpointCmp, propEqFn)
+}
+
+func boundsToEndpoints(bounds base.UserKeyBounds) (start, end axisds.Endpoint[[]byte]) {
+	start = axisds.MakeStartEndpoint(bounds.Start, axisds.Inclusive)
+	end = axisds.MakeEndEndpoint(bounds.End.Key, axisds.InclusiveIf(bounds.End.Kind == base.Inclusive))
+	return start, end
+}
+
+// Add a span to the set. The span automatically expires after the given duration.
+func (s *Set) Add(bounds base.UserKeyBounds, expiration time.Duration) {
+	s.now = s.nowFn()
+	expTime := expirationTime(s.now + crtime.Mono(expiration))
+	start, end := boundsToEndpoints(bounds)
+	s.rt.Update(start, end, func(p expirationTime) expirationTime {
+		return max(p, expTime)
+	})
+}
+
+// Overlaps returns true if the bounds overlap with a non-expired span.
+func (s *Set) Overlaps(bounds base.UserKeyBounds) bool {
+	s.now = s.nowFn()
+	start, end := boundsToEndpoints(bounds)
+	return s.rt.AnyWithGC(start, end, func(exp expirationTime) bool {
+		return crtime.Mono(exp) > s.now
+	})
+}
+
+// Excise removes a span fragment from all spans in the set. Any overlapping
+// non-expired spans are cut accordingly.
+func (s *Set) Excise(bounds base.UserKeyBounds) {
+	s.now = s.nowFn()
+	start, end := boundsToEndpoints(bounds)
+	s.rt.Update(start, end, func(p expirationTime) expirationTime {
+		return 0
+	})
+}
+
+// IsEmpty returns true if the set contains no non-expired spans.
+func (s *Set) IsEmpty() bool {
+	s.now = s.nowFn()
+	return s.rt.IsEmpty()
+}
+
+// String prints all active (non-expired) span fragments.
+func (s *Set) String() string {
+	var buf strings.Builder
+	s.now = s.nowFn()
+	s.rt.EnumerateAll(func(start, end axisds.Endpoint[[]byte], prop expirationTime) bool {
+		fmt.Fprintf(&buf, "%s  expires in: %s\n", keyEndpointIntervalFormatter(start, end), time.Duration(prop)-time.Duration(s.now))
+		return true
+	})
+	if buf.Len() == 0 {
+		return "<empty>"
+	}
+	return buf.String()
+}
+
+var keyBoundaryFormatter axisds.BoundaryFormatter[[]byte] = func(b []byte) string {
+	return string(b)
+}
+
+var keyEndpointIntervalFormatter = axisds.MakeEndpointIntervalFormatter(keyBoundaryFormatter)