Skip to content

Local metrics

harness metrics answers what the governed runs cost, delivered and demanded from people, without a paid service and without calling a model (issue #58). It reads the run records and the event chains of one repository, or of every repository of the run registry, and writes the same numbers as JSON, Markdown, CSV, Prometheus text or one self-contained HTML file. The command needs no configuration key.

harness metrics                      # .harness/metrics/metrics.json, metrics.md, metrics.html
harness metrics --format html --output metrics.html --open
harness metrics --format json --since 7d --task TASK --model MODEL --agent PROVIDER
harness metrics --format csv         # one row per run
harness metrics --format prometheus  # text exposition format for a local scrape
harness metrics --all-repos          # every repository of the run registry (runtime.stateDir)

What it contains

Part Content
Totals Runs, tasks, agent calls, tokens, reported and estimated cost, lines, interactions, approvals, human wait, issues resolved, features delivered.
Tokens Input, output, reasoning and cache tokens and cost by agent provider, model, task, phase, call kind and project.
Models The models used, with the source of their cost: reported, estimated or unpriced.
Lines Lines added and removed in the latest ChangeSet of each run, attributed by provenance to an agent invocation or to a person (out of band), or not attributed when provenance.agentSnapshots is off.
Delivery Features delivered (runs that closed) and issues resolved (metadata.issues of the task or a closing keyword such as Closes #12 in its title or intent), linked to the forge of the origin remote and to the pull request the run opened.
Time Per phase, per agent call (mean, median, 90th percentile) and the time the runs waited for a person.
Quality Approved the first time, corrections, requested changes, blocked and rejected runs, pre-authorised approvals applied and findings by rule.
Friction Per task: size, lane, runs, interactions, approvals, wall minutes and wait minutes against the target of its size.
Trends Runs, tokens, cost, interactions and approvals per day and per ISO week.

No per-person indicator. Interactions, approvals and waits are counted per run, task and project; the report contains no actor id (requirement RD-16 of the thesis, kept since scripts/metrics_report.py).

Human wait is the time from each phase that ended BLOCKED to the next event a person caused or the next phase that started.

Costs without a reported price

Providers that report tokens but no cost (Codex, for example) get an estimate from a price table: US dollars per million input, output and cached tokens, by model id (provider/model, the model, or the provider id for calls that recorded no model).

metrics:
  prices:
    MODEL_ID: {input: 1.25, output: 10.0, cache: 0.125}

The values above are placeholders, not current prices: the harness ships no price, because a number nobody configured would be invented. --prices FILE (YAML or JSON) takes precedence over the project's table. An estimate is always reported apart from the reported cost, labelled estimated, and never written to a run or counted against the budget.

The HTML file

The report is written to .harness/metrics/, which Git ignores, so it stays local; --output exports it elsewhere. It opens with a status of the period (CLEAR, ATTENTION or NO_DATA: ATTENTION when any of blocked runs, rejected runs, HIGH or CRITICAL findings in runs that did not close, or open runs whose latest gate failed is above zero; it is an aid to read the report, not a quality certification), then summary cards per dimension, an anchor navigation and the detail groups. The Spanish guide reporte-de-metricas.md explains each section.

One file, inline CSS and inline SVG charts, no script, no font, no image and nothing fetched from the network: it opens offline from the file system. Every chart has a title, a description and a table with the same numbers; identity is never color alone; light and dark color schemes are both defined. Links to issues and pull requests are plain anchors. The friction flow of scripts/demo_flows.py checks in CI that the file has no remote src or href and no script.

Narrative summary

metrics:
  narrative:
    command: [COMMAND, ARGS]
    timeoutSeconds: 300

harness metrics --narrative adds a narrative of the period: one call, on demand only, to the command, which reads a prompt and the totals, quality, friction, models and trends on standard input and prints the summary. It is shown as generated by that command and not verified by the harness. Without the setting the option exits 2.

The dashboard

harness api serve shows the same report in a Metrics tab (see the local API).