react-telemetry-open

React-aware, vendor-neutral observability for React 18+ applications.

Zero boilerplate. OTLP output. No vendor lock-in.

---

Why react-telemetry-open

Existing observability tools operate below the React layer:

• Error tracking tools capture exceptions — but not render performance, component attribution, or concurrent mode timing
• RUM tools measure browser-level metrics — React-specific signals like unnecessary re-renders emerge at a layer above what standard RUM instruments
• Raw OpenTelemetry requires significant manual instrumentation to produce React-aware signals
• Development-only profilers produce no production observability data

react-telemetry-open fills this gap. It tracks signals that only exist inside React — unnecessary re-renders, component-attributed long tasks, rage clicks, ErrorBoundary catches — and exports them as standard OTLP. One package. Any backend. Zero configuration to start.

---

What it tracks

React signals — render count and duration per component, rage clicks, time to first interaction, ErrorBoundary crashes with componentStack

Web Vitals — FCP, LCP, FID, CLS, INP with good/needs-improvement/poor ratings per Google thresholds

Network — every fetch() and XHR call with duration, status, URL. Error rate over 60-second windows. Online/offline events

Browser — JS errors with stack traces, unhandled promise rejections, long tasks, JS heap memory

Custom — track any business event with useTrackEvent()

Context on every event — component name, route, anonymous session ID, device type, browser, OS, network quality, React version

---

Quick start

npm install react-telemetry-open
npx react-telemetry-open init

The CLI reads your package.json, generates telemetry.config.json, and tells you exactly what to add to your app.

Add to your app entry point (src/main.tsx):

import { TelemetryProvider } from 'react-telemetry-open'
import appConfig from '../telemetry.config.json'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <TelemetryProvider appConfig={appConfig}>
      <BrowserRouter>
        <App />
      </BrowserRouter>
    </TelemetryProvider>
  </React.StrictMode>
)

Open DevTools console. Telemetry appears immediately — no backend required.

▼ [react-telemetry-open] react.render.duration
    Type:      metric
    Route:     /dashboard
    Duration:  2.40ms
    Value:     2.4 ms
    Attributes: { component: "Dashboard", renderCount: 1 }
  ▶ App        { name: "my-app", version: "1.0.0", environment: "development" }
  ▶ Session    { id: "550e8400-...", duration: "4s", pageViews: 1 }
  ▶ Device     { type: "desktop", viewport: "1440×900", cpuCores: 10 }
  ▶ Browser    { name: "Chrome", version: "124", os: "macOS 14.4" }
  ▶ Network    { online: true, type: "4g" }

---

Hooks

Track component renders

import { useTraceRender } from 'react-telemetry-open'

function UserDashboard() {
  useTraceRender('UserDashboard')
  return <div>...</div>
}

Emits react.render.duration with render time, render count, and priority on every render.

Track interactions

import { useTrackInteraction } from 'react-telemetry-open'

function CheckoutButton() {
  const { onClick } = useTrackInteraction('checkout-submit')
  return <button onClick={onClick}>Buy Now</button>
}

Tracks clicks and inputs. Automatically detects rage clicks (3+ rapid clicks = user frustration).

Track custom events

import { useTrackEvent } from 'react-telemetry-open'

function OnboardingFlow() {
  const track = useTrackEvent()

  const handleComplete = () => {
    track('onboarding:completed', { step: 4, plan: 'pro' })
  }
}

Track route changes

import { useRouteTrace } from 'react-telemetry-open'

function AppRouter() {
  useRouteTrace()
  return <Routes>...</Routes>
}

Emits route.change with fromRoute, toRoute, and navigationDurationMs on every navigation.

---

TelemetryProvider props

appConfig — static identity. Import your telemetry.config.json here. Generated by npx react-telemetry-open init.

config — runtime overrides. For values known only at runtime — sampling rate, consent flags, feature toggles.

import appConfig from '../telemetry.config.json'

<TelemetryProvider
  appConfig={appConfig}
  config={{
    sampling: { rate: isSlowDevice ? 0.1 : 1.0 },
    signals: { memory: hasUserConsented },
  }}
>

Both props are optional. Without either, the package works with defaults and shows a setup warning in development.

---

Production setup

Run init to generate both config files:

npx react-telemetry-open init

Edit telemetry.config.prod.json:

{
  "app": {
    "environment": "production",
    "buildId": "$VITE_BUILD_ID"
  },
  "exporter": {
    "type": "otlp",
    "url": "$VITE_OTEL_URL",
    "apiKey": "$VITE_OTEL_KEY"
  },
  "sampling": {
    "rate": 0.1
  },
  "debug": false
}

Add to .env.production:

VITE_OTEL_URL=https://your-collector-endpoint/otlp
VITE_OTEL_KEY=your-api-key
VITE_BUILD_ID=your-git-sha

Switch config based on environment in src/main.tsx:

import appConfig from '../telemetry.config.json'
import prodConfig from '../telemetry.config.prod.json'

const config = import.meta.env.PROD ? prodConfig : appConfig

<TelemetryProvider appConfig={config}>

---

Backend compatibility

react-telemetry-open sends standard OTLP/HTTP — works with any OTel-compatible backend.

Backend	Direct from browser	Notes
Self-hosted OTel Collector	✅	Configure CORS on your collector
Grafana Alloy (self-hosted)	✅	Configure CORS in alloy.config
Honeycomb	✅	Works directly
Axiom	✅	Works directly
Grafana Cloud	⚠️	Requires a proxy — CORS not supported
Any OTLP/HTTP endpoint	✅	As long as CORS headers are present

Grafana Cloud and CORS

Grafana Cloud's OTLP gateway does not support browser CORS. A lightweight proxy is required:

Browser → your proxy (CORS enabled) → Grafana Cloud

The simplest proxy is a single serverless function (Vercel/Netlify) that forwards requests with your Grafana credentials server-side. This keeps your API key off the client.

For self-hosted OTel Collector or Grafana Alloy, direct browser connections work — configure cors.allowed_origins in your collector.

---

Browser support

Signal	Chrome	Edge	Firefox	Safari
Render timing	✅	✅	✅	✅
Web Vitals (full)	✅	✅	FCP only	FCP 15.4+
Long tasks	✅	✅	❌	❌
Memory	✅	✅ 124+	❌	❌
Network	✅	✅	✅	✅
Errors	✅	✅	✅	✅
Resource timing	✅	✅	✅	✅

---

Privacy

• Anonymous sessions — random UUIDs, never linked to user identity
• No input values — only that an interaction occurred, never what was typed
• URL sanitisation — query params stripped; numeric IDs replaced with :id
• No raw user agent — parsed to structured fields only
• Do Not Track — browser DNT setting honoured; all collection skipped when enabled

API keys and collector URLs must never be hardcoded. Use $VAR_NAME syntax — resolved from environment variables at runtime:

{
  "exporter": {
    "url": "$VITE_OTEL_URL",
    "apiKey": "$VITE_OTEL_KEY"
  }
}

---

Contributing & Bug Reports

Found a bug? Have a feature request?

• Report a bug → Open a Bug Report
• Request a feature → Open a Feature Request
• Contribute code → Read CONTRIBUTING.md then open a Pull Request

All contributions are welcome.

---

Documentation

• Getting Started
• Configuration Reference
• Interpreting Your Data
• Signals Overview
• Signals Reference
• API Reference
• System Design
• Troubleshooting

---

License

Apache 2.0 — Copyright 2026 Abhishek Sinha ([email protected])

See LICENSE and NOTICE.