Validate Spring Boot Upgrades with Traffic Replay
TL;DR
Spring Boot version upgrades, whether moving from 2.x to 3.x, 3.x to 4.x, or even minor bumps like 3.2.5 to 3.3.1, regularly introduce subtle, breaking changes that unit and integration tests miss. JSON serialization shifts, autoconfiguration reordering, and transitive dependency conflicts can silently alter your API contract. In this post, you’ll learn how to use Speedscale traffic replay to record production traffic on your current Spring Boot version, replay it against the upgraded build, and check captured paths for response differences before release.
What makes Spring Boot upgrades more dangerous than they appear
Spring Boot’s convention-over-configuration philosophy and aggressive dependency management mean that a version bump can ripple through your application in unexpected ways. Release notes and migration guides cover the obvious breaking changes, but the silent ones, changes that don’t throw exceptions or fail tests, are the ones that reach production.
JSON and serialization drift
Spring Boot upgrades can change the managed Jackson version and application configuration. Check the exact dependency graph and serialization setup rather than assuming a particular minor upgrade changes every application. The Spring Boot JSON reference describes the supported mapper configuration; the 4.0 migration guide explains the Jackson 3 transition.
| Issue | Example | Root cause |
|---|---|---|
| Optional serialization fails | InvalidDefinitionException at runtime | Mapper or module configuration differs |
| Field naming change | createdAt → created_at | Jackson property naming / config change |
| Numeric format change | 1250.0 → 1250 | Serialization default changes |
| Date format change | Timestamp vs ISO-8601 string | Jackson 2→3 or config drift |
| Null handling | null vs omitted field | @JsonInclude or module behavior change |
Autoconfiguration and transitive dependencies
Adding or upgrading dependencies can change which autoconfiguration conditions match. Review the managed dependency tree and condition evaluation report. Spring Boot 4 also reorganizes modules, so follow the official migration guide rather than relying on a fixed module count.
Removed and relocated APIs
Spring Boot 4 removes Undertow (Servlet 6.1 incompatibility), drops Pulsar Reactive, and eliminates embedded executable JAR launch scripts. Spring Boot 2→3 migrates javax.* to jakarta.* for the migrated Jakarta EE APIs, javax.persistence, javax.validation, javax.annotation.PostConstruct, requiring bulk import updates. Elasticsearch’s RestClient is replaced with Rest5Client. Review removed test integrations and the migration guide’s recommended replacements. Null-safety tooling migrates from spring-lang to JSpecify, affecting static null-safety analysis and source compatibility.
Compile-time breaks are obvious. Runtime differences in replacement libraries, behavioral quirks, edge cases, performance characteristics, are not.
Property and configuration changes
spring-boot-properties-migrator helps with renamed properties, but not every change is covered. Actuator security moved from management.security.* in 1.x to Spring Security integration in 2.x+. Health endpoint behavior, endpoint exposure, and role-based visibility have all evolved. Micrometer and OpenTelemetry modules have been reorganized in Spring Boot 4, with property naming changes. Configuration that “just worked” can silently change behavior across versions.
Why traffic replay is the right tool for the job
Existing testing methodologies are insufficient for Spring Boot upgrades:
- Unit tests exercise your code logic, not the framework’s serialization, autoconfiguration order, or dependency-injected behavior. A Jackson upgrade that changes
Optionalserialization won’t be caught unless you explicitly assert on that output. - Integration tests typically use synthetic or fixture data. They rarely cover the full shape of production requests, weird query params, optional headers, malformed-but-accepted inputs, or the exact JSON structures your clients send.
- Manual testing doesn’t scale and can’t cover the combinatorial explosion of API paths, headers, and payloads that production sees.
Traffic replay captures real production traffic, supported captured API calls and downstream exchanges. Replaying that traffic against your upgraded Spring Boot build gives you a response diff using your configured assertions: exactly which responses changed, in which fields, and by how much. Review the configured comparisons and add tests for paths absent from the recording.
Speedscale makes this practical by:
- Recording supported traffic, inbound and outbound, at the network level with the eBPF collector, with verified TLS and Java-agent coverage
- Mocking backend dependencies so you can replay traffic without a full staging environment
- Automatically diffing responses between the baseline and the upgraded build
- Integrating into CI/CD so you can gate Spring Boot upgrades on passing replay tests
Step-by-step: Validating your Spring Boot upgrade with Speedscale
Prerequisites
- Kubernetes cluster with your Spring Boot application deployed on the current version
- Speedscale operator installed
speedctlCLI installed locally- Application deployed as Kubernetes Deployment, StatefulSet, or DaemonSet
Step 1: Instrument your current deployment for recording
Install the operator and collector, check the Java-agent compatibility matrix, and enable capture for the workload. Supported JVM capture requires the Java agent, new pods, and a JVM restart. Inspect decoded inbound and outbound exchanges; eBPF alone does not decode every Java TLS transport.
Let the instrumented deployment run under representative production traffic:
- API services: A few hours during peak traffic
- Batch processors: At least one full batch cycle
- Event-driven services: A period covering all event varieties
Step 2: Create a snapshot
From the Speedscale UI or CLI, create a snapshot from the captured traffic:
# Replace cluster and namespace with your source environment.
speedctl create snapshot --name migration-baseline \
--cluster SOURCE_CLUSTER --namespace SOURCE_NAMESPACE \
--service my-spring-service --start 30m --end 25m
Review the snapshot to ensure it includes the API patterns, payload shapes, and edge cases you care about.
Step 3: Build and deploy your upgraded Spring Boot image
Upgrade your Spring Boot version in pom.xml or build.gradle, resolve any compile-time breaks (e.g., javax → jakarta), and build a new image. Deploy it to a staging or test namespace.
Step 4: Replay the snapshot against the upgraded deployment
Replay the baseline snapshot against your upgraded Spring Boot deployment:
# Use the snapshot ID and reviewed test-configuration ID from Speedscale.
speedctl infra replay --snapshot-id SNAPSHOT_ID \
--cluster TEST_CLUSTER --namespace staging --service my-spring-service \
--test-config-id TEST_CONFIG_ID
Speedscale replays inbound traffic to your app and mocks outbound dependencies with recorded responses.
LLM prompt for this step
Create a snapshot for the real source service and replay it against the upgraded deployment in the selected test cluster and namespace. Use the reviewed test-configuration ID, wait for the actual report to complete, and compare the candidate with the baseline.
Step 5: Analyze the replay report
In the Speedscale UI, inspect:
Response correctness: Compare response bodies field-by-field. Look for:
| Symptom | Likely cause |
|---|---|
| Field name changes | Jackson property naming, config change |
Optional / null handling differences | Jackson module or databind version |
| Date/numeric format changes | Serialization defaults |
| Missing or extra fields | Autoconfiguration, @JsonInclude |
| 500s on previously working paths | Removed API, autoconfig conflict |
Latency: Compare p50/p95/p99. Framework upgrades can change startup cost, connection pooling, or async behavior.
Error rate: Filter by status code. Requests that succeeded on the old version may fail on the new one.
Step 6: Fix, rebuild, replay, iterate until clean
For each regression:
- Diagnose: Use the RRPair diff to see the exact expected vs actual response
- Fix: Adjust configuration (e.g., register
Jdk8Module), update code, or align property names - Rebuild: Push a new image
- Replay: Run the same snapshot again
Repeat until the replay report is clean.
Step 7: Gate your CI/CD pipeline
Once validated, add replay tests to your CI/CD so future Spring Boot upgrades are continuously checked against the same traffic baseline. See the Speedscale CI/CD integration guide for GitHub Actions, GitLab CI, Jenkins, and more.
Using proxymock for local validation
You can validate the upgrade locally before deploying to a cluster using proxymock. For a deeper comparison of local replay tools, see mitmproxy vs. proxymock. See the proxymock getting started guide for setup.
Note: The instructions below handle inbound traffic only. If your service makes outbound calls to databases, APIs, or other services, you may need custom CLI parameters or environment variables to reliably capture that traffic. See the proxymock docs for proxy configuration and outbound capture.
Record with the baseline runtime
Install and initialize proxymock, then follow the Java proxy and truststore setup. Use a known application route in the example below:
proxymock admin certs --jks
proxymock record --app-port 8080 --out ./proxymock/migration-baseline \
-- java -jar my-spring-service.jar
Send representative requests through port 4143, then stop the recorder and application. Direct JVM launch lets the wrapper set HTTP proxy and truststore properties. Database clients and custom transports may require additional configuration.
LLM prompt for this step
Prepare proxymock trust settings for my local baseline Java runtime, record the Spring Boot app on port 8080 into proxymock/migration-baseline, and exercise the representative request set through the recorder.
Replay against the candidate runtime
Select the candidate JDK in the application terminal and start the application with the recorded mocks:
proxymock mock --in ./proxymock/migration-baseline --no-passthrough \
-- java -jar my-spring-service.jar
In another terminal, replay the saved inputs against port 8080:
proxymock replay --in ./proxymock/migration-baseline \
--test-against http://localhost:8080 \
--out ./proxymock/results/migration-candidate \
--fail-if 'requests.result-match-pct < 100'
Inspect observed responses and replay-verdict.json. The example gate checks the response assertion match percentage; also configure a baseline/body regression gate for compatibility checks. --no-passthrough controls calls reaching the mock, so enforce routing separately. Mocked TLS responses do not validate negotiation with the actual provider.
LLM prompt for this step
Run the upgraded Spring Boot app using only recorded dependencies from proxymock/migration-baseline. Replay the preserved inbound requests against port 8080, keep candidate results separate, enforce supported mismatch gates, and report behavior and timing differences.
Upgrade checklist
Before considering the Spring Boot upgrade complete:
- All API endpoints produce identical response bodies, or intentional differences are documented
- JSON field names, formats, and null handling match the baseline
- Latency p99 is within acceptable variance
- No new 4xx/5xx errors on previously successful paths
- Database queries and cache behavior are unchanged
- Actuator and health endpoints behave as expected
- Autoconfiguration and transitive dependencies are verified
- Replay tests are integrated into CI/CD as a regression gate
Run this workflow with an LLM
Give this prompt to a coding assistant with access to your project and this article. Supply environment-specific values it cannot discover.
Whole-workflow LLM prompt
Read https://speedscale.com/blog/spring-boot-migration-traffic-replay-validation/ and inspect my project instructions first. Validate my Spring Boot upgrade using one preserved workload and explicit before/after runtime versions. Choose the cluster snapshot or local proxymock path, retain the reviewed baseline, and compare response semantics, authentication, errors, and latency against equivalent dependency state before deployment. Check installed tool help before adapting commands. Report the checks actually run, their results, and anything you could not verify.
Conclusion
Spring Boot upgrades are necessary to stay current with security patches and features, but they introduce risk at every layer, Jackson, autoconfiguration, transitive dependencies, and removed APIs. Unit and integration tests often pass while production breaks because the bytes on the wire have changed.
Traffic replay turns upgrade validation into a deterministic process: record production traffic on the current version, replay it against the upgraded build, and diff the results. The result covers only the captured inputs and configured assertions. And once the upgrade is complete, the same pattern protects you from regressions in every future release. If you’re tempted to build your own replay harness, read about the scaling pitfalls first.
Resources
- Speedscale documentation
- Speedscale CI/CD integration
- proxymock quickstart
- Spring Boot 4.0 Migration Guide
- Spring Boot 3.3 Release Notes
Frequently asked questions
Which upgrade failures can traffic replay expose?
Replay can reveal changed status codes, JSON fields, authentication behavior, and errors on the captured paths after a Spring Boot upgrade. It cannot cover unrecorded inputs, prove every background task works, or replace compilation and framework migration checks. Follow the migration notes for every skipped release and add targeted tests for the changes they identify.
How do I keep dependencies and input data comparable?
Use the same reviewed traffic fixture for both builds and define which dependencies are mocked. Reset any live test database or cache to a known state and supply valid test credentials. For JVM capture, verify the Java agent’s coverage; for local proxy capture, configure the actual HTTP or database client rather than assuming Java routes every call automatically.
How do I distinguish an intentional response change from a regression?
Compare each difference with the intended contract and the upgrade notes. Preserve strict checks on business fields, and scope transforms to genuinely variable values such as fresh tokens. Document approved differences and update expectations in review. Do not broadly ignore fields or regenerate the baseline from the candidate merely to obtain a passing run.
Sources: Spring Boot upgrade guidance, Spring Boot 4.0 migration guide, Local regression-testing workflow, Configure dependency mocks, Java agent setup and compatibility, Java with proxymock, Replay verdicts and CI gates.