benchmarkengine
- GET /agent/benchmark/fingerprint
Get the hardware fingerprint of this node
Returns the hardware fingerprint captured on the node the agent runs on.
- Status Codes:
200 OK – hardware fingerprint
- POST /agent/benchmark/install
Install a benchmark tool on this node
Installs the apt package for a benchmark tool on this node; returns the installed version if already present.
- Request JSON Object:
tool (string) – (required)
- Status Codes:
200 OK – tool install result
400 Bad Request – invalid body or phoronix-test-suite requested
500 Internal Server Error – apt install failed or binary not found after install
- Response JSON Object:
error (string)
installed (boolean)
tool (string)
version (string)
- POST /agent/benchmark/run
Start a benchmark run on this node
Validates the request, checks the required tool is installed on this node, registers the run and dispatches it asynchronously.
- Request JSON Object:
args[] (string)
category (string) – (required)
cgroup_mode (string)
env (object)
target (string)
test_id (string) – (required)
timeout_sec (integer)
tool (string)
- Status Codes:
202 Accepted – run id, test id and running status
400 Bad Request – invalid body, invalid cgroup_mode or missing tool
503 Service Unavailable – required tool is not installed on this node
- Response JSON Object:
message (string)
run_id (string)
status (string)
test_id (string)
- GET /agent/benchmark/run/{run_id}
Get benchmark run status on this node
Returns the tracked status of a run from the in-memory run tracker of this node.
- Parameters:
run_id (string) – Agent run ID
- Status Codes:
200 OK – run status
404 Not Found – run not found
- Response JSON Object:
duration_sec (number)
error (string)
finished_at (string)
result.category (string)
result.duration_sec (number)
result.metrics (object)
result.raw_output (string)
result.status (string)
result.summary (string)
result.test_id (string)
result.tool (string)
run_id (string)
started_at (string)
status (string)
test_id (string)
- GET /agent/benchmark/targets
List benchmark targets on this node
Discovers block devices, directories and Ceph pools on this node that a benchmark can target.
- Status Codes:
200 OK – block devices, directories and Ceph pools
- Response JSON Object:
block_devices[].free_bytes (integer)
block_devices[].fs_type (string)
block_devices[].mount_point (string)
block_devices[].path (string)
block_devices[].size_bytes (integer)
block_devices[].type (string)
ceph_pools[].free_bytes (integer)
ceph_pools[].fs_type (string)
ceph_pools[].mount_point (string)
ceph_pools[].path (string)
ceph_pools[].size_bytes (integer)
ceph_pools[].type (string)
directories[].free_bytes (integer)
directories[].fs_type (string)
directories[].mount_point (string)
directories[].path (string)
directories[].size_bytes (integer)
directories[].type (string)
- GET /agent/benchmark/tools
List benchmark tools on this node
Reports for each required benchmark tool whether it is installed on this node, with its path and version.
- Status Codes:
200 OK – tool install status
- Response JSON Object:
tools[].installed (boolean)
tools[].name (string)
tools[].path (string)
tools[].version (string)
- GET /benchmarks/baselines
List benchmark baselines
Returns every pinned baseline ordered by category and suite.
- Status Codes:
200 OK – baselines
500 Internal Server Error – baselines query failed
- Response JSON Object:
baselines[].category (string)
baselines[].created_at (string)
baselines[].id (integer)
baselines[].note (string)
baselines[].run_id (string)
baselines[].set_by (string)
baselines[].source (string) – Source distinguishes how the baseline was created.
baselines[].suite (string)
baselines[].target_id (string)
baselines[].target_type (string)
baselines[].template_id (integer) – TemplateID links to the BenchmarkTemplate that was auto-matched during node onboarding. nil when the baseline was manually pinned.
baselines[].updated_at (string)
- POST /benchmarks/baselines
Create a baseline from a run
Pins the run named by run_id in the body as the baseline for its category, suite and target.
- Status Codes:
200 OK – pinned baseline
400 Bad Request – run_id is required in body
404 Not Found – run not found
500 Internal Server Error – baseline upsert failed
- Response JSON Object:
category (string)
created_at (string)
id (integer)
note (string)
run_id (string)
set_by (string)
source (string) – Source distinguishes how the baseline was created.
suite (string)
target_id (string)
target_type (string)
template_id (integer) – TemplateID links to the BenchmarkTemplate that was auto-matched during node onboarding. nil when the baseline was manually pinned.
updated_at (string)
- GET /benchmarks/dashboard
Get the benchmarks dashboard
Returns the latest completed run per category and suite, average score per category and the running count.
- Status Codes:
200 OK – dashboard data
500 Internal Server Error – dashboard query failed
- Response JSON Object:
category_scores (object)
latest_runs[].category (string)
latest_runs[].cgroup_mode (string)
latest_runs[].compared_to_baseline (number) – ComparedToBaseline is the % delta against the pinned baseline for the same (category, suite, target). nil when no baseline exists.
latest_runs[].compared_to_previous (number) – Comparison to the previous run on the same suite/target (delta %). Helps customers see “did the last upgrade make us slower.”
latest_runs[].compared_to_template (number) – ComparedToTemplate is the % delta against the matched hardware template’s expected score. nil when no template matches.
latest_runs[].completed_at (string)
latest_runs[].created_at (string)
latest_runs[].duration_ms (integer)
latest_runs[].error (string)
latest_runs[].hardware_fingerprint[] (integer)
latest_runs[].id (string)
latest_runs[].matched_template_id (integer) – MatchedTemplateID records which template was matched, if any.
latest_runs[].params[] (integer)
latest_runs[].raw_output[] (integer)
latest_runs[].results[].created_at (string)
latest_runs[].results[].higher_is_better (boolean) – HigherIsBetter flips the comparison direction. Latency: lower wins. Throughput: higher wins. Surfaces directly in the UI so we don’t have to special-case metric names client-side.
latest_runs[].results[].id (integer)
latest_runs[].results[].industry_ref_key (string) – IndustryRefKey points at a row in benchmark_industry_refs. Used by the UI to render the “vs vSAN-AF” / “vs gp3” comparison badge.
latest_runs[].results[].metric_key (string)
latest_runs[].results[].metric_name (string)
latest_runs[].results[].run_id (string)
latest_runs[].results[].unit (string)
latest_runs[].results[].value (number)
latest_runs[].score (number) – Score is a normalized 0–100 health score across this run’s results. nil while running. Persisted so the dashboard can render trend lines without re-aggregating result rows.
latest_runs[].started_at (string)
latest_runs[].status (string)
latest_runs[].suite (string)
latest_runs[].suite_name (string)
latest_runs[].target_id (string)
latest_runs[].target_label (string)
latest_runs[].target_type (string)
latest_runs[].triggered_by (string)
latest_runs[].updated_at (string)
latest_runs[].vm_destroyed (boolean)
latest_runs[].vm_destroyed_at (string)
latest_runs[].vm_id (string) – VM lifecycle — populated only for test_vm target runs. Lets the UI show “this number was measured on a fresh VM” and lets ops confirm cleanup happened.
latest_runs[].vm_ip (string)
latest_runs[].vm_name (string)
running_count (integer)
- GET /benchmarks/industry-refs
List benchmark industry references
Returns all industry reference rows ordered by category, suite and metric key.
- Status Codes:
200 OK – industry references
500 Internal Server Error – industry refs query failed
- Response JSON Object:
refs[].category (string)
refs[].key (string)
refs[].metric_key (string)
refs[].notes (string)
refs[].product (string)
refs[].source (string)
refs[].suite (string)
refs[].tier (string)
refs[].unit (string)
refs[].updated_at (string)
refs[].value (number)
refs[].vendor (string)
- POST /benchmarks/run
Launch a benchmark run
Validates cgroup_mode, target_type and suite params, creates the run row and starts the suite in the background.
- Request JSON Object:
category (string) – (required)
cgroup_mode (string)
params[] (integer)
suite (string) – (required)
target_id (string)
target_label (string)
target_type (string)
- Status Codes:
202 Accepted – created run
400 Bad Request – invalid body, cgroup_mode, target_type, params or unknown suite
500 Internal Server Error – launch failed; run included when the row was created
503 Service Unavailable – benchmark engine not initialized
- Response JSON Object:
category (string)
cgroup_mode (string)
compared_to_baseline (number) – ComparedToBaseline is the % delta against the pinned baseline for the same (category, suite, target). nil when no baseline exists.
compared_to_previous (number) – Comparison to the previous run on the same suite/target (delta %). Helps customers see “did the last upgrade make us slower.”
compared_to_template (number) – ComparedToTemplate is the % delta against the matched hardware template’s expected score. nil when no template matches.
completed_at (string)
created_at (string)
duration_ms (integer)
error (string)
hardware_fingerprint[] (integer)
id (string)
matched_template_id (integer) – MatchedTemplateID records which template was matched, if any.
params[] (integer)
raw_output[] (integer)
results[].created_at (string)
results[].higher_is_better (boolean) – HigherIsBetter flips the comparison direction. Latency: lower wins. Throughput: higher wins. Surfaces directly in the UI so we don’t have to special-case metric names client-side.
results[].id (integer)
results[].industry_ref_key (string) – IndustryRefKey points at a row in benchmark_industry_refs. Used by the UI to render the “vs vSAN-AF” / “vs gp3” comparison badge.
results[].metric_key (string)
results[].metric_name (string)
results[].run_id (string)
results[].unit (string)
results[].value (number)
score (number) – Score is a normalized 0–100 health score across this run’s results. nil while running. Persisted so the dashboard can render trend lines without re-aggregating result rows.
started_at (string)
status (string)
suite (string)
suite_name (string)
target_id (string)
target_label (string)
target_type (string)
triggered_by (string)
updated_at (string)
vm_destroyed (boolean)
vm_destroyed_at (string)
vm_id (string) – VM lifecycle — populated only for test_vm target runs. Lets the UI show “this number was measured on a fresh VM” and lets ops confirm cleanup happened.
vm_ip (string)
vm_name (string)
- GET /benchmarks/runs
List benchmark runs
Returns runs ordered by start time, filtered by optional query params, with offset/limit pagination (limit max 200).
- Query Parameters:
category (string) – Filter by category
suite (string) – Filter by suite
target_id (string) – Filter by target ID
status (string) – Filter by run status
target_type (string) – Filter by target type
limit (integer) – Page size (default 50, max 200)
offset (integer) – Page offset
- Status Codes:
200 OK – runs page
500 Internal Server Error – runs query failed
- Response JSON Object:
limit (integer)
offset (integer)
runs[].category (string)
runs[].cgroup_mode (string)
runs[].compared_to_baseline (number) – ComparedToBaseline is the % delta against the pinned baseline for the same (category, suite, target). nil when no baseline exists.
runs[].compared_to_previous (number) – Comparison to the previous run on the same suite/target (delta %). Helps customers see “did the last upgrade make us slower.”
runs[].compared_to_template (number) – ComparedToTemplate is the % delta against the matched hardware template’s expected score. nil when no template matches.
runs[].completed_at (string)
runs[].created_at (string)
runs[].duration_ms (integer)
runs[].error (string)
runs[].hardware_fingerprint[] (integer)
runs[].id (string)
runs[].matched_template_id (integer) – MatchedTemplateID records which template was matched, if any.
runs[].params[] (integer)
runs[].raw_output[] (integer)
runs[].results[].created_at (string)
runs[].results[].higher_is_better (boolean) – HigherIsBetter flips the comparison direction. Latency: lower wins. Throughput: higher wins. Surfaces directly in the UI so we don’t have to special-case metric names client-side.
runs[].results[].id (integer)
runs[].results[].industry_ref_key (string) – IndustryRefKey points at a row in benchmark_industry_refs. Used by the UI to render the “vs vSAN-AF” / “vs gp3” comparison badge.
runs[].results[].metric_key (string)
runs[].results[].metric_name (string)
runs[].results[].run_id (string)
runs[].results[].unit (string)
runs[].results[].value (number)
runs[].score (number) – Score is a normalized 0–100 health score across this run’s results. nil while running. Persisted so the dashboard can render trend lines without re-aggregating result rows.
runs[].started_at (string)
runs[].status (string)
runs[].suite (string)
runs[].suite_name (string)
runs[].target_id (string)
runs[].target_label (string)
runs[].target_type (string)
runs[].triggered_by (string)
runs[].updated_at (string)
runs[].vm_destroyed (boolean)
runs[].vm_destroyed_at (string)
runs[].vm_id (string) – VM lifecycle — populated only for test_vm target runs. Lets the UI show “this number was measured on a fresh VM” and lets ops confirm cleanup happened.
runs[].vm_ip (string)
runs[].vm_name (string)
total (integer)
- GET /benchmarks/runs/{id}
Get a benchmark run
Returns a single benchmark run with its results.
- Parameters:
id (string) – Run ID
- Status Codes:
200 OK – run with results
404 Not Found – run not found
- Response JSON Object:
category (string)
cgroup_mode (string)
compared_to_baseline (number) – ComparedToBaseline is the % delta against the pinned baseline for the same (category, suite, target). nil when no baseline exists.
compared_to_previous (number) – Comparison to the previous run on the same suite/target (delta %). Helps customers see “did the last upgrade make us slower.”
compared_to_template (number) – ComparedToTemplate is the % delta against the matched hardware template’s expected score. nil when no template matches.
completed_at (string)
created_at (string)
duration_ms (integer)
error (string)
hardware_fingerprint[] (integer)
id (string)
matched_template_id (integer) – MatchedTemplateID records which template was matched, if any.
params[] (integer)
raw_output[] (integer)
results[].created_at (string)
results[].higher_is_better (boolean) – HigherIsBetter flips the comparison direction. Latency: lower wins. Throughput: higher wins. Surfaces directly in the UI so we don’t have to special-case metric names client-side.
results[].id (integer)
results[].industry_ref_key (string) – IndustryRefKey points at a row in benchmark_industry_refs. Used by the UI to render the “vs vSAN-AF” / “vs gp3” comparison badge.
results[].metric_key (string)
results[].metric_name (string)
results[].run_id (string)
results[].unit (string)
results[].value (number)
score (number) – Score is a normalized 0–100 health score across this run’s results. nil while running. Persisted so the dashboard can render trend lines without re-aggregating result rows.
started_at (string)
status (string)
suite (string)
suite_name (string)
target_id (string)
target_label (string)
target_type (string)
triggered_by (string)
updated_at (string)
vm_destroyed (boolean)
vm_destroyed_at (string)
vm_id (string) – VM lifecycle — populated only for test_vm target runs. Lets the UI show “this number was measured on a fresh VM” and lets ops confirm cleanup happened.
vm_ip (string)
vm_name (string)
- POST /benchmarks/runs/{id}/baseline
Pin a run as baseline
Upserts the baseline for the run’s category, suite and target to point at this run.
- Parameters:
id (string) – Run ID
- Status Codes:
200 OK – pinned baseline
404 Not Found – run not found
500 Internal Server Error – baseline upsert failed
- Response JSON Object:
category (string)
created_at (string)
id (integer)
note (string)
run_id (string)
set_by (string)
source (string) – Source distinguishes how the baseline was created.
suite (string)
target_id (string)
target_type (string)
template_id (integer) – TemplateID links to the BenchmarkTemplate that was auto-matched during node onboarding. nil when the baseline was manually pinned.
updated_at (string)
- POST /benchmarks/runs/{id}/export-template
Export a template from a run
Creates a learned template from a completed, scored run using its fingerprint and result metrics.
- Parameters:
id (string) – Run ID
- Status Codes:
201 Created – created template
400 Bad Request – run not completed or has no score
404 Not Found – run not found
409 Conflict – template with this category/suite/name already exists
500 Internal Server Error – create failed
- Response JSON Object:
category (string)
created_at (string)
created_by (string)
expected_score (number) – ExpectedScore is the expected overall 0–100 score for this template.
expected_scores[] (integer)
hardware_match[] (integer)
id (integer)
name (string)
notes (string)
source (string) – “manual”, “seeded”, “learned”
suite (string)
updated_at (string)
- GET /benchmarks/runs/{id}/stream
Stream benchmark run progress
Server-Sent Events stream of progress events for a single run.
- Parameters:
id (string) – Run ID
- Status Codes:
200 OK – SSE event stream
400 Bad Request – run id required
500 Internal Server Error – failed to add SSE client
503 Service Unavailable – stream unavailable
- GET /benchmarks/suites
List benchmark suites
Returns the benchmark suite catalog with per-suite duration and resource-mode support flags.
- Status Codes:
200 OK – suite catalog
503 Service Unavailable – benchmark engine not initialized
- Response JSON Object:
suites[].category (string)
suites[].description (string)
suites[].estimated_duration_sec (integer) – EstimatedDurationSec lets the UI show “~2 min” before launch.
suites[].min_versions (object) – MinVersions maps binary name → minimum semver (e.g. “fio” → “3.28”). Checked at run start; mismatch is logged as a warning in raw_output but does not block execution.
suites[].name (string)
suites[].requires_binaries[] (string)
suites[].status (any) – Status defaults to “ready” — runners must opt into “preview” for suites whose execution isn’t wired yet.
suites[].suite (string)
suites[].supports_duration (boolean) – SupportsDuration: catalog-time reflection of schema.Allowed[“duration_sec”].
suites[].supports_resource_mode (boolean) – SupportsResourceMode: true iff the runner honors cgroup_mode.
suites[].target_type (string) – TargetType: “node”, “host”, “cluster”, “pool”, “rbd”, “controlplane”, “test_vm”. The UI uses this to pick the right target picker.
- GET /benchmarks/templates
List benchmark templates
Returns templates ordered by category, suite and name, optionally filtered by category and suite.
- Query Parameters:
category (string) – Filter by category
suite (string) – Filter by suite
- Status Codes:
200 OK – templates list
500 Internal Server Error – templates query failed
- POST /benchmarks/templates
Create a benchmark template
Creates a benchmark template; source defaults to manual.
- Request JSON Object:
category (string) – (required)
expected_score (number) – (required)
expected_scores[] (integer)
hardware_match[] (integer)
name (string) – (required)
notes (string)
source (string)
suite (string) – (required)
- Status Codes:
201 Created – created template
400 Bad Request – invalid body
409 Conflict – template with this category/suite/name already exists
500 Internal Server Error – create failed
- Response JSON Object:
category (string)
created_at (string)
created_by (string)
expected_score (number) – ExpectedScore is the expected overall 0–100 score for this template.
expected_scores[] (integer)
hardware_match[] (integer)
id (integer)
name (string)
notes (string)
source (string) – “manual”, “seeded”, “learned”
suite (string)
updated_at (string)
- GET /benchmarks/templates/export
Export templates in seed format
Returns templates as a JSON array in the seed/templates.json format; download=true sets an attachment header.
- Query Parameters:
source (string) – Filter by source (learned, manual, seeded)
category (string) – Filter by category
suite (string) – Filter by suite
download (string) – true to return as attachment templates.json
- Status Codes:
200 OK – seed entries
500 Internal Server Error – templates query failed
- Response JSON Object:
[] (object)
- GET /benchmarks/templates/{id}
Get a benchmark template
Returns a single benchmark template by ID.
- Parameters:
id (string) – Template ID
- Status Codes:
200 OK – template
404 Not Found – template not found
- Response JSON Object:
category (string)
created_at (string)
created_by (string)
expected_score (number) – ExpectedScore is the expected overall 0–100 score for this template.
expected_scores[] (integer)
hardware_match[] (integer)
id (integer)
name (string)
notes (string)
source (string) – “manual”, “seeded”, “learned”
suite (string)
updated_at (string)
- PUT /benchmarks/templates/{id}
Update a benchmark template
Applies the non-null fields of the request to an existing template and returns it.
- Parameters:
id (string) – Template ID
- Request JSON Object:
expected_score (number)
expected_scores[] (integer)
hardware_match[] (integer)
name (string)
notes (string)
- Status Codes:
200 OK – template
400 Bad Request – invalid body
404 Not Found – template not found
500 Internal Server Error – update failed
- Response JSON Object:
category (string)
created_at (string)
created_by (string)
expected_score (number) – ExpectedScore is the expected overall 0–100 score for this template.
expected_scores[] (integer)
hardware_match[] (integer)
id (integer)
name (string)
notes (string)
source (string) – “manual”, “seeded”, “learned”
suite (string)
updated_at (string)