Dashboarding & Team Adoption

A performance budget that no one can see is a budget that no one defends. The gate may be green in CI, but the moment a regression slips through a tolerance window, or a vendor tag doubles in size, the only people who notice are the ones already running synthetic audits by hand. Dashboarding closes that gap: it turns the raw stream of lab and field measurements produced by the CI machinery in the Lighthouse CI & WebPageTest Integration reference into a trend a frontend lead, an engineering manager, and an on-call engineer can each read at their own altitude. Adoption is the harder half — a dashboard nobody opens and an alert everyone mutes are worse than nothing, because they manufacture the illusion of coverage. This reference treats both as one engineering contract: the data pipeline that feeds the charts, the charts themselves, the alerts that fire on regression, and the team rituals that make the whole apparatus load-bearing.

The work divides into three coupled responsibilities. First, visualization: getting CI and real-user data into a store and onto panels that answer a specific question for a specific audience. Second, infrastructure: standing up the server that retains every run and the dashboards that query it. Third, adoption: ownership, review rituals, and a blameless triage process that keeps the gate trusted rather than resented. Each child reference below owns one of these; this page is the architecture that connects them. The recurring failure across every team that abandons a budget is never that the numbers were wrong — it is that the numbers were invisible, unowned, or unread, and this page is organized around preventing each of those three deaths.

Architecture Overview

Two data sources feed every performance dashboard. Synthetic runs from CI produce deterministic lab metrics on a fixed cadence, and Real User Monitoring (RUM) beacons produce field metrics at whatever percentile your traffic generates. Both land in durable storage, both are queried by a visualization layer, and both can trigger alerts that route into the rituals a team actually runs. The distinction matters because the two streams answer different questions: the lab stream tells you what a controlled device on a controlled network experiences on every commit, and the field stream tells you what your P75 user actually lived through last hour. A dashboard that shows only one is half-blind. The diagram traces that flow end to end.

The visualization tier is built in Visualizing Budget Trends with Grafana, the storage and server tier in Self-Hosting the Lighthouse CI Server, and the human tier — ownership and rituals — in Driving Team Performance Budget Adoption. The RUM half of the data flow originates from Custom Performance Beacons & RUM, and the synthetic half from the collection settings documented in Lighthouse CI Configuration & Storage. Teams that prefer a managed field pipeline instead of self-operated ingestion can shortcut the storage and dashboard tiers with Integrating Performance Budgets With Datadog, which trades operational control for a hosted RUM product that already computes percentiles.

One architectural decision governs everything downstream: the dashboard and the gate must agree on the definition of "over budget." If the CI gate asserts a P75 LCP ceiling of 2500 ms on a mid-range mobile device (a Moto G-class handset) under a Fast 3G network and 4x CPU throttle, then the dashboard's budget line must be drawn at exactly 2500 ms on exactly that device-and-network slice of the field data. The instant those two numbers diverge — because the panel charts an unfiltered global P75 while the gate throttles hard — the team loses the ability to trust either. Every table, panel, and alert in this reference inherits that single rule.

Metric Selection and Visualization Matrix

Different audiences read different charts. An engineering manager wants a single trend line they can put in a quarterly review; an on-call engineer wants a per-route breakdown that pinpoints the regression; a frontend lead wants the lab-versus-field delta that tells them whether the budget is even calibrated to reality. Charting every metric for every audience produces dashboards no one reads. Pick the metric, the percentile, and the visualization to the question being asked, and delete anything that does not answer a question a named person actually poses.

The discipline is to keep field percentiles honest. Always label a chart with both the percentile and the environment — a P75 LCP on a mid-range mobile device under a Fast 3G profile is a different number from a P75 LCP on desktop cable, and a dashboard that conflates them quietly hides the regression that matters. The aggregation that produces these percentiles is built in the RUM reference's P75/P99 aggregation pipelines; the dashboard only displays what that pipeline computes. The executive row in the matrix above is deliberately different in kind: it does not chart a metric, it charts compliance — the fraction of surfaces currently inside budget — and that rollup is the subject of Performance Budget Reporting and Scorecards.

The single most valuable panel for a frontend lead is the lab-versus-field overlay, because it is the only view that catches the failure mode where the gate is green and the users are unhappy. When the lab line sits comfortably under budget while the field line climbs through it, the throttling profile in CI no longer models your real traffic — the lab is testing a device faster than your median visitor owns. The chart below is a worked example of that divergence: the lab P75 holds steady while field P75 crosses the 2500 ms budget line at week two and keeps climbing.

Reading the divergence is only useful if it triggers an action, and the action here is recalibration of the lab profile against the field distribution — the throttling work covered in the calibration reference. The overlay is the tripwire; the fix lives elsewhere. A team that charts this panel but never acts on the gap has built a very expensive way to watch its budget rot.

Tooling and Implementation

Three tools cover the common stack. Grafana renders panels over a time-series store and is the right default when you already run Prometheus, InfluxDB, or a Postgres source. The LHCI server ships its own trend UI for free and is the lowest-friction starting point. A commercial RUM product such as Datadog covers field data without you operating an ingestion pipeline. They compose rather than compete: LHCI for the lab gate's history, Grafana for the unified board, Datadog (or equivalent) for field percentiles when self-hosting RUM is not worth the cost. Most mature teams end up running two of the three, and the choice between them is a function of how much operational surface you want to own versus rent.

A Grafana panel is just JSON; you can version it next to your application and provision it on boot, which means the dashboard itself passes through code review and never drifts from what is committed. The panel below charts P75 LCP per route against a 2500 ms budget line — the canonical "is the gate calibrated" view a frontend lead reviews each release, and the source of the overlay above.

{
  "title": "P75 LCP by route vs budget",
  "type": "timeseries",
  "datasource": { "type": "prometheus", "uid": "perf-tsdb" },
  "fieldConfig": {
    "defaults": {
      "unit": "ms",
      "thresholds": {
        "mode": "absolute",
        "steps": [
          { "color": "green", "value": null },
          { "color": "red", "value": 2500 }
        ]
      }
    }
  },
  "targets": [
    {
      "refId": "A",
      "expr": "histogram_quantile(0.75, sum by (route, le) (rate(lcp_milliseconds_bucket{device=\"mobile\",net=\"fast3g\"}[1h])))",
      "legendFormat": "{{route}}"
    }
  ]
}

The query reads an LCP histogram exported by your RUM ingestion and computes the 75th percentile per route over a one-hour rolling window, filtered to the same mobile / Fast 3G slice the gate throttles to. The 2500 ms threshold step turns the panel red the moment a route's field P75 crosses the budget — the same number the lab gate asserts, so the dashboard and the gate never disagree on what "over budget" means. Note the device and net label filters in the PromQL: without them the panel would compute a blended P75 across desktop and mobile, which is the single most common way a dashboard silently lies. Building the full board, including INP and CLS panels, is covered in Building a Web Vitals Grafana Dashboard.

The same panel pattern extends to the two other Core Web Vitals with only a metric name and a threshold change: an INP panel asserts a P75 ceiling of 200 ms on the same mid-range mobile profile, and a CLS panel asserts a P75 ceiling of 0.1 (unitless, device-independent since layout shift does not scale with CPU). Keep the three panels in one row so a reviewer reads the whole vitals story in a single glance rather than clicking between boards.

CI/CD Integration

A dashboard is only as current as its last write. Every CI run that produces metrics should publish them to the store so the trend line never has a hole where a build should be. With the LHCI server as the backend, lhci upload does this automatically; the job below runs the assertion gate and then pushes results to the dashboard's storage on every push to the main branch, and drops a deploy annotation so the trend line is forensically linked to commits.

name: Publish performance to dashboard
on:
  push:
    branches: [main]

jobs:
  collect-and-publish:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"
      - run: npm ci
      - run: npm run build
      - name: Collect and assert
        run: npx lhci autorun
        env:
          LHCI_TOKEN: ${{ secrets.LHCI_TOKEN }}
          LHCI_SERVER_BASE_URL: ${{ secrets.LHCI_SERVER_BASE_URL }}
      - name: Annotate Grafana with deploy marker
        if: success()
        run: |
          curl -s -X POST "$GRAFANA_URL/api/annotations" \
            -H "Authorization: Bearer $GRAFANA_TOKEN" \
            -H "Content-Type: application/json" \
            -d "{\"text\":\"deploy ${GITHUB_SHA:0:7}\",\"tags\":[\"deploy\"]}"
        env:
          GRAFANA_URL: ${{ secrets.GRAFANA_URL }}
          GRAFANA_TOKEN: ${{ secrets.GRAFANA_TOKEN }}

The annotation step is what turns a trend line into a forensic tool: every deploy leaves a vertical marker on the chart, so when a regression appears the team can read off the exact commit that introduced it instead of bisecting by hand. Wire the same lhci autorun invocation that gates pull requests into this publish job so the lab numbers on the dashboard are the identical numbers the gate enforced — calibrated per the methodology in Lighthouse CI Configuration & Storage.

Publishing on every push to main is the minimum. Teams that want to catch drift that only appears under production traffic — third-party tags that grow, CDN cache-hit rates that decay, image weight that creeps as the CMS fills — add a scheduled synthetic run on top of the push-triggered one, the pattern documented in Continuous Performance Monitoring. A nightly run against production URLs fills the trend line on days with no deploys and is often the first place a slow, silent regression becomes visible, because it removes the confound of "the code changed" from "the number changed."

The Adoption Maturity Model

Tooling is necessary and never sufficient. A team can stand up a perfect dashboard and still let the budget rot, because the failure that kills budgets is social, not technical. It helps to name where a team sits on an adoption ladder, because each rung has a characteristic failure and a characteristic next move. Most teams begin at ad hoc — someone runs Lighthouse by hand before a big launch — and the goal is to climb to owned, where the budget has a codeowner, a review ritual, and an exception process. The rungs are cumulative: you cannot skip monitoring to reach ownership, because you cannot own what you cannot see.

The transition that stalls most teams is gated to monitored. Gating is a one-time engineering task — write the assertion config, wire the Action — and it produces an immediate, visible win. Monitoring is ongoing operational work with no launch moment, so it is the rung teams intend to reach and never do. The way through is to make the dashboard part of an existing ritual rather than a new one: put the vitals row on the same board the team already reviews at sprint review, and the monitoring habit inherits an audience it did not have to recruit. The full playbook for the top two rungs — assigning ownership, writing the policy, running blameless triage — is Driving Team Performance Budget Adoption, and the codified exception process it depends on is Writing a Performance Budget Policy.

A useful diagnostic: ask a team where its budget lives. If the answer is "in someone's head," it is ad hoc. If the answer is "in the CI config," it is gated. If the answer is "on the dashboard we check," it is monitored. Only when the answer is "in the policy, and Priya's team owns it" is it truly owned — and only then does the budget reliably survive a reorg, a launch crunch, or the departure of the person who set it up.

Observability and Regression Detection

A dashboard shows trends; alerting catches the regression while it is still cheap to revert. The signal that matters is not a single bad build — synthetic runs carry noise — but a sustained shift in the percentile. Configure alerts to fire only when the field or lab metric exceeds its budget for a window long enough to clear the noise floor, typically three consecutive evaluations or a one-hour persistence. A point-in-time alert on a noisy metric is an alert that will be muted within a week, and a muted alert is indistinguishable from no alert at all.

Tie alert thresholds to the same ceilings the gate asserts so a fired alert always corresponds to a real budget breach. When field data is the trigger, route the alert with the offending route, the percentile, and the device class in the payload so the on-call engineer can act without first opening the dashboard — a P75 INP breach of 240 ms against a 200 ms budget on mid-range mobile is actionable in the alert body; "performance alert: INP high" is not. The statistical machinery for separating a real regression from variance lives in Automated Regression Detection, and the concrete alert wiring for budget breaches is built in Alerting on Performance Budget Regressions. Teams on a managed stack get the equivalent through Datadog monitors for budget regressions.

The alert's persistence window and the noise floor of the underlying metric are the two knobs that decide whether you are trusted or muted. A field P75 aggregated over an hour of high traffic is inherently stable, so a one-hour persistence window is generous. A lab metric from a single synthetic run on a shared CI runner can swing 10-15% between identical builds, so the same alert on lab data needs either median-of-three collection or a wider window to avoid firing on runner noise. Match the window to the metric's variance, not to a fixed rule copied from another team's setup.

Failure Modes and Escalation Paths

Dashboards and alerts fail in predictable, human ways. Knowing the failure mode tells you the escalation, and every one of these has been the cause of a quietly abandoned budget somewhere.

• Alert fatigue. A flaky metric fires nightly, the team adds a mute, and the mute outlives the flakiness. Escalation: fix the variance at the source — see the staging-variance and significance-testing references — then re-enable at a persistence window, never lower the threshold to stop the noise. Lowering the threshold to silence an alert is how a budget quietly stops asserting anything.
• Dashboards no one reads. A board with forty panels answers no one's question, so it is opened during onboarding and never again. Escalation: delete panels until each one maps to a row in the audience matrix above; a board read weekly beats a board built once. Ruthless deletion is the maintenance, not a failure of it.
• Budget erosion. Each PR widens a tolerance "just this once" and six months later the gate asserts nothing real. Escalation: require a budget change to go through the exception workflow with a named owner and an expiry date, enforced by the adoption policy so that widening a budget is a deliberate, logged decision rather than a silent diff.
• Lab/field divergence. The gate is green but RUM shows a P75 regression because the lab profile no longer matches real devices. Escalation: recalibrate the lab throttling against field percentiles; the dual-line overlay panel exists precisely to surface this gap before it becomes a customer complaint.
• Orphaned ownership. The engineer who built the dashboard leaves and no codeowner inherits it. Escalation: assign the board and its alerts to a team in the policy, never to an individual, so a departure does not silently retire the coverage.
• Vanity green. Leadership sees a green scorecard and stops funding performance work, right up until a field regression that the synthetic-only board never caught. Escalation: always pair the lab scorecard with a field-data tile so "green" means green for real users, and report both in the reporting and scorecards rollup.

Every one of these is ultimately an adoption failure, not a tooling failure, which is why the human tier of this reference is as load-bearing as the data tier. You can buy your way out of a storage problem; you cannot buy your way out of a team that does not trust its own alerts.

Frequently Asked Questions