> ## Documentation Index > Fetch the complete documentation index at: https://docs.fallow.tools/llms.txt > Use this file to discover all available pages before exploring further. # Runtime coverage > Merge runtime coverage into fallow health to see which functions actually execute in production-like traffic, which stay cold, and which hot paths changed. Runtime 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. Runtime coverage answers a different question: which functions actually executed when your deployed app handled real traffic. ```bash theme={null} fallow license activate --trial --email you@company.com fallow coverage setup fallow health --runtime-coverage ./coverage ``` ## What it tells you When runtime 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: | Verdict | Meaning | | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `safe_to_delete` | Statically unused AND V8 tracked AND zero invocations. The strongest delete signal fallow emits. | | `review_required` | Statically used but never invoked in production. Needs a human look: could be seasonal, error-path-only, or legitimately dead. | | `low_traffic` | Invoked 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_unavailable` | V8 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. | | `active` | Invoked in production above the low-traffic threshold. Not dead. | | `unknown` | Forward-compat sentinel returned by newer sidecars. Rare. | Fallow also surfaces: | Output | Meaning | | :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `verdict` | Overall report status: `clean`, `cold-code-detected`, `hot-path-touched`, `license-expired-grace`, or `unknown`. Promotes `hot-path-touched` over `cold-code-detected` in PR-review contexts when `--diff-file` (or `--changed-since`) is set. | | `signals` | Array of every signal the post-processing pass detected, independent of `verdict` (which is the single most actionable signal under the current context). Ordered severity-descending; omitted entirely when empty. A typical PR run emits `["cold-code-detected", "hot-path-touched"]` together when both apply. | | `summary` | Aggregate counts (`functions_tracked`, `functions_hit`, `functions_unhit`, `functions_untracked`, `coverage_percent`) plus `trace_count`, `period_days`, `deployments_seen`, and an optional `capture_quality` block (`window_seconds`, `instances_observed`, `lazy_parse_warning`, `untracked_ratio_percent`) on protocol-0.3+ sidecars that flags short-window captures where lazy-parsed scripts may not appear. | | `findings` | Cold or unresolved functions with a per-finding suppression `id` (`fallow:prod:`, hashes the current line), an optional cross-surface `stable_id` (`fallow:fn:`, hashes file + name + start line; one value per function across findings / hot-paths / blast-radius / importance and across V8/Istanbul/oxc producers), an optional content-digest `source_hash` (line-move-immune: a moved-but-unedited function keeps the same value, so baselines stay suppressed across a pure line shift), `line`, per-finding `verdict`, `confidence`, supporting `evidence`, machine-readable `actions`, and an optional `discriminators` block exposing the inputs behind the verdict (`tracking_state` of `called` / `never_called` / `untracked`, `invocation_ratio`, the `low_traffic_threshold` and `min_observation_volume` in effect, and `trace_count` with `meets_observation_volume`) so an agent can reproduce the verdict without re-deriving it. | | `hot_paths` | The busiest runtime functions with a stable `id`, an optional `stable_id` join key, `line`, `invocations`, and `percentile` rank. | | `actionable` | Whether the report carries enough evidence to act on, with `actionability_reason` and `actionability_verdict`. A capture with no tracked functions reports a first-class `insufficient_evidence` verdict rather than being read as cold. This is a non-action floor: it never gates a positive verdict or a confidence score. | | `provenance` | Context block describing the data behind the report (`data_source`, `is_production`, `freshness_days`, `untracked_ratio`, `unresolved_ratio`, `stale`, `stale_after_days`). Context only; it never gates a verdict. | | `watermark` | Trial/license grace marker applied when paid-feature access is in warning mode. | | `warnings` | Non-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: ```json theme={null} "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: | Flag | Default | Effect | | :-------------------------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--min-observation-volume ` | 5000 | Minimum 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 ` | 0.001 | Fraction 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: | Surface | Flag | Input | Answers | Paid | | :----------------------- | :------------------- | :------------------------------------------- | :---------------------------------------------------------------------------- | :--- | | Static reachability gaps | `--coverage-gaps` | none | Which runtime files and exports have no transitive test path? | no | | Exact CRAP scoring | `--coverage` | Istanbul JSON | How covered is each function for CRAP calculation? | no | | Runtime runtime coverage | `--runtime-coverage` | V8 directory, V8 JSON file, or Istanbul JSON | Which 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 `--runtime-coverage` when you want runtime evidence about real execution paths. ## Accepted input `fallow health --runtime-coverage ` accepts: | Input | Example | | :------------------------------------- | :------------------------------------------------------ | | 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. ## Production coverage: getting source attribution Production runtime coverage is collected against your **built bundle** (a Next.js `.next/server/chunks/*.js`, an Electron `out/main/index.js`, a NestJS `dist/`, a minified browser bundle). Those positions cannot map back to your TypeScript or JSX source on their own, so unless you take one of the two steps below the cloud records every function as `unresolved` and `fallow coverage analyze --cloud` surfaces no attributable findings (a `coverage_unresolved` warning explains why). Pick one: * **Upload source maps** (for V8 coverage). After the build, upload the `.map` files as a CI step so the cloud can map bundle positions back to source: ```bash theme={null} fallow coverage upload-source-maps --dir # e.g. dist, .next, out ``` The maps must be uploaded for the same commit the coverage was collected on. See [`fallow coverage`](/cli/coverage) for the flags, per-commit SHA matching, and CI snippets. When `fallow coverage analyze --cloud` finds built `.map` files locally that have not been uploaded, it prints the exact command to run. * **Instrument at build time with Istanbul** (no maps needed). `oxc-coverage-instrument` rewrites your source so the original file and line positions are embedded in the coverage itself, so nothing has to be remapped afterward. This is the path the fallow project dogfoods. ## First-run workflow The intended first-run path is: 1. Start a trial or activate a license with [`fallow license`](/cli/license). 2. Run [`fallow coverage setup`](/cli/coverage). 3. Follow the generated recipe in `docs/collect-coverage.md`. 4. Re-run `fallow coverage setup` or `fallow health --runtime-coverage ` 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 --runtime-coverage`. ## Review changed code Runtime coverage becomes especially useful during change review: ```bash theme={null} fallow health --changed-since main --runtime-coverage ./coverage ``` When changed files touch hot runtime code, fallow can upgrade the overall verdict to `hot-path-touched`. That gives PR review a stronger signal than static complexity alone. For tighter line-level scoping, pass a pre-computed unified diff: ```bash theme={null} git diff --unified=0 main...HEAD > /tmp/pr.diff fallow health --runtime-coverage ./coverage --diff-file /tmp/pr.diff ``` A hot function is then flagged only when the diff modifies a line inside its `[start_line, end_line]` range, instead of matching the whole file. The bundled GitHub Action and GitLab CI template already pre-compute the diff and pass it through, so PR comments only highlight hot paths the change actually touches. Hot-path matching needs protocol 0.5 or newer in the sidecar (older sidecars only report a start line, so fallow falls back to file-level scoping). ## Trial and watermark behavior Runtime 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 Runtime coverage merges into the standard health report and output formats. Start a trial, inspect license status, refresh, or deactivate a local token.