ENG-9166 feat(otel): browser tracing plugin — traceparent per event, web vitals, render timing (3/3)

[FarhanAliRaza]

Part of #6227 (ENG-9166). Stack: 1/3 → 2/3 → 3/3 (this). Base is farhan/eng-9166-reflex-otel-3; the diff is the two commits on top of 2/3.

What

reflex_otel.OtelPlugin (add to rx.Config(plugins=[...])) compiles a small OpenTelemetry web bundle into the frontend:

• every event sent to the backend gets a PRODUCER span and a W3C traceparent, so one user interaction is one trace: browser → backend SERVER event → chained INTERNAL events;
• web vitals (web_vital.LCP/CLS/INP/FCP/TTFB) as spans with value/rating attributes;
• socket.connect / socket.disconnect spans (unintentional disconnects marked ERROR);
• opt-in render_timing=True: react.render span per React commit via a root <Profiler>; the plugin aliases react-dom/client → react-dom/profiling in vite.config.js because <Profiler> is a no-op in production builds otherwise. Off by default (span volume). Verified in a --env prod build.

Wiring: get_frontend_dependencies (pinned @opentelemetry/*, web-vitals), get_static_assets (utils/otel.js), update_env_json (OTEL entry: endpoint, service name, headers, flags), add_modify_task on entry.client.js (import + root wrap). Endpoint defaults follow OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / OTEL_EXPORTER_OTLP_ENDPOINT → /v1/traces; must allow CORS. headers are compiled into the public bundle (documented).

Framework seam: state.js calls window.__reflex_otel?.onEventSend/onSocketConnect/onSocketDisconnect — undefined unless the plugin is active.

Docs: new docs/api-reference/observability.md (backend + frontend setup, hot-reload-safe guard, metrics table). Log correlation is out of this stack (follow-up: #6903).

Known limitation: the browser has no per-event completion signal, so the browser event span has no duration; it exists to carry the trace context.

Tests

tests/units/reflex_otel/test_plugin.py (env/endpoint resolution, asset, env.json, entry patch idempotency + warning, profiling alias patch).

[linear-code]

ENG-9166

[codspeed-hq]

Merging this PR will not alter performance

✅ 26 untouched benchmarks
⏩ 8 skipped benchmarks¹

---

_{Comparing farhan/eng-9166-reflex-otel-4 (4e1d604) with farhan/eng-9166-reflex-otel-3 (7427498)}

Footnotes

1. 8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[greptile-apps]

Greptile Summary

The PR adds opt-in browser OpenTelemetry instrumentation and wires it into the generated frontend event and socket lifecycle.

• Adds per-event trace-context propagation, web-vital spans, socket lifecycle spans, and optional React render timing.
• Adds compile-time plugin configuration, frontend dependencies, entry-point wrapping, and production profiling alias support.
• Documents frontend observability setup and adds unit coverage for plugin configuration and source patching.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
packages/reflex-base/src/reflex_base/.templates/web/utils/state.js	Adds optional frontend telemetry callbacks around event sending and socket connect/disconnect handling; no eligible unresolved follow-up issue remains.
packages/reflex-otel/src/reflex_otel/otel.js	Implements browser tracing, web-vital reporting, socket spans, and optional React Profiler spans.
packages/reflex-otel/src/reflex_otel/plugin.py	Adds the compile-time plugin, validated sampling configuration, frontend assets and dependencies, environment data, and source patching.
tests/units/reflex_otel/test_plugin.py	Covers endpoint resolution, generated configuration, static assets, entry patching, profiling aliasing, idempotency, and sampling validation.
docs/api-reference/observability.md	Documents backend and browser OpenTelemetry setup, emitted telemetry, defaults, sampling, and public-header constraints.

_{Reviews (7): Last reviewed commit: "fix(otel): reject out-of-range sample_ra..." | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 81df35005c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cubic-dev-ai]

All reported issues were addressed across 11 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[Alek99]

The browser → backend → chained-event parentage, production render spans, FCP, and TTFB all worked in a local Reflex app. These remaining browser-policy/lifecycle issues are not covered by the happy path.

[cubic-dev-ai]

All reported issues were addressed across 4 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>