Skip to content

v0.4.1

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 16 Jul 08:33
v0.4.1
5e4107c
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Umami Compass 0.4.1 — Trustworthy performance breakdowns

Umami Compass 0.4.1 is a focused patch release that prevents worst-page and environment rankings from being dominated by one-off Core Web Vital measurements. It adds a defensible sample guard, validates upstream percentile rows, and reports when Umami's own candidate limits make a filtered ranking incomplete.

Important

get_performance_breakdown now requires at least 20 samples per row by default for page, page-title, device, and browser rankings. Set minimumSampleCount explicitly to tighten the guard or use 1 to include every otherwise valid row. The tool surface and read-only security model are unchanged.

Fixes

  • Exclude rows with fewer than 20 measurements from p75 rankings by default.
  • Validate that row counts are positive integers and that p50 ≤ p75 ≤ p95 with nonnegative values.
  • Reject missing names, missing counts, malformed percentiles, and impossible percentile ordering instead of silently ranking those rows.
  • Distinguish genuinely empty ranges from insufficient_sample_size.
  • Report the effective sample threshold and separate malformed-row and undersized-row counts.
  • Apply the same quality policy consistently to page, page-title, device, and browser breakdowns.

Candidate coverage

Umami 3.2 sorts page-level performance candidates by p75 and caps page, page-title, and browser results at 500 before Compass receives them.

  • Compass now reports the upstream candidate limit, how many candidates were evaluated, and whether coverage may be truncated.
  • If all fully observed candidates are undersized, the result is empty with emptyReason: "insufficient_sample_size".
  • If the 500-row cap prevents a complete conclusion, the result uses dataStatus: "unknown" instead of presenting the filtered ranking as exhaustive.
  • Device results remain uncapped by this Umami route and report candidateItemLimit: null.

Why 20 samples?

The default is an exploratory p75 quality guard, not a claim of statistical significance. With 20 observations, the upper quartile represented by p75 contains at least five measurements, which prevents a single extreme visit from deciding the worst-page ranking. Callers with stricter evidence requirements can raise the threshold.

Safety and data quality

  • All 37 tools remain read-only.
  • The change adds no upstream requests and exposes no additional identifiers or event/session payloads.
  • Invalid upstream aggregate rows are separated from valid but undersized rows.
  • Result metadata preserves uncertainty when upstream candidate coverage is incomplete.
  • Ranking remains deterministic: p75 descending, then sample count descending, then name.

Upgrade

npx --yes --prefer-online umami-compass@latest

Pin this exact patch when reproducibility matters:

npx --yes umami-compass@0.4.1

Restart the MCP process or client after upgrading so it discovers the updated tool schema.

Compatibility and verification

  • Umami Cloud and self-hosted Umami 3.2+.
  • Node.js 22 or newer.
  • 109 automated tests plus lint, typecheck, build, package smoke testing, and CI on Node.js 22, 24, and 26.
  • Packed-package verification covers CLI version, MCP initialization, and the 14-tool default surface.
  • Official MCP Registry metadata validation completed before publication.
  • npm publication includes SLSA provenance.

Release links

Assets 2
Loading