Traffic Replay Tutorial: Capture, Replay, Read Results

A traffic replay is useful when it answers a specific question: did a code change alter how this service responds to requests it has already handled? Start with one service, a small slice of recorded traffic, and a test workload. You can expand the test once you know what a clean replay looks like.

This tutorial uses Speedscale Cloud with a Kubernetes workload. You will inspect captured requests, run them against a separate workload, and read the replay report. If your app runs only on your laptop, use the proxymock local development guide instead. For the broader concepts, see our traffic replay guide.

The flow has three parts: capture traffic from a running service, replay a slice of it against a separate test workload with dependencies mocked, and read the report to decide whether a change is a regression.

flowchart LR
    A[Service receiving traffic] -->|eBPF capture| B[Traffic Viewer]
    B -->|select one endpoint| C[Snapshot]
    C -->|replay requests| D[Test workload]
    C -->|mock outbound calls| D
    D --> E[Replay report]
    E -->|regression or setup issue| F[Fix and replay again]

What you need

You need a Speedscale account, access to a Kubernetes cluster with the Speedscale Operator installed, and a service receiving API traffic. You also need a separate development or test deployment of that service to replay against. Do not point the first replay at a production workload: generated requests can change data or load a service, and outbound calls may need isolation.

For a disposable application, use the Speedscale demo tutorial. It includes an example service and a client that generates traffic. If you already have a service recording traffic, use that instead. In either case, confirm that you can see the service in the Speedscale Traffic Viewer before continuing.

Current Kubernetes installations should use the eBPF collector when their nodes and workloads meet its requirements. The older version of this article walked through injecting proxy sidecars into every demo pod. Sidecar capture is now a fallback for environments where eBPF is unsuitable, so follow the current installation guide rather than those old steps.

If you are capturing real customer traffic, configure data loss prevention and capture filters before recording sensitive fields. A test cluster is not a reason to copy credentials or personal data into a snapshot.

1. Find a useful slice of traffic

Open the service in the Speedscale Traffic Viewer. Set a short time window and filter down to requests for one endpoint or one behavior you want to protect. A small, repeatable sample is easier to diagnose than an hour of unrelated traffic. Exclude health checks and other background noise.

Open a request/response pair and check both directions. The inbound request is what replay will send to your service. The outbound calls are candidates for mocks, so your test can exercise the service without calling every real dependency. If the selected traffic includes login, changing timestamps, generated IDs, or stateful operations, note that now. Those details often explain an apparent failure later.

You do not have to create a snapshot in a separate, earlier wizard. The current replay flow creates a reusable snapshot from the selected traffic. You can inspect and tune that snapshot after the first run.

2. Run your first traffic replay

Select Replay in the Traffic Viewer. First choose the target cluster and namespace. Use a separate development or test deployment of the service, and check that its version is the one you intend to test.

Under Select type of test to run, open Custom Scenario and select standard. This config compares response bodies and gates the run on passing assertions. The regression config used by Regression (1x traffic, with service mocks) checks response schema instead of exact body values. A changed value can keep the same schema, so use standard for this first comparison and pass the same config ID in step 4.

Under Choose where to send traffic, include the inbound service you want to test and confirm its target namespace and workload. Keep the initial selection narrow. Include recorded outbound dependencies as mocks unless you intentionally want to call a test instance of one of them. Sending replayed requests to a live payment, email, or identity service is a bad first experiment.

Select Start Replay. Speedscale creates a snapshot of the selected traffic and opens the report as the replay runs. Save the snapshot ID if you want to run the same traffic again from the CLI or against another version of the service. The current dashboard replay guide shows the wizard screens if the labels in your account differ from this description.

3. Read the traffic replay report before calling it a pass

Start with the report’s four outcome checks: Completed, Accuracy, Mocks, and Goals. A completed replay only means the run finished. Accuracy asks whether responses matched the recorded behavior. Mocks asks whether outbound requests matched the configured dependency responses. Goals checks any performance or validation thresholds you set. A green completion check is not proof that latency goals passed if you never configured those goals. If Accuracy says Nothing asserted, no response assertions ran. If Goals says None set, there are no configured goals to gate the result. Check the selected config, assertions, and goals before calling it a pass.

Open a failed request and compare its recorded response with the replayed response. If a response code or stable field changed after your code change, you may have found a regression. If the failure is an expired token, a timestamp, or a generated ID, first check whether the captured traffic needs a transform or a more precise assertion. An unmatched outbound call usually means the mock selection or request matching needs attention, not that the service code is broken.

The report also shows latency percentiles and throughput. Look at the affected endpoint and the traffic volume before treating a higher P95 as a performance regression. The report guide explains each outcome check and where to inspect a failed goal. Fix the setup issue or the code, then replay the same snapshot so the comparison stays meaningful.

4. Replay the same snapshot from the CLI

The dashboard is the easiest place to inspect the first run. Once you have a useful snapshot, speedctl lets you repeat it against a known workload. Install the CLI and run speedctl init to connect it to your account. Use the snapshot ID from the snapshot page or the replay wizard.

Check that the target cluster has an active inspector before starting:

speedctl infra inspectors -o pretty

Then set the values for your test environment and start a replay:

SNAPSHOT_ID="your-snapshot-id"
CLUSTER_NAME="your-test-cluster"
NAMESPACE="your-test-namespace"
SERVICE_NAME="your-test-workload"

speedctl infra replay \
  --snapshot-id "$SNAPSHOT_ID" \
  --cluster "$CLUSTER_NAME" \
  --namespace "$NAMESPACE" \
  --service "$SERVICE_NAME" \
  --test-config-id standard

The command returns a report ID. Open that report in the dashboard, or fetch its JSON with speedctl get report <report-id> after the run completes. The current speedctl replay reference documents flags for targeting a different service and choosing which outbound dependencies to mock. Avoid --no-mocks unless you have checked where every real outbound call will go.

Do not turn this example into a CI gate by checking only whether the command launched. A gate needs to wait for the run, inspect the finished report, and fail on the particular accuracy or performance goals your team cares about. The CI integration guide is the next step once this manual replay produces a useful result.

What to do next

Keep the first snapshot small enough that you can explain every failure. Once it passes against the current version, replay it against the proposed change and compare the same endpoint, mocks, and goals. That gives you a repeatable test of real API behavior rather than a one-off screenshot of traffic.

If the replay exposes authentication or session problems, see how to fix 403 errors during replay. If you are validating a framework upgrade, the Spring Boot migration walkthrough shows how to use a recorded baseline against the upgraded deployment.

Originally published by Nate Lee in 2023. Updated by the Speedscale team in 2026 to reflect the current capture, replay, and report workflow.