autotel-devtools 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/package.json +19 -3
  2. package/skills/autotel-devtools/SKILL.md +123 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "autotel-devtools",
3
- "version": "1.0.1",
3
+ "version": "1.0.2",
4
4
  "description": "Standalone OTLP receiver with web UI for local development",
5
5
  "type": "module",
6
6
  "sideEffects": false,
@@ -27,7 +27,22 @@
27
27
  "main": "./dist/index.js",
28
28
  "types": "./dist/index.d.ts",
29
29
  "files": [
30
- "dist"
30
+ "dist",
31
+ "skills",
32
+ "!skills/_artifacts"
33
+ ],
34
+ "keywords": [
35
+ "opentelemetry",
36
+ "otel",
37
+ "devtools",
38
+ "observability",
39
+ "traces",
40
+ "logs",
41
+ "metrics",
42
+ "otlp",
43
+ "dashboard",
44
+ "widget",
45
+ "tanstack-intent"
31
46
  ],
32
47
  "dependencies": {
33
48
  "@preact/signals": "^2.9.0",
@@ -40,6 +55,7 @@
40
55
  "ws": "^8.20.0"
41
56
  },
42
57
  "devDependencies": {
58
+ "@tanstack/intent": "^0.0.29",
43
59
  "@chromatic-com/storybook": "^5.1.1",
44
60
  "@opentelemetry/api": "^1.9.1",
45
61
  "@opentelemetry/core": "^2.6.1",
@@ -70,7 +86,7 @@
70
86
  "vitest-mock-extended": "^4.0.0"
71
87
  },
72
88
  "peerDependencies": {
73
- "autotel": "2.26.1"
89
+ "autotel": "2.26.2"
74
90
  },
75
91
  "peerDependenciesMeta": {
76
92
  "autotel": {
package/skills/autotel-devtools/SKILL.md ADDED
@@ -0,0 +1,123 @@
1
+ ---
2
+ name: autotel-devtools
3
+ description: >
4
+ 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.
5
+ type: integration
6
+ library: autotel-devtools
7
+ library_version: '1.0.1'
8
+ sources:
9
+ - jagreehal/autotel:packages/autotel-devtools/CLAUDE.md
10
+ - jagreehal/autotel:packages/autotel-devtools/README.md
11
+ ---
12
+
13
+ # autotel-devtools
14
+
15
+ 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.
16
+
17
+ ## Quick Start — pick an approach
18
+
19
+ ### Standalone dashboard
20
+
21
+ ```bash
22
+ npx autotel-devtools
23
+ # → OTLP receiver on :4318, UI at http://localhost:4318
24
+ ```
25
+
26
+ Point any OTel-instrumented app at it:
27
+
28
+ ```bash
29
+ OTEL_EXPORTER_OTLP_PROTOCOL=http/json \
30
+ OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
31
+ node app.js
32
+ ```
33
+
34
+ ### Embedded widget
35
+
36
+ ```html
37
+ <script src="http://localhost:4318/widget.js"></script>
38
+ <autotel-devtools></autotel-devtools>
39
+ ```
40
+
41
+ Shadow-DOM-isolated — never leaks styles into the host page.
42
+
43
+ ### Programmatic (Node + autotel)
44
+
45
+ ```typescript
46
+ import { init, trace } from 'autotel';
47
+ import { createDevtools } from 'autotel-devtools';
48
+
49
+ const { exporter, close } = createDevtools({ port: 4318, verbose: true });
50
+
51
+ init({
52
+ service: 'my-app',
53
+ endpoint: 'http://localhost:4318',
54
+ spanProcessors: [exporter], // stream spans to the devtools UI
55
+ });
56
+
57
+ export const loadUser = trace(ctx => async (id: string) => {
58
+ // ... span shows up live in devtools
59
+ });
60
+ ```
61
+
62
+ ## Package Entry Points
63
+
64
+ | Import | What |
65
+ | --- | --- |
66
+ | `autotel-devtools` | `createDevtools()`, `DevtoolsServer`, exporters, types |
67
+ | `autotel-devtools/server` | `DevtoolsServer`, OTLP parsing (`parseOtlpTraces`, `parseOtlpLogs`), HTTP routes (`attachDevtoolsRoutes`, `createDevtoolsHttpServer`), telemetry-limit helpers |
68
+ | `autotel-devtools/exporter` | `DevtoolsSpanExporter` (standalone) |
69
+
70
+ ## Server Endpoints
71
+
72
+ | Route | What |
73
+ | --- | --- |
74
+ | `POST /v1/traces` · `/v1/logs` · `/v1/metrics` | OTLP JSON receivers |
75
+ | `GET /` | Dashboard UI (traces, logs, metrics, errors, resources, service map) |
76
+ | `GET /widget.js` | Embeddable widget bundle (IIFE) |
77
+ | `GET /healthz` | Health check |
78
+ | `WS /ws` | WebSocket stream (history replay on connect) |
79
+
80
+ ## Views in the UI
81
+
82
+ - **Traces** — waterfall + flame graph, search with 300 ms debounce
83
+ - **Logs** — severity/resource filtering
84
+ - **Metrics** — per-metric time series
85
+ - **Errors** — aggregated and grouped by fingerprint
86
+ - **Resources** — derived from ingested telemetry
87
+ - **Service map** — visualises call graph
88
+
89
+ ## Environment Variables
90
+
91
+ | Variable | Default | Purpose |
92
+ | --- | --- | --- |
93
+ | `AUTOTEL_DEVTOOLS_PORT` | `4318` | Server port |
94
+ | `AUTOTEL_DEVTOOLS_HOST` | `127.0.0.1` | Bind host |
95
+ | `AUTOTEL_DEVTOOLS_TITLE` | — | Dashboard title |
96
+ | `AUTOTEL_MAX_TRACE_COUNT` | `100` | Max traces retained in memory |
97
+ | `AUTOTEL_MAX_LOG_COUNT` | `100` | Max logs retained |
98
+ | `AUTOTEL_MAX_METRIC_COUNT` | `100` | Max metric points retained |
99
+
100
+ ## CLI
101
+
102
+ ```bash
103
+ npx autotel-devtools --port 4319 --host 0.0.0.0 --title "My App"
104
+ ```
105
+
106
+ | Flag | Short | Purpose |
107
+ | --- | --- | --- |
108
+ | `--port` | `-p` | Listen port (default 4318) |
109
+ | `--host` | `-H` | Bind host (default 127.0.0.1) |
110
+ | `--title` | `-t` | Dashboard title |
111
+
112
+ ## Works With
113
+
114
+ - **autotel** — pass `exporter` into `spanProcessors` for live streaming
115
+ - **Standard OpenTelemetry SDK** — any OTLP exporter targeting `http://localhost:4318` works; autotel is not required
116
+ - **Browser apps** — the widget is a custom element with Shadow DOM, so drop it in without CSS conflicts
117
+
118
+ ## Common Mistakes
119
+
120
+ - Do NOT use the widget in Node — it's a browser-only IIFE bundle. Use `createDevtools()` server-side instead.
121
+ - 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.
122
+ - 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.
123
+ - 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.