Load testing guide

Outcome: A validated load test against your production-class Nakama deployment, with clear performance baselines.

Prerequisites #

  • A production-type Nakama deployment dedicated to load testing. Development environments aren’t scalable and can’t be used for load testing or any performance assessment.
  • Nakama configuration tuned for your workload (see below).
  • A load testing tool that supports WebSocket connections.
  • Notify the Heroic Labs support team before running load tests. Let them know which instance you’ll be testing and when, so the team can monitor and assist if needed.

Steps #

1. Prepare your Nakama configuration #

Before running load tests, review these settings:

  • JSVM pool counts: If you write JavaScript or TypeScript code, check your JSVM min and max pool counts. The default pool size is 64 (64 concurrent VM-based requests). For high-concurrency load tests, increase this value in your Nakama configuration. Each additional VM instance consumes memory, so scale your Nakama tier accordingly.

2. Choose a load testing tool #

Heroic Labs recommends Artillery for load testing Nakama. Artillery supports WebSocket connections, which is essential for testing Nakama’s real-time features.

Heroic Labs can provide Artillery scripts on request to customize for your specific workload. Contact sales@heroiclabs.com to request load testing scripts and guidance.

k6 is an alternative that also supports WebSocket connections.

3. Design realistic scenarios #

Your load test should simulate realistic player behavior. At a minimum, cover authentication flows and whichever server-side features your game actually uses. No universal baseline exists—every game uses the backend differently, so performance figures depend entirely on your implementation.

4. Run the test and scale #

Scale your deployment proactively before the test begins. See Scaling for how to apply tier changes and how long they take to take effect. Leave at least 25% headroom so the deployment has capacity to absorb traffic spikes during the test.

For scaling advice specific to your load test scenario, contact sales@heroiclabs.com.

Baseline performance #

Heroic Labs has stress-tested Nakama to over 2 million CCUs. Contact sales@heroiclabs.com for benchmarking reports and guidance on sizing for your specific workload.

Benchmark numbers represent the Nakama server without custom game code. Every game uses the backend differently, so no universal formula exists for how many vCPUs you need for a given CCU target. Always load test your own deployment with your own custom code to validate performance. The Heroic Labs team can help you interpret results and recommend scaling adjustments.

Troubleshooting #

  • Low throughput on dev instance: Development instances can’t be scaled. Switch to a production-type instance.
  • Connection failures at high load: Check JSVM pool counts and ensure your scaling tier has enough CPU and memory for the target CCU.