Load Testing

Use load testing to ensure that your Blnk deployment can handle expected traffic and maintain performance under various conditions. This is a critical step in setting up your Blnk server. Blnk includes a comprehensive load testing suite built with k6, a modern load testing tool. This guide walks you through finding, configuring, and running load tests to validate your Blnk server’s performance across different scenarios.

Before you start

Make sure you have:

Cloned the Blnk repository to your local machine
Docker and Docker Compose installed, for running the Blnk server
k6 installed on your machine. Visit k6.io for installation instructions
Your Blnk server running and accessible

If you haven’t deployed Blnk yet, follow the installation guide first.

Getting started

You can find the load test files in the tests/loadtest directory of the Blnk repository. Navigate to this directory to access all available test scripts:

cd tests/loadtest

Main test script

The primary load test script (script.js) supports five configurable load-testing scenarios, each controlled via environment variables. Each scenario targets a specific aspect of your Blnk server’s transaction performance, allowing you to test different load patterns and system behaviors.

Baseline: Steady, constant load to measure normal performance.
Ramp: Gradually increasing load to find when your server struggles.
Contention: Tests when one balance gets most of the traffic.
Soak: Long-duration test (2 hours) to find memory leaks and stability issues.
Spike: Sudden traffic surge to test recovery behavior.

By default, tests target http://localhost:5001. Ensure your Blnk server is running and accessible at this address, or configure the URL using the URL environment variable.

Use the SCENARIO environment variable to select which scenario to run. Each scenario has specific configuration options:

Baseline
Ramp
Contention
Soak
Spike

Runs a steady, constant load to measure your server’s normal performance. Use this to see how fast your server responds under normal conditions.

tests/loadtest

k6 run --env URL=http://localhost:5001/transactions --env SCENARIO=baseline --env VUS=100 --env DURATION=5m script.js

VUS

integer

default:"100"

Number of virtual users to run concurrently

DURATION

string

default:"5m"

Test duration (e.g., “5m”, ”30s”, “1h”)

Slowly increases traffic over time to find when your server starts to struggle. Starts with 100 users and gradually increases to 1000 users across three stages.

k6 run --env URL=http://localhost:5001/transactions --env SCENARIO=ramp \
  --env START_VUS=100 \
  --env VUS1=300 --env STAGE1=5m \
  --env VUS2=600 --env STAGE2=5m \
  --env VUS3=1000 --env STAGE3=5m \
  script.js

START_VUS

integer

default:"100"

Initial number of virtual users at the start of the test

VUS1

integer

default:"300"

Target number of virtual users for the first ramp stage

STAGE1

string

default:"5m"

Duration of the first ramp stage

VUS2

integer

default:"600"

Target number of virtual users for the second ramp stage

STAGE2

string

default:"5m"

Duration of the second ramp stage

VUS3

integer

default:"1000"

Target number of virtual users for the third ramp stage

STAGE3

string

default:"5m"

Duration of the third ramp stage

Tests what happens when one balance gets most of the traffic while others get less. This simulates real-world scenarios where some accounts are much busier than others.

tests/loadtest

k6 run --env URL=http://localhost:5001/transactions --env SCENARIO=contention \
  --env HOT_DEST=@hot-balance-0001 \
  --env HOT_RPS=308 \
  --env RANDOM_RPS=132 \
  --env DURATION=5m \
  --env VUS=200 \
  --env MAX_VUS=800 \
  script.js

HOT_DEST

string

default:"@hot-balance-0001"

The balance identifier that receives concentrated traffic (70% of requests)

HOT_RPS

integer

default:"308"

Requests per second targeting the hot balance

RANDOM_RPS

integer

default:"132"

Requests per second targeting random balances

DURATION

string

default:"5m"

Test duration (e.g., “5m”, ”30s”, “1h”)

VUS

integer

default:"200"

Number of pre-allocated virtual users

MAX_VUS

integer

default:"800"

Maximum number of virtual users that can be allocated

Runs a steady load for a long time (default: 2 hours) to check if your server has memory leaks or other problems that only show up after running for a while.

tests/loadtest

k6 run --env URL=http://localhost:5001/transactions --env SCENARIO=soak --env VUS=200 --env DURATION=2h script.js

VUS

integer

default:"200"

Number of virtual users to run concurrently

DURATION

string

default:"2h"

Test duration (e.g., “5m”, ”30s”, “1h”, “2h”)

Soak tests run for extended periods. Monitor your server’s resource usage during these tests.

Simulates a sudden traffic spike to see if your server can handle the surge and recover afterward.

tests/loadtest

k6 run --env URL=http://localhost:5001/transactions --env SCENARIO=spike \
  --env BASE_RPS=200 \
  --env SPIKE_RPS=600 \
  --env WARM=2m \
  --env PEAK=1m \
  --env COOL=3m \
  --env PRE_VUS=300 \
  --env MAX_VUS=1200 \
  script.js

BASE_RPS

integer

default:"200"

Baseline requests per second during warm-up and recovery phases

SPIKE_RPS

integer

default:"600"

Peak requests per second during spike phase

WARM

string

default:"2m"

Duration of warm-up phase before spike

PEAK

string

default:"1m"

Duration of spike phase

COOL

string

default:"3m"

Duration of recovery phase after spike

PRE_VUS

integer

default:"300"

Number of pre-allocated virtual users

MAX_VUS

integer

default:"1200"

Maximum number of virtual users that can be allocated during the spike

Feature-specific tests

Run targeted tests to verify specific Blnk features. Each test focuses on one capability to confirm it works correctly and performs as expected under load.

Bulk transactions

Tests atomic bulk transaction processing with 1000 virtual users creating batches of 4 transactions each.

tests/loadtest

k6 run bulk.js

Inflight transactions

Tests the inflight transaction workflow: creating an inflight transaction and committing it.

tests/loadtest

k6 run inflight.js

Concurrent inflight commits

Tests race conditions by having 100 virtual users attempt to commit the same inflight transaction simultaneously.

tests/loadtest

k6 run inflight-concurrent-commit.js

Multiple destinations

Tests transactions that split amounts across multiple destination accounts using percentage, fixed amount, and “left” distribution methods.

tests/loadtest

k6 run multi-destinations.js

Multiple sources

Tests transactions that aggregate amounts from multiple source accounts.

tests/loadtest

k6 run multi-sources.js

Refunds

Tests the refund workflow by creating transactions and immediately refunding them.

tests/loadtest

k6 run refund.js

Scheduled transactions

Tests scheduled transaction creation with future execution times.

tests/loadtest

k6 run scheduled.js

Understanding test results

k6 provides comprehensive metrics for each test run. Key metrics to monitor include:

http_req_duration: Request latency (p50, p95, p99 percentiles)
http_req_failed: Error rate (should be < 0.1%)
http_reqs: Total requests processed
vus: Virtual users active during the test

Performance thresholds

The main test script (script.js) includes built-in performance thresholds that automatically fail tests if exceeded:

Error rate: Less than 0.1% (http_req_failed < 0.001)
P95 latency: Less than 300ms
P99 latency: Less than 600ms

Exporting results

The main test script automatically exports results to summary.json. Run any scenario:

k6 run --env SCENARIO=baseline script.js

Results are automatically saved to summary.json in the current directory.

Analyze results with TPM tool

The test suite includes a utility script to convert k6 JSON output into transactions per minute (TPM) CSV format.First, export k6 results as JSON:

k6 run --out json=results.json --env SCENARIO=baseline script.js

Then convert to CSV:

python3 tools/k6_json_to_tpm.py results.json tpm_results.csv

input.json

string

required

Path to k6 JSON output file (use --out json=output.json when running k6)

output.csv

string

required

Path to output CSV file

The generated CSV includes: minute timestamp, requests, transactions per minute (tpm), success ratio, p50/p95/p99 latency, and apdex score.

Troubleshooting

Connection refused errors

If you see connection errors, verify:

Your Blnk server is running and accessible.
The URL matches your server’s address and port.
Firewall rules allow connections to the Blnk server.

High error rates

If error rates exceed thresholds:

Check Blnk server logs for errors.
Verify database connection pool settings.
Review server resource usage (CPU, memory).
Consider reducing virtual users or request rate.

Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.

Tip: Connect to Blnk Cloud to see your Core data.You can view your transactions, manage identities, create custom reports, invite other team members to collaborate, and perform operations on your Core — all in one dashboard.Check out Blnk Cloud →

Getting Started

Ledgers

Ledger Balances

Transactions

Reconciliation

Identities

Metadata

Hooks

Search

Guides

Advanced

Before you start

Getting started

Main test script

Feature-specific tests

Understanding test results

Troubleshooting

Connection refused errors

High error rates

Need help?

Getting Started

Ledgers

Ledger Balances

Transactions

Reconciliation

Identities

Metadata

Hooks

Search

Guides

Advanced

​Before you start

​Getting started

​Main test script

​Feature-specific tests

​Understanding test results

​Troubleshooting

​Connection refused errors

​High error rates

​Need help?

Before you start

Getting started

Main test script

Feature-specific tests

Understanding test results

Troubleshooting

Connection refused errors

High error rates

Need help?