feat: add multimodal benchmark history and observability

.gitignore

@@ -18,6 +18,7 @@ htmlcov/
 *.log
 artifacts/
 dist/
+node_modules/
 .DS_Store
 uv.lock
 profile.json

README.md

@@ -203,6 +203,7 @@ Log File: /home/user/Code/aiperf/artifacts/granite4:350m-openai-chat-concurrency
 - [Multi-Run Confidence](docs/tutorials/multi-run-confidence.md) - Confidence intervals across repeated runs
 - [Profile Exports](docs/tutorials/working-with-profile-exports.md) - Post-processing with Pydantic models
 - [Visualization and Plotting](docs/tutorials/plot.md) - PNG charts and multi-run comparison
+- [Benchmark History Dashboard](docs/tutorials/history-dashboard.md) - GreptimeDB-backed Vue history and cross-run metric curves
 - [Auto-Plot After Profile](docs/tutorials/auto-plot.md) - Run `aiperf plot` automatically after `aiperf profile`
 - [GPU Telemetry](docs/tutorials/gpu-telemetry.md) - DCGM metrics collection
 - [OTel + MLflow Live Telemetry](docs/tutorials/otel-mlflow.md) - Stream metrics to OTel and MLflow in real time
@@ -214,6 +215,7 @@ Log File: /home/user/Code/aiperf/artifacts/granite4:350m-openai-chat-concurrency
 | Document | Purpose |
 |----------|---------|
 | [Architecture](docs/architecture.md) | Three-plane architecture, core components, credit system, data flow |
+| [History Service Design](docs/dev/history-service-design.md) | GreptimeDB schema, import lifecycle, API/UI boundary, and failure semantics |
 | [CLI Options](docs/cli-options.md) | Complete command and option reference |
 | [Metrics Reference](docs/metrics-reference.md) | All metric definitions, formulas, and requirements |
 | [Environment Variables](docs/environment-variables.md) | All `AIPERF_*` configuration variables |

docs/architecture.md

@@ -369,3 +369,78 @@ sequenceDiagram
         F->>M: log_metric(live.<name>, delta)
     end
 ```
+
+## Multimodal benchmark extension layer
+
+Long-running media sessions use protocol-based extension points rather than embedding
+WebRTC, WebSocket, or framework-specific logic in the core runner.
+
+`StreamBenchmarkRunner` consumes a `StreamWorkloadProtocol` and a
+`StreamTransportAdapterProtocol`, then emits transport-independent `SessionResult`
+records. `ObservationLifecycle` implements the same phase callbacks for any transport
+and joins those client phase windows with `ServerMetricsResults` by `benchmark_id`.
+
+`aiperf profile --stream-config` selects this mode before the request/response service
+graph is built. `ContractStreamWorkload` drives the shared runner through either the
+built-in WebRTC or MessagePack WebSocket adapter. The profile controller owns those
+event-loop-bound media connections and wraps them with the same server-metrics
+collectors and aggregation models used by the multiprocess request pipeline.
+
+```mermaid
+flowchart LR
+    CLI[aiperf profile --stream-config] --> CFG[StreamProfileConfig]
+    CFG --> CONTRACT[BenchmarkContract]
+    CONTRACT --> WORKLOAD[ContractStreamWorkload]
+    WORKLOAD --> RUNNER[StreamBenchmarkRunner]
+    RUNNER --> ADAPTER[WebRTC or WebSocket adapter]
+    ADAPTER --> TARGET[Target service]
+    TARGET --> AGENT[AIPerf resource agent]
+    AGENT -->|1 s samples / 15 s batches| HISTORY[History API]
+    TARGET --> PROM[Prometheus endpoint]
+    PROM --> COLLECTOR[ServerMetricsDataCollector]
+    RUNNER --> ARTIFACTS[Sessions and events]
+    COLLECTOR --> NORMALIZED[Raw and normalized metrics]
+    ARTIFACTS --> MANIFEST[Observation manifest]
+    NORMALIZED --> MANIFEST
+```
+
+Native Prometheus aggregates are converted to `SourceMetricObservation` records and
+processed by versioned `SemanticMetricMapping` rules. The mapper produces a derived
+view while raw server-metrics exports remain authoritative. See
+[Multimodal Generation and Observability Contracts](benchmark-modes/multimodal-generation.md)
+for interfaces, artifact semantics, and current integration status.
+
+## Benchmark history service
+
+The standalone `aiperf history` command is outside the per-run ZMQ service graph. It
+indexes completed artifacts, accepts strict active resource batches, writes to a required
+GreptimeDB backend, and exposes a FastAPI API plus a bundled Vue application. JSON and
+JSONL artifacts remain replayable benchmark facts; GreptimeDB is the only query path used
+by the API and UI.
+
+```mermaid
+flowchart LR
+    P[Profile exports] --> IMPORT[History importer]
+    S[Stream artifacts] --> IMPORT
+    A[Target-side AIPerf resource agent] -->|Versioned batch POST| API
+    IMPORT --> RUNS[(GreptimeDB runs)]
+    IMPORT --> POINTS[(GreptimeDB metric points)]
+    RUNS --> API[History FastAPI]
+    POINTS --> API
+    API --> VUE[Vue and ECharts]
+```
+
+Metric points use framework-neutral dimensions (`run_id`, metric, statistic, scope,
+phase, session, sample, device, and source). Target-specific parsing stops at artifact
+normalization; neither API queries nor frontend rendering branch on TeleFuser or SGLang.
+Artifact replacement preserves source-timestamped `resource` points received during the
+run. The agent is common to both targets and includes the configured PID's descendants.
+It also records machine Ethernet and RDMA receive/transmit rates plus discoverable link
+capacity under one canonical network metric.
+GreptimeDB startup failures propagate and prevent the service from becoming ready.
+There is no SQLite, in-memory, or direct-filesystem query fallback.
+
+See [Benchmark History Service Design](dev/history-service-design.md) for ownership,
+schema, revision, query, recovery, and extension decisions, and
+[Benchmark History Dashboard with GreptimeDB](tutorials/history-dashboard.md) for the
+operator workflow.