← Back to Development Workflow

7.8 Performance Sizing & Risk Monitoring

This guide defines a repeatable benchmark workflow for:

  1. Generating installer-facing environment sizing suggestions.
  2. Detecting performance risks (slow routes, query-heavy pages, concurrency pressure).
  3. Driving targeted optimization work.

Overview

KMP ships with a performance sizing benchmark script at:

The benchmark uses authenticated Playwright flows over production-like seed data and can optionally profile route-level SQL workload via MariaDB slow log tables.

Running the Benchmark

cd /workspaces/KMP
./load_test.sh

Artifacts are written to:

Key Environment Variables

Variable Default Purpose
KMP_BASE_URL http://127.0.0.1:8080 Base URL for benchmark traffic
KMP_LOGIN_EMAIL admin@amp.ansteorra.org Login identity for authenticated routes
KMP_LOGIN_PASSWORD TestPassword Login password
KMP_ROUTE_RUNS 5 Number of sequential profiling runs per route
KMP_CONCURRENCY_LEVELS 1,5,10,20 Virtual-user concurrency levels to test
KMP_SLOW_REQUEST_MS 1500 Slow-route threshold used for risk flags and sizing logic
KMP_CPU_TARGET_UTIL_PCT 70 CPU target utilization used to convert observed host load into capacity guidance
KMP_MEMORY_TARGET_UTIL_PCT 80 Memory target utilization used to convert observed host load into capacity guidance
KMP_TELEMETRY_SAMPLE_MS 500 Host telemetry sample interval (CPU%, memory%, load average) during concurrency tests
KMP_ENABLE_DB_PROFILE 1 Enables per-route SQL query-count/rows profiling
KMP_DB_HOST 127.0.0.1 DB host for SQL profiling
KMP_DB_USER KMPSQLDEV DB user for SQL profiling
KMP_DB_PASS P@ssw0rd DB password for SQL profiling
KMP_DB_NAME KMP_DEV DB name for SQL profiling
KMP_PERF_OUTPUT_DIR test-results/perf Report output directory

Example:

KMP_CONCURRENCY_LEVELS=1,5,10,20,30 \
KMP_SLOW_REQUEST_MS=1800 \
./load_test.sh

Runtime Instrumentation for Ongoing Monitoring

KMP supports optional request timing logs to identify route regressions in staging/production-like environments.

Enable request timing instrumentation

Add to app/config/.env (or deployment environment):

PERF_REQUEST_LOG_ENABLED=true
PERF_SLOW_REQUEST_MS=750
PERF_LOG_ALL_REQUESTS=false

Optional external sink:

LOG_PERFORMANCE_URL=syslog://your-log-host:514

When enabled, slow requests are emitted to logs/performance.log with scope app.performance.

How to Use Results for Installer Sizing

The generated report includes:

How recommendation values are derived

recommendation.app and recommendation.database are now derived from measured benchmark-host behavior, not static defaults:

  1. Find the highest tested concurrency with:
    • 0% request errors
    • p95 route latency <= KMP_SLOW_REQUEST_MS
  2. Read host telemetry at that concurrency (CPU p95 and memory p95).
  3. Convert observed utilization to capacity using target utilization guards:
    • CPU target: KMP_CPU_TARGET_UTIL_PCT (default 70%)
    • Memory target: KMP_MEMORY_TARGET_UTIL_PCT (default 80%)
  4. Split combined derived capacity into app/db guidance using a documented split model in the report.

This keeps recommendations tied to the actual benchmark machine and observed host pressure.

Use the recommendation as a starting point, then tune for:

Performance Risk Triage Workflow

  1. Run ./load_test.sh on current branch and capture report.
  2. Prioritize risks in this order:
    • Concurrency errors / high error rate
    • Routes with p95 above threshold
    • DB-heavy routes with high query counts or rows examined
  3. For each risky route:
    • Inspect associated grid/contain queries.
    • Validate index coverage and count query strategy.
    • Re-run benchmark after changes.
  4. Track trend over time by keeping benchmark artifacts from each release branch.

Suggested Cadence

← Back to Development Workflow