feat: /metrics endpoint, cache eviction, and observability fixes #16

2026-05-18T23:14:48+05:30

starkSV commented

2026-05-18 23:14:48 +05:30

(Migrated from github.com)

Summary

/metrics endpoint — auth-protected (METRICS_SECRET env var) JSON endpoint exposing per-endpoint request counts, cache hits, MS fetch counts, neg-cache hits, stale serves, hit rates, and live cache sizes
Cache eviction — cleanupCaches() goroutine runs every 30min, evicts expired SKU/neg entries and link entries past ExpiresAt + 4h stale window — fixes unbounded map growth
Local rand source — package-level rand.Rand replaces global rand to avoid mutex contention at high QPS
Clearer singleflight keys — sfKey separated from negKey in both handlers
Background refresh via singleflight — stale serve triggers a background goroutine that goes through sfGroup.Do, so concurrent stale hits still produce only one Microsoft call
Cleanup logging — only logs when entries are actually evicted

Set up

Add METRICS_SECRET=<strong-value> in Coolify before deploying, then check via:

https://api.msdl.tech-latest.com/metrics?secret=YOUR_SECRET

Example response

{
    "sku":  { "requests": 8, "cache_hits": 6, "ms_fetches": 2, "neg_hits": 0, "hit_rate": "75.0%", "cache_size": 2 },
    "link": { "requests": 3, "cache_hits": 2, "ms_fetches": 1, "neg_hits": 0, "stale": 0, "hit_rate": "66.7%", "cache_size": 1 },
    "eval": { "requests": 3, "cache_hits": 2, "stale": 0, "hit_rate": "66.7%", "cache_size": 5 },
    "neg_cache_size": 0,
    "total_ms_fetches": 3
}

Test plan

Add METRICS_SECRET in Coolify env vars
Deploy and confirm /health passes
Hit GET /metrics?secret=YOUR_SECRET → should return JSON with live counters
Hit /metrics with no secret → 403, wrong secret → 401
Watch Coolify logs — cache cleanup: evicted ... should only appear when entries expire

Summary by CodeRabbit

New Features
- Added metrics endpoint for backend performance monitoring (protected by METRICS_SECRET).
Improvements
- Enhanced cache behavior with stale-on-failure mechanism to serve cached data if fetch fails.
- Optimized performance and reduced contention under concurrent load.
Chores
- Implemented automatic cache cleanup to evict expired entries.

## Summary - **`/metrics` endpoint** — auth-protected (METRICS_SECRET env var) JSON endpoint exposing per-endpoint request counts, cache hits, MS fetch counts, neg-cache hits, stale serves, hit rates, and live cache sizes - **Cache eviction** — `cleanupCaches()` goroutine runs every 30min, evicts expired SKU/neg entries and link entries past ExpiresAt + 4h stale window — fixes unbounded map growth - **Local rand source** — package-level `rand.Rand` replaces global rand to avoid mutex contention at high QPS - **Clearer singleflight keys** — `sfKey` separated from `negKey` in both handlers - **Background refresh via singleflight** — stale serve triggers a background goroutine that goes through `sfGroup.Do`, so concurrent stale hits still produce only one Microsoft call - **Cleanup logging** — only logs when entries are actually evicted ## Set up Add `METRICS_SECRET=<strong-value>` in Coolify before deploying, then check via: ``` https://api.msdl.tech-latest.com/metrics?secret=YOUR_SECRET ``` ## Example response ```json { "sku": { "requests": 8, "cache_hits": 6, "ms_fetches": 2, "neg_hits": 0, "hit_rate": "75.0%", "cache_size": 2 }, "link": { "requests": 3, "cache_hits": 2, "ms_fetches": 1, "neg_hits": 0, "stale": 0, "hit_rate": "66.7%", "cache_size": 1 }, "eval": { "requests": 3, "cache_hits": 2, "stale": 0, "hit_rate": "66.7%", "cache_size": 5 }, "neg_cache_size": 0, "total_ms_fetches": 3 } ``` ## Test plan - [ ] Add `METRICS_SECRET` in Coolify env vars - [ ] Deploy and confirm `/health` passes - [ ] Hit `GET /metrics?secret=YOUR_SECRET` → should return JSON with live counters - [ ] Hit `/metrics` with no secret → 403, wrong secret → 401 - [ ] Watch Coolify logs — `cache cleanup: evicted ...` should only appear when entries expire  ## Summary by CodeRabbit * **New Features** * Added metrics endpoint for backend performance monitoring (protected by METRICS_SECRET). * **Improvements** * Enhanced cache behavior with stale-on-failure mechanism to serve cached data if fetch fails. * Optimized performance and reduced contention under concurrent load. * **Chores** * Implemented automatic cache cleanup to evict expired entries.  [![Review Change Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/starkSV/windows-iso-downloader/pull/16?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)

coderabbitai[bot] commented

2026-05-18 23:14:57 +05:30

(Migrated from github.com)

📝 Walkthrough

Walkthrough

This PR adds internal observability and improves cache resilience to the backend HTTP service. It introduces package-level metrics counters across /skuinfo, /proxy, and /evallinks endpoints; exposes metrics via a new /metrics endpoint; implements periodic cache cleanup; and enhances /proxy stale-on-failure handling with background refresh. The /skuinfo singleflight key is refactored from negative-cache key to a dedicated sku:<product_id> pattern, and global rand is replaced with a package-level instance for concurrent safety in jitter generation.

Changes

Metrics and Cache Resilience

Layer / File(s)	Summary
RNG and metric counter infrastructure `backend/main.go` (lines 19–29, 98–119, 164)	Package-level `rand.Rand` instance seeded at startup; atomic counter variables for request volume, cache hits, negative-cache hits, fetches, and stale serves across three endpoints; jitter function updated to use package-level RNG.
Metrics endpoint handler and cache eviction `backend/main.go` (lines 945–1070)	`cleanupCaches()` function periodically evicts expired SKU, link, and negative-cache entries; `/metrics` handler authenticates via `METRICS_SECRET`, reports atomic counter values, computes hit rates, and exposes cache sizes in Prometheus-like plaintext format.
SKU info endpoint monitoring and singleflight optimization `backend/main.go` (lines 699–730, 765)	Negative-cache-hit, cache-hit, and fetch metrics integrated; singleflight deduplication key changed from negative-cache key to dedicated `sku:<product_id>` key with result struct wrapper.
Link proxy endpoint monitoring and stale-on-failure background refresh `backend/main.go` (lines 790, 800, 812–847, 881)	Request, cache-hit, negative-cache-hit, fetch, and stale-serve metrics added; stale-on-failure flow reworked to serve stale cache immediately, increment stale metric, and trigger deduped background refresh that re-fetches, recalculates TTL, and updates link cache.
Eval links endpoint monitoring `backend/main.go` (lines 902–908)	Request and cache-hit metrics integrated for `/evallinks` endpoint.
Main function integration `backend/main.go` (lines 1089–1097)	Cache cleanup coroutine and `/metrics` route registered in `main()` alongside existing session cleanup and eval cache warmup.

Poem

🐰 A rabbit hops through caches bright,
Metrics gathered, stale served right,
Background refreshes deduplicate the load,
Observability lights the Kubernetes road! 🚀

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main changes: adding a /metrics endpoint, implementing cache eviction, and improving observability. All three components align with the actual changeset.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/metrics

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.12.2)

level=error msg="[linters_context] typechecking error: pattern ./...: directory prefix . does not contain main module or its selected dependencies"

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

<details> <summary>📝 Walkthrough</summary> ## Walkthrough This PR adds internal observability and improves cache resilience to the backend HTTP service. It introduces package-level metrics counters across `/skuinfo`, `/proxy`, and `/evallinks` endpoints; exposes metrics via a new `/metrics` endpoint; implements periodic cache cleanup; and enhances `/proxy` stale-on-failure handling with background refresh. The `/skuinfo` singleflight key is refactored from negative-cache key to a dedicated `sku:<product_id>` pattern, and global `rand` is replaced with a package-level instance for concurrent safety in jitter generation. ## Changes **Metrics and Cache Resilience** |Layer / File(s)|Summary| |---|---| |**RNG and metric counter infrastructure** `backend/main.go` (lines 19–29, 98–119, 164)|Package-level `rand.Rand` instance seeded at startup; atomic counter variables for request volume, cache hits, negative-cache hits, fetches, and stale serves across three endpoints; jitter function updated to use package-level RNG.| |**Metrics endpoint handler and cache eviction** `backend/main.go` (lines 945–1070)|`cleanupCaches()` function periodically evicts expired SKU, link, and negative-cache entries; `/metrics` handler authenticates via `METRICS_SECRET`, reports atomic counter values, computes hit rates, and exposes cache sizes in Prometheus-like plaintext format.| |**SKU info endpoint monitoring and singleflight optimization** `backend/main.go` (lines 699–730, 765)|Negative-cache-hit, cache-hit, and fetch metrics integrated; singleflight deduplication key changed from negative-cache key to dedicated `sku:<product_id>` key with result struct wrapper.| |**Link proxy endpoint monitoring and stale-on-failure background refresh** `backend/main.go` (lines 790, 800, 812–847, 881)|Request, cache-hit, negative-cache-hit, fetch, and stale-serve metrics added; stale-on-failure flow reworked to serve stale cache immediately, increment stale metric, and trigger deduped background refresh that re-fetches, recalculates TTL, and updates link cache.| |**Eval links endpoint monitoring** `backend/main.go` (lines 902–908)|Request and cache-hit metrics integrated for `/evallinks` endpoint.| |**Main function integration** `backend/main.go` (lines 1089–1097)|Cache cleanup coroutine and `/metrics` route registered in `main()` alongside existing session cleanup and eval cache warmup.| ## Poem > 🐰 *A rabbit hops through caches bright,* > *Metrics gathered, stale served right,* > *Background refreshes deduplicate the load,* > *Observability lights the Kubernetes road!* 🚀 🎯 3 (Moderate) | ⏱️ ~25 minutes </details>   <details> <summary>🚥 Pre-merge checks | ✅ 4 | ❌ 1</summary> ### ❌ Failed checks (1 warning) | Check name | Status | Explanation | Resolution | | :----------------: | :--------- | :------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------- | | Docstring Coverage | ⚠️ Warning | Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%. | Write docstrings for the functions missing them to satisfy the coverage threshold. | <details> <summary>✅ Passed checks (4 passed)</summary> | Check name | Status | Explanation | | :------------------------: | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Description Check | ✅ Passed | Check skipped - CodeRabbit’s high-level summary is enabled. | | Title check | ✅ Passed | The title clearly and concisely summarizes the main changes: adding a /metrics endpoint, implementing cache eviction, and improving observability. All three components align with the actual changeset. | | Linked Issues check | ✅ Passed | Check skipped because no linked issues were found for this pull request. | | Out of Scope Changes check | ✅ Passed | Check skipped because no linked issues were found for this pull request. | </details> ✏️ Tip: You can configure your own custom pre-merge checks in the settings. </details>   <details> <summary>✨ Finishing Touches</summary> <details> <summary>📝 Generate docstrings</summary> - [ ]  Create stacked PR - [ ]  Commit on current branch </details> <details> <summary>🧪 Generate unit tests (beta)</summary> - [ ]  Create PR with unit tests - [ ]  Commit unit tests in branch `feat/metrics` </details> </details>   > [!WARNING] > There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. > > <details> > <summary>🔧 golangci-lint (2.12.2)</summary> > > level=error msg="[linters_context] typechecking error: pattern ./...: directory prefix . does not contain main module or its selected dependencies" > > > > > </details>   --- Comment `@coderabbitai help` to get the list of available commands and usage tips.

coderabbitai[bot] (Migrated from github.com) reviewed 2026-05-18 23:17:59 +05:30

coderabbitai[bot] (Migrated from github.com) left a comment

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@backend/main.go`:
- Around line 831-847: The background refresh inside the goroutine (the
sfGroup.Do closure that calls fetchDownloadLinksFromMS) updates linkCache on
success but never increments the mLinkFetches metric; after a successful fetch
and cache update (i.e., after linkCache[cacheKey] = ... and before returning
nil), increment the mLinkFetches counter the same way you do for foreground
fetches (e.g., atomic.AddInt64(&mLinkFetches, 1) or the existing metric helper)
so /metrics reflects these background Microsoft API calls.
- Around line 26-28: The package-level rng (var rng = rand.New(...)) is being
used concurrently by jitter(), causing a data race because rand.Rand is not
goroutine-safe; either guard rng with a sync.Mutex (add a mutex variable and
lock/unlock around all accesses to rng inside jitter() and any other uses) or
replace uses of rng in jitter() with the global, thread-safe rand functions
(e.g., rand.Int63n) and remove the package-level rng; update references to
rng/jitter() accordingly to eliminate unsynchronized access.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 659481bd-0af9-4bb5-b443-92890b7ad5c3

📥 Commits

Reviewing files that changed from the base of the PR and between 3329cd1b52 and 90c498233b.

📒 Files selected for processing (1)

backend/main.go

**Actionable comments posted: 2** <details> <summary>🤖 Prompt for all review comments with AI agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. Inline comments: In `@backend/main.go`: - Around line 831-847: The background refresh inside the goroutine (the sfGroup.Do closure that calls fetchDownloadLinksFromMS) updates linkCache on success but never increments the mLinkFetches metric; after a successful fetch and cache update (i.e., after linkCache[cacheKey] = ... and before returning nil), increment the mLinkFetches counter the same way you do for foreground fetches (e.g., atomic.AddInt64(&mLinkFetches, 1) or the existing metric helper) so /metrics reflects these background Microsoft API calls. - Around line 26-28: The package-level rng (var rng = rand.New(...)) is being used concurrently by jitter(), causing a data race because rand.Rand is not goroutine-safe; either guard rng with a sync.Mutex (add a mutex variable and lock/unlock around all accesses to rng inside jitter() and any other uses) or replace uses of rng in jitter() with the global, thread-safe rand functions (e.g., rand.Int63n) and remove the package-level rng; update references to rng/jitter() accordingly to eliminate unsynchronized access. ``` </details> <details> <summary>🪄 Autofix (Beta)</summary> Fix all unresolved CodeRabbit comments on this PR: - [ ]  Push a commit to this branch (recommended) - [ ]  Create a new PR with the fixes </details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro Plus **Run ID**: `659481bd-0af9-4bb5-b443-92890b7ad5c3` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 3329cd1b52ac5dc7c2ed625b715fafc2955798f6 and 90c498233bc85602e282ff5d3a44b66f82b16a3a. </details> <details> <summary>📒 Files selected for processing (1)</summary> * `backend/main.go` </details> </details>

backend/main.go

					
				@ -24,1 +25,4 @@

				// Package-level rand source — avoids global mutex contention under concurrent load.

				// Go 1.20+ auto-seeds the global rand, but a local source is faster at high QPS.

				var rng = rand.New(rand.NewSource(time.Now().UnixNano()))

coderabbitai[bot] (Migrated from github.com) commented

2026-05-18 23:17:58 +05:30

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

🧩 Analysis chain

🌐 Web query:

Is Go rand.Rand safe for concurrent use?

💡 Result:

No, instances of rand.Rand are not safe for concurrent use [1][2]. According to the official Go documentation, both the rand.Rand type and the underlying rand.Source type must be used by only a single goroutine at a time [1][2]. If you need to share a random number generator across multiple goroutines, you must implement your own synchronization, such as using a sync.Mutex to guard access to the rand.Rand instance [3][4]. In contrast, the top-level functions provided by the math/rand package (such as rand.Float64 and rand.Int) are safe for concurrent use because they utilize a global, synchronized source [1][5]. If you require a cryptographically secure random number generator that is safe for concurrent use, you should use the crypto/rand package, which provides a global, thread-safe reader [6].

Citations:

🏁 Script executed:

# Check the jitter() function definition and usage
grep -n "func jitter" backend/main.go