@atrim/instrument-web 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Atrim AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,360 @@
+# @atrim/instrument-web
+
+OpenTelemetry instrumentation for browsers with centralized YAML configuration.
+
+[![npm version](https://img.shields.io/npm/v/@atrim/instrument-web.svg)](https://www.npmjs.com/package/@atrim/instrument-web)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- ✅ **Zero-config OpenTelemetry setup** for browser applications
+- ✅ **Auto-instrumentation** (fetch, XHR, document load, user interactions)
+- ✅ **Pattern-based span filtering** via `instrumentation.yaml`
+- ✅ **OTLP export over HTTP** (browser-compatible)
+- ✅ **TypeScript support** with full type definitions
+- ✅ **<50KB bundle size** (gzipped) - optimized for web
+- ✅ **Modern browsers** (Chrome 90+, Firefox 88+, Safari 14+, Edge 90+)
+
+## Installation
+
+```bash
+npm install @atrim/instrument-web
+```
+
+## Quick Start
+
+```typescript
+import { initializeInstrumentation } from '@atrim/instrument-web'
+
+// Initialize once at application startup
+await initializeInstrumentation({
+  serviceName: 'my-app',
+  otlpEndpoint: 'http://localhost:4318/v1/traces'
+})
+
+// That's it! Auto-instrumentation is now active.
+```
+
+## Auto-Instrumentations
+
+The following are automatically instrumented when you initialize:
+
+### 1. Document Load
+Captures page load timing metrics (LCP, FCP, TTFB).
+
+### 2. Fetch API
+All `fetch()` calls are automatically traced with:
+- HTTP method, URL, status code
+- Request/response headers (configurable)
+- Request/response timing
+
+### 3. XMLHttpRequest (XHR)
+Legacy AJAX requests are traced automatically.
+
+### 4. User Interactions
+Click events and form submissions are captured.
+
+## Manual Instrumentation
+
+You can also create custom spans:
+
+```typescript
+import { trace } from '@opentelemetry/api'
+
+const tracer = trace.getTracer('my-app')
+
+tracer.startActiveSpan('my-operation', (span) => {
+  try {
+    // Your code here
+    span.setAttribute('user.id', '123')
+    span.setAttribute('operation.type', 'checkout')
+
+    // ... do work ...
+
+    span.setStatus({ code: 1 }) // OK
+  } catch (error) {
+    span.recordException(error)
+    span.setStatus({ code: 2 }) // ERROR
+    throw error
+  } finally {
+    span.end()
+  }
+})
+```
+
+## Span Helpers
+
+We provide convenient helpers for common annotations:
+
+```typescript
+import {
+  annotateHttpRequest,
+  annotateCacheOperation,
+  annotateUserInteraction,
+  annotateNavigation
+} from '@atrim/instrument-web'
+
+// HTTP request
+annotateHttpRequest(span, {
+  method: 'GET',
+  url: 'https://api.example.com/users',
+  statusCode: 200,
+  responseTime: 150
+})
+
+// Cache operation
+annotateCacheOperation(span, {
+  operation: 'get',
+  key: 'user:123',
+  hit: true
+})
+
+// User interaction
+annotateUserInteraction(span, {
+  type: 'click',
+  target: 'button#submit',
+  page: '/checkout'
+})
+
+// Navigation
+annotateNavigation(span, {
+  from: '/home',
+  to: '/profile',
+  type: 'client-side'
+})
+```
+
+## Configuration
+
+### Basic Configuration
+
+```typescript
+await initializeInstrumentation({
+  serviceName: 'my-app',          // Required
+  serviceVersion: '1.0.0',         // Optional
+  otlpEndpoint: 'http://localhost:4318/v1/traces', // Optional
+  otlpHeaders: {                   // Optional
+    'Authorization': 'Bearer token'
+  }
+})
+```
+
+### Pattern-Based Filtering
+
+Create an `instrumentation.yaml` file:
+
+```yaml
+version: "1.0"
+
+instrumentation:
+  enabled: true
+
+  # Only instrument these patterns
+  instrument_patterns:
+    - pattern: "^documentLoad"
+      description: "Page load metrics"
+    - pattern: "^HTTP (GET|POST)"
+      description: "API requests"
+    - pattern: "^click"
+      description: "User clicks"
+
+  # Ignore these patterns
+  ignore_patterns:
+    - pattern: "^HTTP GET /health"
+      description: "Health check endpoints"
+    - pattern: "^HTTP.*analytics"
+      description: "Analytics requests"
+```
+
+Then load it:
+
+```typescript
+await initializeInstrumentation({
+  serviceName: 'my-app',
+  configPath: '/instrumentation.yaml'  // Path relative to your app
+})
+```
+
+### Remote Configuration
+
+Load configuration from a remote URL:
+
+```typescript
+await initializeInstrumentation({
+  serviceName: 'my-app',
+  configUrl: 'https://config.company.com/instrumentation.yaml'
+})
+```
+
+### Disable Specific Instrumentations
+
+```typescript
+await initializeInstrumentation({
+  serviceName: 'my-app',
+  enableDocumentLoad: true,      // Page load metrics
+  enableUserInteraction: false,  // Disable click tracking
+  enableFetch: true,             // HTTP requests via fetch()
+  enableXhr: false               // Disable XMLHttpRequest
+})
+```
+
+## Environment Variables
+
+Configure via Vite/Webpack environment variables:
+
+```bash
+# .env
+VITE_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces
+```
+
+Or set at runtime via window object:
+
+```typescript
+window.OTEL_EXPORTER_OTLP_ENDPOINT = 'http://custom:4318/v1/traces'
+```
+
+## Browser Considerations
+
+### CORS
+
+Your OpenTelemetry collector must have CORS enabled:
+
+```yaml
+# otel-collector-config.yaml
+receivers:
+  otlp:
+    protocols:
+      http:
+        cors:
+          allowed_origins:
+            - "http://localhost:3000"
+            - "https://your-app.com"
+          allowed_headers:
+            - "*"
+```
+
+### Content Security Policy (CSP)
+
+Add your OTLP endpoint to CSP:
+
+```html
+<meta http-equiv="Content-Security-Policy"
+      content="connect-src 'self' http://localhost:4318">
+```
+
+### Bundle Size
+
+The package is optimized for web with:
+- ESM-only (no CJS overhead)
+- Tree-shakeable exports
+- Code splitting support
+- Minification-friendly
+
+**Estimated sizes:**
+- Core SDK: ~15KB (gzipped)
+- Auto-instrumentations: ~20KB (gzipped)
+- OTLP exporter: ~10KB (gzipped)
+- **Total: ~45KB (gzipped)**
+
+## Examples
+
+See the [examples/web-vanilla](../../examples/web-vanilla) directory for a complete working example.
+
+## API Reference
+
+### `initializeInstrumentation(options)`
+
+Initialize OpenTelemetry for the browser.
+
+**Options:**
+- `serviceName` (string, required) - Service name for telemetry
+- `serviceVersion` (string, optional) - Service version
+- `otlpEndpoint` (string, optional) - OTLP HTTP endpoint (default: `http://localhost:4318/v1/traces`)
+- `otlpHeaders` (object, optional) - Custom HTTP headers for OTLP export
+- `configPath` (string, optional) - Path to `instrumentation.yaml` file
+- `configUrl` (string, optional) - URL to remote `instrumentation.yaml`
+- `config` (object, optional) - Inline configuration object
+- `enableDocumentLoad` (boolean, optional) - Enable document load instrumentation (default: true)
+- `enableUserInteraction` (boolean, optional) - Enable user interaction instrumentation (default: true)
+- `enableFetch` (boolean, optional) - Enable fetch instrumentation (default: true)
+- `enableXhr` (boolean, optional) - Enable XMLHttpRequest instrumentation (default: true)
+
+**Returns:** `Promise<WebTracerProvider>`
+
+### `getSdkInstance()`
+
+Get the current SDK instance.
+
+**Returns:** `WebTracerProvider | null`
+
+### `shutdownSdk()`
+
+Shutdown the SDK gracefully.
+
+**Returns:** `Promise<void>`
+
+## Comparison with Node.js Package
+
+| Feature | @atrim/instrument-web | @atrim/instrument-node |
+|---------|----------------------|------------------------|
+| Platform | Browser | Node.js, Bun, Deno |
+| Export Protocol | HTTP only | HTTP + gRPC |
+| Auto-instrumentations | Fetch, XHR, DOM events | HTTP, gRPC, DB, etc. |
+| Effect-TS | ❌ No | ✅ Yes |
+| Bundle Size | <50KB | N/A |
+| Service Detection | Manual | Automatic |
+
+## Requirements
+
+- **Modern browsers:** Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
+- **Build tool:** Vite, Webpack, or similar (for bundling)
+- **OpenTelemetry Collector:** Running with HTTP endpoint
+
+## Troubleshooting
+
+### Traces not appearing
+
+1. **Check collector is running:**
+   ```bash
+   docker run -p 4318:4318 otel/opentelemetry-collector
+   ```
+
+2. **Check CORS configuration** on your collector
+
+3. **Check browser console** for errors
+
+4. **Verify endpoint:**
+   ```typescript
+   import { getOtlpEndpoint } from '@atrim/instrument-web'
+   console.log('OTLP endpoint:', getOtlpEndpoint())
+   ```
+
+### Performance issues
+
+1. **Disable unused instrumentations:**
+   ```typescript
+   await initializeInstrumentation({
+     serviceName: 'my-app',
+     enableUserInteraction: false,  // Reduce overhead
+     enableDocumentLoad: false
+   })
+   ```
+
+2. **Use pattern filtering** to reduce span volume
+
+3. **Sample traces** at the collector level
+
+## Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development setup.
+
+## License
+
+MIT License - see [LICENSE](../../LICENSE) for details.
+
+## Links
+
+- [GitHub Repository](https://github.com/atrim-ai/instrumentation)
+- [Issue Tracker](https://github.com/atrim-ai/instrumentation/issues)
+- [OpenTelemetry JavaScript](https://opentelemetry.io/docs/languages/js/)
+- [Atrim Platform](https://atrim.ai)

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@atrim/instrument-web",
+  "version": "0.1.0",
+  "description": "OpenTelemetry instrumentation for browsers with centralized YAML configuration",
+  "type": "module",
+  "license": "MIT",
+  "author": "Atrim AI",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/atrim-ai/instrumentation.git",
+    "directory": "packages/web"
+  },
+  "bugs": {
+    "url": "https://github.com/atrim-ai/instrumentation/issues"
+  },
+  "homepage": "https://github.com/atrim-ai/instrumentation#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "opentelemetry",
+    "instrumentation",
+    "tracing",
+    "observability",
+    "browser",
+    "web",
+    "frontend",
+    "spa",
+    "react",
+    "fetch",
+    "xhr"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./target/dist/index.d.ts",
+      "import": "./target/dist/index.js"
+    }
+  },
+  "main": "./target/dist/index.js",
+  "module": "./target/dist/index.js",
+  "types": "./target/dist/index.d.ts",
+  "files": [
+    "target/dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@effect/platform": "^0.93.0",
+    "effect": "^3.19.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/auto-instrumentations-web": "^0.54.0",
+    "@opentelemetry/context-zone": "^2.2.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.208.0",
+    "@opentelemetry/instrumentation": "^0.208.0",
+    "@opentelemetry/resources": "^2.2.0",
+    "@opentelemetry/sdk-trace-base": "^2.2.0",
+    "@opentelemetry/sdk-trace-web": "^2.2.0",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@opentelemetry/semantic-conventions": "^1.38.0",
+    "@types/node": "^20.10.0",
+    "@vitest/coverage-v8": "^4.0.8",
+    "jsdom": "^24.0.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.8",
+    "@atrim/instrument-core": "0.4.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\"",
+    "clean": "rm -rf target",
+    "publish:dev:version": "npm version $(git describe --tags --abbrev=0 | sed 's/^.*@//' | sed 's/^v//')-$(git rev-parse --short HEAD)-$(date -u +%Y%m%d%H%M%S) --no-git-tag-version",
+    "publish:dev:save": "node -p \"require('./package.json').version\" > .version",
+    "publish:dev:publish": "pnpm build && pnpm publish --tag dev --access public --no-git-checks",
+    "publish:dev:reset": "npm version 0.1.0 --no-git-tag-version",
+    "publish:dev": "pnpm publish:dev:version && pnpm publish:dev:save && pnpm publish:dev:publish && pnpm publish:dev:reset"
+  }
+}