# Experiment Specification: Baseline VM Utilization Capture

> This spec describes the default experiment included with the Weave Template.
> Use it as a reference when filling in your own spec with `/design-experiment`.

---

## 1. Research Overview

- **Research Question**: What is the baseline CPU, memory, and network utilization of a freshly provisioned Ubuntu 22.04 VM on FABRIC under idle conditions?
- **Hypothesis**: A minimal VM (2 cores, 8 GB RAM) at idle should show <5% CPU usage (user+system), <30% memory usage, and negligible network throughput (<10 KB/s).
- **Domain**: Cloud/testbed infrastructure — baseline performance characterization
- **Background**: Before running real experiments on FABRIC, it's useful to establish baseline resource utilization. This helps identify anomalies, validate that the VM is healthy, and provides a reference point for comparing loaded vs. idle performance.

---

## 2. Experiment Type

- **Category**: Measurement
- **Methodology**: Time-series observation — capture system metrics at 1-second intervals for a configurable duration
- **Repetitions**: 1 (single run per invocation; re-run the weave for additional samples)

---

## 3. Infrastructure Requirements

### Nodes
| Role | Count | Cores | RAM (GB) | Disk (GB) | Image | Special Hardware |
|------|-------|-------|----------|-----------|-------|-----------------|
| Measurement target | 1 | 2 | 8 | 10 | default_ubuntu_22 | None |

### Networking
- **Topology**: None (single node, no inter-node communication)
- **Network type**: None
- **Cross-site**: No
- **External access needed**: No (management network SSH only)
- **Bandwidth requirements**: N/A

### Software Stack
- **OS packages**: `sysstat`, `jq`
- **Python packages**: None (uses standard shell tools)
- **Containers**: None
- **Custom software**: None

---

## 4. Experiment Parameters

- **Independent variables**: Duration (seconds)
- **Dependent variables**: CPU % (user, system, idle, wait), memory usage (bytes), network throughput (rx/tx bytes/sec)
- **Control variables**: VM size (2 cores, 8 GB, 10 GB), OS image (Ubuntu 22.04), no user workload

| Parameter | Values / Range | Unit |
|-----------|---------------|------|
| Duration  | 10–3600 (default: 60) | seconds |

- **Total configurations**: 1
- **Runs per configuration**: 1
- **Total experiment runs**: 1

---

## 5. Data Collection

- **Metrics**:
  - CPU: user %, system %, idle %, I/O wait % (via `vmstat`)
  - Memory: total, used, free, shared, buff/cache, available (via `free`)
  - Network: rx bytes/sec, tx bytes/sec per interface (via `/sys/class/net`)
- **Collection method**: Shell scripts running on the VM, output as newline-delimited JSON
- **Collection frequency**: Every 1 second for the configured duration
- **Data format**: JSON arrays (one file per metric type)
- **Storage location**: `data/` subdirectory — `vmstat.json`, `memory.json`, `network.json`
- **Expected data volume**: ~50 KB for a 60-second run

---

## 6. Success Criteria

- **Minimum viable result**: All three JSON files (vmstat, memory, network) contain at least `DURATION` records each
- **Expected outcome**: CPU idle >90%, memory used <30%, network throughput <10 KB/s
- **Statistical requirements**: None — single observational run
- **Comparison baselines**: These results *are* the baseline for future experiments

---

## 7. Constraints & Risks

- **Time budget**: ~10 minutes total (5 min provisioning + DURATION + 1 min collection/analysis)
- **Resource limits**: 1 node, 2 cores — minimal FABRIC quota usage
- **Site preferences**: Any site (`auto` selection)
- **Lease duration**: <1 hour (slice is deleted after experiment completes)
- **Known risks**: Site may be at capacity; SSH may take time to become available
- **Mitigation strategies**: `auto` site selection picks an available site; `wait_ssh()` retries automatically

---

## 8. Execution Plan

- **Deployment mode**: Single slice, fully automated
- **Autonomy level**: Fully autonomous — no user intervention needed after clicking Run
- **Error recovery**: Fail and report — no retries (simple enough to just re-run)
- **Checkpoint/resume**: Not needed (short experiment)
- **Output**: Results in `data/` directory; open `notebooks/results.ipynb` for visualizations

### Run States

The weave must report one of these four states after the user clicks **Run**:

| State | Meaning |
|-------|---------|
| `stopped` | Initial state — the weave has not been run, or a previous run completed and was reset |
| `running` | The weave script is actively executing (set immediately when the user clicks Run) |
| `done` | The script finished successfully |
| `error` | The script exited with a non-zero code or encountered a fatal error |

**Transition diagram:**
```
stopped ──[Run clicked]──> running ──[exit 0]──> done
                                   ──[exit ≠0]──> error
done   ──[reset/re-run]──> running
error  ──[reset/re-run]──> running
```

- There is no "deploying" state. When the user clicks Run, the state must transition directly to `running`.
- The state should be stored in a field accessible to the UI (e.g., `data/metadata.json` or `weave.json`).
