Test how fast, stable and healthy your backend is.

Bongo Performance Studio is a web app that runs on your own computer (by default at http://localhost:3333). It tests any backend that serves an HTTP API, whatever language or framework it is written in, and it can inspect and seed any MongoDB database. See Supported Backends for the details.

It answers questions like: "How many users can our server handle?", "Which API is the slowest?", "Did the last release break any route?", "Are our database queries using indexes?" and "What happens when there are 100,000 records in the database?"

What you can do

Who it is for

• Backend developers — find slow queries and routes before users do.
• QA testers — run a regression scan of every API after each change.
• DevOps — find the breaking point of a server and size it correctly.
• Team leads — share a clear, graded report with management or clients.

What it connects to

The studio talks to two things, both set per environment on the Settings screen:

Both are optional on their own: without a DB link the testing screens still work, and without a running backend the database screens still work. See Architecture for the full picture.

Any backend that speaks HTTP

The testing screens only send HTTP requests and measure the responses. They never look at your source code, so the language and framework do not matter. If you can call it with curl, the studio can test it.

It does not matter where the backend runs: on your computer, in Docker, on a staging server, in the cloud, or behind Nginx or a load balancer. The studio only needs a reachable http:// or https:// Base URL.

What each feature needs

What is not covered

• Other databases. MySQL, PostgreSQL, SQL Server, Redis and others cannot be connected on the database screens. The HTTP testing screens still work for backends that use them.
• Other ways to log in. The built-in screens only send a Bearer token. API-key headers (such as x-api-key), cookie-only sessions, HTTP Basic auth and OAuth redirect flows are not sent. To use them, set the header in a k6 script.
• Non-HTTP protocols. WebSockets, gRPC and message queues are not tested by the built-in screens. k6 has its own modules for WebSockets and gRPC that you can use in a custom script, but the dashboard numbers only count HTTP requests.
• GraphQL errors. A GraphQL API can be tested as a POST route with a body such as {"query":"{ users { id } }"}. Many GraphQL servers return errors with status 200, and the scanner judges only the status code, so those errors still count as passed.

Replace the sample defaults

A few built-in defaults are only examples. Change them to match your backend:

Requirements

Steps

1. Install and start the studio

   Open a terminal in the project folder and run:

   TerminalCopy

   cd bongo_performance_suite
   npm install
   npm start

   Then open http://localhost:3333. To use another port: UI_PORT=4000 npm start.

2. Point it at your backend and database

   Go to Settings & Environments, choose the Development (DEV) tab and fill in Target Backend Base URL and MongoDB Connection String. Click Test Connection, then Save Settings, then Set as Active Environment.

3. Check the top bar

   The status pill should turn green and show Online (x ms). The Home cards fill with your database numbers within a few seconds.

4. Log in once (for protected APIs)

   In Settings, add a Test Login Email and Password (use a dedicated test account). Then open Auth & Tokens and click Log In Now. Every test now sends this token automatically.

5. Run your first tests

   Start gentle: API Health Scanner → Run Full Health Scan. Then Load & Spike Testing with 20–50 users for 15 seconds.

6. Review and share

   Open Test History to compare runs, and Executive Report to produce a printable summary.

Top bar

Sidebar

• Home — dashboard overview of the database and recent runs.
• Database — Collections Seeder, Inventory, Index Auditor. (Connected Collections opens from the Seeder page.)
• Testing — Load & Spike, Endpoint Benchmark, API Scanner, Cloud Testing (k6), Test History, Auth & Tokens.
• Executive Report and Settings & Environments.

Small badges show live counts, for example the number of documents next to Inventory or saved runs next to Test History.

Live Operation Stream

At the bottom of every studio screen there is a log panel. The server pushes messages to it in real time (seeding progress, test start/finish, errors, k6 output) using Server-Sent Events. Use Clear All to empty it. If something seems stuck, look here first.

Direct links to a screen

You can open a screen directly by adding its name after # in the address bar, for example http://localhost:3333/#loadTest. The Open in Studio buttons in these docs use this.

The rules

1. Seeding writes real documents. Every dummy document is tagged with isPerformanceTestData: true so it can be removed later. See Dummy Data & Purge.
2. Purge deletes real documents — only those that match the test-data rules, but it deletes them for good. There is no undo.
3. Do not seed or load-test PROD unless it is planned and agreed. The Settings screen shows a warning banner when PROD is selected.
4. Load tests create real traffic. On a shared server, other users will feel it. Start small and increase step by step.
5. Rate limiters can block you. Many backends limit requests per IP, for example 500 requests per 5 minutes overall and only a few login attempts per 5 minutes. After a big test, your IP may get HTTP 429 until the limit window resets. Find out your backend's limits before testing.
6. Write routes are sent for real. POST / PUT / DELETE routes in the API directory create, change or delete records when the scanner or benchmark runs them.
7. Use a dedicated test account for Test Login, never a real admin or customer account.
8. Settings contain secrets. src/config/environments.json stores DB links, tokens and the test password in plain text. Do not commit or share it.

Quick actions

The buttons next to the greeting jump straight to API Scanner, Executive Report and Cloud Testing (k6).

The eight KPI cards

Storage cards

• Document Storage and Index Storage rings show each part's share of total disk. Detail opens Inventory or the Index Auditor.
• Storage Engine shows the total footprint, the uncompressed data size and the compression ratio (uncompressed data ÷ document storage).

Insights row

• Health Overview — quick checks: backend online and ping (warns above 1.5 s), latest API scan score, latest saved load test, reference indexes and broken references (from Connected Collections). Click a row to open the related screen.
• Recent Test Runs — the newest saved runs from reports/. Open Test History shows all of them.
• Largest Collections — bar chart of the biggest collections by Documents or Disk Size.

Home uses only data that is already available. It never starts a scan or test on its own. The numbers refresh every 8 seconds.

Option 1: Seed all collections (1-click)

The Universal Master Seeder card adds the same number of documents to every collection in the active database (system collections and sessions are skipped).

With 100 collections, Medium adds about 100,000 documents. Progress appears in the Live Operation Stream.

Option 2: Seed one collection

1. Find the collection

   Use the filter box, or sort by documents, disk space, storage, index size, data size, name or "Most Dummy".

2. Choose a count

   Click a preset (100, 500, 1k, 5k) or type your own number on the collection card.

3. Seed

   Click the seed button on the card. Refresh reloads the list and counts.

How the dummy documents are made

The seeder does not need your schema. It reads one existing document from the collection and builds new documents with the same field names and types:

Every document also gets isPerformanceTestData: true, createdAt and updatedAt. An empty collection (no template) gets simple documents with name, code, status and description. Documents are inserted in batches of 1,000; duplicate-key collisions are skipped and logged.

How it works

The newest 20 documents of each collection are sampled. Any ObjectId (or 24-character id string) whose value exists as an _id in another collection becomes an arrow A → B: "documents in A store the id of a document in B". Results are cached for 5 minutes; Re-scan builds the map again. Nothing is written to the database.

Reading the map

Tools on this screen

• Find a collection — search and focus a node. Fit to Screen resets the view.
• Check Broken References — counts documents whose reference points to a missing record (read-only $lookup).
• Collection Details — click a node to see which fields link it to other collections.
• Index & Integrity Findings — lists unindexed reference fields with a ready createIndex command, and broken-reference counts.
• Not Connected — collections with no detected links in either direction.

Summary tiles at the top show total collections, documents, disk space, document storage, index size and uncompressed data. The table below has one row per collection:

Use the search box to filter by name and Refresh after seeding or purging.

What "Run Live DB Audit" does

The auditor works on a fixed preset of six collections. For each one it lists every index (name, keys, unique) and runs one typical query with MongoDB's explain("executionStats"):

Reading the result

• IXSCAN (index scan) — good. MongoDB jumped straight to the matching entries.
• COLLSCAN (collection scan) — slow. MongoDB read every document because no index matched.
• Docs examined vs keys examined — many documents examined for few results means a missing or poor index.
• Health score — the share of the six collections whose query did not do a COLLSCAN.

Below the results you get best-practice recommendations (connection pool size and compound indexes for the preset collections) with copy-ready code.

The four scenarios

How to run a test

1. Pick a scenario

   Click one of the four scenario cards.

2. Set users and duration

   Concurrent Virtual Users: 5–500. Duration: 5–60 seconds. Start with 20–50 users.

3. Choose the route

   Pick from Select API Route to Hit (filled from the API directory in Settings) or choose Custom Endpoint Path. You can edit the path and add query parameters, e.g. /api/v1/users?page=1&limit=20.

4. Add a token if the route is protected

   The Bearer Token field is filled automatically from Auth & Tokens. Without a token, protected routes answer 401 and the test measures only the rejection.

5. Launch

   Click Launch Load Test. The scorecard shows the result when the run finishes.

Results scorecard

Settings

Routes run one after another, so the total time is about routes × seconds per route (40 routes × 5 s ≈ 3.5 minutes). Duplicate method + path pairs run once. The token from Auth & Tokens is used automatically. Stop ends the run after the current route; finished routes are still saved.

Results

Routes are ranked by p99 latency (slowest first). Each row shows requests/sec, average, p50 / p90 / p99 and max latency, errors (network errors + timeouts), non-2xx responses and the 2xx / 4xx / 5xx split. Every run is saved as reports/endpoint_benchmark_*.json; you can reopen and compare runs in Test History.

How to run a scan

1. Check the target and token

   Target Base URL follows the active environment. The Bearer Token is filled from Auth & Tokens.

2. Choose speed

   Concurrency: 1, 3, 5 (recommended) or 10 parallel workers. Timeout: 3, 6 or 10 seconds per request.

3. Run Full Health Scan

   Every route in the API directory is called once, with its method and saved body. Stop Scan cancels it.

Reading the results

Special status values

• 0 · Connection Refused — nothing is listening at the Base URL. Is the backend running?
• 408 · Request Timeout — no answer within the timeout.
• 500 · Network Error — another network problem (DNS, TLS…). Check the message; this is not necessarily a real server 500.
• 401 / 403 — usually a missing or expired token. Log in again in Auth & Tokens.

Export JSON downloads the full result. Each scan is saved to Test History with the token replaced by <token>, and the latest scan feeds the Executive Report.

How to run a k6 test

1. Pick a preset

   The preset sets the number of virtual users (VUs) and the duration (table below).

2. Pick the target route

   Choose a route or Custom Path. The host comes from the top-bar Target field.

3. Check the token

   The Authorization Bearer Token is filled from Auth & Tokens and written into the script.

4. Review the script

   The editor shows the exact k6 JavaScript that will run. You can edit it.

5. Run k6 Cloud Test

   The k6 Engine Log tab shows k6's output. Abort Test stops it.

Presets

What actually runs

The script in the editor is exactly what k6 runs. The studio writes a simple script for you: the chosen VUs for the whole duration, one GET request to the route, a check that the status is 200, and a threshold of p95 < 500 ms.

• Changing the preset, route or token, or clicking Reset Script, rewrites the script and replaces your edits. Make manual edits last.
• Moving the VUs or Duration slider does not change the script by itself. Click Reset Script afterwards to apply the new values.
• To run the built-in staged version of a preset (ramp up → hold → ramp down, and the multi-step flow), clear the editor completely before clicking Run. The server then uses its own template for that preset.
• Export .js downloads the script so you can run k6 run test.js yourself or in CI.

Dashboard panels

The six KPI cards (VUs, throughput, p95, p99, error rate, checks passed) come from k6's own end-of-test summary, so they are exact. An error rate under 1% is shown as SLA Healthy.

Prometheus and PromQL

• Raw /metrics Stream shows the studio's own endpoint http://localhost:3333/metrics in Prometheus text format: request counts by status, latency quantiles from the last k6 run, current/peak VUs, and the studio process's CPU, heap memory and uptime. A real Prometheus server can scrape it.
• PromQL Explorer is a simplified lookup, not a full PromQL engine. It recognises the words http_requests_total, duration / latency, vus, cpu and heap / mem and returns the matching current values. Functions such as rate() are not calculated.

Each run is saved to Test History, and the latest run feeds the Executive Report.

What is saved

Using the table

• Filter by kind or search by route; Refresh reloads the folder.
• Columns: run, when, setup, requests/sec, average, p99, problems, status and actions.
• View opens the full details of a run. Delete removes the file from reports/ (it asks first).

Comparing two runs

1. Tick two runs

   They must be the same kind: two load tests (k6 runs count as load tests here), two benchmarks or two API scans.

2. Click Compare

   A is the older run, B the newer one. You see the change in each number; for benchmarks per route, for scans which routes changed status.

Login settings (per environment)

{
  "email": "{{TEST_ADMIN_EMAIL}}",
  "password": "{{TEST_ADMIN_PASSWORD}}"
}

The current token

• Log In Now calls the login route and keeps the token in the studio server's memory for the active environment, with its expiry time (read from the JWT).
• You can copy it, Clear Token, or Paste a token instead → Use This Token.
• The token is lost when the studio server restarts; log in again.

Where the token is used

The token fields of Load & Spike Testing, API Health Scanner and Cloud Testing (k6) are filled automatically, unless you typed a different token there. Endpoint Benchmark uses it directly. Before a test, the studio logs in again only if the token expires within one minute.

Where the numbers come from

How the grade is calculated

The score starts at 100 and loses points:

• error rate × 10 (for example 2% errors = −20)
• p95 latency above 300 ms: −5 · above 500 ms: −15 · above 1,000 ms: −25
• (100 − API health score) × 0.5

Recommendations are added by rule: high error rate, p95 above 500 ms, more than 5,000 records (pagination advice), plus two general tips (caching and CI regression tests).

Sharing

• Generate Fresh Report — builds the report from the current data.
• Copy Markdown — paste into GitHub, Slack, Notion or an email.
• Print / Save as PDF — the print layout hides the sidebar and controls; choose "Save as PDF" in the print dialog.

Environments (DEV, QA, PROD)

Test Connection pings the Base URL and opens a short test connection to MongoDB (reports the number of collections). Save Settings stores the tab; Set as Active Environment makes it the one every screen uses.

Seeder defaults

Insert Batch Size, Default Student Count and Default Attendance Count are used by the built-in student/attendance sample seeders and the command-line tools. The Collections Seeder does not use them.

API route directory

The list of routes used by Load & Spike Testing, Endpoint Benchmark and the API Scanner. Add routes in two ways:

Option 1 — upload files

Drag & drop or browse: Excel (.xlsx, .xls), .csv, .json or .txt. Several files at once; every sheet is read. Download the Excel, CSV or JSON template to start.

The first row must be the column headers. Rows already in the list (same method + path) are skipped.

Option 2 — type them in

One path per line, pick the method and an optional category, add a JSON body for POST / PUT, then Add Routes. The table below lists all routes; filter, delete single routes, or Reset to Default Routes.

How settings are saved

• On the server in src/config/environments.json.
• A copy is also saved in this browser (localStorage key bongoStudio.settings). When the studio loads and the server's settings differ, the browser copy is pushed back to the server — the browser copy wins.

Before every release (regression check)

1. Log in

   Auth & Tokens → Log In Now.

2. Scan

   API Health Scanner → Run Full Health Scan. Target: 100% health.

3. Compare

   Test History → tick this scan and the previous one → Compare. Investigate any route that changed from passing to failing.

4. Load

   Cloud Testing → Standard Load preset on the busiest route.

5. Report

   Executive Report → Generate → Print / Save as PDF.

Find and fix slow endpoints

1. Benchmark

   Endpoint Benchmark, GET only, 10 users, 5 seconds per route.

2. Pick the worst

   Look at the top of the list (highest p99).

3. Check the database

   Index Auditor for COLLSCANs; Connected Collections for unindexed reference fields (copy the createIndex command).

4. Fix and re-run

   Add the index or pagination, run the same benchmark, compare in Test History.

Prepare for a traffic peak (launch, sale, big announcement)

1. Seed realistic volume

   Collections Seeder → bring key collections to the size you expect.

2. Normal load

   Load & Spike → Standard Load at your expected number of users.

3. Spike

   Sudden Traffic Spike at 3–5× that number. Drop rate should stay near 0%.

4. Find the limit

   Breaking Point Stress. Note the stage where p95 passes 1 s or errors appear: that is your capacity.

5. Clean up

   Home → Purge All.

Monthly database health check

1. Inventory

   Which collections grow fastest? Is index size reasonable?

2. Index Auditor

   Any COLLSCAN?

3. Connected Collections

   Re-scan, then Check Broken References. Fix unindexed and broken references.

Good, watch, bad

These are the thresholds the studio itself uses for grades and warnings.

p95 latency

Error rate

API health score

Glossary

What counts as test data

A document counts as test data (and will be purged) if any of these is true. The first rule covers everything the Collections Seeder creates; the others match the ids and codes written by the built-in sample seeders.

Purging

1. Open the purge dialog

   Home → Test Purge card → Purge All.

2. Confirm

   Yes, Purge All Test Data runs deleteMany with the rules above on every collection.

3. Verify

   The Test Data card should show 0. Inventory's "Dummy Test" column should be empty.

From the terminal: npm run clean does the same.

What happens when you click a button

1. The browser calls the studio server

   For example POST /api/test/run with the route, users and duration.

2. The server runs the engine

   autocannon, axios, k6 or Mongoose does the real work against the target backend or MongoDB. The browser never talks to the target directly, so there are no CORS problems.

3. Progress streams back live

   The engine writes to an internal event bus; GET /api/events streams it to the Live Operation Stream with Server-Sent Events.

4. The result is returned and saved

   The response carries the result for the screen; most test kinds are also written to reports/ for Test History.

Server (Node.js, from package.json)

Web UI (loaded from CDNs, no build step)

Not stored anywhere: Load & Spike stress/rate-limiter results, Index Auditor results and the Executive Report itself (generate it again any time).

Live stream, environments and stats

Database

Testing and reports

curl -X POST http://localhost:3333/api/test/run \
  -H "Content-Type: application/json" \
  -d '{"type":"load","targetUrl":"http://localhost:5000/api/v1/users","connections":50,"duration":20}'

The templates are written for a Node.js backend. Before using them, change the build folder, start script and ports to your own project. For backends in other languages, the Nginx file still applies; PM2 and the Compose file need your own start command or image.

Typical loop: stress-test one instance → note the breaking point → run more instances behind Nginx or PM2 → stress-test again and compare in Test History.