Skip to content

fix(cache): add structured debug log for each cache eviction (#737) - #749

Merged
Chucks1093 merged 1 commit into
accesslayerorg:mainfrom
Alaka-ibr:fix/cache-eviction-structured-log-737
Aug 23, 2026
Merged

fix(cache): add structured debug log for each cache eviction (#737)#749
Chucks1093 merged 1 commit into
accesslayerorg:mainfrom
Alaka-ibr:fix/cache-eviction-structured-log-737

Conversation

@Alaka-ibr

Copy link
Copy Markdown
Contributor

Closes #737

The in-memory creator list cache evicts entries on TTL expiry and capacity overflow, but neither case was logged with the structured fields needed to tune cache size and TTL in production. This PR adds a debug-level structured log at each eviction site with a consistent field schema.

Changes

src/modules/creators/creators.cache.ts

  • TTL expiry eviction (both the prune loop and the stale-on-read path in getCachedCreatorList): now logs with reason: 'ttl_expired' and includes cache_key, cache_size_after, and evicted_at.
  • Capacity overflow eviction in pruneCreatorListCache: now logs with reason: 'capacity_overflow' and includes the same fields.
  • The delete() call is performed before the log statement so cache_size_after reflects the post-eviction map size.
  • All eviction logs are emitted at debug level, suppressed at the default info level in production.

src/modules/creators/creators-cache-eviction-log.test.ts [NEW]

Seven unit tests covering all four acceptance criteria:

Test Criteria
emits debug log with reason ttl_expired when a stale entry is read TTL expiry fields
cache_size_after reflects the size after eviction post-eviction size
evicted_at is a valid ISO 8601 timestamp timestamp format
log level is debug log level
emits debug log with reason capacity_overflow when cache exceeds max entries overflow fields
cache_size_after reflects the size after the overflow eviction post-eviction size
evicted_at is a valid ISO 8601 timestamp on overflow eviction timestamp format

Log schema

{
  "msg": "Creator list cache eviction",
  "event": "creator_list_cache_eviction",
  "cache_key": "creators:limit=20:offset=0:sort=createdAt:order=desc",
  "reason": "ttl_expired | capacity_overflow",
  "cache_size_after": 249,
  "evicted_at": "2026-08-23T20:59:00.000Z"
}

@Alaka-ibr
Alaka-ibr force-pushed the fix/cache-eviction-structured-log-737 branch from cbb178c to 0103df1 Compare August 23, 2026 22:53
…ayerorg#737)

Emit a debug-level structured log on every in-memory cache eviction with
the fields required by the acceptance criteria:

- cache_key: the evicted entry's key
- reason: 'ttl_expired' or 'capacity_overflow'
- cache_size_after: map size read after the delete call
- evicted_at: ISO 8601 timestamp at eviction time

The stale-on-read path in getCachedCreatorList is a TTL expiry variant
and now logs with reason 'ttl_expired' instead of the previous 'stale'.
The delete is performed before the log call so cache_size_after reflects
the post-eviction size as specified.
@Alaka-ibr
Alaka-ibr force-pushed the fix/cache-eviction-structured-log-737 branch from 0103df1 to be3430a Compare August 23, 2026 22:55
@Alaka-ibr

Copy link
Copy Markdown
Contributor Author

Done with this, please review

@Chucks1093

Copy link
Copy Markdown
Member

LGTM!

@Chucks1093
Chucks1093 merged commit 0c940b8 into accesslayerorg:main Aug 23, 2026
1 check passed
@Chucks1093

Copy link
Copy Markdown
Member

This is a very clean implementation. Adding the structured debug logs with the eviction reason and cache size after deletion will make production debugging so much easier going forward.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add structured log for each cache eviction including the evicted key, reason, and cache size at eviction time

2 participants