autotel-devtools 1.0.1 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel-devtools",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Standalone OTLP receiver with web UI for local development",
   "type": "module",
   "sideEffects": false,
@@ -27,50 +27,66 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "!skills/_artifacts"
+  ],
+  "keywords": [
+    "opentelemetry",
+    "otel",
+    "devtools",
+    "observability",
+    "traces",
+    "logs",
+    "metrics",
+    "otlp",
+    "dashboard",
+    "widget",
+    "tanstack-intent"
   ],
   "dependencies": {
     "@preact/signals": "^2.9.0",
     "clsx": "^2.1.1",
-    "lucide-preact": "^1.7.0",
-    "markdown-to-jsx": "^9.7.15",
+    "lucide-preact": "^1.11.0",
+    "markdown-to-jsx": "^9.7.16",
     "preact": "^10.29.1",
     "react-json-view-lite": "^2.5.0",
     "tailwind-merge": "^3.5.0",
     "ws": "^8.20.0"
   },
   "devDependencies": {
-    "@chromatic-com/storybook": "^5.1.1",
+    "@tanstack/intent": "^0.0.36",
+    "@chromatic-com/storybook": "^5.1.2",
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/core": "^2.6.1",
-    "@opentelemetry/sdk-logs": "^0.214.0",
-    "@opentelemetry/sdk-trace-base": "^2.6.1",
+    "@opentelemetry/core": "^2.7.0",
+    "@opentelemetry/sdk-logs": "^0.215.0",
+    "@opentelemetry/sdk-trace-base": "^2.7.0",
     "@preact/preset-vite": "^2.10.5",
     "@storybook/addon-a11y": "^10.3.5",
     "@storybook/addon-docs": "^10.3.5",
     "@storybook/addon-vitest": "^10.3.5",
     "@storybook/preact-vite": "^10.3.5",
-    "@tailwindcss/postcss": "^4.2.2",
-    "@tailwindcss/vite": "^4.2.2",
+    "@tailwindcss/postcss": "^4.2.4",
+    "@tailwindcss/vite": "^4.2.4",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/preact": "^3.2.4",
-    "@types/node": "^25.5.2",
+    "@types/node": "^25.6.0",
     "@types/ws": "^8.18.1",
-    "@vitest/browser-playwright": "4.1.3",
-    "@vitest/coverage-v8": "4.1.3",
+    "@vitest/browser-playwright": "4.1.5",
+    "@vitest/coverage-v8": "4.1.5",
     "eslint-plugin-storybook": "^10.3.5",
     "playwright": "^1.59.1",
-    "postcss": "^8.5.9",
+    "postcss": "^8.5.12",
     "storybook": "^10.3.5",
-    "tailwindcss": "^4.2.2",
-    "typescript": "^6.0.2",
-    "vite": "^8.0.7",
+    "tailwindcss": "^4.2.4",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.10",
     "tsup": "^8.5.1",
-    "vitest": "^4.1.3",
+    "vitest": "^4.1.5",
     "vitest-mock-extended": "^4.0.0"
   },
   "peerDependencies": {
-    "autotel": "2.26.1"
+    "autotel": "2.26.3"
   },
   "peerDependenciesMeta": {
     "autotel": {

package/skills/autotel-devtools/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: autotel-devtools
+description: >
+  Standalone OTLP receiver with a Preact web UI for local-dev observability. Use when a developer wants to see OpenTelemetry traces, logs, metrics, and service maps streaming from a running app without setting up Jaeger/Tempo/Prometheus — either as a CLI dashboard or an embedded `<autotel-devtools>` widget.
+type: integration
+library: autotel-devtools
+library_version: '1.0.1'
+sources:
+  - jagreehal/autotel:packages/autotel-devtools/CLAUDE.md
+  - jagreehal/autotel:packages/autotel-devtools/README.md
+---
+
+# autotel-devtools
+
+Local-dev OTLP receiver with a browser UI. Think TanStack Devtools for OpenTelemetry — runs as CLI or embeds as a Shadow-DOM-isolated widget in any web app.
+
+## Quick Start — pick an approach
+
+### Standalone dashboard
+
+```bash
+npx autotel-devtools
+# → OTLP receiver on :4318, UI at http://localhost:4318
+```
+
+Point any OTel-instrumented app at it:
+
+```bash
+OTEL_EXPORTER_OTLP_PROTOCOL=http/json \
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
+node app.js
+```
+
+### Embedded widget
+
+```html
+<script src="http://localhost:4318/widget.js"></script>
+<autotel-devtools></autotel-devtools>
+```
+
+Shadow-DOM-isolated — never leaks styles into the host page.
+
+### Programmatic (Node + autotel)
+
+```typescript
+import { init, trace } from 'autotel';
+import { createDevtools } from 'autotel-devtools';
+
+const { exporter, close } = createDevtools({ port: 4318, verbose: true });
+
+init({
+  service: 'my-app',
+  endpoint: 'http://localhost:4318',
+  spanProcessors: [exporter], // stream spans to the devtools UI
+});
+
+export const loadUser = trace(ctx => async (id: string) => {
+  // ... span shows up live in devtools
+});
+```
+
+## Package Entry Points
+
+| Import | What |
+| --- | --- |
+| `autotel-devtools` | `createDevtools()`, `DevtoolsServer`, exporters, types |
+| `autotel-devtools/server` | `DevtoolsServer`, OTLP parsing (`parseOtlpTraces`, `parseOtlpLogs`), HTTP routes (`attachDevtoolsRoutes`, `createDevtoolsHttpServer`), telemetry-limit helpers |
+| `autotel-devtools/exporter` | `DevtoolsSpanExporter` (standalone) |
+
+## Server Endpoints
+
+| Route | What |
+| --- | --- |
+| `POST /v1/traces` · `/v1/logs` · `/v1/metrics` | OTLP JSON receivers |
+| `GET /` | Dashboard UI (traces, logs, metrics, errors, resources, service map) |
+| `GET /widget.js` | Embeddable widget bundle (IIFE) |
+| `GET /healthz` | Health check |
+| `WS /ws` | WebSocket stream (history replay on connect) |
+
+## Views in the UI
+
+- **Traces** — waterfall + flame graph, search with 300 ms debounce
+- **Logs** — severity/resource filtering
+- **Metrics** — per-metric time series
+- **Errors** — aggregated and grouped by fingerprint
+- **Resources** — derived from ingested telemetry
+- **Service map** — visualises call graph
+
+## Environment Variables
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `AUTOTEL_DEVTOOLS_PORT` | `4318` | Server port |
+| `AUTOTEL_DEVTOOLS_HOST` | `127.0.0.1` | Bind host |
+| `AUTOTEL_DEVTOOLS_TITLE` | — | Dashboard title |
+| `AUTOTEL_MAX_TRACE_COUNT` | `100` | Max traces retained in memory |
+| `AUTOTEL_MAX_LOG_COUNT` | `100` | Max logs retained |
+| `AUTOTEL_MAX_METRIC_COUNT` | `100` | Max metric points retained |
+
+## CLI
+
+```bash
+npx autotel-devtools --port 4319 --host 0.0.0.0 --title "My App"
+```
+
+| Flag | Short | Purpose |
+| --- | --- | --- |
+| `--port` | `-p` | Listen port (default 4318) |
+| `--host` | `-H` | Bind host (default 127.0.0.1) |
+| `--title` | `-t` | Dashboard title |
+
+## Works With
+
+- **autotel** — pass `exporter` into `spanProcessors` for live streaming
+- **Standard OpenTelemetry SDK** — any OTLP exporter targeting `http://localhost:4318` works; autotel is not required
+- **Browser apps** — the widget is a custom element with Shadow DOM, so drop it in without CSS conflicts
+
+## Common Mistakes
+
+- Do NOT use the widget in Node — it's a browser-only IIFE bundle. Use `createDevtools()` server-side instead.
+- Do NOT set a production OTLP endpoint at `localhost:4318` — devtools is in-memory only (no persistence, caps at 100 items per signal by default). Bump `AUTOTEL_MAX_*_COUNT` for longer local sessions.
+- Do NOT embed the widget into pages served via strict CSP without allowing `http://localhost:4318` — the WebSocket connection and script load both need the devtools origin allowed.
+- Do NOT confuse the two builds — the **server** uses tsup (Node ESM + CJS), the **widget** uses Vite's IIFE build. Don't import `autotel-devtools/server` into widget code; it pulls in Node APIs.