frontend-observability-rum-instrumentation
Design or review browser-side Real User Monitoring instrumentation for Core Web Vitals (LCP, INP, CLS) using the web-vitals attribution build and distributed tracing via OpenTelemetry Web, enforcing lab-vs-field evidence labeling, sampling/cardinality sizing, and PII-in-telemetry
Install
npx skills add https://github.com/VincentChuWaiChow/vanguard-frontier-agentic/tree/master/skills/frontend/frontend-observability-rum-instrumentation
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install vincentchuwaichow-vanguard-frontier-agentic@llmmart
git clone https://github.com/VincentChuWaiChow/vanguard-frontier-agentic.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole vincentchuwaichow/vanguard-frontier-agentic collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Frontend Observability RUM Instrumentation
Purpose
Lab-only performance testing (Lighthouse, synthetic CI runs) systematically misses the device/network diversity of real users, and ad-hoc telemetry instrumentation routinely leaks PII into span attributes or blows up observability cost through unsampled high-cardinality export. This skill wires and reviews field RUM (web-vitals + OpenTelemetry Web) with explicit evidence labeling and privacy/cost guardrails baked in from the start.
When to use
Use this skill when the user asks to:
- instrument Core Web Vitals (LCP, INP, CLS) field measurement in a web app,
- set up or review OpenTelemetry Web browser tracing (document load, fetch/XHR spans),
- review an existing RUM/telemetry pipeline for PII exposure or sampling/cost issues,
- interpret or report on Core Web Vitals data and needs a lab-vs-field distinction made explicit,
- set or validate a performance budget against field p75 data.
When NOT to use
- Diagnosing why a specific LCP/INP/CLS number is high (phase decomposition of an existing regression) — hand off to
core-web-vitals-triage; this skill instruments the pipeline that produces the data, it does not decompose an already-captured regression. - Bundle size, code-splitting, or caching remediation once a cause is known — hand off to
bundle-budget-code-splitting-revieworservice-worker-cache-strategy-review. - Server-side or backend-service tracing with no browser-origin span — this skill is scoped to browser-side RUM and OpenTelemetry Web only.
Context7 Documentation Protocol
web-vitals and OpenTelemetry Web packages ship breaking API changes across major versions (attribution-build option shapes, sampler class names, exporter constructor options), and memorized snippets go stale. Before writing or reviewing instrumentation code:
- Call
ToolSearchwith query"context7"(or"select:mcp__Context7__resolve-library-id,mcp__Context7__query-docs") to load the Context7 tools if not already loaded this session. - Call
mcp__Context7__resolve-library-idforweb-vitalsand/oropentelemetry-jsbefore making any claim about their current API shape. Verified IDs as of this skill'supdateddate:/googlechrome/web-vitalsand/open-telemetry/opentelemetry-js. - Call
mcp__Context7__query-docsfor the specific mechanism in scope — e.g. "attribution build generateTarget option", "INPAttributionReportOpts durationThreshold", "WebTracerProvider spanProcessors config", "TraceIdRatioBasedSampler" — before ruling on it. Do this per review; do not reuse a prior session's memory of these APIs. - Known facts verified via Context7 as of this skill's
updateddate: the attribution build (web-vitals/attribution) acceptsAttributionReportOpts(reportAllChanges,generateTarget) ononCLS/onFCP/onLCP/onTTFB, andINPAttributionReportOptsadditionally exposesdurationThreshold(default40) andincludeProcessedEventEntries(defaulttrue) ononINP.WebTracerProvider(from@opentelemetry/sdk-trace-web) takes aspanProcessorsarray in its constructor — do not tell a user to call a separateaddSpanProcessormethod as the primary pattern without checking the installed SDK version.TraceIdRatioBasedSamplertakes a single ratio argument (0–1) and is normally wrapped inParentBasedSampler({ root: ... })so that downstream/parent sampling decisions are respected. - If Context7 is unavailable or returns no relevant match, fall back to
official_docs/references/*.mdand mark the claimdocumentation-based (Context7 unavailable)rather than presenting it as freshly verified. - Never invent a
web-vitalsmetric field, attribution property, OpenTelemetry exporter option, or sampler class that no queried source confirms.
Lean operating rules
- Always label every performance number as lab evidence (Lighthouse/CI/synthetic) or field evidence (RUM, real users — state the percentile; p75 is the CWV standard) — never let the two blur into an unlabeled "the site is fast" claim.
- Default to the standard
web-vitalsbuild (onLCP/onINP/onCLS) for production reporting; only use the/attributionbuild's richer diagnostic payload when actively debugging a specific regression, and only send that extra payload to a dev/debug destination, not blanket production export. - Do not enable
reportAllChanges: truein production by default — it multiplies event volume for a debugging-only benefit. - Before adding any custom span/metric attribute, run it through a PII check: no raw URLs with query strings, no user IDs, no free-text form input, no precise geolocation, unless explicitly scrubbed and justified.
- Size the OpenTelemetry sampling rate (e.g.
TraceIdRatioBasedSamplerwrapped inParentBasedSampler) against the stated/estimated traffic volume and the backend's cost/cardinality limits; never recommend 100% unsampled export for a high-traffic app without an explicit cost review. - Use OpenTelemetry Semantic Conventions attribute names instead of inventing ad-hoc span/attribute naming, so telemetry stays queryable/comparable across services.
- Treat any recommended performance budget threshold as grounded in web.dev's documented "good" ranges (LCP ≤2.5s, INP ≤200ms, CLS ≤0.1 at p75) unless the org has an explicitly stricter documented SLO.
- This skill performs static review and instrumentation-code authoring only; it does not deploy telemetry configuration to production or flip sampling/export settings on a live collector without explicit human sign-off logged outside this skill.
References
Load these only when needed:
- web-vitals attribution build wiring — use when writing or reviewing the actual
onLCP/onINP/onCLSinstrumentation call, choosing between standard and attribution builds, or settinggenerateTarget/durationThreshold/reportAllChanges. - OpenTelemetry Web tracing wiring — use only when wiring or reviewing
WebTracerProvider,DocumentLoadInstrumentation,FetchInstrumentation, exporter, or sampler configuration. - Sampling, cardinality, and PII controls — use when sizing sampling rates against traffic/cost, naming attributes via Semantic Conventions, or auditing an existing pipeline for PII leakage.
Response minimum
Return, at minimum:
- the metric/trace component in scope and whether guidance concerns lab or field measurement,
- evidence level for any performance claim (lab-evidence, field-evidence with percentile, or documentation-based),
- instrumentation code or review findings with exact API options used,
- PII-in-telemetry check result for every attribute touched,
- sampling-rate rationale tied to stated traffic volume and cost constraints.
Files (vanguard-frontier-agentic)
-
references
-
opentelemetry-web-tracing-wiring.md 7.5 KB
Loading… -
sampling-cardinality-pii-controls.md 7.9 KB
Loading… -
web-vitals-attribution-wiring.md 6.6 KB
Loading…
-
-
metadata.json 1.2 KB
Loading… -
SKILL.md 7.4 KB
--- name: frontend-observability-rum-instrumentation description: Design or review browser-side Real User Monitoring instrumentation for Core Web Vitals (LCP, INP, CLS) using the web-vitals attribution build and distributed tracing via OpenTelemetry Web, enforcing lab-vs-field evidence labeling, sampling/cardinality sizing, and PII-in-telemetry controls, with library-specific wiring references loaded only when instrumentation code is actually being written or reviewed. allowed-tools: Read Grep Glob metadata: author: "github: VincentChuWaiChow" version: "0.1.0" updated: "2026-07-02" category: observability --- # Frontend Observability RUM Instrumentation ## Purpose Lab-only performance testing (Lighthouse, synthetic CI runs) systematically misses the device/network diversity of real users, and ad-hoc telemetry instrumentation routinely leaks PII into span attributes or blows up observability cost through unsampled high-cardinality export. This skill wires and reviews field RUM (web-vitals + OpenTelemetry Web) with explicit evidence labeling and privacy/cost guardrails baked in from the start. ## When to use Use this skill when the user asks to: - instrument Core Web Vitals (LCP, INP, CLS) field measurement in a web app, - set up or review OpenTelemetry Web browser tracing (document load, fetch/XHR spans), - review an existing RUM/telemetry pipeline for PII exposure or sampling/cost issues, - interpret or report on Core Web Vitals data and needs a lab-vs-field distinction made explicit, - set or validate a performance budget against field p75 data. ## When NOT to use - Diagnosing *why* a specific LCP/INP/CLS number is high (phase decomposition of an existing regression) — hand off to `core-web-vitals-triage`; this skill instruments the pipeline that produces the data, it does not decompose an already-captured regression. - Bundle size, code-splitting, or caching remediation once a cause is known — hand off to `bundle-budget-code-splitting-review` or `service-worker-cache-strategy-review`. - Server-side or backend-service tracing with no browser-origin span — this skill is scoped to browser-side RUM and OpenTelemetry Web only. ## Context7 Documentation Protocol `web-vitals` and OpenTelemetry Web packages ship breaking API changes across major versions (attribution-build option shapes, sampler class names, exporter constructor options), and memorized snippets go stale. Before writing or reviewing instrumentation code: 1. Call `ToolSearch` with query `"context7"` (or `"select:mcp__Context7__resolve-library-id,mcp__Context7__query-docs"`) to load the Context7 tools if not already loaded this session. 2. Call `mcp__Context7__resolve-library-id` for `web-vitals` and/or `opentelemetry-js` before making any claim about their current API shape. Verified IDs as of this skill's `updated` date: `/googlechrome/web-vitals` and `/open-telemetry/opentelemetry-js`. 3. Call `mcp__Context7__query-docs` for the specific mechanism in scope — e.g. "attribution build generateTarget option", "INPAttributionReportOpts durationThreshold", "WebTracerProvider spanProcessors config", "TraceIdRatioBasedSampler" — before ruling on it. Do this per review; do not reuse a prior session's memory of these APIs. 4. Known facts verified via Context7 as of this skill's `updated` date: the attribution build (`web-vitals/attribution`) accepts `AttributionReportOpts` (`reportAllChanges`, `generateTarget`) on `onCLS`/`onFCP`/`onLCP`/`onTTFB`, and `INPAttributionReportOpts` additionally exposes `durationThreshold` (default `40`) and `includeProcessedEventEntries` (default `true`) on `onINP`. `WebTracerProvider` (from `@opentelemetry/sdk-trace-web`) takes a `spanProcessors` array in its constructor — do not tell a user to call a separate `addSpanProcessor` method as the primary pattern without checking the installed SDK version. `TraceIdRatioBasedSampler` takes a single ratio argument (0–1) and is normally wrapped in `ParentBasedSampler({ root: ... })` so that downstream/parent sampling decisions are respected. 5. If Context7 is unavailable or returns no relevant match, fall back to `official_docs` / `references/*.md` and mark the claim `documentation-based (Context7 unavailable)` rather than presenting it as freshly verified. 6. Never invent a `web-vitals` metric field, attribution property, OpenTelemetry exporter option, or sampler class that no queried source confirms. ## Lean operating rules - Always label every performance number as lab evidence (Lighthouse/CI/synthetic) or field evidence (RUM, real users — state the percentile; p75 is the CWV standard) — never let the two blur into an unlabeled "the site is fast" claim. - Default to the standard `web-vitals` build (`onLCP`/`onINP`/`onCLS`) for production reporting; only use the `/attribution` build's richer diagnostic payload when actively debugging a specific regression, and only send that extra payload to a dev/debug destination, not blanket production export. - Do not enable `reportAllChanges: true` in production by default — it multiplies event volume for a debugging-only benefit. - Before adding any custom span/metric attribute, run it through a PII check: no raw URLs with query strings, no user IDs, no free-text form input, no precise geolocation, unless explicitly scrubbed and justified. - Size the OpenTelemetry sampling rate (e.g. `TraceIdRatioBasedSampler` wrapped in `ParentBasedSampler`) against the stated/estimated traffic volume and the backend's cost/cardinality limits; never recommend 100% unsampled export for a high-traffic app without an explicit cost review. - Use OpenTelemetry Semantic Conventions attribute names instead of inventing ad-hoc span/attribute naming, so telemetry stays queryable/comparable across services. - Treat any recommended performance budget threshold as grounded in web.dev's documented "good" ranges (LCP ≤2.5s, INP ≤200ms, CLS ≤0.1 at p75) unless the org has an explicitly stricter documented SLO. - This skill performs static review and instrumentation-code authoring only; it does not deploy telemetry configuration to production or flip sampling/export settings on a live collector without explicit human sign-off logged outside this skill. ## References Load these only when needed: - [web-vitals attribution build wiring](references/web-vitals-attribution-wiring.md) — use when writing or reviewing the actual `onLCP`/`onINP`/`onCLS` instrumentation call, choosing between standard and attribution builds, or setting `generateTarget`/`durationThreshold`/`reportAllChanges`. - [OpenTelemetry Web tracing wiring](references/opentelemetry-web-tracing-wiring.md) — use only when wiring or reviewing `WebTracerProvider`, `DocumentLoadInstrumentation`, `FetchInstrumentation`, exporter, or sampler configuration. - [Sampling, cardinality, and PII controls](references/sampling-cardinality-pii-controls.md) — use when sizing sampling rates against traffic/cost, naming attributes via Semantic Conventions, or auditing an existing pipeline for PII leakage. ## Response minimum Return, at minimum: - the metric/trace component in scope and whether guidance concerns lab or field measurement, - evidence level for any performance claim (lab-evidence, field-evidence with percentile, or documentation-based), - instrumentation code or review findings with exact API options used, - PII-in-telemetry check result for every attribute touched, - sampling-rate rationale tied to stated traffic volume and cost constraints.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.