JSON and CSV

What it is

Exports turn a terminal result into data that can be archived, compared, plotted, or checked by another program. DoL8 writes a structured JSON result and a CSV timeline through the --json and --csv options.

The current JSON contract includes tool/version/timestamp/CPU/OS metadata, duration and energy metrics, per-domain values, thermal fields, and repeated-run statistics. CSV stores time-series sample rows.

Why it matters

Terminal text is easy to read once but difficult to compare across builds. A stable structured contract lets scripts, dashboards, and notebooks process measurements without scraping presentation text.

A timeline is valuable for understanding when power or temperature changed during a run. It is distinct from a summary: consumers need units, field definitions, and a clear statement of what data was sampled.

How it works

dol8/report.py builds JSON metadata and metric groups; the project validates the shape against docs/schema.json. Timeline CSV uses the columns t_seconds, joules_cum, watts, and temp_c. The poller samples at 100 ms and the exported timeline keeps one representative sample per one-second bucket.

t_seconds,joules_cum,watts,temp_c
0,2.810,28.100,62.0
1,31.220,28.410,63.0
2,59.840,28.620,64.0

Example current JSON shape (values are illustrative):

{
  "metadata": {
    "tool": "DoL8",
    "version": "0.1.0",
    "timestamp": "2026-09-27T12:00:00+00:00",
    "cpu": "CPU model",
    "os": "Linux",
    "measurement": "high-resolution estimate"
  },
  "metrics": {
    "duration_seconds": 14.224,
    "energy_joules": 412.5,
    "energy_kwh": 0.00011458,
    "avg_watts": 29.0,
    "peak_watts": 46.2
  },
  "per_domain": {"PACKAGE": 412.5},
  "statistics": {"runs": 5, "mean_j": 412.5, "stdev_j": 6.2}
}

Use pandas.read_csv("timeline.csv") for plotting and jq '.metrics.energy_joules' result.json for quick shell inspection.

What to build

1. Keep a versioned contract. Extend docs/schema.json alongside dol8/report.py. Add schema_version: 1 before downstream users depend on incompatible shapes.
2. Make provenance useful. Add hostname and kernel metadata if desired, and document which fields can be absent. The current exporter has CPU and OS but not hostname or kernel.
3. Preserve time-series data. Add the sampled timeline to JSON if JSON-only consumers need it; today the JSON converter omits timeline while --csv writes it separately.
4. Define CSV semantics. Document units, bucket selection, missing temperatures, and column order; keep the header stable for pandas and spreadsheet imports.
5. Validate outputs. Test single runs, multi-target results, partial reports, optional sensors, and exact CSV headers against the published schema and examples.

How to use it

Write both a machine-readable summary and the timeline from a measured run. The output values are illustrative.

python -m dol8.cli run workload.py --runs 5 --json result.json --csv timeline.csv

python -c "import pandas as pd; print(pd.read_csv('timeline.csv').describe())"
jq '.metrics.energy_joules, .statistics.confidence' result.json

Edge cases & gotchas

• Multiple-target JSON has a wrapper containing per-file documents and a summary; consumers should handle both shapes.
• Partial or interrupted runs must be identifiable. Do not interpret a missing optional thermal value as zero.
• The CSV timeline currently comes from the last measured run in a multi-run invocation, not every individual run.
• One-second representative buckets can hide brief power peaks; peak watts are tracked separately from the CSV timeline.
• Keep energy in joules and power in watts explicit. Never silently change units or field meanings within the same schema version.

Related