reflex-otel 0.1.0a1__tar.gz

reflex_otel-0.1.0a1/.gitignore

@@ -0,0 +1,35 @@
+**/.DS_Store
+**/*.pyc
+**/__pycache__/
+.pytest_cache/
+.ruff_cache/
+**/.ruff_cache/
+.mypy_cache/
+assets/external/*
+dist/*
+examples/
+.web
+.states
+.idea
+.vscode
+.coverage
+.coverage.*
+.venv
+venv
+requirements.txt
+.pyi_generator_last_run
+.pyi_generator_diff
+reflex.db
+.codspeed
+.env
+.env.*
+node_modules
+package-lock.json
+*.pyi
+.pre-commit-config.yaml
+.claude/.worktrees
+.claude/settings.local.json
+CLAUDE.local.md
+
+# Backups written by scripts/delete_automated_releases.sh
+automated-releases-backup-*.json

reflex_otel-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,9 @@
+
+
+<!-- towncrier release notes start -->
+
+## v0.1.0a1 (2026-09-10)
+
+### Features
+
+- Add the `reflex-otel` package: an OpenTelemetry instrumentor that turns on the framework's built-in trace points and metrics (one span per event handler run, chained events parented under the enqueuing span, frontend `traceparent` propagation, event/state/websocket metrics, compile spans) and wraps the ASGI app in the OpenTelemetry ASGI middleware. `OtelPlugin(endpoint=...)` adds browser tracing (a `traceparent` on sampled events and uploads, web vitals, React render timing) to the compiled frontend; without an endpoint nothing is exported. Failed browser exports (for example a collector without CORS) are reported through the app's `frontend_exception_handler`. ([#6227](https://github.com/reflex-dev/reflex/issues/6227))

reflex_otel-0.1.0a1/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.5
+Name: reflex-otel
+Version: 0.1.0a1
+Summary: OpenTelemetry instrumentation for the Reflex framework.
+Author-email: Khaleel Al-Adhami <khaleel@reflex.dev>
+Maintainer-email: Khaleel Al-Adhami <khaleel@reflex.dev>
+License: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: opentelemetry-api<2.0,>=1.30.0
+Requires-Dist: opentelemetry-instrumentation-asgi<1.0,>=0.49b0
+Requires-Dist: opentelemetry-instrumentation<1.0,>=0.49b0
+Requires-Dist: reflex-base>=0.9.11a1
+Description-Content-Type: text/markdown
+
+# reflex-otel
+
+OpenTelemetry instrumentation for the Reflex framework.
+
+```python
+from reflex_otel import ReflexInstrumentor
+
+ReflexInstrumentor().instrument()
+```
+
+Nothing in the app module needs guarding: a second `instrument()` is a silent
+no-op, so the line above can run every time the module is imported.
+
+Configure the SDK the way you prefer:
+
+- Set the standard variables and let `instrument()` do it. When
+  `OTEL_TRACES_EXPORTER` or `OTEL_METRICS_EXPORTER` is set and no SDK provider
+  has been installed yet, `instrument()` configures `opentelemetry-sdk` from
+  the `OTEL_*` environment, exactly as `opentelemetry-instrument` would:
+
+  ```bash
+  OTEL_SERVICE_NAME=myapp OTEL_TRACES_EXPORTER=otlp OTEL_METRICS_EXPORTER=otlp \
+  OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318 reflex run
+  ```
+
+- Or build the providers yourself and pass them:
+  `ReflexInstrumentor().instrument(tracer_provider=provider, meter_provider=meter_provider)`.
+  Do that from a module that is imported once (not the app module, which
+  test harnesses may re-import) or the SDK warns about overriding providers.
+
+- Or use no code at all: the package registers an `opentelemetry_instrumentor`
+  entry point, so `opentelemetry-instrument reflex run` enables it (the
+  auto-instrumentation `sitecustomize` reaches the backend worker through the
+  inherited `PYTHONPATH`).
+
+## What you get
+
+Traces:
+
+- One span per event handler run, named after the event: `CONSUMER` for
+  events sent by the frontend (a new trace, or a child of the browser's
+  `PRODUCER` span when the event carries a `traceparent` field), `INTERNAL`
+  for chained events, which are children of the span that enqueued them.
+  Only string `traceparent`/`tracestate` fields are read from the event;
+  they never reach the handler, and `baggage` or anything else a client
+  sends is ignored. The sampled flag of a client `traceparent` is honoured
+  by the SDK's default parent-based sampler, so a client decides whether its
+  own events are recorded; use `ParentBased(root=..., remote_parent_sampled=...,
+  remote_parent_not_sampled=...)` or `OTEL_TRACES_SAMPLER=always_on` to keep
+  that decision on the server.
+- HTTP requests and the websocket connection are wrapped in the standard
+  OpenTelemetry ASGI middleware (per-message websocket spans are off).
+- One `reflex.compile` span per app compile (`reflex.compile.trigger`,
+  `reflex.compile.dry_run`) with the stages `reflex.compile.evaluate_pages`,
+  `.pages`, `.copy_assets`, `.install_frontend_packages`, `.write` as
+  child spans.
+
+What leaves the process: event and handler names, a pseudonymous
+`session.id` (a truncated SHA-256 of the client token, never the token
+itself), exception types, messages and stack traces of failed handlers, and
+the ASGI middleware's request attributes with the `token` query parameter of
+the websocket URL redacted. Event payloads and state are never recorded.
+
+Metrics:
+
+| Instrument | Type | Unit | Attributes |
+| --- | --- | --- | --- |
+| `reflex.event.duration` | histogram | s | `reflex.event.name`, `reflex.event.background`, `error.type` |
+| `reflex.state.acquire.duration` | histogram | s | `reflex.event.name` |
+| `reflex.websocket.message.size` | histogram | By | `network.io.direction` (`transmit`/`receive`); default `sio` only |
+| `reflex.websocket.connections` | up-down counter | `{connection}` | |
+
+Plus the ASGI middleware's `http.server.*` metrics. The instrumentor opts the
+middleware into the stable HTTP semantic conventions
+(`OTEL_SEMCONV_STABILITY_OPT_IN=http`) unless that variable is already set,
+so request attributes use the same generation of names as Reflex's own.
+
+## Browser (frontend) tracing
+
+```python
+# rxconfig.py
+from reflex_otel import OtelPlugin
+
+config = rx.Config(
+    app_name="myapp",
+    plugins=[OtelPlugin(endpoint="https://collector.example.com/v1/traces")],
+)
+```
+
+The plugin compiles a small OpenTelemetry web bundle into the frontend:
+
+- every event sent to the backend gets a `PRODUCER` span and a W3C
+  `traceparent`, so the backend event span joins the browser trace (one trace
+  per interaction, browser → backend → chained events);
+- web vitals (`web_vital.LCP`, `CLS`, `INP`, `FCP`, `TTFB`) as spans with
+  `web_vital.value` / `web_vital.rating`;
+- with `render_timing=True`, React commits as `react.render` spans
+  (`react.render.phase`, `react.render.actual_duration_ms`); this aliases
+  `react-dom/client` to the `react-dom/profiling` build and emits one span per
+  commit, so it is off by default;
+- `socket.connect` / `socket.disconnect` spans for reconnect tracking
+  (unintentional disconnects are marked as errors).
+
+Options: `endpoint` (OTLP/HTTP traces URL reachable from the browser; required
+to export, with no default and no `OTEL_EXPORTER_OTLP_*` fallback: without it
+no exporter is installed and browser spans are dropped), `service_name` (default
+`<app_name>-frontend`), `headers` (compiled into the public bundle — no
+secrets), `web_vitals`, `render_timing`. The endpoint must allow CORS from the
+app origin.
+
+## Options
+
+`instrument()` accepts `tracer_provider`, `meter_provider`, `excluded_urls`
+(comma-separated URL patterns skipped by the ASGI middleware; defaults to
+`OTEL_PYTHON_REFLEX_EXCLUDED_URLS`, else `OTEL_PYTHON_EXCLUDED_URLS`, else
+`/ping` plus the compiled frontend's `/assets/` when the backend serves it,
+as `reflex run --env prod` does on one port; pass `""`, or set the variable
+to an empty string, to exclude nothing) and the ASGI hooks
+`server_request_hook`, `client_request_hook`, `client_response_hook`.
+Call `instrument()` before the app is served: `uninstrument()` turns the
+framework trace points off again, but an ASGI middleware that was already
+installed stays until the process restarts.

reflex_otel-0.1.0a1/README.md

@@ -0,0 +1,122 @@
+# reflex-otel
+
+OpenTelemetry instrumentation for the Reflex framework.
+
+```python
+from reflex_otel import ReflexInstrumentor
+
+ReflexInstrumentor().instrument()
+```
+
+Nothing in the app module needs guarding: a second `instrument()` is a silent
+no-op, so the line above can run every time the module is imported.
+
+Configure the SDK the way you prefer:
+
+- Set the standard variables and let `instrument()` do it. When
+  `OTEL_TRACES_EXPORTER` or `OTEL_METRICS_EXPORTER` is set and no SDK provider
+  has been installed yet, `instrument()` configures `opentelemetry-sdk` from
+  the `OTEL_*` environment, exactly as `opentelemetry-instrument` would:
+
+  ```bash
+  OTEL_SERVICE_NAME=myapp OTEL_TRACES_EXPORTER=otlp OTEL_METRICS_EXPORTER=otlp \
+  OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318 reflex run
+  ```
+
+- Or build the providers yourself and pass them:
+  `ReflexInstrumentor().instrument(tracer_provider=provider, meter_provider=meter_provider)`.
+  Do that from a module that is imported once (not the app module, which
+  test harnesses may re-import) or the SDK warns about overriding providers.
+
+- Or use no code at all: the package registers an `opentelemetry_instrumentor`
+  entry point, so `opentelemetry-instrument reflex run` enables it (the
+  auto-instrumentation `sitecustomize` reaches the backend worker through the
+  inherited `PYTHONPATH`).
+
+## What you get
+
+Traces:
+
+- One span per event handler run, named after the event: `CONSUMER` for
+  events sent by the frontend (a new trace, or a child of the browser's
+  `PRODUCER` span when the event carries a `traceparent` field), `INTERNAL`
+  for chained events, which are children of the span that enqueued them.
+  Only string `traceparent`/`tracestate` fields are read from the event;
+  they never reach the handler, and `baggage` or anything else a client
+  sends is ignored. The sampled flag of a client `traceparent` is honoured
+  by the SDK's default parent-based sampler, so a client decides whether its
+  own events are recorded; use `ParentBased(root=..., remote_parent_sampled=...,
+  remote_parent_not_sampled=...)` or `OTEL_TRACES_SAMPLER=always_on` to keep
+  that decision on the server.
+- HTTP requests and the websocket connection are wrapped in the standard
+  OpenTelemetry ASGI middleware (per-message websocket spans are off).
+- One `reflex.compile` span per app compile (`reflex.compile.trigger`,
+  `reflex.compile.dry_run`) with the stages `reflex.compile.evaluate_pages`,
+  `.pages`, `.copy_assets`, `.install_frontend_packages`, `.write` as
+  child spans.
+
+What leaves the process: event and handler names, a pseudonymous
+`session.id` (a truncated SHA-256 of the client token, never the token
+itself), exception types, messages and stack traces of failed handlers, and
+the ASGI middleware's request attributes with the `token` query parameter of
+the websocket URL redacted. Event payloads and state are never recorded.
+
+Metrics:
+
+| Instrument | Type | Unit | Attributes |
+| --- | --- | --- | --- |
+| `reflex.event.duration` | histogram | s | `reflex.event.name`, `reflex.event.background`, `error.type` |
+| `reflex.state.acquire.duration` | histogram | s | `reflex.event.name` |
+| `reflex.websocket.message.size` | histogram | By | `network.io.direction` (`transmit`/`receive`); default `sio` only |
+| `reflex.websocket.connections` | up-down counter | `{connection}` | |
+
+Plus the ASGI middleware's `http.server.*` metrics. The instrumentor opts the
+middleware into the stable HTTP semantic conventions
+(`OTEL_SEMCONV_STABILITY_OPT_IN=http`) unless that variable is already set,
+so request attributes use the same generation of names as Reflex's own.
+
+## Browser (frontend) tracing
+
+```python
+# rxconfig.py
+from reflex_otel import OtelPlugin
+
+config = rx.Config(
+    app_name="myapp",
+    plugins=[OtelPlugin(endpoint="https://collector.example.com/v1/traces")],
+)
+```
+
+The plugin compiles a small OpenTelemetry web bundle into the frontend:
+
+- every event sent to the backend gets a `PRODUCER` span and a W3C
+  `traceparent`, so the backend event span joins the browser trace (one trace
+  per interaction, browser → backend → chained events);
+- web vitals (`web_vital.LCP`, `CLS`, `INP`, `FCP`, `TTFB`) as spans with
+  `web_vital.value` / `web_vital.rating`;
+- with `render_timing=True`, React commits as `react.render` spans
+  (`react.render.phase`, `react.render.actual_duration_ms`); this aliases
+  `react-dom/client` to the `react-dom/profiling` build and emits one span per
+  commit, so it is off by default;
+- `socket.connect` / `socket.disconnect` spans for reconnect tracking
+  (unintentional disconnects are marked as errors).
+
+Options: `endpoint` (OTLP/HTTP traces URL reachable from the browser; required
+to export, with no default and no `OTEL_EXPORTER_OTLP_*` fallback: without it
+no exporter is installed and browser spans are dropped), `service_name` (default
+`<app_name>-frontend`), `headers` (compiled into the public bundle — no
+secrets), `web_vitals`, `render_timing`. The endpoint must allow CORS from the
+app origin.
+
+## Options
+
+`instrument()` accepts `tracer_provider`, `meter_provider`, `excluded_urls`
+(comma-separated URL patterns skipped by the ASGI middleware; defaults to
+`OTEL_PYTHON_REFLEX_EXCLUDED_URLS`, else `OTEL_PYTHON_EXCLUDED_URLS`, else
+`/ping` plus the compiled frontend's `/assets/` when the backend serves it,
+as `reflex run --env prod` does on one port; pass `""`, or set the variable
+to an empty string, to exclude nothing) and the ASGI hooks
+`server_request_hook`, `client_request_hook`, `client_response_hook`.
+Call `instrument()` before the app is served: `uninstrument()` turns the
+framework trace points off again, but an ASGI middleware that was already
+installed stays until the process restarts.

reflex_otel-0.1.0a1/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "reflex-otel"
+dynamic = ["version"]
+description = "OpenTelemetry instrumentation for the Reflex framework."
+license.text = "Apache-2.0"
+readme = "README.md"
+authors = [{ name = "Khaleel Al-Adhami", email = "khaleel@reflex.dev" }]
+maintainers = [{ name = "Khaleel Al-Adhami", email = "khaleel@reflex.dev" }]
+requires-python = ">=3.10"
+dependencies = [
+  "opentelemetry-api >=1.30.0,<2.0",
+  "opentelemetry-instrumentation >=0.49b0,<1.0",
+  "opentelemetry-instrumentation-asgi >=0.49b0,<1.0",
+  # A dev floor above every published reflex-base release: the release tooling
+  # lifts it to the earliest published version that satisfies it, which is the
+  # first release to ship reflex_base/otel.py.
+  "reflex-base >= 0.9.11a1",
+]
+
+[project.entry-points.opentelemetry_instrumentor]
+reflex = "reflex_otel.instrumentor:ReflexInstrumentor"
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.uv-dynamic-versioning]
+pattern-prefix = "reflex-otel-"
+fallback-version = "0.0.0dev0"
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning"]
+build-backend = "hatchling.build"

reflex_otel-0.1.0a1/src/reflex_otel/__init__.py

@@ -0,0 +1,37 @@
+"""OpenTelemetry instrumentation for the Reflex framework."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from reflex_otel.plugin import OtelPlugin
+
+if TYPE_CHECKING:
+    from reflex_otel.instrumentor import ReflexInstrumentor
+
+
+def __getattr__(name: str) -> Any:
+    """Load the instrumentor on first use.
+
+    ``rxconfig.py`` imports ``OtelPlugin`` in every CLI process; the instrumentor
+    pulls in ``opentelemetry.instrumentation`` (and ``wrapt``), which only the
+    backend needs.
+
+    Args:
+        name: The attribute being looked up.
+
+    Returns:
+        The instrumentor class.
+
+    Raises:
+        AttributeError: For any other name.
+    """
+    if name == "ReflexInstrumentor":
+        from reflex_otel.instrumentor import ReflexInstrumentor
+
+        return ReflexInstrumentor
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)
+
+
+__all__ = ["OtelPlugin", "ReflexInstrumentor"]

reflex_otel-0.1.0a1/src/reflex_otel/instrumentor.py

@@ -0,0 +1,241 @@
+"""The Reflex instrumentor: turns the framework's built-in trace points on."""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from collections.abc import Callable, Collection
+from typing import TYPE_CHECKING, Any, Literal
+
+from opentelemetry import trace
+from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
+from reflex_base import otel
+from reflex_base.config import get_config
+from reflex_base.environment import environment
+
+if TYPE_CHECKING:
+    from opentelemetry.trace import Span
+
+logger = logging.getLogger(__name__)
+
+# Reflex's own attributes follow the current semantic conventions; the contrib
+# ASGI middleware still defaults to the old HTTP names unless opted in, which
+# would mix both generations in one trace. The contrib packages read the
+# variable once per process, the first time any instrumentor's instrument()
+# runs, so it is set as early as this package can: at import of this module,
+# which every way of reaching the instrumentor goes through.
+os.environ.setdefault("OTEL_SEMCONV_STABILITY_OPT_IN", "http")
+
+# Per-message websocket spans are noise; Reflex emits one span per event instead.
+_ASGI_EXCLUDED_SPANS: list[Literal["receive", "send"]] = ["receive", "send"]
+# Frontend health polling; override with excluded_urls or the variables below.
+_DEFAULT_EXCLUDED_URLS = "/ping"
+_EXCLUDED_URLS_ENV_VARS = (
+    "OTEL_PYTHON_REFLEX_EXCLUDED_URLS",
+    "OTEL_PYTHON_EXCLUDED_URLS",
+)
+# The websocket connects with ?token=<client token>; the token authorizes access
+# to the session's state, so it is stripped from the URL attributes the ASGI
+# middleware records (old and current HTTP semantic conventions).
+_URL_ATTRIBUTES = ("http.url", "url.full", "url.query")
+# Setting either asks for the SDK to be configured from the environment.
+_EXPORTER_ENV_VARS = ("OTEL_TRACES_EXPORTER", "OTEL_METRICS_EXPORTER")
+_TOKEN_PARAM = re.compile(r"\btoken=[^&#]*")
+_REDACTED_TOKEN = "token=REDACTED"
+
+
+def _default_excluded_urls() -> str:
+    """URL patterns the ASGI middleware skips unless configured otherwise.
+
+    Returns:
+        The frontend health poll, plus the compiled frontend's static assets
+        when the backend serves them (``reflex run --env prod`` on one port),
+        where every chunk of a page load would otherwise get a span.
+    """
+    patterns = [_DEFAULT_EXCLUDED_URLS]
+    if environment.REFLEX_MOUNT_FRONTEND_COMPILED_APP.get():
+        assets = re.escape(get_config().prepend_frontend_path("/assets/"))
+        patterns.append(f"^[a-z]+://[^/]+{assets}")
+    return ",".join(patterns)
+
+
+def _configure_sdk_from_environment() -> None:
+    """Install SDK providers from the ``OTEL_*`` environment when nobody has yet.
+
+    Runs only when an exporter is requested through ``OTEL_TRACES_EXPORTER``
+    or ``OTEL_METRICS_EXPORTER`` and the global tracer provider is still the
+    API's proxy, i.e. neither the app nor ``opentelemetry-instrument`` set the
+    SDK up. It is what lets an app module enable telemetry with a single,
+    repeatable ``instrument()`` call instead of building providers itself.
+    """
+    if not any(os.environ.get(name) for name in _EXPORTER_ENV_VARS):
+        return
+    if not isinstance(trace.get_tracer_provider(), trace.ProxyTracerProvider):
+        return
+    try:
+        # The configurator behind opentelemetry-instrument and the distro package.
+        from opentelemetry.sdk._configuration import _OTelSDKConfigurator
+    except ImportError:
+        logger.warning(
+            "OTEL_TRACES_EXPORTER / OTEL_METRICS_EXPORTER are set but "
+            "opentelemetry-sdk is not installed; nothing is exported."
+        )
+        return
+    try:
+        _OTelSDKConfigurator().configure()
+    except Exception:
+        logger.exception(
+            "Configuring the OpenTelemetry SDK from the environment failed:"
+        )
+
+
+def _redact_token(span: Span, scope: Any) -> None:
+    """Strip the client token from a server span's URL attributes.
+
+    Args:
+        span: The span the ASGI middleware opened for the request.
+        scope: The ASGI scope (unused).
+    """
+    attributes = getattr(span, "attributes", None)
+    if not attributes:
+        return
+    for key in _URL_ATTRIBUTES:
+        value = attributes.get(key)
+        if isinstance(value, str) and "token=" in value:
+            span.set_attribute(key, _TOKEN_PARAM.sub(_REDACTED_TOKEN, value))
+
+
+def _server_request_hook(
+    user_hook: Callable[[Span, Any], None] | None,
+) -> Callable[[Span, Any], None]:
+    """Chain the token redaction in front of the user's server request hook.
+
+    Args:
+        user_hook: The hook passed to ``instrument()``, if any.
+
+    Returns:
+        The hook to install on the ASGI middleware.
+    """
+    if user_hook is None:
+        return _redact_token
+
+    def hook(span: Span, scope: Any) -> None:
+        _redact_token(span, scope)
+        user_hook(span, scope)
+
+    return hook
+
+
+class ReflexInstrumentor(BaseInstrumentor):
+    """Enable the trace points and metrics built into the Reflex runtime.
+
+    Usage::
+
+        ReflexInstrumentor().instrument(tracer_provider=provider)
+
+    or let ``opentelemetry-instrument`` load it through the
+    ``opentelemetry_instrumentor`` entry point.
+
+    Besides the per-event spans and metrics, the app's ASGI callable is
+    wrapped in the OpenTelemetry ASGI middleware, so HTTP requests (uploads,
+    custom API routes) and the websocket connection get server spans and
+    HTTP metrics as well.
+    """
+
+    def instrument(self, **kwargs: Any) -> None:
+        """Turn the Reflex trace points on, once per process.
+
+        A second call is a silent no-op, so the call needs no guard even when
+        the app module is imported more than once (test harnesses do that).
+
+        Args:
+            **kwargs: See :meth:`_instrument`.
+        """
+        if self.is_instrumented_by_opentelemetry:
+            return
+        super().instrument(**kwargs)
+
+    def instrumentation_dependencies(self) -> Collection[str]:
+        """Return the requirements the base class checks before instrumenting.
+
+        Empty on purpose: reflex-base is a hard dependency of this package, so
+        the resolver already enforces its floor at install time. A runtime
+        re-check would only reject the workspace's own development builds.
+
+        Returns:
+            No requirements.
+        """
+        return ()
+
+    def _instrument(self, **kwargs: Any) -> None:
+        """Turn on the Reflex trace points.
+
+        Args:
+            **kwargs: ``tracer_provider`` and ``meter_provider`` select the
+                providers (default: the global ones; when neither is given,
+                ``OTEL_TRACES_EXPORTER`` / ``OTEL_METRICS_EXPORTER`` set and no
+                SDK installed yet, the SDK is configured from ``OTEL_*``). ``excluded_urls`` is a
+                comma-separated list of URL patterns the ASGI middleware skips
+                (default: ``OTEL_PYTHON_REFLEX_EXCLUDED_URLS``, else
+                ``OTEL_PYTHON_EXCLUDED_URLS``, else ``/ping`` plus the compiled
+                frontend's ``/assets/`` when the backend serves it; pass ``""``
+                to exclude nothing).
+                ``server_request_hook``, ``client_request_hook`` and
+                ``client_response_hook`` are forwarded to the ASGI middleware.
+        """
+        if os.environ.get("OTEL_SDK_DISABLED", "").strip().lower() == "true":
+            # The SDK is a no-op; skip the per-event trace points as well.
+            logger.info("OTEL_SDK_DISABLED is set; Reflex trace points stay off.")
+            return
+        # Imported here so `from reflex_otel import OtelPlugin` in rxconfig.py
+        # stays cheap for CLI processes that never instrument.
+        from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware
+        from opentelemetry.util.http import parse_excluded_urls
+
+        tracer_provider = kwargs.get("tracer_provider")
+        meter_provider = kwargs.get("meter_provider")
+        if tracer_provider is None and meter_provider is None:
+            _configure_sdk_from_environment()
+        excluded_urls = kwargs.get("excluded_urls")
+        if excluded_urls is None:
+            # A variable set to "" means "exclude nothing", like an empty kwarg.
+            for name in _EXCLUDED_URLS_ENV_VARS:
+                if (value := os.environ.get(name)) is not None:
+                    excluded_urls = value
+                    break
+
+        def asgi_middleware(app: otel.ASGIApp) -> otel.ASGIApp:
+            # Defaults resolve when the app builds its ASGI callable: only then
+            # is it known whether the compiled frontend is mounted into it.
+            urls = _default_excluded_urls() if excluded_urls is None else excluded_urls
+            # opentelemetry-instrumentation-asgi < 0.56b0 stores a str verbatim
+            # and then calls .url_disabled() on it, failing every request.
+            if isinstance(urls, str):
+                urls = parse_excluded_urls(urls)
+            return OpenTelemetryMiddleware(
+                app,
+                excluded_urls=urls,
+                server_request_hook=_server_request_hook(
+                    kwargs.get("server_request_hook")
+                ),
+                client_request_hook=kwargs.get("client_request_hook"),
+                client_response_hook=kwargs.get("client_response_hook"),
+                tracer_provider=tracer_provider,
+                meter_provider=meter_provider,
+                exclude_spans=_ASGI_EXCLUDED_SPANS,
+            )
+
+        otel.enable(
+            tracer_provider=tracer_provider,
+            meter_provider=meter_provider,
+            asgi_middleware_factory=asgi_middleware,
+        )
+
+    def _uninstrument(self, **kwargs: Any) -> None:
+        """Turn off the Reflex trace points.
+
+        Args:
+            **kwargs: Ignored.
+        """
+        otel.disable()

reflex_otel-0.1.0a1/src/reflex_otel/otel.js

@@ -0,0 +1,209 @@
+/**
+ * Browser-side OpenTelemetry for Reflex apps, installed by reflex_otel.OtelPlugin.
+ *
+ * - Every event and file upload sent to the backend is marked with a PRODUCER
+ *   span; sampled sends carry a W3C `traceparent`, so the backend event span
+ *   joins the browser trace.
+ * - Web vitals (LCP, CLS, INP, FCP, TTFB) are reported as spans.
+ * - React commits are reported as `react.render` spans via a root <Profiler>
+ *   (opt-in; production builds need the react-dom profiling alias the plugin adds).
+ * - Socket connects/disconnects are recorded as spans for reconnect tracking.
+ *
+ * Configuration comes from `env.json` (`OTEL` key), written by the plugin.
+ */
+import { createElement, Profiler } from "react";
+import {
+  context,
+  SpanKind,
+  SpanStatusCode,
+  trace,
+  TraceFlags,
+} from "@opentelemetry/api";
+import {
+  setGlobalErrorHandler,
+  W3CTraceContextPropagator,
+} from "@opentelemetry/core";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import {
+  AlwaysOffSampler,
+  BatchSpanProcessor,
+  ParentBasedSampler,
+  TraceIdRatioBasedSampler,
+  WebTracerProvider,
+} from "@opentelemetry/sdk-trace-web";
+import { onCLS, onFCP, onINP, onLCP, onTTFB } from "web-vitals";
+import env from "$/env.json";
+
+const config = env.OTEL ?? {};
+// No endpoint, no exporter: nothing is sampled, so no traceparent is injected
+// either and the backend keeps tracing on its own.
+const exporting = Boolean(config.endpoint);
+
+const provider = new WebTracerProvider({
+  resource: resourceFromAttributes({ "service.name": config.service_name }),
+  // Browser spans are trace roots. Only a sampled span injects a `traceparent`
+  // (see onEventSend), so the backend inherits a positive decision and makes
+  // its own for everything else.
+  sampler: exporting
+    ? new ParentBasedSampler({
+        root: new TraceIdRatioBasedSampler(config.sample_rate ?? 1),
+      })
+    : new AlwaysOffSampler(),
+  spanProcessors: exporting
+    ? [
+        new BatchSpanProcessor(
+          new OTLPTraceExporter({
+            url: config.endpoint,
+            headers: config.headers,
+          }),
+        ),
+      ]
+    : [],
+});
+const tracer = provider.getTracer("reflex", config.version);
+
+// The exporter swallows its own failures (a collector missing CORS headers
+// surfaces only as the browser's console line), so route the first one through
+// the same path as any other frontend exception: it reaches the backend's
+// frontend_exception_handler and the terminal. Once per page: exports retry on
+// every batch and would otherwise repeat the report.
+let exportFailureReported = false;
+setGlobalErrorHandler((error) => {
+  if (exportFailureReported || typeof window.onerror !== "function") {
+    return;
+  }
+  exportFailureReported = true;
+  const cause = error?.cause ? ` (${error.cause})` : "";
+  const hint = error?.cause
+    ? " A collector on another origin must allow CORS requests from this page."
+    : "";
+  const report = new Error(
+    `OtelPlugin: exporting browser spans to ${config.endpoint} failed: ${error?.message ?? error}${cause}.${hint}`,
+  );
+  report.name = "OtelExportError";
+  window.onerror(report.message, null, null, null, report);
+});
+const propagator = new W3CTraceContextPropagator();
+
+const setter = {
+  set(carrier, key, value) {
+    carrier[key] = value;
+  },
+};
+
+// Absolute epoch time (ms) of a performance timeline offset.
+const epoch = (offset) => performance.timeOrigin + offset;
+
+let connectCount = 0;
+
+// Fire-and-forget to the backend: a PRODUCER span that marks the send. The
+// browser has no completion signal for an event, so it has no duration. An
+// unsampled span carries no traceparent: the backend then samples the event
+// as a root of its own instead of inheriting "not sampled".
+const markSend = (name, carrier) => {
+  const span = tracer.startSpan(name, {
+    kind: SpanKind.PRODUCER,
+    attributes: { "reflex.event.name": name },
+  });
+  if (span.spanContext().traceFlags & TraceFlags.SAMPLED) {
+    propagator.inject(trace.setSpan(context.active(), span), carrier, setter);
+  }
+  span.end();
+};
+
+window.__reflex_otel = {
+  onEventSend(event) {
+    markSend(event.name, event);
+  },
+  onUploadSend(handler, headers) {
+    // The upload is an HTTP request: the traceparent travels as a header and
+    // the backend's request span, then the handler span, join the trace.
+    markSend(handler, headers);
+  },
+  onSocketConnect() {
+    connectCount += 1;
+    tracer
+      .startSpan("socket.connect", {
+        attributes: { "reflex.socket.connect_count": connectCount },
+      })
+      .end();
+  },
+  onSocketDisconnect(reason) {
+    const span = tracer.startSpan("socket.disconnect", {
+      attributes: { "reflex.socket.disconnect_reason": reason },
+    });
+    // Intentional disconnects (navigation, server shutdown) are not errors.
+    if (!reason.startsWith("io ")) {
+      span.setStatus({ code: SpanStatusCode.ERROR, message: reason });
+    }
+    span.end();
+    // Unload disconnects happen after the processor's own pagehide flush ran,
+    // so the span would otherwise sit in the queue while the page tears down.
+    // Export failures are already reported by the global error handler.
+    provider.forceFlush().catch(() => {});
+  },
+};
+
+if (config.web_vitals) {
+  // FCP/LCP/TTFB values are offsets from the current navigation: activation
+  // start for a (pre)rendered page, `navigationStartTime` for a BFCache
+  // restore or soft navigation. INP is a duration starting at its interaction;
+  // CLS is unitless and reported as an instant.
+  const report = (metric) => {
+    const activationStart =
+      performance.getEntriesByType("navigation")[0]?.activationStart ?? 0;
+    const attributes = {
+      "web_vital.name": metric.name,
+      "web_vital.value": metric.value,
+      "web_vital.rating": metric.rating,
+      "web_vital.id": metric.id,
+      "web_vital.navigation_type": metric.navigationType,
+    };
+    let startTime = epoch(metric.navigationStartTime || activationStart);
+    let endTime = startTime + metric.value;
+    if (metric.name === "INP") {
+      startTime = epoch(metric.entries[0]?.startTime ?? 0);
+      endTime = startTime + metric.value;
+    } else if (metric.name === "CLS") {
+      startTime = endTime = Date.now();
+    }
+    tracer
+      .startSpan(`web_vital.${metric.name}`, { startTime, attributes })
+      .end(endTime);
+  };
+  onCLS(report);
+  onFCP(report);
+  onINP(report);
+  onLCP(report);
+  onTTFB(report);
+}
+
+const onRender = (
+  id,
+  phase,
+  actualDuration,
+  baseDuration,
+  startTime,
+  commitTime,
+) => {
+  tracer
+    .startSpan("react.render", {
+      startTime: epoch(startTime),
+      attributes: {
+        "react.profiler.id": id,
+        "react.render.phase": phase,
+        "react.render.actual_duration_ms": actualDuration,
+        "react.render.base_duration_ms": baseDuration,
+      },
+    })
+    .end(epoch(commitTime));
+};
+
+/**
+ * Root wrapper used by the patched entry: profiles React commits when enabled.
+ */
+export const OtelRoot = ({ children }) =>
+  config.render_timing
+    ? createElement(Profiler, { id: "app", onRender }, children)
+    : children;

reflex_otel-0.1.0a1/src/reflex_otel/plugin.py

@@ -0,0 +1,193 @@
+"""Compile-time plugin that adds browser-side OpenTelemetry to a Reflex app."""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from reflex_base.config import get_config
+from reflex_base.constants.base import ReactRouter, Reflex
+from reflex_base.constants.compiler import Embed
+from reflex_base.plugins.base import Plugin
+
+logger = logging.getLogger(__name__)
+
+BROWSER_MODULE = "utils/otel.js"
+_BROWSER_MODULE_SOURCE = Path(__file__).with_name("otel.js")
+
+# Pinned npm packages for the browser module.
+FRONTEND_DEPENDENCIES = (
+    "@opentelemetry/api@1.9.1",
+    "@opentelemetry/core@2.10.0",
+    "@opentelemetry/exporter-trace-otlp-http@0.221.0",
+    "@opentelemetry/resources@2.10.0",
+    "@opentelemetry/sdk-trace-web@2.10.0",
+    "web-vitals@6.1.1",
+)
+
+_ENTRY_IMPORT = 'import { OtelRoot } from "$/utils/otel";\n'
+# React roots rendered by the entry: the hydrated document root, and the
+# embed entry's client-rendered root. Each is wrapped in the profiling root.
+_ENTRY_ROOT_ANCHORS = (
+    "createElement(HydratedRouter)",
+    "createElement(RouterProvider, { router })",
+)
+
+# React strips <Profiler> from production builds; the profiling build keeps it.
+# The alias is appended to the existing `resolve.alias` array of the generated
+# config: a second `resolve` key would silently override the first one. The
+# anchor tolerates whitespace changes in the template.
+_VITE_CONFIG_ANCHOR = re.compile(
+    r"resolve:\s*\{\s*mainFields:\s*\[[^\]]*\],\s*alias:\s*\[[ \t]*\n"
+)
+_VITE_PROFILING_ALIAS = (
+    '      { find: "react-dom/client", replacement: "react-dom/profiling" },\n'
+)
+
+
+def _patch_entry_client(content: str) -> str:
+    """Load the browser module and profile the React root in ``entry.client.js``.
+
+    Args:
+        content: The current entry file.
+
+    Returns:
+        The patched entry file.
+    """
+    if _ENTRY_IMPORT in content:
+        return content
+    if not any(anchor in content for anchor in _ENTRY_ROOT_ANCHORS):
+        logger.warning(
+            "OtelPlugin: no React root found in %s; render timing is disabled.",
+            Embed.ENTRY_PATH,
+        )
+    for anchor in _ENTRY_ROOT_ANCHORS:
+        content = content.replace(anchor, f"createElement(OtelRoot, null, {anchor})", 1)
+    return _ENTRY_IMPORT + content
+
+
+def _patch_vite_config(content: str) -> str:
+    """Alias react-dom to its profiling build so <Profiler> works in production.
+
+    Args:
+        content: The current ``vite.config.js``.
+
+    Returns:
+        The patched config.
+
+    Raises:
+        RuntimeError: If the config no longer has the expected shape.
+    """
+    if _VITE_PROFILING_ALIAS in content:
+        return content
+    match = _VITE_CONFIG_ANCHOR.search(content)
+    if match is None:
+        msg = (
+            "OtelPlugin cannot enable render_timing: the resolve.alias block "
+            f"was not found in {ReactRouter.VITE_CONFIG_FILE}."
+        )
+        raise RuntimeError(msg)
+    return content[: match.end()] + _VITE_PROFILING_ALIAS + content[match.end() :]
+
+
+# repr=False keeps Plugin.__repr__ (headers would print otherwise); eq=False
+# keeps instances hashable, like every other plugin.
+@dataclass(repr=False, eq=False)
+class OtelPlugin(Plugin):
+    """Ship the reflex-otel browser module with the compiled frontend.
+
+    Add it to ``rx.Config(plugins=[...])``. Every event sent to the backend
+    then carries a W3C ``traceparent`` (the backend event span becomes a
+    child of the browser span), and web vitals, React commit timings and
+    socket (re)connects are exported as spans.
+
+    The endpoint must accept OTLP/HTTP from the browser (CORS). ``headers``
+    are compiled into the public bundle, so never put secrets there.
+    """
+
+    # OTLP/HTTP traces URL the browser exports to. Deliberately no default and
+    # no OTEL_EXPORTER_OTLP_* fallback: those name the backend's collector,
+    # usually on a private network. Without it no exporter is installed.
+    endpoint: str | None = None
+    # Resource service.name of the browser spans; defaults to "<app_name>-frontend".
+    service_name: str | None = None
+    # Extra HTTP headers sent by the browser exporter (public!).
+    headers: dict[str, str] = field(default_factory=dict)
+    web_vitals: bool = True
+    # One `react.render` span per React commit (uses the react-dom profiling
+    # build in production). Off by default because of the span volume.
+    render_timing: bool = False
+    # Fraction of browser traces to sample (0..1). Browser spans are trace
+    # roots, so the backend's parent-based sampler follows this decision.
+    sample_rate: float = 1.0
+
+    def __post_init__(self):
+        """Validate the sampling ratio.
+
+        Raises:
+            ValueError: If ``sample_rate`` is outside ``[0, 1]``.
+        """
+        if not 0 <= self.sample_rate <= 1:
+            msg = f"sample_rate must be between 0 and 1, got {self.sample_rate!r}."
+            raise ValueError(msg)
+
+    def get_frontend_dependencies(self, **context: Any) -> tuple[str, ...]:
+        """Return the npm packages the browser module imports.
+
+        Args:
+            context: The context for the plugin.
+
+        Returns:
+            The pinned package specifiers.
+        """
+        return FRONTEND_DEPENDENCIES
+
+    def get_static_assets(self, **context: Any) -> list[tuple[Path, str]]:
+        """Return the browser module to write into ``.web``.
+
+        Args:
+            context: The context for the plugin.
+
+        Returns:
+            The module path and its source.
+        """
+        return [(Path(BROWSER_MODULE), _BROWSER_MODULE_SOURCE.read_text())]
+
+    def pre_compile(self, **context: Any) -> None:
+        """Patch the client entry to load the module and profile the root.
+
+        Args:
+            context: The pre-compile plugin context.
+        """
+        if self.endpoint is None:
+            logger.warning(
+                "OtelPlugin: no endpoint configured; browser spans are not exported."
+            )
+        context["add_modify_task"](Embed.ENTRY_PATH, _patch_entry_client)
+        if self.render_timing:
+            context["add_modify_task"](ReactRouter.VITE_CONFIG_FILE, _patch_vite_config)
+
+    def update_env_json(self, **context: Any) -> dict[str, Any]:
+        """Expose the browser configuration through ``env.json``.
+
+        Args:
+            context: The context for the plugin.
+
+        Returns:
+            The ``OTEL`` entry read by the browser module.
+        """
+        return {
+            "OTEL": {
+                "endpoint": self.endpoint,
+                "service_name": self.service_name
+                or f"{get_config().app_name}-frontend",
+                "headers": self.headers,
+                "web_vitals": self.web_vitals,
+                "render_timing": self.render_timing,
+                "sample_rate": self.sample_rate,
+                "version": Reflex.VERSION,
+            }
+        }