Skip to content

ADR-001: Sysbench Multi-Workload Integration

  • Status: Accepted
  • Date: 2026-04-25

Context

The project previously treated Sysbench OLTP as a single benchmark profile (oltp_read_write). This created ambiguity when comparing sessions that are semantically different (oltp_read_only, oltp_read_write, oltp_write_only) but share the same output path and session metadata shape.

The ambiguity impacted:

  • Reproducibility of tuning and evaluation artifacts.
  • Fair comparison between default, BO, and PBT under different transaction mixes.
  • Downstream automation (analysis, aggregation, and reporting).

Decision

We introduce explicit Sysbench workload mode handling end-to-end:

  1. Canonical modes:

  2. oltp_read_only

  3. oltp_read_write

  4. oltp_write_only

  5. Session metadata:

  6. Add tuning_session.sysbench_workload for Sysbench runs.

  7. Backward-compatible fallback for legacy sessions: oltp_read_write.

  8. CLI contracts:

  9. Add --sysbench-workload to tuner, BO runner, and evaluation CLI.

  10. Use precedence in evaluation: CLI override -> session metadata -> default.

  11. Output partitioning:

  12. PBT: results/oltp/{sysbench_workload}/pbt_runs/{tier}/...

  13. BO: results/oltp/{sysbench_workload}/bo_runs/{tier}/...

  14. Evaluation: results/oltp/{sysbench_workload}/comparisons/{tier}/...

  15. Executor behavior:

  16. SysbenchExecutor validates script mode and uses it as Sysbench Lua script selector.

Consequences

Positive:

  • Clear, machine-readable differentiation between Sysbench workload classes.
  • Reduced risk of cross-mode artifact contamination.
  • Stronger methodological reproducibility for research comparisons.

Trade-offs:

  • Result directory hierarchy becomes deeper for Sysbench workflows.
  • Historical scripts that hardcode old paths may need updates.

Compatibility and Migration

  • Legacy sessions lacking sysbench_workload continue to load with default oltp_read_write.
  • Tier resolution from legacy path layout remains supported.
  • Non-Sysbench benchmarks (TPC-H/custom workloads) keep existing behavior.

Rejected Alternatives

  1. Path-only encoding of workload mode without session metadata.

  2. Rejected because session files must remain self-describing.

  3. Separate executors per Sysbench mode.

  4. Rejected because one validated executor with script selection is simpler and less error-prone.

  5. Numeric mode IDs.

  6. Rejected because script names are more readable and map directly to Sysbench CLI semantics.