Skip to main content
Production coverage adds a runtime layer on top of fallow health. Static analysis can tell you which exports have no references and which files are not test-reachable. Production coverage answers a different question: which functions actually executed when your deployed app handled real traffic. 
fallow license activate --trial --email you@company.com
fallow coverage setup
fallow health --production-coverage ./coverage

​
What it tells you

When production coverage is enabled, fallow merges runtime evidence into the existing health report and assigns each function a per-finding verdict combining the static reachability signal with observed production invocations:
VerdictMeaning
safe_to_deleteStatically unused AND V8 tracked AND zero invocations. The strongest delete signal fallow emits.
review_requiredStatically used but never invoked in production. Needs a human look — could be seasonal, error-path-only, or legitimately dead.
low_trafficInvoked in production, but below the configured --low-traffic-threshold ratio of total trace count (spec default 0.1%). Effectively dead for the observed period.
coverage_unavailableV8 could not track the function (lazy-parsed, worker-thread isolate, dynamic eval, or the source map did not resolve). Advisory, not a dead-code signal.
activeInvoked in production above the low-traffic threshold — not dead.
unknownForward-compat sentinel returned by newer sidecars. Rare.
Fallow also surfaces:
OutputMeaning
verdictOverall report status: clean, cold-code-detected, hot-path-changes-needed, license-expired-grace, or unknown.
summaryAggregate counts (functions_tracked, functions_hit, functions_unhit, functions_untracked, coverage_percent) plus trace_count, period_days, deployments_seen.
findingsCold or unresolved functions with a stable id (fallow:prod:<hash>), line, per-finding verdict, confidence, supporting evidence, and machine-readable actions.
hot_pathsThe busiest runtime functions with a stable id, line, invocations, and percentile rank.
watermarkTrial/license grace marker applied when paid-feature access is in warning mode.
warningsNon-fatal merge diagnostics, for example partial source-map remapping.
Every finding carries an evidence block so the “why” behind a verdict is machine-readable without re-deriving it: 
"evidence": {
  "static_status": "used",
  "test_coverage": "not_covered",
  "v8_tracking": "tracked",
  "untracked_reason": null,
  "observation_days": 30,
  "deployments_observed": 14
}

​
Confidence thresholds

Two flags tune how aggressively fallow applies verdicts:
FlagDefaultEffect
--min-observation-volume <N>5000Minimum total trace volume before the sidecar is allowed to emit high-confidence safe_to_delete or review_required verdicts. Below this threshold, confidence is capped at medium to protect against overconfident verdicts on new or low-traffic services.
--low-traffic-threshold <RATIO>0.001Fraction of trace_count below which an invoked function is classified low_traffic rather than active. Expressed as a decimal (0.001 = 0.1%).

​
Static coverage vs runtime coverage

These three surfaces live side by side inside fallow health, but they answer different questions:
SurfaceFlagInputAnswersPaid
Static reachability gaps--coverage-gapsnoneWhich runtime files and exports have no transitive test path?no
Exact CRAP scoring--coverageIstanbul JSONHow covered is each function for CRAP calculation?no
Runtime production coverage--production-coverageV8 directory, V8 JSON file, or Istanbul JSONWhich functions actually ran, which stayed cold, and which hot paths changed?yes
Use --coverage-gaps when you want to find untested code. Use --coverage when you want better CRAP scores. Use --production-coverage when you want runtime evidence about real execution paths.

​
Accepted input

fallow health --production-coverage <path> accepts:
InputExample
V8 dump directory./coverage created with NODE_V8_COVERAGE=./coverage
Single V8 JSON file./coverage/12345.json
Single Istanbul coverage map JSON file./coverage/coverage-final.json
If a V8 dump includes Node’s source-map-cache, fallow remaps supported source-map URLs before analysis, including file paths, relative paths, webpack://..., and vite://.... Unsupported virtual schemes fall back safely to raw V8 handling instead of failing the whole run.

​
First-run workflow

The intended first-run path is:
  1. Start a trial or activate a license with fallow license.
  2. Run fallow coverage setup.
  3. Follow the generated recipe in docs/collect-coverage.md.
  4. Re-run fallow coverage setup or fallow health --production-coverage <path> once coverage exists.
fallow coverage setup is resumable. It checks license state, installs or locates fallow-cov, writes a framework-specific collection recipe, detects an existing coverage artifact when present, and then hands off into fallow health --production-coverage.

​
Review changed code

Production coverage becomes especially useful during change review: 
fallow health --changed-since main --production-coverage ./coverage
When changed files touch hot runtime code, fallow can upgrade the overall verdict to hot-path-changes-needed. That gives PR review a stronger signal than static complexity alone.

​
Trial and watermark behavior

Production coverage is a paid feature with a trial flow. Verification is offline against a compiled-in Ed25519 public key; only fallow license activate --trial and fallow license refresh require network access. If a license is expired but still inside the grace window, fallow keeps the analysis available but annotates the output with a watermark. Once the hard-fail window is exceeded, paid features are blocked until the license is refreshed.

​
See also

fallow health

Runtime coverage merges into the standard health report and output formats.

License commands

Start a trial, inspect license status, refresh, or deactivate a local token.