Performance Mode (Load Simulation)

Planned / not yet available. /api/performance/* and a UI page exist, but the simulator is not yet on the request path (it neither generates load nor shapes responses), and there is no mockforge performance CLI. This page describes the intended design and is kept for reference; do not rely on it in a released build. Track progress at https://github.com/SaaSy-Solutions/mockforge/issues.

Pillars: [DevX]

Performance Mode provides lightweight load simulation for running scenarios at N RPS, simulating bottlenecks, recording latencies, and observing how responses change under load. This is NOT true load testing—it’s realistic behavior simulation under stress testing conditions.

Overview

Performance Mode enables:

  • Run scenarios at n RPS: Control request rate
  • Simulate bottlenecks: Add artificial delays
  • Record latencies: Track response times
  • Observe behavior changes: See how responses change under load

Quick Start

There is no mockforge performance CLI. Performance mode is driven through the HTTP API.

Via API

# Start performance mode
POST /api/performance/start
{
  "initial_rps": 100,
  "bottlenecks": [
    {
      "bottleneck_type": "network",
      "severity": 0.5,
      "endpoint_pattern": "/api/checkout/*"
    }
  ]
}

# Stop it
POST /api/performance/stop

Other endpoints: GET /api/performance/status, GET /api/performance/snapshot, POST /api/performance/rps, and POST/DELETE /api/performance/bottlenecks.

RPS Profiles

Constant RPS

Maintain constant requests per second:

rps_profile:
  type: constant
  rps: 100

Ramp Profile

Gradually increase RPS:

rps_profile:
  type: ramp
  start_rps: 10
  end_rps: 100
  duration_seconds: 60

Spike Profile

Sudden spike in RPS:

rps_profile:
  type: spike
  base_rps: 50
  spike_rps: 200
  spike_duration_seconds: 10
  spike_interval_seconds: 60

Bottleneck Simulation

Endpoint Bottlenecks

Add delays to specific endpoints:

bottlenecks:
  - endpoint: "/api/checkout/*"
    delay_ms: 500
    probability: 1.0  # Always delay
  - endpoint: "/api/payments/*"
    delay_ms: 1000
    probability: 0.5  # 50% chance

Database Bottlenecks

Simulate database slowdowns:

bottlenecks:
  - type: database
    delay_ms: 200
    probability: 0.3

Network Bottlenecks

Simulate network conditions:

bottlenecks:
  - type: network
    latency_ms: 100
    packet_loss: 0.01

Latency Recording

Automatic Recording

Latencies are automatically recorded:

{
  "endpoint": "/api/users/{id}",
  "method": "GET",
  "latency_ms": 150,
  "status_code": 200,
  "timestamp": "2025-01-27T10:00:00Z"
}

Latency Analysis

Analyze recorded latencies:

# Get latency statistics
GET /api/performance/snapshot

# Response:
{
  "stats": {
    "mean_latency_ms": 150,
    "p50_latency_ms": 140,
    "p95_latency_ms": 250,
    "p99_latency_ms": 400,
    "max_latency_ms": 500
  }
}

Response Changes Under Load

Behavioral Economics Integration

Responses may change under load due to behavioral economics:

# Under normal load
GET /api/checkout → 200 OK, conversion: 90%

# Under high load (latency > 400ms)
GET /api/checkout → 200 OK, conversion: 70%  # 20% drop

Error Rate Increases

Error rates may increase under load:

# Normal load
Error rate: 1%

# High load
Error rate: 5%  # Increased errors

Usage Examples

There is no mockforge performance CLI. The simulator is controlled through the /api/performance endpoints on the HTTP server.

Example 1: Constant Load

# Start at a constant 100 RPS
curl -X POST http://localhost:3000/api/performance/start \
  -H "Content-Type: application/json" \
  -d '{"initial_rps": 100}'

# Monitor
curl http://localhost:3000/api/performance/snapshot

Example 2: Ramp Load

# Ramp from 10 to 100 RPS using profile stages
curl -X POST http://localhost:3000/api/performance/start \
  -H "Content-Type: application/json" \
  -d '{
    "initial_rps": 10,
    "rps_profile": {
      "name": "ramp",
      "stages": [
        {"duration_secs": 30, "target_rps": 10},
        {"duration_secs": 30, "target_rps": 100}
      ]
    }
  }'

# Or change the target RPS of a running simulation
curl -X POST http://localhost:3000/api/performance/rps \
  -H "Content-Type: application/json" \
  -d '{"target_rps": 100}'

Example 3: With Bottlenecks

# Add a database bottleneck on checkout endpoints
curl -X POST http://localhost:3000/api/performance/bottlenecks \
  -H "Content-Type: application/json" \
  -d '{"bottleneck": {"bottleneck_type": "database", "severity": 0.5, "endpoint_pattern": "/api/checkout/*"}}'

# Clear all bottlenecks
curl -X DELETE http://localhost:3000/api/performance/bottlenecks

Configuration

Performance Mode Config

# mockforge.yaml
performance:
  enabled: true
  default_rps: 100
  max_latency_samples: 10000
  max_latency_age_seconds: 300

RPS Controller

performance:
  rps_controller:
    type: token_bucket
    capacity: 1000
    refill_rate: 100  # per second

Best Practices

  1. Start Low: Begin with low RPS and increase gradually
  2. Monitor Latencies: Watch latency percentiles
  3. Test Bottlenecks: Simulate realistic bottlenecks
  4. Observe Behavior: Watch how responses change
  5. Not True Load Testing: This is simulation, not production load testing