# Experiment Roadmap: Baseline VM Utilization Capture

> This roadmap is filled in for the default experiment included with the Weave Template.
> Use it as a reference when planning your own experiment.

---

## Phase 1: Infrastructure Validation
**Goal:** Confirm FABRIC has the resources you need.

- [x] Check site availability with `fabric_list_sites` — any site with 2 cores free works
- [x] No special hardware required (standard VM)
- [x] Minimal quota: 1 node, 2 cores, 8 GB RAM, 10 GB disk
- [x] Test deploying a single node — confirmed StableOK and SSH access

**Checkpoint:** A single node deploys to StableOK and SSH works.

---

## Phase 2: Software Setup
**Goal:** All required software installs and configures correctly.

- [x] Write `tools/setup-node.sh` — installs `sysstat` and `jq` via apt
- [x] Boot config runs setup-node.sh automatically after provisioning
- [x] Packages install without errors on Ubuntu 22.04
- [x] Single-node experiment — no inter-node connectivity needed

**Checkpoint:** A fresh node installs sysstat and jq via boot config and is ready.

---

## Phase 3: Experiment Implementation
**Goal:** The measurement logic works correctly.

- [x] Implement CPU capture via `vmstat` (1-second intervals, JSON output)
- [x] Implement memory capture via `free` (1-second intervals, JSON output)
- [x] Implement network capture via `/sys/class/net` stats (1-second intervals, JSON output)
- [x] Duration parameter controls capture length
- [x] All output written to `/tmp/experiment_data/` on the VM
- [x] `### PROGRESS:` markers added for all major steps

**Checkpoint:** A single run produces three valid JSON files with the expected number of records.

---

## Phase 4: Pilot Run (Smoke Test)
**Goal:** End-to-end validation with minimal parameters.

- [x] Run with DURATION=10 (10-second capture)
- [x] Verify: vmstat.json, memory.json, network.json all have ~10 records
- [x] Verify: progress messages appear in Build Log
- [x] Verify: data downloads to local `data/` directory
- [x] Verify: summary.json contains CPU, memory, and network statistics
- [x] Verify: slice is deleted after completion

**Checkpoint:** One complete cycle: deploy → measure → collect → analyze → delete.

---

## Phase 5: Full Experiment
**Goal:** Execute the complete experiment with default parameters.

- [x] Run with DURATION=60 (default)
- [x] Monitor progress via Build Log
- [x] Verify all 60 data points per metric file
- [x] Confirm data completeness — no missing or truncated records

**Checkpoint:** 60-second run produces complete, valid data in all three files.

---

## Phase 6: Analysis
**Goal:** Transform raw data into insights.

- [x] Load data in `notebooks/results.ipynb`
- [x] Generate CPU utilization chart (stacked area: user/sys/wait/idle)
- [x] Generate memory utilization chart (used/buff-cache/available over time)
- [x] Generate network throughput chart (rx/tx bytes per second)
- [x] Summary statistics: averages, maximums, sample counts
- [x] Charts saved as PNG images in `data/`

**Checkpoint:** `notebooks/results.ipynb` has complete analysis with three charts.

---

## Phase 7: Documentation & Sharing
**Goal:** Make the experiment reproducible and shareable.

- [x] README describes the experiment and how to run it
- [x] Tutorial notebook walks through customization with Claude
- [x] Spec, roadmap, and testing documents filled in
- [ ] Publish to Artifact Manager if sharing: `/publish-artifact`

**Checkpoint:** Another researcher could reproduce the experiment from the weave.

---

## Future Enhancements

- [ ] Multi-site comparison — run the same baseline at multiple FABRIC sites
- [ ] Longer duration observations — 1-hour or 24-hour captures
- [ ] Loaded baselines — measure utilization under synthetic CPU/memory/IO stress
- [ ] Additional metrics — disk I/O, process counts, system load averages
