CNDB-15360 Chunk Cache inspection #2140

lesnik2u · 2025-11-24T10:39:37Z

What is the issue

https://github.com/riptano/cndb/issues/15360

What does this PR fix and why was it fixed

This PR adds the ability to inspect hot and cold entries in ChunkCache to better understand cache dynamics and identify which files and sections are most useful for caching.

Changes

New ChunkCache methods:

Added inspectEntries() method to iterate over cache entries ordered by access frequency
Added InspectEntriesOrder enum (HOTTEST/COLDEST) to specify ordering by access frequency
Added ChunkCacheInspectionEntry class containing file, position, and size metadata for each cached chunk
Leverages Caffeine's policy().eviction().hottest()/coldest() APIs to efficiently retrieve ordered entries without materializing full cache in memory
Consumer pattern avoids creating large in-memory lists

Use Cases

Identify which files/sections benefit most from caching vs. eviction candidates
Compare access patterns between different file types (partition index vs. data, SAI token files vs. kdtree files)
Debug cache efficiency and inform cache sizing decisions
Complement predictive caching metrics with lower-level cache behavior insights

Testing

Added comprehensive parameterized unit tests covering:

Multiple files with different limits
Both HOTTEST and COLDEST ordering
Edge cases (empty cache, zero limit, disabled cache)
Verification that all cached files appear when limit exceeds cache size

github-actions · 2025-11-24T10:39:56Z

eolivelli

I have left a couple of suggestions, you are on your way.

Let's add unit tests, there are some tests about ChunkCache, you can add them there.

We don't really care about the implementation of Caffeine, you will hardly have a deterministic behavior for ordering, for the unit tests it is just enough to ensure that if there is something that it is returned correctly, in any order

src/java/org/apache/cassandra/cache/ChunkCache.java

test/unit/org/apache/cassandra/cache/ChunkCacheTest.java

src/java/org/apache/cassandra/cache/ChunkCache.java

eolivelli · 2025-12-01T15:52:07Z

src/java/org/apache/cassandra/cache/ChunkCache.java

    private long assignFileId(File file)
    {
-        return nextFileId.getAndIncrement();
+        long id = nextFileId.getAndIncrement();


nit: revert unneeded change

eolivelli · 2025-12-01T15:53:58Z

src/java/org/apache/cassandra/cache/ChunkCache.java

+     * @param limit    maximum number of entries to inspect
+     * @param consumer consumer to process each entry
+     */
+    public void inspectHotEntries(int limit, java.util.function.Consumer<ChunkCacheInspectionEntry> consumer)


why do we have 2 methods ?

can't we keep the boolean parameter ?
if you have two methods I guess that on the caller site you will have some "if (hottest) inspectHotEntries else inspectColdEntries" and you have to unroll this

src/java/org/apache/cassandra/cache/ChunkCache.java

eolivelli · 2025-12-01T15:57:31Z

src/java/org/apache/cassandra/cache/ChunkCache.java

+        // We need to shift right to extract just the File ID portion by discarding the lower bits
+        int shift = CHUNK_SIZE_LOG2_BITS + READER_TYPE_BITS;
+
+        synchronousCache.policy().eviction().ifPresent(policy -> {


if there is no eviction policy we should throw and exception, because there is no concept of "hot" or "cold"

This it not going to happen, so you can simply add a precondition

src/java/org/apache/cassandra/cache/ChunkCache.java

test/unit/org/apache/cassandra/cache/ChunkCacheTest.java

eolivelli · 2025-12-02T11:28:04Z

test/unit/org/apache/cassandra/cache/ChunkCacheTest.java

+    }
+
+    @Test
+    public void testInspectEntriesWithLimit() throws IOException


you can put this into the parametrizedtest

public static Stream<Argument> testInspectEntriesValues() { return ..... Arguments.of(CacheOrder.HOTTEST, 10), Arguments.of(CacheOrder.HOTTEST, 2).... } @ParametrizedTest vood testInspectEntries(CacheOrder order, int limit)

Had to put tests in separate class because in Junit4 for test's to be parameterised the entire class has to run with Parameterised.class

eolivelli · 2025-12-04T16:04:17Z

src/java/org/apache/cassandra/cache/ChunkCache.java

-        implements RemovalListener<ChunkCache.Key, ChunkCache.Chunk>, CacheSize
+import java.util.Map;
+
+public class ChunkCache implements RemovalListener<ChunkCache.Key, ChunkCache.Chunk>, CacheSize


let's not reformat code we don't touch, if not really useful

eolivelli · 2025-12-04T16:05:24Z

src/java/org/apache/cassandra/cache/ChunkCache.java

+    /**
+     * Defines the ordering strategy for cache entries during inspection.
+     */
+    public enum CacheOrder


InspectEntriesOrder ?

eolivelli · 2025-12-04T16:05:37Z

src/java/org/apache/cassandra/cache/ChunkCache.java

+     */
+    public enum CacheOrder
+    {
+        /** Orders cache entries from most frequently accessed to least */


style ? missing new lines

eolivelli · 2025-12-04T16:07:56Z

test/unit/org/apache/cassandra/cache/ChunkCacheInspectEntriesTest.java

+    public void testInspectEntriesWithEmptyCache()
+    {
+        logger.info("Testing inspect entries with empty cache for order={}", order);
+        ChunkCache.instance.clear();


is there any particular reason to not using a "new ChunkCache" in each test ?

eolivelli · 2025-12-04T16:08:28Z

test/unit/org/apache/cassandra/cache/ChunkCacheTest.java


        try (FileHandle.Builder builder1 = new FileHandle.Builder(file).withChunkCache(ChunkCache.instance))
        {
-             try (FileHandle handle1 = builder1.complete();


is this only removing blank lines?

Yes, I've overlooked this

…e a new chunkCache for every test

eolivelli

Overall LGTM

I have left a minor comment about Files.write.

eolivelli · 2025-12-05T12:26:25Z

test/unit/org/apache/cassandra/cache/ChunkCacheInspectEntriesTest.java

+            {
+                File file = FileUtils.createTempFile("test" + i, null);
+                file.deleteOnExit();
+                writeBytes(file, new byte[RandomAccessReader.DEFAULT_BUFFER_SIZE]);


nit: you can use Files.write(file.toPath() .... )

sonarqubecloud · 2025-12-05T15:33:04Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
83.3% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

cassci-bot · 2025-12-05T15:37:24Z

❌ Build ds-cassandra-pr-gate/PR-2140 rejected by Butler

2 regressions found
See build details here

Found 2 new test failures

Test	Explanation	Runs	Upstream
o.a.c.index.sai.cql.VectorCompaction100dTest.testOneToManyCompaction[eb true]	NEW	🔴⚪	0 / 19
o.a.c.index.sai.cql.VectorSiftSmallTest.testCompaction[ca false]	REGRESSION	🔴⚪	0 / 19

Found 3 known test failures

jasonstack · 2025-12-12T03:42:11Z

src/java/org/apache/cassandra/cache/ChunkCache.java

+
+            // Look up the File by searching through fileIdMap entries
+            File file = null;
+            for (Map.Entry<File, Long> entry : fileIdMap.entrySet())


The overall time complexity would be: O (N * F) where N is the num of cache entries and F is num of files in cache..

Should we build a temporary Map<Long, File> above to cache the reversed mappings once? This will save some CPU cycles. Time complexity would be O(N + F)

lesnik2u changed the title ~~[WIP] CNDB-15360 Chunk Cache inspection~~ [WIP] CNDB-15360 Chunk Cache inspection POC Nov 24, 2025

lesnik2u marked this pull request as ready for review November 26, 2025 11:42

eolivelli requested changes Nov 26, 2025

View reviewed changes

lesnik2u added 2 commits November 28, 2025 14:05

CNDB-15360: ChunkCache hot and cold inspection POC

cdcac40

CNDB-15360: added unit test coverage for inspection methods

1c9a057

lesnik2u force-pushed the CNDB-15360-ChunkCache branch from 1fa7663 to 1c9a057 Compare November 28, 2025 13:05

eolivelli requested changes Nov 28, 2025

View reviewed changes

src/java/org/apache/cassandra/cache/ChunkCache.java Outdated Show resolved Hide resolved

test/unit/org/apache/cassandra/cache/ChunkCacheTest.java Outdated Show resolved Hide resolved

lesnik2u added 2 commits December 1, 2025 16:49

CNDB-15360: Removed the flaky "hotness" test and focus on data validity

17f7a1b

CNDB-15360: Remove unnecessary/unwanted reverse map

1cdb563

lesnik2u changed the title ~~[WIP] CNDB-15360 Chunk Cache inspection POC~~ CNDB-15360 Chunk Cache inspection POC Dec 1, 2025

lesnik2u commented Dec 1, 2025

View reviewed changes

src/java/org/apache/cassandra/cache/ChunkCache.java Outdated Show resolved Hide resolved

eolivelli requested changes Dec 1, 2025

View reviewed changes

CNDB-15360: fixes from git review

abf97b6

lesnik2u force-pushed the CNDB-15360-ChunkCache branch from b236ad5 to abf97b6 Compare December 1, 2025 16:52

CNDB-15360: fixes nit making enum public

b58bdd1

eolivelli requested changes Dec 2, 2025

View reviewed changes

lesnik2u added 2 commits December 3, 2025 11:09

CNDB-15360: Simplified inspection method

b0d6ea2

CNDB-15360: Changed tests to be parameterized

cc6d3b3

eolivelli reviewed Dec 4, 2025

View reviewed changes

lesnik2u changed the title ~~CNDB-15360 Chunk Cache inspection POC~~ CNDB-15360 Chunk Cache inspection Dec 4, 2025

lesnik2u added 2 commits December 5, 2025 11:05

CNDB-15360: Changed to inspectEntriesOrder and changed tests to creat…

7f0c12c

…e a new chunkCache for every test

CNDB-15360: nit style

ea3ae23

eolivelli approved these changes Dec 5, 2025

View reviewed changes

CNDB-15360: Simplified test logic

40adb60

jasonstack reviewed Dec 12, 2025

View reviewed changes

CNDB-15360 Chunk Cache inspection #2140

Are you sure you want to change the base?

CNDB-15360 Chunk Cache inspection #2140

Uh oh!

Conversation

lesnik2u commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is the issue

What does this PR fix and why was it fixed

Changes

Use Cases

Testing

Uh oh!

github-actions bot commented Nov 24, 2025

Checklist before you submit for review

Uh oh!

eolivelli left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eolivelli left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud bot commented Dec 5, 2025

Quality Gate passed

Uh oh!

cassci-bot commented Dec 5, 2025

❌ Build ds-cassandra-pr-gate/PR-2140 rejected by Butler

Found 2 new test failures

Found 3 known test failures

Uh oh!

jasonstack Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

lesnik2u commented Nov 24, 2025 •

edited

Loading

jasonstack Dec 12, 2025 •

edited

Loading