reroute-js 0.25.2 → 0.26.0

package/README.md

@@ -185,7 +185,7 @@ Reroute is a dead-simple file-based routing framework for building full-stack Re
 - 📚 **Content API Routes** - Dynamic content endpoints
 - 🛠️ **Dev Mode Routes** - Development tooling and live reload
 - 📦 **Artifact Routes** - Serve generated content chunks and registry
-- 📊 **Optional OpenTelemetry** - Built-in tracing for SSR, 404s, cache hits (install `@elysiajs/opentelemetry` to enable)
+- 📊 **Optional OpenTelemetry** - Built-in tracing for SSR, 404s, cache hits
 
 ### 🎯 Build System
 - 🔧 **Transpilation** - TypeScript/JSX to optimized JavaScript
@@ -1479,81 +1479,179 @@ If no `[og].tsx` exists for a route, uses built-in template with:
 
 ## 📊 OpenTelemetry (Optional)
 
-Reroute has built-in support for OpenTelemetry tracing to help debug SSR, 404s, and cache behavior.
+### Server Telemetry
 
-### Installation
+Track HTTP requests, errors, and system metrics.
+
+**Installation:**
 
 ```bash
-bun add @elysiajs/opentelemetry
+# Server telemetry packages
+bun add @opentelemetry/api \
+  @opentelemetry/api-logs \
+  @opentelemetry/exporter-logs-otlp-proto \
+  @opentelemetry/exporter-metrics-otlp-proto \
+  @opentelemetry/exporter-trace-otlp-proto \
+  @opentelemetry/resources \
+  @opentelemetry/sdk-logs \
+  @opentelemetry/sdk-metrics \
+  @opentelemetry/sdk-trace-node \
+  @opentelemetry/semantic-conventions
 ```
 
-That's it! Reroute automatically detects and uses it.
+**Configuration** in `reroute.config.ts`:
 
-### What Gets Traced
+```typescript
+export default defineConfig({
+  telemetry: {
+    // Server telemetry
+    enabled: true,
+    environment: process.env.NODE_ENV || 'development',
+    ignoreRoutes: [
+      '/health',
+      (pathname) => pathname.startsWith('/assets/'),
+      /\.(js|css|png|jpg|svg|ico)$/,
+    ],
+    sampleRate: 1.0,
+    captureHeaders: ['user-agent'],
+    
+    // Browser telemetry proxy (avoids CORS and ad blockers)
+    proxy: {
+      enabled: true,              // Default when proxy is an object
+      pathname: '/api/telemetry', // Default
+      verbose: false,             // Log proxy requests
+    },
+    
+    // Browser telemetry
+    browser: {
+      enabled: true,
+      serviceName: 'my-app-browser',
+      environment: process.env.NODE_ENV || 'development',
+      otlpEndpoint: '/api/telemetry',  // Must match proxy.pathname
+      enableConsoleCapture: true,
+    },
+  },
+});
+```
 
-Once installed, Reroute sends traces with detailed attributes:
+**Usage** - Config loaded automatically:
 
-- **SSR Rendering** (`reroute.ssr.render_stream`, `reroute.ssr.render_sync`)
-  - `reroute.ssr.streaming`: `true`/`false`
-  - `reroute.pathname`: `/blog/my-post`
-  - `reroute.collection`: `blog`
-  - `reroute.cache.hit`: `true`/`false`
+```typescript
+import { telemetry } from 'reroute-js/telemetry/server';
 
-- **404 Not Found** (When routes don't exist)
-  - `reroute.not_found`: `true`
-  - `reroute.pathname`: `/missing-page`
-  - `reroute.method`: `GET`
+new Elysia()
+  .use(telemetry())
+  .use(reroute({ app: createElement(App) }))
+  .listen(3000);
+```
 
-- **SSR Data Loading** (`reroute.data.compute`)
-  - `reroute.data.path`: `/products/123`
-  - `reroute.data.cache_hit`: `true`/`false`
+**Browser telemetry** - Track client-side events and errors.
 
-- **Errors** (SSR failures, data loading errors)
-  - `reroute.error`: `true`
-  - `reroute.error.type`: `SSRRenderError`, `SSRDataError`, etc.
-  - `reroute.error.collection`: `blog`
+**Installation:**
 
-### Usage with Your App Telemetry
+```bash
+# Browser telemetry packages
+bun add @opentelemetry/api \
+  @opentelemetry/auto-instrumentations-web \
+  @opentelemetry/context-zone \
+  @opentelemetry/exporter-trace-otlp-http \
+  @opentelemetry/instrumentation \
+  @opentelemetry/resources \
+  @opentelemetry/sdk-trace-base \
+  @opentelemetry/sdk-trace-web \
+  @opentelemetry/semantic-conventions
+```
 
-```typescript
-import { Elysia } from 'elysia';
-import { reroute } from 'reroute-js/elysia';
-import { opentelemetry } from '@elysiajs/opentelemetry';
-import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-node';
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
+**Usage:**
 
-new Elysia()
-  .use(opentelemetry({
-    serviceName: 'My App',
-    spanProcessors: [
-      new BatchSpanProcessor(
-        new OTLPTraceExporter({
-          url: 'http://localhost:4318/v1/traces',
-        })
-      )
-    ]
-  }))
-  .use(reroute({ app: createElement(App) }))
-  .listen(3000);
+```tsx
+import { TelemetryProvider } from 'reroute-js/telemetry/react/react';
+
+// Auto-loads from telemetry.browser config
+<TelemetryProvider>
+  <RerouteProvider {...bundle} />
+</TelemetryProvider>
+
+// Or override config values
+<TelemetryProvider enabled={true} serviceName="custom-name">
+  <RerouteProvider {...bundle} />
+</TelemetryProvider>
 ```
 
-Reroute traces will appear nested under your request spans. Filter by `reroute.*` attributes in SigNoz/Jaeger.
+See [examples/landing](./examples/landing) for a complete example.
 
-**Best Practice:** Use named functions (not arrow functions) for better span names:
+### Custom Instrumentation
+
+Create custom spans for API calls, database queries, or any operation:
 
 ```typescript
-// ❌ Bad: Shows as "N/A" or "anonymous" in traces
-.get('/api/users', async ({ params }) => {
-  return await getUsers();
+import { withSpan } from 'reroute-js/telemetry/server';
+
+// Instrument API endpoints
+app.get('/api/products', async () => {
+  return withSpan('api.get_products', async (span) => {
+    span.setAttribute('api.operation', 'list_products');
+    
+    const products = await fetchProducts();
+    span.setAttribute('api.result_count', products.length);
+    
+    return products;
+  });
 });
 
-// ✅ Good: Shows as "fetchUsers" in traces
-.get('/api/users', async function fetchUsers({ params }) {
-  return await getUsers();
+// Nested spans automatically create parent-child relationships
+app.get('/api/orders', async () => {
+  return withSpan('api.get_orders', async (span) => {
+    span.setAttribute('api.operation', 'list_orders');
+    
+    // Child span
+    const user = await withSpan('api.fetch_user', async (childSpan) => {
+      childSpan.setAttribute('user.id', userId);
+      return await getUser(userId);
+    });
+    
+    return { user, orders: await getOrders(user.id) };
+  });
 });
 ```
 
-See [examples/landing/src/plugins/telemetry.ts](./examples/landing/src/plugins/telemetry.ts) for a complete telemetry setup.
+**Error Handling:**
+
+Errors are automatically tracked and the span is properly closed:
+
+```typescript
+app.get('/api/user/:id', async ({ params }) => {
+  return withSpan('api.get_user', async (span) => {
+    span.setAttribute('user.id', params.id);
+    
+    const user = await getUser(params.id);
+    
+    if (!user) {
+      // Error is automatically captured in the span
+      throw new Error('User not found');
+    }
+    
+    return user;
+  });
+});
+```
+
+When an error occurs inside a span:
+1. **Error is recorded** - `span.recordException()` captures the full error details
+2. **Status is set** - Span status automatically set to `ERROR` with error message
+3. **Span is closed** - Span properly ended even when errors occur
+4. **Error is re-thrown** - Error propagates normally (not swallowed)
+
+This means errors appear in your traces with full context while maintaining normal error handling behavior.
+
+**Key Features:**
+- **Automatic error tracking** - Errors are captured and recorded in spans
+- **Nested spans** - Child spans automatically linked to parent context
+- **Zero overhead when disabled** - No-op implementation when OpenTelemetry not installed
+
+### Reroute SSR Tracing
+
+Built-in tracing for debugging SSR, 404s, and cache behavior. Automatically traces SSR rendering, 404s, data loading, and errors. Filter by `reroute.*` attributes in SigNoz/Jaeger.
 
 ## 📖 Learn More
 

package/cli/bin.d.ts

@@ -1,5 +1,5 @@
 /**
- * reroute-js v0.25.2
+ * reroute-js v0.26.0
  *
  * @license MIT
  * @copyright 2025 stewones <hi@stewan.io>