Caching & Performance Tuning

Most often: @EnableCaching is missing, the call is a self-invocation (bypasses the proxy), the method is private/final or the class is not a Spring bean, or the key changes on each call.

@Service
class PriceService {
    @Cacheable("prices")
    public Price get(String sku) { ... }
    public Price wrapper(String sku) { return get(sku); } // cache bypassed
}

• Fix self-invocation by moving the cached method to another bean, or by AspectJ mode (mode = ASPECTJ).
• Verify with a cache hit/miss log or CacheManager.getCache("prices").get(key).

SimpleKeyGenerator: no args -> SimpleKey.EMPTY, one arg -> that arg, several -> SimpleKey of all args. Objects without a proper equals/hashCode never match; mutable objects mutated after caching confuse lookups.

• Declare keys explicitly with SpEL: key = "#userId + ':' + #locale", key = "#root.methodName + #p0".
• Two methods sharing a cache name with the same argument collide (both keyed by 1L). Use separate cache names or include the method name in the key.
• Redis keys are serialized; make sure the key class serializes deterministically (use Strings).

By default Spring caches null (Caffeine and the default Redis config store a null placeholder). A "not found" result is then served from cache, so a later insert is invisible until eviction or TTL. If Redis is configured with disableCachingNullValues(), returning null from a @Cacheable method without an unless guard throws IllegalArgumentException.

• Don't cache nulls: @Cacheable(value = "users", unless = "#result == null").
• Deliberate negative caching protects the DB against repeated misses (cache-penetration attack), but use a short TTL.
• Return Optional and Spring unwraps it, caching the contained value.

Evict or update the entry on every write path using the same cache and key.

@CacheEvict(value = "users", key = "#user.id")
public User update(User user) { ... }

@CachePut(value = "users", key = "#result.id")
public User create(User u) { ... }

• @CachePut always executes the method and stores the result; do not combine with @Cacheable on the same method.
• Eviction happens after the method returns (or beforeInvocation = true) but not necessarily after the transaction commits; a concurrent reader can repopulate stale data between evict and commit.
• Writes bypassing the service (other apps, SQL scripts) are not seen.

Caffeine is an in-process cache: nanosecond access, no serialization, but per-instance (copies differ across pods, invalidation does not propagate) and bounded by heap. Redis is shared and external: consistent across instances, survives restarts, bigger capacity, but adds a network hop (~0.3-1 ms) and serialization.

• Common pattern: two-level cache; short-TTL Caffeine (L1) in front of Redis (L2), with pub/sub invalidation.
• Use Caffeine for immutable reference data and hot lookups; Redis for session-like shared state, rate limiting, cross-instance consistency.
• Always set maximumSize/expireAfterWrite on Caffeine; unbounded caches are memory leaks.

Boot's spring.cache.caffeine.spec applies one spec to all caches; for different TTLs register CaffeineCache instances by name. Redis TTL is set per cache in RedisCacheManager.

@Bean
RedisCacheManager cacheManager(RedisConnectionFactory cf) {
    var defaults = RedisCacheConfiguration.defaultCacheConfig()
        .entryTtl(Duration.ofMinutes(10)).disableCachingNullValues();
    return RedisCacheManager.builder(cf).cacheDefaults(defaults)
        .withCacheConfiguration("prices", defaults.entryTtl(Duration.ofSeconds(30)))
        .build();
}

• spring.cache.redis.time-to-live sets a global default; there is no TTL by default (entries never expire).
• Caffeine expireAfterWrite vs expireAfterAccess: the latter lets hot keys live forever and go stale.

A cache stampede (thundering herd). Mitigate so that one caller recomputes while others wait or use stale data.

• @Cacheable(sync = true) makes Spring lock per key so only one thread loads (local to the JVM; Caffeine supports it natively, Redis does not coordinate across instances).
• Caffeine refreshAfterWrite with LoadingCache serves the old value while refreshing asynchronously.
• TTL jitter (random +/- 10%) avoids mass expiry at the same moment.
• Distributed lock (Redis SET NX PX) or request coalescing for cross-instance protection; probabilistic early refresh.

Use cache-aside: read from cache, on miss load and put; on write update DB first then delete (not update) the key. Race: reader loads old value from DB, writer updates and deletes, reader then writes the old value, leaving stale data until TTL.

• Mitigations: short TTL as a backstop, delayed double-delete, versioned values (reject older version), or CDC (Debezium) driven invalidation from the DB log.
• Write-through/write-behind make the cache the front door but add complexity and data-loss risk (write-behind).
• Accept eventual consistency and document the staleness window; do not cache data that needs strong consistency (balances).

Threads hold connections longer than they should, or demand exceeds the pool. Find leaks and long holds before increasing size.

• Enable leakDetectionThreshold (e.g. 20000 ms) to log stack traces of connections held too long.
• Causes: long transactions wrapping remote HTTP calls, OSIV holding connections during serialization, unclosed streams, REQUIRES_NEW nested connection needs, slow queries, locks waiting.
• Metrics: hikaricp.connections.active/pending/usage/acquire via Micrometer.
• Sizing guideline: pool ≈ cores * 2 + effective spindles is small (10 to 30); a bigger pool often worsens DB contention.

Defaults (max 10, minIdle = max) are generally good. Key settings:

spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 20          # fixed-size pool recommended
      connection-timeout: 3000  # fail fast
      max-lifetime: 1500000     # < DB/LB idle kill (25 min)
      idle-timeout: 600000
      leak-detection-threshold: 20000

• max-lifetime must be shorter than any DB or network device connection timeout (MySQL wait_timeout, cloud LB idle timeout) to avoid "connection reset" errors.
• With many instances, total connections = instances * pool size; check against the DB's max_connections (PgBouncer helps).
• Set statement/transaction timeouts too (spring.jpa.properties.jakarta.persistence.query.timeout, @Transactional(timeout)).

Threads are blocked on I/O (DB, HTTP calls, locks), not computing. Take a thread dump (jcmd <pid> Thread.print) and see what http-nio-*-exec-* threads wait on.

• Defaults: server.tomcat.threads.max=200, accept-count=100. Raising max just moves the queue; fix slow dependencies, add timeouts (connect/read) on every client and bulkheads/circuit breakers (Resilience4j).
• Pool sizing for CPU-bound: ~cores; for blocking: cores * (1 + wait/compute).
• Java 21: spring.threads.virtual.enabled=true (Boot 3.2+) lets blocking calls scale, but the DB pool and downstream capacity remain bottlenecks, and synchronized pinning applies before JDK 24.

Without a custom executor, Boot auto-configures ThreadPoolTaskExecutor (core 8, unbounded queue, applicationTaskExecutor); an unbounded queue hides overload and grows memory. With @EnableAsync but self-invocation, the method runs synchronously.

@Bean
ThreadPoolTaskExecutor reportExecutor() {
    var e = new ThreadPoolTaskExecutor();
    e.setCorePoolSize(4); e.setMaxPoolSize(8);
    e.setQueueCapacity(100);
    e.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
    e.setThreadNamePrefix("report-");
    return e;
}

• Max threads only grow beyond core after the queue is full.
• Exceptions in void @Async methods are lost unless an AsyncUncaughtExceptionHandler is set; return CompletableFuture to propagate.
• Security and MDC context are not propagated to new threads without a TaskDecorator.

Return Cache-Control and validators so clients and CDNs skip or revalidate.

@GetMapping("/products/{id}")
ResponseEntity<ProductDto> get(@PathVariable long id) {
    var p = service.get(id);
    return ResponseEntity.ok()
        .cacheControl(CacheControl.maxAge(Duration.ofMinutes(5)).cachePublic())
        .eTag(String.valueOf(p.version()))
        .body(p);
}

• ShallowEtagHeaderFilter computes ETags from the body: saves bandwidth (304) but not server work.
• If-None-Match handling with request.checkNotModified(etag) avoids building the body.
• Authenticated responses should use private or no-store; Spring Security adds Cache-Control: no-cache, no-store by default for secured responses.
• Add Vary headers for content negotiation (Accept-Encoding, Accept-Language).

Enable response compression (server.compression.enabled=true, min-response-size, mime types), trim payloads (DTOs, pagination, sparse fields), and use HTTP/2.

• Compression costs CPU; often better done at the reverse proxy/CDN.
• Avoid compressing already-compressed content and avoid compressing secrets mixed with attacker-controlled input (BREACH) without mitigations.
• Jackson settings: omit nulls, use @JsonView or projections.

Tail latency comes from queuing, GC pauses, slow dependencies, lock contention or cold paths. Correlate by tracing and metrics before changing code.

• Distributed tracing (Micrometer Tracing + OpenTelemetry) breaks a slow request down by span (DB, HTTP).
• GC logs (-Xlog:gc*) or JFR (jcmd <pid> JFR.start) for pauses and allocation hot spots; async-profiler for CPU/wall-clock flame graphs.
• Check pool saturation (Hikari pending, Tomcat busy), DB slow query log, retries, and noisy neighbours.
• Look at percentiles per endpoint (http.server.requests histogram with management.metrics.distribution.percentiles-histogram).

Common flaws: closed-model load (users wait for responses, hiding overload; use open-model arrival rate), coordinated omission (stalls not counted), small dataset (cached data), warmless JVM (no JIT warm-up), test client as bottleneck, missing think time/mix, and a non-prod-sized DB.

• Tools: k6, Gatling, JMeter; use constant arrival rate and ramp to saturation, watch error rates and queue growth.
• Realistic data volume and distribution (Zipf hot keys) matter for caches and plans.
• Test with the same pool sizes and resource limits (container CPU quotas change thread/GC ergonomics).

A coarse cache entry (the whole list) becomes stale on any change, so you either evict everything on each write (low hit rate) or serve stale lists. Use per-entity caching plus ID lists, or @CacheEvict(allEntries = true) for rarely written reference data.

• Cached collections are mutable; callers modifying the returned list corrupt the cache with in-memory providers (Caffeine returns the same instance). Return immutable copies.
• Cache DTOs, not managed JPA entities (detached, lazy proxies break outside sessions).

Use condition (checked before call, with args) and unless (checked after, with #result).

@Cacheable(value = "reports", key = "#userId",
           condition = "#premium", unless = "#result.isEmpty()")
public List<Row> report(long userId, boolean premium) { ... }

• If condition is false, the cache is neither read nor written.
• unless only vetoes writes; the lookup still happens.

Pre-warm: after the job, repopulate keys (@CachePut or cache.put) in batches, or switch to a LoadingCache with refreshAfterWrite so reads serve stale data while a background refresh runs. Avoid allEntries eviction during peak traffic.

• Warm-up at startup (ApplicationReadyEvent) avoids cold-start spikes after deploys, but delay readiness until done only if needed.
• For Redis, use versioned key namespaces (prices:v42:), flip a pointer to the new version, and let old keys expire.

With OSIV on, a connection stays checked out after the service transaction ends until the response is rendered, so slow clients or serializers extend hold time and pool utilization. Turning it off shortens hold time to the transaction itself, raising throughput on the same pool.

• Combine with short transactions: do remote calls outside @Transactional.
• Measure hikaricp.connections.usage (time a connection is held) before and after.

Large payloads, reflection on big graphs, and creating ObjectMapper per call (costly) show up in flame graphs. Reuse the Boot-managed mapper, return slim DTOs, stream large results (StreamingResponseBody, NDJSON), and paginate.

• Register the Afterburner/Blackbird module for faster access on older JDKs; avoid pretty printing in production.
• Avoid double serialization (string JSON stored in a cache then parsed again).

Include tenant (and user where needed) in the key so entries never cross tenants: key = "#tenantId + ':' + #id". A cache keyed only by entity ID can leak another tenant's data, a data-breach class bug.

• Prefer a KeyGenerator that reads the tenant from the security/tenant context so developers cannot forget it.
• Separate Redis key prefixes per tenant allow targeted eviction and quotas.
• Never cache authorization decisions longer than permissions can change without an invalidation.

Hit ratio, load latency, eviction count and size. With Boot, Actuator exposes cache.gets{result=hit|miss}, cache.puts, cache.evictions; Caffeine requires recordStats() (spring.cache.caffeine.spec=maximumSize=1000,recordStats).

• Low hit ratio (<50%) with high keys cardinality means the cache wastes memory; consider a different granularity or drop it.
• Compare end-to-end latency, not just hit ratio.

Cached JSON/Java-serialized values contain the old class structure or type ids (@class); after a refactor (renamed package, changed fields, or deserialized LinkedHashMap instead of the DTO) old entries cannot be read, or are returned as maps and fail on cast.

• Version your cache key prefix with the schema/app version (app:v3:), or flush on incompatible deploys.
• Prefer records with explicit typed serializers (Jackson2JsonRedisSerializer<T>) per cache.
• Handle deserialization failures via CacheErrorHandler by treating them as a miss.

It has no eviction, TTL, size bound, stats or stampede protection; it grows until OutOfMemoryError and is inconsistent across instances. Use Caffeine with maximumSize and expiry.

• computeIfAbsent holds bin locks while computing, blocking other keys in the same bin and failing on recursive updates.
• It is fine for tiny static lookup tables built at startup.