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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
GET /benchmarks/suites

List benchmark suites

Returns the benchmark suite catalog with per-suite duration and resource-mode support flags.

Status Codes:
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:
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:
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:
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:
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:
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)