ripley - replay HTTP

Ripley replays HTTP traffic at multiples of the original rate. While similar tools usually generate load at a set rate, such as 100 requests per second, ripley uses request timestamps, for example those recorded in access logs, to more accurately represent real world load. It simulates traffic ramp up or down by specifying rate phases for each run. For example, you can replay HTTP requests at twice the original rate for ten minutes, then three times the original rate for five minutes, then ten times the original rate for an hour and so on. Ripley's original use case is load testing by replaying HTTP access logs from production applications.

Install

# go >= 1.17
# Using `go get` to install binaries is deprecated.
# The version suffix is mandatory.
go install github.com/loveholidays/ripley@latest

# go < 1.17
go get github.com/loveholidays/ripley

Homebrew

brew install loveholidays/tap/ripley

Docker

docker pull loveholidays/ripley

Linux

Grab the latest OS/Arch compatible binary from our Releases page.

From source

git clone git@github.com:loveholidays/ripley.git
cd ripley
go build -o ripley main.go

Quickstart from source

Run a web server to replay traffic against

go run etc/dummyweb.go

Loop 10 times over a set of HTTP requests at 1x rate for 10 seconds, then at 5x for 10 seconds, then at 10x for the remaining requests

seq 10 | xargs -I{} cat etc/requests.jsonl | ./ripley -pace "10s@1 10s@5 1h@10"

Replaying HTTP traffic

Ripley reads a representation of HTTP requests in JSON Lines format from STDIN and replays them at different rates in phases as specified by the -pace flag.

An example ripley request:

{
  "url": "http://localhost:8080/",
  "method": "POST",
  "body": "{\"foo\": \"bar\"}",
  "headers": {
    "Accept": "text/plain"
  },
  "timestamp": "2021-11-08T18:59:58.9Z"
}

url, method and timestamp are required, headers and body are optional.

-pace specifies rate phases in [duration]@[rate] format. For example, 10s@5 5m@10 1h30m@100 means replay traffic at 5x for 10 seconds, 10x for 5 minutes and 100x for one and a half hours. The run will stop either when ripley stops receiving requests from STDIN or when the last phase elapses, whichever happens first.

Ripley writes request results as JSON Lines to STDOUT

echo '{"url": "http://localhost:8080/", "method": "GET", "timestamp": "2021-11-08T18:59:50.9Z"}' | ./ripley | jq

produces

{
  "statusCode": 200,
  "latency": 3915447,
  "request": {
    "method": "GET",
    "url": "http://localhost:8080/",
    "body": "",
    "timestamp": "2021-11-08T18:59:50.9Z",
    "headers": null
  }
}

Results output can be suppressed using the -silent flag.

Metrics and profiling

Enable Prometheus metrics with -metricsServerEnable. Ripley listens on 0.0.0.0:8081 by default and exposes metrics at /metrics.

Use -pushgateway-url, -pushgateway-job, and -pushgateway-interval to persist metrics for short-lived Jobs. Ripley pushes immediately, at the configured interval, and when it exits normally.

Use -pprof-enable with -metricsServerEnable to expose Go profiles on the same listener. Keep this endpoint private. During an active run, use port-forwarding to inspect:

/debug/pprof/goroutine?debug=1
/debug/pprof/heap
/debug/pprof/profile?seconds=30
/debug/pprof/threadcreate
/debug/pprof/block
/debug/pprof/mutex
/debug/pprof/trace?seconds=5

For an example of working with ripley's output to generate statistics, refer to https://gist.github.com/georgemalamidis-lh/39b4f4a6c9c82f6cc8b7370219e93cd2

cat etc/requests.jsonl | ./ripley | go run ripley_stats.go | jq

{
  "totalRequests": 10,
  "statusCodes": {
    "200": 10
  },
  "latency": {
    "max": 2074819,
    "mean": 968998.6,
    "median": 843486,
    "min": 696708,
    "p95": 1548438.5,
    "p99": 1548438.5,
    "stdDev": 377913.54080112034
  }
}

It is possible to disable sending HTTP requests to the targets with the -dry-run flag:

cat etc/requests.jsonl | ./ripley -pace "30s@1" -dry-run

Converting Linkerd Access Logs

The linkerdxripley tool converts Linkerd JSONL access logs into Ripley's request format, enabling you to replay production Linkerd traffic for load testing.

Installation

Build from source:

cd tools/linkerdxripley
go build -o linkerdxripley main.go

Or install directly:

go install github.com/loveholidays/ripley/tools/linkerdxripley@latest

Usage

Basic conversion:

cat linkerd.jsonl | linkerdxripley > ripley.jsonl

Convert with host replacement:

cat linkerd.jsonl | linkerdxripley -host localhost:8080 > ripley.jsonl

Convert with HTTPS upgrade:

cat linkerd.jsonl | linkerdxripley -host localhost:8443 -https > ripley.jsonl

Full pipeline (convert and replay):

cat linkerd.jsonl | linkerdxripley -host localhost:8080 | ./ripley -pace "1m@2 5m@5"

Input Format

The tool expects Linkerd JSONL access logs with these fields:

{
  "client.addr": "192.168.1.100:12345",
  "client.id": "service.namespace.serviceaccount.identity.linkerd.cluster.local",
  "host": "api.example.com",
  "method": "GET",
  "processing_ns": "50000",
  "request_bytes": "256",
  "status": 200,
  "timestamp": "2025-09-03T15:30:32.928995068Z",
  "total_ns": "2500000",
  "trace_id": "abc123",
  "uri": "http://api.example.com/api/v1/data?id=123",
  "user_agent": "MyApp/1.0",
  "version": "HTTP/2.0"
}

Required fields: method, timestamp, uri

Output Format

Produces Ripley-compatible JSONL:

{
  "method": "GET",
  "url": "http://localhost:8080/api/v1/data?id=123",
  "body": "",
  "timestamp": "2025-09-03T15:30:32.928995068Z",
  "headers": {
    "User-Agent": "MyApp/1.0"
  }
}

Command Options

• -host <host:port> - Replace the original host with a new target host
• -https - Upgrade HTTP requests to HTTPS (useful for local testing with TLS)
• -help - Show usage information

Running the tests

go test pkg/*.go

Releasing new versions

A successful merge to main creates a release tag and starts GoReleaser.

• Normal merge: increments the minor version, for example v0.1.3 to v0.2.0.
• Merge commit message containing #major: increments the major version, for example v0.1.3 to v1.0.0.

Do not create release tags manually.