-
Notifications
You must be signed in to change notification settings - Fork 1
Caching
Statfyr caches API responses in memory to reduce repeated stat lookups and keep performance consistent under load.
When a request is made for a player's stats or a leaderboard, Statfyr fetches the data, serves the response, and stores a cached copy. Subsequent requests for the same data are served from cache until the TTL expires.
A background refresh process runs on a configurable interval to proactively update stale cache entries before they expire.
cache:
ttl-seconds: 60
refresh-seconds: 10| Key | Default | Description |
|---|---|---|
ttl-seconds |
60 |
How long (in seconds) a cached entry remains valid |
refresh-seconds |
10 |
How often the cache checks for and refreshes stale entries |
- Cache is in-memory — it does not persist across restarts
- Each unique request URL is cached separately (e.g.
/api/player/Steveand/api/player/Steve?summary=falseare separate cache entries) - The
metadata.generated_atandmetadata.execution_time_msfields in responses reflect when the data was last generated, not when it was served from cache
| Scenario | Suggested Config |
|---|---|
| Live dashboard, near-real-time updates |
ttl: 10, refresh: 5
|
| Standard leaderboard site |
ttl: 60, refresh: 10 (default) |
| Low-traffic, infrequent polling |
ttl: 300, refresh: 60
|
| Very high traffic, many players |
ttl: 120, refresh: 30
|
Lowering ttl-seconds gives fresher data but increases stat read frequency. Raising it reduces load but data will be more stale.
Caching works alongside the async loader (async.enabled: true). Stats are always fetched off the main thread, so cache misses do not cause TPS spikes. The combined effect is:
- Cache hit → instant response, no stat read needed
- Cache miss → async stat fetch, response served and cached
- Background refresh → cache stays warm, future requests always hit
Next: Commands & Permissions