autotel-devtools 21.0.1 → 23.0.0

package/README.md

@@ -24,11 +24,26 @@ Standalone OTLP receiver with web UI for local development. Think TanStack Devto
 │  │  ├── GET  /healthz     → Health check  │ │
 │  │  └── WS   /ws          ←→ WebSocket    │ │
 │  └───────────────────────────────────────┘ │
+│  OTLP/gRPC receiver (port 4317)             │
 └─────────────────────────────────────────────┘
 ```
 
 ## Quick Start
 
+### Installing with pnpm
+
+This package pulls in `esbuild` and `protobufjs`, both of which run install
+scripts. pnpm 10+ blocks those by default and then refuses to run anything else
+until you decide about them, so `pnpm install && pnpm start` fails on a fresh
+clone with a deps-status error rather than an obvious one. Approve them once in
+`pnpm-workspace.yaml`:
+
+```yaml
+allowBuilds:
+  esbuild: true
+  protobufjs: true
+```
+
 ### Standalone Mode
 
 ```bash
@@ -42,17 +57,23 @@ node app.js
 ```
 
 The endpoints accept **both OTLP/JSON and OTLP/protobuf** (`application/x-protobuf`),
-selected automatically from the request `Content-Type`. That means SDKs that default
-to protobuf over OTLP HTTP, including the Python, Java, and Go OpenTelemetry SDKs.
-Work without any extra configuration:
+chosen from the request `Content-Type`. SDKs that default to protobuf over OTLP
+HTTP, including the Python, Java, and Go OpenTelemetry SDKs, work with no extra
+configuration:
 
 ```bash
-# Python / Java / Go SDKs default to http/protobuf — just point them at the receiver
+# Python / Java / Go SDKs default to http/protobuf; point them at the receiver
 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 python app.py
 ```
 
 Open http://localhost:4318 to see traces, logs, and metrics.
 
+SDKs configured for OTLP/gRPC can use the standard endpoint directly:
+
+```bash
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 python app.py
+```
+
 ### Embedded Widget
 
 Add the widget to your web app:
@@ -111,6 +132,7 @@ const myFunction = withTracing({ name: 'example.run' })((ctx) => async () => {
 
 - **DevtoolsServer** - WebSocket server + in-memory data store
 - **HTTP Routes** - OTLP receivers for traces/logs/metrics (JSON + protobuf)
+- **gRPC Receiver** - canonical OTLP trace, log, and metric services on port 4317
 
 #### Detecting the receiver
 
@@ -145,14 +167,18 @@ process. Point them at the bound port, or free the original.
 
 - ✅ Real-time OTLP ingestion (traces, logs, metrics)
 - ✅ WebSocket streaming with history replay
-- ✅ Traces view with waterfall + flame graph
-- ✅ Logs view with severity/resource filtering
+- ✅ **Query language** over traces and logs, run as SQL against a sqlite store (see below)
+- ✅ **Persistence**: `--db` keeps telemetry across restarts; retention applies count and byte caps
+- ✅ Traces view with waterfall (tree connectors, event markers, critical path) + flame graph
+- ✅ Logs view with a query bar and severity filtering
+- ✅ **Metrics view**: server-reduced time series, merged histogram distributions, interpolated quantiles, sparklines, and capped exemplars that open the trace behind a spike
 - ✅ Error aggregation and grouping
 - ✅ Service map visualization
 - ✅ Resources view (derived from telemetry)
 - ✅ GenAI run summaries + narrated walkthrough
 - ✅ **Agents view**: observe coding agents (Claude Code, opencode) from their OTel metrics + log events
-- ✅ Search with debounce (300ms)
+- ✅ Global time window shared by every tab
+- ✅ Live tail that freezes while you read, with a "N new" pill to catch up
 - ✅ Configurable telemetry limits (env vars)
 - ✅ Widget position persistence (localStorage)
 - ✅ Export traces as JSON
@@ -171,8 +197,8 @@ on top of the per-span detail:
 - An **Explain run** button steps through the run in chronological order with
   plain-language narration of each step. Auto-play or step manually with the
   arrow keys / Space (Esc exits); clicking a span jumps the tour to that step.
-  Useful for showing a teammate or a client exactly what the agent did, which
-  tools it called, and where the cost went.
+  Use it to show a teammate or a client what the agent did, which tools it
+  called, and where the cost went.
 
 ### Agents: observe Claude Code (and other coding agents)
 
@@ -187,9 +213,9 @@ One command starts the receiver _and_ launches Claude Code wired to it:
 npx autotel-devtools claude
 ```
 
-This sets the telemetry env for a live local view. OTLP **`http/protobuf`** to
-this receiver (not the gRPC setup in most guides, which this receiver doesn't
-speak), 1s export intervals, and `session.id` kept on metrics. Then open the UI
+This sets the telemetry env for a live local view: OTLP **`http/protobuf`**, 1s
+export intervals, and `session.id` kept on metrics. The receiver also accepts
+standard OTLP/gRPC on `:4317`. Then open the UI
 and switch to **Agents**.
 
 - `--print-env`: print the env block instead of launching (for managed-settings
@@ -201,17 +227,116 @@ decisions), a **rollup** (cost, tokens, requests, lines changed), and breakdowns
 by **tool category**, **MCP server** (`mcp__server__tool`), **sub-agent** (`Task`)
 and **skill** (`Skill`). Plus an aggregate strip across all sessions. Cost uses
 the agent's reported `cost_usd`, falling back to a token estimate (badged). MCP
-protocol internals are out of scope here. That's `autotel-mcp-instrumentation`.
+protocol internals live in `autotel-mcp-instrumentation`.
+
+## Querying
+
+The Traces and Logs tabs take a query, which the server compiles to SQL and runs
+against everything it has kept, rather than only what is on screen.
+
+```
+service = api AND duration > 100
+name CONTAINS checkout
+http.status_code = 500
+service IN [api, web, worker]
+name REGEXP "^GET /users/[0-9]+$"
+severity_number >= 17          # logs: error and above
+parent_span_id = NULL          # root spans only
+"user id" = "u-42"             # quote a key a bare word can't spell
+checkout                       # bare words are free text
+```
+
+**Fields.** Traces: `service`, `name`, `kind`, `duration`, `status`, `trace_id`,
+`span_id`, `parent_span_id`. Logs: `service`, `severity`, `severity_number`,
+`trace_id`, `span_id`, `body`. **Anything else is looked up as an attribute**, so
+every attribute your services emit is queryable without being declared.
+
+`severity` and `severity_number` both exist on purpose: the text is what you
+read, but "error and above" is a numeric comparison and string ordering cannot
+express it.
+
+**Operators.** `=` `!=` `>` `<` `>=` `<=` for comparison; `CONTAINS`,
+`NOT CONTAINS`, `^` (starts with), `$` (ends with), `REGEXP` / `=~`,
+`NOT REGEXP` / `!~` for text; `IN` / `NOT IN` with `[…]`; `= NULL` and
+`!= NULL` for presence. Combine with `AND`, `OR` and parentheses. Two
+conditions side by side mean `AND`.
+
+Values are always sent as bound parameters and field names always come from a
+schema, so nothing you type reaches the SQL string.
+
+### The HTTP API
+
+The same query the UI runs is available over HTTP, so a test can assert on what
+a run actually emitted instead of on a log line. Requests to the `/api/*`
+endpoints must come from loopback, or the server answers `403 Forbidden`.
+
+| Endpoint                       | Body / result                                                    |
+| ------------------------------ | ---------------------------------------------------------------- |
+| `POST /api/query/traces`       | `{ query, window?, limit?, cursor? }` → `{ traces, nextCursor }` |
+| `POST /api/query/logs`         | same shape, over logs                                            |
+| `POST /api/query/errors`       | same shape, error spans only                                     |
+| `POST /api/query/metrics`      | same shape, over metric series                                   |
+| `GET /api/query/traces/fields` | `{ fields }` - the bare field names a query can use              |
+| `GET /api/stats`               | `{ traceCount, spanCount, logCount, bytesUsed, maxBytes, … }`    |
+| `GET /v1/traces`               | every trace held, no query                                       |
+| `DELETE /v1/traces`            | `{ cleared: true }` - empty the store between tests              |
+| `GET /healthz`                 | `{ ok, service, version, clients }`                              |
+
+`query` takes the language above, so anything the Traces tab can filter on, a
+script can too. Each returned trace carries `traceId`, `service`, `rootSpan`,
+`spans`, `duration` and `status`.
+
+### Asserting on traces in CI
+
+Clear the store, run the thing, then ask what it emitted. A query count is a far
+steadier assertion than a duration:
+
+```bash
+curl -sX DELETE http://127.0.0.1:4318/v1/traces
+node app.js
+
+curl -s -X POST http://127.0.0.1:4318/api/query/traces \
+  -H 'content-type: application/json' \
+  -d '{"query":"name = \"GET /feed\"","limit":1}' \
+  | jq -e '.traces[0].spans | length == 2'
+```
+
+That fails the moment someone reintroduces an N+1 on `/feed`, and it does not
+care how fast the machine running CI happens to be.
+
+### Live tail and the time window
+
+The list follows new data by default. It **freezes** the moment you type a
+query, scroll back, select a row, or bound the time window, and a "N new" pill
+counts the matches instead of reordering rows under you. Click the pill to catch
+up. There is no mode to manage: freezing follows from what you did.
+
+The time window is one control shared by every tab. Presets track _now_ rather
+than freezing when clicked, and **"All time" means "I haven't said"**: a view
+may fit itself to its own data then, but a window you choose is never widened or
+cropped, because an empty 15-minute window is the answer.
+
+### Reading it from a CLI or an agent
+
+The same store backs `autotel-mcp`'s `devtools` backend, so `autotel diagnose`,
+`autotel query` and the MCP tools read what the viewer shows:
+
+```bash
+autotel diagnose errors --backend devtools --devtools-base-url http://localhost:4318
+```
 
 ## Configuration
 
 ### Environment Variables
 
 ```bash
-AUTOTEL_MAX_TRACE_COUNT=10000    # Max traces to keep (default: 100)
-AUTOTEL_MAX_LOG_COUNT=10000      # Max logs to keep (default: 100)
-AUTOTEL_MAX_METRIC_COUNT=50000   # Max metrics to keep (default: 100)
+AUTOTEL_MAX_TRACE_COUNT=10000    # Live-tail buffer size (default: 100)
+AUTOTEL_MAX_LOG_COUNT=10000      # Live-tail buffer size (default: 100)
+AUTOTEL_DEVTOOLS_DB=./tel.db     # sqlite file for the store (default: in-memory)
+AUTOTEL_DEVTOOLS_MAX_TRACES=100000  # Traces retained in the store before pruning
 AUTOTEL_DEVTOOLS_PORT=4318       # Server port (default: 4318)
+AUTOTEL_DEVTOOLS_GRPC_PORT=4317  # OTLP/gRPC port (default: 4317)
+AUTOTEL_DEVTOOLS_DB_MAX_SIZE=2gb # Logical sqlite retention cap
 AUTOTEL_DEVTOOLS_HOST=127.0.0.1  # Bind host (default: 127.0.0.1)
 AUTOTEL_DEVTOOLS_TITLE="My App"  # Dashboard title (optional)
 AUTOTEL_DEVTOOLS_SOURCE_ROOT=.   # Root GET /source may read (default: cwd on a loopback bind, else off; `false` disables)
@@ -222,6 +347,7 @@ AUTOTEL_DEVTOOLS_SOURCE_ROOT=.   # Root GET /source may read (default: cwd on a
 ```bash
 npx autotel-devtools 4319                      # port as a bare positional
 npx autotel-devtools --port 4319 --host 0.0.0.0
+npx autotel-devtools --db ./telemetry.db        # keep telemetry across restarts
 npx autotel-devtools claude                     # receiver + launch Claude Code wired to it
 npx autotel-devtools claude --print-env         # print the telemetry env, don't launch
 ```
@@ -239,17 +365,22 @@ Options:
 - `--port, -p` - Port to listen on (default: 4318). If the port is taken, the receiver walks forward to the next free port and prints a warning.
 - `--host, -H` - Host to bind to (default: 127.0.0.1)
 - `--title, -t` - Dashboard title, used for the startup banner and the browser tab (default: `autotel-devtools`). Useful when several dashboards are open at once.
+- `--db, -d` - sqlite file backing the store, so telemetry survives a restart (default: in-memory, which keeps everything until the process exits)
+- `--max-traces` - Traces retained in the store before the oldest are pruned (default: 100000). Pruning runs every 30s.
+- `--grpc-port` - OTLP/gRPC port (default: 4317). If busy, the receiver reports the fallback port.
+- `--db-max-size` - Logical sqlite retention cap (`512mb`, `2gb`, etc.). Defaults to 512 MiB in memory and 2 GiB on disk.
 
 When bound to a loopback host, the receiver listens on **both** `127.0.0.1`
 and `::1`, so a client connecting via `localhost` reaches it regardless of how
 the OS resolves `localhost` (macOS prefers IPv6 `::1`). The startup banner
-prints every address it bound; if a family can't be bound you get a warning,
-not a silent black hole.
+prints every address it bound, and warns when it cannot bind a family rather
+than failing silently. Both listeners serve the HTTP routes _and_ the `/ws`
+live tail, so the widget streams whichever form of `localhost` it resolved.
 
 ## Behind a dev-server proxy
 
-If your app's dev server proxies `/v1/traces` to the receiver, two classic
-bugs make spans vanish with **no error**. Both worth knowing:
+If your app's dev server proxies `/v1/traces` to the receiver, two bugs make
+spans vanish with **no error**:
 
 ```ts
 // Express / http-proxy-middleware
@@ -270,15 +401,15 @@ app.use(
 ```
 
 > Symptom of either bug: the browser shows the request leaving (200/no error),
-> but the receiver stays empty. Always verify on the **receiver** side (below),
-> not just that the browser tried to send.
+> but the receiver stays empty. Always verify on the **receiver** side (below).
+> The browser trying to send proves nothing.
 
 ## Verifying ingestion in tests
 
 The receiver exposes an HTTP read-back so a test can assert the collector
-**actually received** spans. Instead of asserting "the client tried to send",
-which a browser-level route intercept can fake (it fulfils the request before
-it reaches any server):
+**received** spans, rather than that the client tried to send them. A
+browser-level route intercept can fake the second one by fulfilling the request
+before it reaches any server:
 
 ```bash
 GET    /v1/traces   # → { traces: [...], count: N }  what the receiver has
@@ -286,7 +417,7 @@ DELETE /v1/traces   # clear captured telemetry (reset between tests)
 ```
 
 ```ts
-// Playwright / integration test — bypass any page.route() intercept and ask
+// Playwright / integration test: bypass any page.route() intercept and ask
 // the collector directly.
 await fetch(`${RECEIVER}/v1/traces`, { method: 'DELETE' }); // reset
 await runTheUserFlow(); // app emits spans
@@ -295,8 +426,32 @@ await expect
   .toBeGreaterThan(0);
 ```
 
-These read-back calls run from Node (no `Origin` header), so they are unaffected
-by the origin guard below.
+These read-back calls run from Node with no `Origin` header, so the origin guard
+below leaves them alone.
+
+## Trace payload shape
+
+The server **answers in full and streams compact**. Every HTTP response carries
+a complete trace, so `GET /v1/traces`, `POST /api/query/traces` and anything
+else you can `curl` need no decoding.
+
+The `/ws` stream is the one exception. It leaves off any span `endTime` that
+`startTime + duration` already reproduces, which is 32% of the compressed
+payload on a large trace. Writing your own WebSocket client? Rehydrate in one
+call:
+
+```ts
+import { decodeTraces } from 'autotel-devtools/wire';
+
+ws.addEventListener('message', (event) => {
+  const data = JSON.parse(event.data);
+  const traces = decodeTraces(data.traces ?? []);
+});
+```
+
+Responses over 1 KiB are gzipped when the client accepts it, and the WebSocket
+negotiates `permessage-deflate`. Browser `fetch`, browser `WebSocket` and
+undici all handle that transparently, so this is normally invisible.
 
 ## Read-surface origin guard
 

package/dist/cli.cjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-const require_http = require('./http-CXSzX4ee.cjs');
-const require_listen = require('./listen-CEJ3nYJf.cjs');
+const require_http = require('./http-Cqm_MAtc.cjs');
+const require_listen = require('./listen-l09RRHht.cjs');
+const require_grpc = require('./grpc-CSWjMRiB.cjs');
 let node_http = require("node:http");
 let node_fs = require("node:fs");
 let node_path = require("node:path");
@@ -9,7 +10,7 @@ let node_child_process = require("node:child_process");
 
 //#region src/cli.ts
 function printHelp() {
-	process.stdout.write("autotel-devtools - Standalone OTLP receiver with web devtools UI\n\nUsage: autotel-devtools [port] [options]\n       autotel-devtools claude [claude args] [--print-env] [--log-prompts]\n\nSubcommands:\n  claude               Start the receiver AND launch Claude Code wired to it\n                       (HTTP/protobuf → this receiver, 1s intervals, session id on).\n                       Open the \"Agents\" tab to watch sessions, tokens, cost,\n                       tool / MCP / sub-agent / skill usage live.\n                         --print-env    Print the telemetry env block and exit (don't launch)\n                         --log-prompts  Capture prompt text (default: length only / private)\n\nArguments:\n  port                 Port to listen on (shorthand for --port; must be a positive integer)\n\nOptions:\n  -p, --port <port>    Port to listen on (default: 4318, env: AUTOTEL_DEVTOOLS_PORT).\n                       If the port is taken, the next free port is used and a warning is shown.\n  -H, --host <host>    Host to bind to (default: 127.0.0.1, env: AUTOTEL_DEVTOOLS_HOST)\n  -t, --title <title>  Dashboard title, shown in the banner and browser tab\n                       (env: AUTOTEL_DEVTOOLS_TITLE)\n  Env limits:          AUTOTEL_MAX_TRACE_COUNT, AUTOTEL_MAX_LOG_COUNT, AUTOTEL_MAX_METRIC_COUNT\n  -h, --help           Show this help message\n  -v, --version        Show version number\n\nEndpoints:\n  GET    /             Web devtools UI (fullpage)\n  GET    /widget.js    Widget bundle (embed in your app)\n  POST   /v1/traces    Receive OTLP JSON trace data\n  GET    /v1/traces    Read back received traces (verify ingestion in tests)\n  DELETE /v1/traces    Clear captured telemetry (test reset)\n  POST   /v1/logs      Receive OTLP JSON log data\n  POST   /v1/metrics   Receive OTLP JSON metric data\n  WS     /ws           WebSocket stream for real-time updates\n  GET    /healthz      Health check\n\nExamples:\n  npx autotel-devtools\n  npx autotel-devtools 4319\n  npx autotel-devtools -p 4319 -H 0.0.0.0\n  npx autotel-devtools claude                 # watch Claude Code in the Agents tab\n  npx autotel-devtools claude --print-env     # just print the env (for MDM / VS Code)\n\nThen point your app:\n  OTEL_EXPORTER_OTLP_PROTOCOL=http/json OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 node app.js\n\nView in browser:\n  http://localhost:4318\n\nOr embed widget in your app:\n  <script src=\"http://localhost:4318/widget.js\"><\/script>\n\n");
+	process.stdout.write("autotel-devtools - Standalone OTLP receiver with web devtools UI\n\nUsage: autotel-devtools [port] [options]\n       autotel-devtools claude [claude args] [--print-env] [--log-prompts]\n\nSubcommands:\n  claude               Start the receiver AND launch Claude Code wired to it\n                       (HTTP/protobuf → this receiver, 1s intervals, session id on).\n                       Open the \"Agents\" tab to watch sessions, tokens, cost,\n                       tool / MCP / sub-agent / skill usage live.\n                         --print-env    Print the telemetry env block and exit (don't launch)\n                         --log-prompts  Capture prompt text (default: length only / private)\n\nArguments:\n  port                 Port to listen on (shorthand for --port; must be a positive integer)\n\nOptions:\n  -p, --port <port>    Port to listen on (default: 4318, env: AUTOTEL_DEVTOOLS_PORT).\n                       If the port is taken, the next free port is used and a warning is shown.\n  -H, --host <host>    Host to bind to (default: 127.0.0.1, env: AUTOTEL_DEVTOOLS_HOST)\n  -t, --title <title>  Dashboard title, shown in the banner and browser tab\n  -d, --db <path>      Keep telemetry in a sqlite file so it survives restarts\n                       (default: in-memory, env: AUTOTEL_DEVTOOLS_DB)\n      --max-traces <n> Traces retained before the oldest are pruned\n                       (default: 100000, env: AUTOTEL_DEVTOOLS_MAX_TRACES)\n      --grpc-port <n>  OTLP/gRPC port (default: 4317, env: AUTOTEL_DEVTOOLS_GRPC_PORT)\n      --db-max-size <size> Logical store cap, e.g. 512mb or 2gb\n                       (default: 512mb memory / 2gb disk, env: AUTOTEL_DEVTOOLS_DB_MAX_SIZE)\n                       (env: AUTOTEL_DEVTOOLS_TITLE)\n  Env limits:          AUTOTEL_MAX_TRACE_COUNT, AUTOTEL_MAX_LOG_COUNT\n  -h, --help           Show this help message\n  -v, --version        Show version number\n\nEndpoints:\n  GET    /             Web devtools UI (fullpage)\n  GET    /widget.js    Widget bundle (embed in your app)\n  POST   /v1/traces    Receive OTLP JSON trace data\n  GET    /v1/traces    Read back received traces (verify ingestion in tests)\n  DELETE /v1/traces    Clear captured telemetry (test reset)\n  POST   /v1/logs      Receive OTLP JSON log data\n  POST   /v1/metrics   Receive OTLP JSON metric data\n  gRPC   :4317         Receive OTLP protobuf traces, logs and metrics\n  WS     /ws           WebSocket stream for real-time updates\n  GET    /healthz      Health check\n\nExamples:\n  npx autotel-devtools\n  npx autotel-devtools 4319\n  npx autotel-devtools -p 4319 -H 0.0.0.0\n  npx autotel-devtools claude                 # watch Claude Code in the Agents tab\n  npx autotel-devtools claude --print-env     # just print the env (for MDM / VS Code)\n\nThen point your app:\n  OTEL_EXPORTER_OTLP_PROTOCOL=http/json OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 node app.js\n\nView in browser:\n  http://localhost:4318\n\nOr embed widget in your app:\n  <script src=\"http://localhost:4318/widget.js\"><\/script>\n\n");
 }
 function printVersion() {
 	try {
@@ -24,7 +25,11 @@ function parseArgs(argv) {
 	const options = {
 		port: parsePort(process.env.AUTOTEL_DEVTOOLS_PORT || "4318"),
 		host: process.env.AUTOTEL_DEVTOOLS_HOST || "127.0.0.1",
-		title: process.env.AUTOTEL_DEVTOOLS_TITLE
+		title: process.env.AUTOTEL_DEVTOOLS_TITLE,
+		dbPath: process.env.AUTOTEL_DEVTOOLS_DB,
+		maxTraces: parseCount(process.env.AUTOTEL_DEVTOOLS_MAX_TRACES),
+		maxDbBytes: parseBytes(process.env.AUTOTEL_DEVTOOLS_DB_MAX_SIZE),
+		grpcPort: parsePort(process.env.AUTOTEL_DEVTOOLS_GRPC_PORT || "4317")
 	};
 	let portWasExplicit = false;
 	let positionalPortConsumed = false;
@@ -55,6 +60,26 @@ function parseArgs(argv) {
 			i++;
 			continue;
 		}
+		if ((arg === "--db" || arg === "-d") && next) {
+			options.dbPath = next;
+			i++;
+			continue;
+		}
+		if (arg === "--max-traces" && next) {
+			options.maxTraces = parseCount(next);
+			i++;
+			continue;
+		}
+		if (arg === "--grpc-port" && next) {
+			options.grpcPort = parsePort(next);
+			i++;
+			continue;
+		}
+		if (arg === "--db-max-size" && next) {
+			options.maxDbBytes = parseBytes(next);
+			i++;
+			continue;
+		}
 		if (/^\d+$/.test(arg) && !positionalPortConsumed) {
 			if (!portWasExplicit) options.port = parsePort(arg);
 			positionalPortConsumed = true;
@@ -63,6 +88,28 @@ function parseArgs(argv) {
 	}
 	return options;
 }
+/**
+* A positive integer option, or undefined when unset.
+*
+* Unlike `parsePort` this does not exit on a bad value: a nonsense retention
+* cap should fall back to the default rather than refuse to start a viewer.
+*/
+function parseCount(value) {
+	if (!value) return void 0;
+	const n = Number(value);
+	return Number.isInteger(n) && n > 0 ? n : void 0;
+}
+function parseBytes(value) {
+	if (!value) return void 0;
+	const match = value.trim().toLowerCase().match(/^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb)?$/);
+	if (!match) return void 0;
+	return Math.floor(Number(match[1]) * {
+		b: 1,
+		kb: 1024,
+		mb: 1024 ** 2,
+		gb: 1024 ** 3
+	}[match[2] || "b"]);
+}
 function parsePort(value) {
 	const n = Number(value);
 	if (!Number.isInteger(n) || n < 0 || n > 65535) {
@@ -77,7 +124,10 @@ async function startReceiver(options) {
 	const wsServer = new require_http.DevtoolsServer({
 		server: httpServer,
 		host: options.host,
-		verbose: true
+		verbose: true,
+		dbPath: options.dbPath,
+		maxTraces: options.maxTraces,
+		maxDbBytes: options.maxDbBytes
 	});
 	const sourceRoot = require_http.resolveSourceRoot(process.env.AUTOTEL_DEVTOOLS_SOURCE_ROOT, process.cwd(), loopbackOnly);
 	require_http.attachDevtoolsRoutes(httpServer, wsServer, {
@@ -89,22 +139,36 @@ async function startReceiver(options) {
 		primary: httpServer,
 		port: options.port,
 		host: options.host,
-		attachSecondary: (s) => require_http.attachDevtoolsRoutes(s, wsServer, {
-			loopbackOnly,
-			title: options.title,
-			sourceRoot
-		})
+		attachSecondary: (s) => {
+			require_http.attachDevtoolsRoutes(s, wsServer, {
+				loopbackOnly,
+				title: options.title,
+				sourceRoot
+			});
+			wsServer.attachWebSocket(s);
+		}
 	});
 	const { addresses, warnings, port: boundPort } = await listeners.ready;
+	const grpc = await require_grpc.startOtlpGrpcReceiver({
+		devtools: wsServer,
+		host: options.host,
+		port: options.grpcPort
+	});
+	if (grpc.port !== options.grpcPort) warnings.push(`OTLP/gRPC port ${options.grpcPort} was busy; using ${grpc.port}.`);
 	if (boundPort !== options.port) if (await require_http.probePortHolder(options.host, options.port) === "autotel-devtools") warnings.push(`another autotel-devtools is already running on port ${options.port}; this instance is on ${boundPort}. Use the existing one, or stop it and restart here.`);
 	else warnings.push(`port ${options.port} is held by another process that is NOT autotel-devtools. Anything exporting OTLP to :${options.port} is reaching that process, not this devtools. Point your exporter at :${boundPort}, or free :${options.port} and restart.`);
 	return {
 		wsServer,
-		closeAll: () => Promise.all([wsServer.close(), listeners.closeSibling()]).then(() => void 0),
+		closeAll: () => Promise.all([
+			wsServer.close(),
+			listeners.closeSibling(),
+			grpc.close()
+		]).then(() => void 0),
 		addresses,
 		warnings,
 		boundPort,
-		uiBase: `http://${options.host === "localhost" ? "127.0.0.1" : options.host}:${boundPort}`
+		uiBase: `http://${options.host === "localhost" ? "127.0.0.1" : options.host}:${boundPort}`,
+		grpcAddress: grpc.address
 	};
 }
 function buildAgentEnv(uiBase, logPrompts) {
@@ -169,7 +233,8 @@ async function runClaudeSubcommand(argv) {
 	}
 	const receiver = await startReceiver({
 		port: opts.port,
-		host: opts.host
+		host: opts.host,
+		grpcPort: 4317
 	});
 	const env = buildAgentEnv(receiver.uiBase, opts.logPrompts);
 	process.stdout.write(`\n  autotel-devtools — Claude Code\n\n`);
@@ -214,6 +279,7 @@ async function main() {
 	process.stdout.write(`  Listening: ${addresses.join("  +  ")}\n`);
 	process.stdout.write(`  UI:        ${uiBase}   (open in a browser)\n`);
 	process.stdout.write(`  OTLP:      ${uiBase}/v1/traces\n`);
+	process.stdout.write(`  OTLP/gRPC: ${receiver.grpcAddress}\n`);
 	process.stdout.write(`  WebSocket: ${uiBase.replace("http", "ws")}/ws\n\n`);
 	process.stdout.write(`  Embed in your app — paste into your HTML; a floating panel appears automatically:\n`);
 	process.stdout.write(`    <script src="${uiBase}/widget.js"><\/script>\n\n`);
@@ -222,6 +288,7 @@ async function main() {
 	process.stdout.write(`  Or point any OTLP exporter at this receiver:\n`);
 	process.stdout.write(`    OTEL_EXPORTER_OTLP_PROTOCOL=http/json\n`);
 	process.stdout.write(`    OTEL_EXPORTER_OTLP_ENDPOINT=${uiBase}\n\n`);
+	process.stdout.write(`  Or use gRPC: OTEL_EXPORTER_OTLP_ENDPOINT=http://${receiver.grpcAddress}\n\n`);
 	process.stdout.write(`  Verify ingestion: curl -s ${uiBase}/v1/traces\n\n`);
 	for (const w of warnings) process.stdout.write(`  ⚠ ${w}\n`);
 	if (warnings.length > 0) process.stdout.write("\n");