Track TTA of items on NVM hit as ODS stat

Summary:
Add a percentile stat tracking Time-To-Access (TTA) — how long ago items
were last accessed before being looked up from NVM. This helps understand
working set recency: for each NVM cache hit, how stale the item was when
it was re-accessed.

The `lastAccessTimeSecs` is already stored in Navy's `BlockCache::EntryDesc`
on disk (set during DRAM→NVM eviction) and plumbed through the Navy lookup
path all the way to `NvmCache::onGetComplete()`. No new plumbing is needed.

Changes:
- Declare `nvmHitTTASecs_` PercentileStats field in `detail::Stats`
  (CacheStatsInternal.h).
- Declare `nvmHitTTASecs` Estimates field in `GlobalCacheStats` (CacheStats.h).
- Populate the estimate in `Stats::populateGlobalCacheStats()` and update the
  `EXPECTED_SIZE` compile-time check (CacheStats.cpp).
- Track TTA in `NvmCache::onGetComplete()` after all early-return checks
  confirm a genuine NVM hit. Guarded by `lastAccessTimeSecs > 0` since
  BigHash items don't store access time (NvmCache.h).
- Export via `visitEstimates()` as `nvm.hit_tta_secs` with standard
  percentile suffixes (_p50, _p99, _avg, etc.) (Cache.cpp).

Reviewed By: AlnisM

Differential Revision: D94783700

fbshipit-source-id: 4000027e7c2bd2bfd9eeb448901ddce94a2ffef7

Author: pbhandar2

cachelib/allocator/Cache.cpp

@@ -481,6 +481,8 @@ void CacheBase::updateGlobalCacheStats(const std::string& statPrefix) const {
                    statPrefix + "nvm.make_obj_cb.latency_us");
     visitEstimates(uploadStats, stats.nvmPutSize,
                    statPrefix + "nvm.incoming_item_size_bytes");
+    visitEstimates(uploadStats, stats.nvmHitTTASecs,
+                   statPrefix + "nvm.hit_tta_secs");
 
     if (stats.numNvmDestructorRefcountOverflow > 0) {
       counters_.updateCount(statPrefix + "nvm.destructors.refcount_overflow",

cachelib/allocator/CacheStats.cpp

@@ -54,10 +54,10 @@ struct SizeVerify {};
 void Stats::populateGlobalCacheStats(GlobalCacheStats& ret) const {
 #ifndef SKIP_SIZE_VERIFY
 #ifdef __GLIBCXX__
-#define EXPECTED_SIZE 16736
+#define EXPECTED_SIZE 16912
 #endif
 #ifdef _LIBCPP_VERSION
-#define EXPECTED_SIZE 16736
+#define EXPECTED_SIZE 16912
 #endif
   SizeVerify<sizeof(Stats)> a = SizeVerify<EXPECTED_SIZE>{};
   std::ignore = a;
@@ -125,6 +125,7 @@ void Stats::populateGlobalCacheStats(GlobalCacheStats& ret) const {
       this->nvmEvictionSecondsPastExpiry_.estimate();
   ret.nvmEvictionSecondsToExpiry = this->nvmEvictionSecondsToExpiry_.estimate();
   ret.nvmPutSize = this->nvmPutSize_.estimate();
+  ret.nvmHitTTASecs = this->nvmHitTTASecs_.estimate();
 
   auto accum = [](const PerPoolClassAtomicCounters& c) {
     uint64_t sum = 0;

cachelib/allocator/CacheStats.h

@@ -527,6 +527,7 @@ struct GlobalCacheStats {
   util::PercentileStats::Estimates nvmEvictionSecondsPastExpiry{};
   util::PercentileStats::Estimates nvmEvictionSecondsToExpiry{};
   util::PercentileStats::Estimates nvmPutSize{};
+  util::PercentileStats::Estimates nvmHitTTASecs{};
 
   // time when CacheAllocator structure is created. Whenever a process restarts
   // and even if cache content is persisted, this will be reset. It's similar

cachelib/allocator/CacheStatsInternal.h

@@ -209,6 +209,7 @@ struct Stats {
   mutable util::PercentileStats nvmLargeLifetimeSecs_;
   mutable util::PercentileStats nvmEvictionSecondsPastExpiry_;
   mutable util::PercentileStats nvmEvictionSecondsToExpiry_;
+  mutable util::PercentileStats nvmHitTTASecs_;
 
   // per-pool percentile stats for eviction age
   std::array<util::PercentileStats, MemoryPoolManager::kMaxPools>

cachelib/allocator/nvmcache/NvmCache.h

@@ -1271,9 +1271,6 @@ void NvmCache<C>::onGetComplete(GetCtx& ctx,
                                 HashedKey hk,
                                 navy::BufferView val,
                                 uint32_t lastAccessTimeSecs) {
-  // lastAccessTimeSecs will be used by retention threshold enforcement
-  // in a follow-up diff.
-  (void)lastAccessTimeSecs;
   auto guard =
       folly::makeGuard([&ctx, hk]() { ctx.cache.removeFromFillMap(hk); });
   // navy got disabled while we were fetching. If so, safely return a miss.
@@ -1338,6 +1335,16 @@ void NvmCache<C>::onGetComplete(GetCtx& ctx,
 
   recordEvent(AllocatorApiEvent::NVM_FIND, hk.key(), AllocatorApiResult::FOUND,
               nvmItem);
+
+  // Track NVM hit time-to-access for every NVM hit, regardless of whether
+  // the DRAM promotion succeeds (another thread may have already promoted).
+  // TTA = currentTime - lastAccessTimeSecs (how long ago item was last
+  // accessed). Guard > 0 because BigHash doesn't store access time.
+  if (lastAccessTimeSecs > 0) {
+    auto ttaSecs = util::getCurrentTimeSec() - lastAccessTimeSecs;
+    stats().nvmHitTTASecs_.trackValue(ttaSecs);
+  }
+
   // by the time we filled from navy, another thread inserted in RAM. We
   // disregard.
   if (CacheAPIWrapperForNvm<C>::insertFromNvm(cache_, it)) {

cachelib/allocator/nvmcache/tests/NvmCacheTests.cpp

@@ -2925,6 +2925,49 @@ TEST_F(NvmCacheTest, DataCorruption) {
     EXPECT_EQ(nullptr, it);
   }
 }
+
+TEST_F(NvmCacheTest, NvmHitTTATracking) {
+  // Disable BigHash — it doesn't store lastAccessTimeSecs (returns 0).
+  // BlockCache tracks it, so TTA can be computed.
+  this->config_.bigHash().setSizePctAndMaxItemSize(0, 100);
+  LruAllocator::NvmCacheConfig nvmConfig;
+  nvmConfig.navyConfig = config_;
+  this->allocConfig_.enableNvmCache(nvmConfig);
+  this->makeCache();
+
+  auto& cache = this->cache();
+  auto pid = this->poolId();
+
+  std::string key = "tta_test_key";
+  std::string val = "tta_test_value";
+
+  // 1. Insert item into DRAM
+  {
+    auto it = cache.allocate(pid, key, val.length());
+    ASSERT_NE(nullptr, it);
+    ::memcpy(it->getMemory(), val.data(), val.length());
+    cache.insertOrReplace(it);
+  }
+
+  // 2. Push to NVM and remove from RAM
+  this->pushToNvmCacheFromRamForTesting(key);
+  this->removeFromRamForTesting(key);
+
+  // 3. Wait so TTA (currentTime - lastAccessTimeSecs) > 0
+  /* sleep override */ std::this_thread::sleep_for(std::chrono::seconds(1));
+
+  // 4. Fetch from NVM (triggers onGetComplete -> TTA tracking)
+  auto it = this->fetch(key, false /* ramOnly */);
+  ASSERT_NE(nullptr, it);
+
+  // 5. Verify NVM hit occurred
+  auto stats = this->getStats();
+  EXPECT_GT(stats.numNvmGets, 0);
+  EXPECT_GT(stats.numNvmGets - stats.numNvmGetMiss, 0);
+
+  // 6. Verify TTA was tracked (>= 1 second)
+  EXPECT_GE(stats.nvmHitTTASecs.p50, 1);
+}
 } // namespace tests
 } // namespace cachelib
 } // namespace facebook