@glimt.dev/otel-browser 0.1.2 → 0.2.1

package/README.md

@@ -5,7 +5,7 @@ OpenTelemetry for the browser. Works out of the box, highly configurable.
 ## Quick Start (3 lines)
 
 ```bash
-npm install @glimt.dev/otel-browser
+npm install @glimt.dev/otel-browser @opentelemetry/api @opentelemetry/api-logs
 ```
 
 ```ts
@@ -14,7 +14,31 @@ import { registerOTelBrowser } from '@glimt.dev/otel-browser'
 registerOTelBrowser({ serviceName: 'my-web-app' })
 ```
 
-Done. Traces go to `http://localhost:4318/v1/traces`, logs to `/v1/logs`.
+Done. Traces go to `https://ingest.glimt.dev/v1/traces`, logs to `/v1/logs`.
+
+### Local Development
+
+For local development with a local collector:
+
+```ts
+registerOTelBrowser({
+  serviceName: 'my-web-app',
+  exporterUrl: 'http://localhost:4318',
+})
+```
+
+### Production: Glimt.dev Ingest
+
+For production with Glimt authentication:
+
+```ts
+registerOTelBrowser({
+  serviceName: 'my-web-app',
+  // exporterUrl defaults to https://ingest.glimt.dev
+  organisationId: 'your-org-id',
+  publishableKey: 'your-publishable-key',
+})
+```
 
 ---
 
@@ -31,8 +55,16 @@ const sdk = registerOTelBrowser({
   organisationId: 'org_xxx',
   publishableKey: 'pk_xxx',
 
-  // Export
-  exporterUrl: 'https://ingest.glimt.dev/v1/traces',
+  // Release metadata (CRITICAL for source mapping)
+  release: {
+    commit: process.env.NEXT_PUBLIC_COMMIT_SHA,  // or 'abc1234'
+    branch: process.env.NEXT_PUBLIC_COMMIT_REF,  // or 'main'
+    version: '1.0.0',
+    environment: 'production',
+  },
+
+  // Export - base URL, SDK derives /v1/traces and /v1/logs
+  exporterUrl: 'https://ingest.glimt.dev',
   exporter: 'http/protobuf',  // or 'http/json'
   exporterHeaders: { 'x-tenant-id': 'acme' },
   credentials: 'include',  // for CORS
@@ -50,9 +82,9 @@ const sdk = registerOTelBrowser({
   },
 
   // Capture
-  errors: { captureUnhandled: true },
-  console: { enabled: true },  // capture console.* as logs
-  includeUserAgent: false,     // privacy default
+  captureUnhandledErrors: true,  // window.onerror, unhandledrejection (default: true)
+  captureConsoleLogs: true,      // console.* as OTLP logs (default: false)
+  includeUserAgent: false,       // privacy default
 
   // Initial user context
   user: { userId: 'user_123', role: 'admin' },
@@ -68,6 +100,35 @@ sdk.setUserContext(null)
 
 ---
 
+## Environment Variables (via Build Tools)
+
+Browsers don't have runtime environment variables, but you can inject them at build time using your bundler:
+
+**Next.js (`next.config.mjs`):**
+```js
+// Automatically available as process.env.NEXT_PUBLIC_*
+// Set in .env or CI environment
+```
+
+**Vite (`vite.config.ts`):**
+```ts
+export default defineConfig({
+  define: {
+    'import.meta.env.VITE_OTEL_ENDPOINT': JSON.stringify(process.env.OTEL_EXPORTER_OTLP_ENDPOINT),
+    'import.meta.env.VITE_COMMIT_SHA': JSON.stringify(process.env.COMMIT_SHA),
+  }
+})
+```
+
+**Webpack:**
+```js
+new webpack.DefinePlugin({
+  'process.env.OTEL_ENDPOINT': JSON.stringify(process.env.OTEL_EXPORTER_OTLP_ENDPOINT),
+})
+```
+
+---
+
 ## React / Next.js Integration
 
 ```tsx
@@ -83,6 +144,11 @@ export function TelemetryProvider({ userId }: { userId?: string }) {
       serviceName: process.env.NEXT_PUBLIC_OTEL_SERVICE_NAME!,
       exporterUrl: process.env.NEXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT,
       user: userId ? { userId } : undefined,
+      release: {
+        commit: process.env.NEXT_PUBLIC_COMMIT_SHA || process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA,
+        branch: process.env.NEXT_PUBLIC_COMMIT_REF || process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF,
+        environment: process.env.NEXT_PUBLIC_VERCEL_ENV,
+      }
     })
   }, [])
 
@@ -139,8 +205,8 @@ Access-Control-Allow-Credentials: true (if using credentials)
 
 | Feature | Default |
 |---------|---------|
-| Trace exporter | `http/protobuf` → `localhost:4318/v1/traces` |
-| Log exporter | `http/protobuf` → auto-derived `/v1/logs` |
+| Trace exporter | `http/protobuf` → `https://ingest.glimt.dev/v1/traces` |
+| Log exporter | `http/protobuf` → `https://ingest.glimt.dev/v1/logs` |
 | Instrumentations | document-load, user-interaction, xhr, fetch |
 | Error capture | `window.onerror`, `unhandledrejection` |
 | User agent | NOT included (privacy) |