Files
miner/docs/implementation/03-response-engine-comparability.md
T

89 lines
4.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Response Summary (03): Engine `Found` hash_count Included for Accurate Metrics, Logging/CLI Updates, and Dashboards
This document summarizes the implementation that augments the mining engine’s result reporting so that the final “Found” event carries the per-thread `hash_count`. This enables accurate global, per-job, and per-thread metrics (including rates), improving Grafana comparisons between engines (e.g., `cpu-baseline` vs `cpu-fast`).
## Overview
- Extended the engine result type so `Found` includes `{ candidate, hash_count }`.
- Updated both CPU engines to return the final `hash_count` on `Found`.
- Modified the service to forward and accumulate this count:
- Global totals (`miner_hashes_total`)
- Per-job totals (`miner_job_hashes_total{engine,job_id}`)
- Per-thread totals (`miner_thread_hashes_total{engine,job_id,thread_id}`)
- Per-thread hash-rate gauge via delta-rate with EMA smoothing
- No changes to the node-facing HTTP API.
## Changes Implemented
### 1) Engine API
- File: `crates/engine-cpu/src/lib.rs`
- Updated `EngineStatus`:
- Before: `Found(Candidate)`
- Now: `Found { candidate: Candidate, hash_count: u64 }`
- Other variants (`Exhausted`, `Cancelled`, `Running`) retain their `hash_count` shape for consistency.
### 2) Engines
- Files: `crates/engine-cpu/src/lib.rs`
- `BaselineCpuEngine`:
- On discovering a solution, returns `EngineStatus::Found { candidate, hash_count }` with the accumulated count for the current range.
- `FastCpuEngine`:
- Same behavior as baseline but using the incremental path (init once with `init_worker_y0`, then `step_mul` per nonce).
### 3) Service
- File: `crates/miner-service/src/lib.rs`
- `mine_range_with_engine`:
- Updated to extract `hash_count` from `EngineStatus::Found` and include it in the `ThreadResult`.
- `update_from_results`:
- Accumulates `hash_count` into:
- `total_hash_count`
- Global/engine-aware per-job/per-thread counters
- Per-thread delta-rate calculation with EMA smoothing now uses the `hash_count` from `Found` as well.
- All metric updates are engine-aware and job-/thread-labeled where appropriate.
### 4) Metrics
- No new metrics introduced; existing labeled series are now fully accurate for winning threads:
- Global:
- `miner_jobs_total{status}`
- `miner_hashes_total`
- `miner_hash_rate`
- Engine-/job-aware:
- `miner_job_hashes_total{engine,job_id}`
- `miner_job_hash_rate{engine,job_id}`
- `miner_job_status{engine,job_id,status}` (IntGauge)
- `miner_jobs_by_engine_total{engine,status}`
- Engine-/job-/thread-aware:
- `miner_thread_hashes_total{engine,job_id,thread_id}`
- `miner_thread_hash_rate{engine,job_id,thread_id}` (EMA-smoothed)
## Compatibility
- The public HTTP API (endpoints and payloads) remains unchanged.
- Engine abstraction change is internal to the workspace; service updated accordingly.
- Works with both `cpu-baseline` and `cpu-fast`, enabling apples-to-apples comparisons using the `engine` label in Grafana.
## Build and Run
- Build (release):
- `cargo build -p miner-cli --release`
- Run (baseline, no metrics):
- `cargo run -p miner-cli -- --port 9833 --engine cpu-baseline`
- Run (fast engine, with metrics):
- `cargo run -p miner-cli -- --port 9833 --engine cpu-fast --metrics-port 9900`
- Scrape: `http://localhost:9900/metrics`
## Verification
- Compile-time: Verified in release mode after updating the service to consume the new `Found` shape.
- Runtime: The winning thread’s final work is now counted in totals and informs the per-thread rate EMA, reducing undercounting and improving rate fidelity.
## Notes and Next Steps
- With winning-thread `hash_count` included, Grafana dashboards can fairly compare engines across global/job/thread metrics.
- Next logical optimization steps:
- Add correctness tests that compare baseline vs fast engine outcomes on small ranges (golden tests).
- Add benchmark harness to quantify nonces/sec improvements.
- Implement Montgomery multiplication in `pow-core` and switch `cpu-fast` to it for further speedups.