feat: add React + Sentry example

.gitignore

@@ -19,5 +19,7 @@ go-zero/go-zero
 db.sqlite3
 gorm.db
 
+**/docs/superpowers/
+
 # Misc
 .DS_Store

README.md

@@ -54,6 +54,7 @@ project.
 - [sentry-go](sentry-go) — errors and tracing with sentry-go.
 - [sentry-python](sentry-python) — nested exception chains with sentry-python.
 - [sentry-browser](sentry-browser) — events with @sentry/browser.
+- [sentry-react](sentry-react) — errors, breadcrumbs, and tracing with @sentry/react in a todo app.
 
 ### Logs, Collector, and demos
 

sentry-react/.env.example

@@ -0,0 +1,12 @@
+# Copy this file to `.env` and paste your Uptrace Sentry DSN.
+#
+# Get it from Uptrace: open your project, go to "DSN", switch to the
+# "Sentry" tab, and copy the DSN. It looks like:
+#
+#   http://<project_token>@<uptrace-host>/<project_id>
+VITE_SENTRY_DSN=
+
+# Optional: base URL of your Uptrace UI (its site URL), used to turn the current
+# trace badge into a clickable link to that trace. Without it the badge still
+# shows the trace id.
+VITE_UPTRACE_URL=

sentry-react/.gitignore

@@ -0,0 +1,8 @@
+node_modules
+dist
+.env
+*.local
+*.tsbuildinfo
+test-results
+playwright-report
+blob-report

sentry-react/AGENTS.md

@@ -0,0 +1,82 @@
+# React + Sentry example
+
+Rules here apply to `examples/sentry-react`, one of the `uptrace/examples` projects:
+small, runnable apps that show how to send data to Uptrace. This one shows how
+to integrate the Sentry SDK (`@sentry/react`) with a React frontend reporting to
+Uptrace, and that is the one thing it teaches. Keep it minimal: an example is
+read more than it is run, so every extra feature, file, or dependency is noise
+that hides the integration. Add something only when it makes the integration
+clearer, not the app richer. The `README.md` is the primary deliverable; when
+behavior changes, update it in the same change.
+
+## Core Rules
+
+- The only Uptrace-specific code is `Sentry.init()` in `src/instrument.ts`;
+  `src/telemetry.ts` holds the rest of the Sentry SDK usage. `instrument.ts` is
+  imported first in `src/main.tsx` (before React) so instrumentation is in place
+  before the app renders. `instrument.ts` also installs a reporting transport
+  wrapper (`src/delivery.ts`) that observes send outcomes for the UI — it wraps
+  the standard fetch transport and does not change delivery, so it is not an
+  Uptrace-specific adapter.
+- The DSN comes from `VITE_SENTRY_DSN`; never hardcode a DSN. `.env` is
+  gitignored — keep `.env.example` as the template and document it in the README.
+- Uptrace ingests the standard Sentry protocol, so there is no Uptrace exporter
+  or adapter. If you reach for one, you are doing it wrong.
+- Never reach for `Sentry.logger.*` / `enableLogs`. They emit `log` envelope items,
+  and Uptrace's Sentry ingest handles only `transaction`, `event` and
+  `client_report` — anything else is skipped, so the data is silently dropped (the
+  SDK still reports a successful send). A `logger.*` Logs panel was added and
+  removed once already; do not re-add it. `Sentry.captureMessage()` is the path
+  that works: Uptrace stores a Sentry event carrying a `message` as a log
+  (`event_name=log`, the level normalized into `log_severity`).
+- The app is a small routed single-page app: Vite + React + TypeScript with
+  React Router v7, state held in memory (`useState`). There is no separate
+  backend — the `/api/ok|slow|fail` endpoints are Vite dev-server middleware
+  (`vite.config.ts`), so they exist under `npm run dev` but not in a static
+  `vite preview` build. No UI framework.
+- Navigation is traced by `Sentry.wrapReactRouterRouting` (`src/main.tsx`),
+  which names each navigation trace by its route pattern (`/products/:id`,
+  `/categories/*`), not the concrete URL. Keep that: it is a deliberate
+  low-cardinality demonstration, and the concrete URL still rides on the root span
+  as `url.full`.
+- Each control fires an explicit Sentry signal and leaves a breadcrumb; keep both
+  going for new controls. The signals are: Todos (a `created todo` span on add, a
+  back-dated `completed todo` span on Done), HTTP (`/api/ok|slow|fail` → a
+  `GET /api/…` span nested under the page root, wrapping the SDK's auto-instrumented
+  `http.client` span; Fail also captures an error), and Errors (one exception per
+  button — the home panel uses fixed types, each sub-route its own named errors).
+  The not-found route auto-reports a `PageNotFound` error when shown. Document any
+  new control in the README.
+- Hard rule: never call `Sentry.startNewTrace()` — the trace comes only from the
+  browser-tracing integration (a pageload trace on load, a navigation trace on each
+  route change). Every signal attaches to the current trace **nested under the
+  page's root span** (via `startSpan`/`startInactiveSpan` with `parentSpan` +
+  `forceTransaction`, wired in `telemetry.ts`), because Uptrace renders only one
+  root span per trace — sibling roots would be dropped from the trace tree.
+- TypeScript with `strict` on. JS/TS comments use `//` line comments, including
+  comments for exported types and functions. Comment only what the code cannot say.
+- Order code top-down, as the Go backend does: module doc, imports, package-level
+  consts, then the entry points, then their callees below them — a helper goes under
+  the function that calls it, never above. A const or type used by exactly one
+  function sits directly above that function. Read a file top to bottom and the call
+  stack unfolds in order.
+- The UI is four files grouped by what they do — `shell.tsx` (frame), `inspector.tsx`
+  (bottom readout), `panels.tsx` (the demo controls), `pages.tsx` (the routes) — not
+  one file per component. An example is read top to bottom; keep it that way.
+- Plain CSS only. Design tokens (OKLCH colors, radius, easing) live in `:root` in
+  `src/index.css`; component styles in `src/App.css`. No Tailwind, no component
+  library, no CSS-in-JS. Keep the dependency list short.
+
+## Commands
+
+- `npm install`
+- `npm run dev` — local dev server.
+- `npm run build` — type-check (`tsc -b`) and production build.
+- `npm test` — two Playwright specs, guarding only what is Uptrace-specific: single-
+  root trace nesting, and route-pattern trace naming. They read the intercepted Sentry
+  envelopes, so no credentials and no running Uptrace are needed: `playwright.config.ts`
+  gives the test dev server a dummy DSN and ignores your `.env`, keeping them green on
+  a fresh clone. Keep it that way — the SDK is inert without a DSN (no spans, no trace
+  ids, no envelopes), so a suite that reads them must supply one itself. The app must
+  not carry test hooks: assert on what it sends, never on globals it exposes for tests.
+  Run `npm run build` and `npm test` when changing behavior, and click through the app.

sentry-react/README.md

@@ -0,0 +1,126 @@
+# React + Sentry → Uptrace
+
+A minimal React (Vite + TypeScript) app instrumented with the
+[`@sentry/react`](https://docs.sentry.io/platforms/javascript/guides/react/)
+SDK. Uptrace speaks the Sentry ingest protocol, so the SDK sends data to Uptrace
+**without any extra exporter** — you point the SDK's DSN at your Uptrace project.
+
+Every control fires one explicit Sentry signal and shows what it sent in an
+in-page inspector, so you can watch each signal type and then find it in Uptrace.
+
+- **Todos** — add a todo (a `created todo` span) and mark it **Done** (a
+  `completed todo` span whose duration is how long the todo was open).
+- **HTTP** — **OK / Slow (~5s) / Fail (500)** fetch a dev endpoint. Each request is
+  a `GET /api/…` span on the current trace, wrapping the `http.client` span the SDK
+  instruments fetch with (Fail also captures an error).
+- **Errors** — one button per type (`Error`, `TypeError`, `RangeError`,
+  `SyncError`); each is a distinct, findable issue.
+- **Routes** — a side nav lists the app's routes (Products, Categories, News,
+  Settings, Redirect, Not found). Each navigation mints a new trace named by its
+  route **pattern** (`/products/:id`, `/categories/*`), so Uptrace groups
+  navigations by route rather than by concrete URL. An unmatched path renders
+  NotFound, which reports itself as a `PageNotFound` error.
+- A **trace badge** shows the current trace id (and a link to it if you set
+  `VITE_UPTRACE_URL`); a bottom **inspector** shows what the last control sent,
+  whether it reached Uptrace (its **delivery status**), and (when
+  `VITE_UPTRACE_URL` is set) links straight to it in Uptrace — to the exact span
+  for a custom span (`/traces/<traceId>/<spanId>`), or to the trace for other
+  signals.
+
+> Session Replay is intentionally not included: Uptrace's Sentry ingest does not
+> confirm replay support, and this example only demonstrates signals you can find
+> in Uptrace (errors, spans).
+
+## How it works
+
+The Sentry SDK builds its request URLs from the DSN
+(`http://<token>@<host>/<project_id>` → `POST <host>/api/<project_id>/envelope/`),
+which is exactly what Uptrace exposes. So instrumentation is a standard
+`Sentry.init({ dsn })` — see [`src/instrument.ts`](src/instrument.ts). The app
+never starts a trace itself: the React Router tracing integration opens a
+pageload trace on load and a navigation trace on each route change, and every
+span, request, and error attaches to the current trace.
+
+The **HTTP** panel calls `/api/ok`, `/api/slow`, and `/api/fail`, served by a
+small Vite dev-server middleware (see [`vite.config.ts`](vite.config.ts)) so
+there is **no separate backend**. These endpoints exist under `npm run dev`; a
+static `vite preview` build does not include them.
+
+### One trace, one tree
+
+Every signal on a page (custom spans, errors, HTTP) is nested under that
+page's pageload/navigation root span, so opening the trace in Uptrace shows one
+tree with everything in it. Uptrace stores one root span per trace, so signals are
+attached as children rather than as separate roots. Each interaction is therefore
+sent as its own Sentry transaction — you will see multiple transaction envelopes
+for one page in the Network tab; in Uptrace they appear as one nested tree.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org) 20 or newer.
+- A running Uptrace and a project to send data to:
+  - **Self-hosted:** [Uptrace get-started guide](https://uptrace.dev/get-started).
+    The Sentry ingest host is usually `localhost:14318`.
+  - **Uptrace Cloud:** create a project at <https://app.uptrace.dev>.
+
+## 1. Get your Uptrace Sentry DSN
+
+Open your project in Uptrace → **Project → Data Source Name** → **Sentry** tab →
+copy the DSN. It looks like `http://project2_secret_token@localhost:14318/2`.
+
+## 2. Configure and run
+
+```bash
+# from this directory: examples/sentry-react
+cp .env.example .env
+# edit .env: paste your DSN into VITE_SENTRY_DSN
+# optionally set VITE_UPTRACE_URL to your Uptrace UI for clickable trace links
+
+npm install
+npm run dev
+```
+
+Open the URL Vite prints (default <http://localhost:5173>).
+
+## 3. Generate and find data
+
+Use the panels, watching the inspector and delivery-status line. Then in Uptrace:
+
+- **Errors** — the four error buttons (each a distinct type).
+- **Traces / spans** — your todo spans (`created todo` / `completed todo`), the
+  request spans (`GET /api/slow` is visibly long, with the SDK's `http.client` span
+  nested inside it), and the pageload/navigation traces. Navigate between routes and
+  watch the trace id change.
+
+If nothing shows up, check that `VITE_SENTRY_DSN` is set (the app warns in the
+console if not) and that the DSN host matches your Uptrace ingest address.
+Restart `npm run dev` after editing `.env`. The delivery-status line distinguishes
+"can't reach Uptrace" (host unreachable) from "Uptrace rejected the data" (bad
+DSN key/project).
+
+## Tests
+
+```bash
+npm test
+```
+
+Two specs, covering only what is Uptrace-specific: every signal nests under one
+root span per trace, and each navigation mints a trace named by its route pattern.
+They intercept the Sentry envelopes in the browser and read them, so no Sentry
+credentials and no running Uptrace are needed — `playwright.config.ts` gives the
+test dev server a dummy DSN (the SDK is inert without one) and ignores your `.env`.
+
+## Project layout
+
+| File | Purpose |
+| --- | --- |
+| `src/instrument.ts` | `Sentry.init()` — the only Uptrace-specific wiring — plus React Router tracing. |
+| `src/main.tsx` | Imports instrumentation first; sets up the router and `Sentry.ErrorBoundary`. |
+| `src/telemetry.ts` | Every Sentry SDK call: breadcrumbs, custom spans, errors, requests, trace helpers. |
+| `src/signals.ts` | Framework-free "last signal sent" store the inspector renders. |
+| `src/pages.tsx` | The routes: home console, `/products/:id`, `/categories/*`, not-found, and the shared route body. |
+| `src/panels.tsx` | The three demo controls: todos, HTTP, errors. |
+| `src/shell.tsx` | Persistent frame: side nav, trace badge, routed content, inspector. |
+| `src/inspector.tsx` | Bottom bar: what the last control sent, and whether it reached Uptrace. |
+| `src/delivery.ts` | Observe and show whether envelopes reach Uptrace. |
+| `vite.config.ts` | Dev-server middleware for `/api/ok|slow|fail`. |

sentry-react/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>