autotel-devtools 4.0.0 → 5.0.1

package/README.md

@@ -16,9 +16,9 @@ Standalone OTLP receiver with web UI for local development. Think TanStack Devto
 │  npx autotel-devtools                       │
 │  ┌───────────────────────────────────────┐ │
 │  │  HTTP Server (port 4318)               │ │
-│  │  ├── POST /v1/traces  ← OTLP JSON     │ │
-│  │  ├── POST /v1/logs     ← OTLP JSON     │ │
-│  │  ├── POST /v1/metrics  ← OTLP JSON     │ │
+│  │  ├── POST /v1/traces  ← OTLP JSON/PB │ │
+│  │  ├── POST /v1/logs     ← OTLP JSON/PB │ │
+│  │  ├── POST /v1/metrics  ← OTLP JSON/PB │ │
 │  │  ├── GET  /            → Full page UI  │ │
 │  │  ├── GET  /widget.js   → Widget bundle │ │
 │  │  ├── GET  /healthz     → Health check  │ │
@@ -41,6 +41,16 @@ OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
 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:
+
+```bash
+# Python / Java / Go SDKs default to http/protobuf — just 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.
 
 ### Embedded Widget
@@ -100,7 +110,7 @@ const myFunction = trace((ctx) => async () => {
 ### Server (Node.js)
 
 - **DevtoolsServer** - WebSocket server + in-memory data store
-- **HTTP Routes** - OTLP receivers for traces/logs/metrics
+- **HTTP Routes** - OTLP receivers for traces/logs/metrics (JSON + protobuf)
 - **Exporters** - OpenTelemetry span/log exporters
 
 ### Widget (Preact)
@@ -151,6 +161,61 @@ Options:
 - `--host, -H` - Host to bind to (default: 127.0.0.1)
 - `--title, -t` - Dashboard title
 
+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.
+
+## 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:
+
+```ts
+// Express / http-proxy-middleware
+import { createProxyMiddleware } from 'http-proxy-middleware';
+
+app.use(
+  '/v1/traces',
+  createProxyMiddleware({
+    // (a) Express strips the mount prefix before calling middleware, so the
+    //     proxy would otherwise forward "/" instead of "/v1/traces".
+    pathRewrite: () => '/v1/traces',
+    // (b) Use 127.0.0.1, NOT localhost. On macOS `localhost` resolves to ::1;
+    //     pin the family so you reach the receiver deterministically.
+    target: 'http://127.0.0.1:4318',
+    changeOrigin: true,
+  }),
+);
+```
+
+> 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.
+
+## 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):
+
+```bash
+GET    /v1/traces   # → { traces: [...], count: N }  what the receiver has
+DELETE /v1/traces   # clear captured telemetry (reset between tests)
+```
+
+```ts
+// 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
+await expect
+  .poll(async () => (await (await fetch(`${RECEIVER}/v1/traces`)).json()).count)
+  .toBeGreaterThan(0);
+```
+
 ## License
 
 MIT

package/dist/cli.cjs

@@ -6,8 +6,29 @@ var fs = require('fs');
 var path = require('path');
 var url = require('url');
 var ws = require('ws');
+var protobuf = require('protobufjs');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var protobuf__namespace = /*#__PURE__*/_interopNamespace(protobuf);
+
 // src/server/error-aggregator.ts
 var ErrorAggregator = class {
   errorGroups = /* @__PURE__ */ new Map();
@@ -528,7 +549,7 @@ var SPAN_KIND_MAP = {
 function normalizeHexId(id) {
   if (!id) return "";
   const isBase64Like = /^[A-Za-z0-9+/=]+$/.test(id) && !/^[0-9a-f]+$/i.test(id);
-  const isLikelyBase64Id = isBase64Like && (id.length === 24 || id.length === 28 || id.length === 44 || id.length === 48);
+  const isLikelyBase64Id = isBase64Like && (id.length === 12 || id.length === 24 || id.length === 28 || id.length === 44 || id.length === 48);
   if (isLikelyBase64Id) {
     try {
       const bytes = Buffer.from(id, "base64");
@@ -660,13 +681,255 @@ async function readJsonBody(req) {
     req.on("error", reject);
   });
 }
+async function readRawBody(req) {
+  return new Promise((resolve3, reject) => {
+    const chunks = [];
+    req.on("data", (chunk) => chunks.push(chunk));
+    req.on("end", () => resolve3(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}
+function isProtobufContentType(contentType) {
+  if (!contentType) return false;
+  const value = contentType.toLowerCase();
+  return value.includes("application/x-protobuf") || value.includes("application/protobuf");
+}
 function sendJson(res, status, data) {
   const body = JSON.stringify(data);
   res.writeHead(status, { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(body) });
   res.end(body);
 }
+var COMMON_PROTO = `
+syntax = "proto3";
+package opentelemetry.proto.common.v1;
+
+message AnyValue {
+  oneof value {
+    string string_value = 1;
+    bool bool_value = 2;
+    int64 int_value = 3;
+    double double_value = 4;
+    ArrayValue array_value = 5;
+    KeyValueList kvlist_value = 6;
+    bytes bytes_value = 7;
+  }
+}
+message ArrayValue { repeated AnyValue values = 1; }
+message KeyValueList { repeated KeyValue values = 1; }
+message KeyValue {
+  string key = 1;
+  AnyValue value = 2;
+}
+message InstrumentationScope {
+  string name = 1;
+  string version = 2;
+  repeated KeyValue attributes = 3;
+  uint32 dropped_attributes_count = 4;
+}
+`;
+var RESOURCE_PROTO = `
+syntax = "proto3";
+package opentelemetry.proto.resource.v1;
+
+message Resource {
+  repeated opentelemetry.proto.common.v1.KeyValue attributes = 1;
+  uint32 dropped_attributes_count = 2;
+}
+`;
+var TRACE_PROTO = `
+syntax = "proto3";
+package opentelemetry.proto.trace.v1;
+
+message ResourceSpans {
+  opentelemetry.proto.resource.v1.Resource resource = 1;
+  repeated ScopeSpans scope_spans = 2;
+  string schema_url = 3;
+}
+message ScopeSpans {
+  opentelemetry.proto.common.v1.InstrumentationScope scope = 1;
+  repeated Span spans = 2;
+  string schema_url = 3;
+}
+message Span {
+  bytes trace_id = 1;
+  bytes span_id = 2;
+  string trace_state = 3;
+  bytes parent_span_id = 4;
+  fixed32 flags = 16;
+  string name = 5;
+  SpanKind kind = 6;
+  fixed64 start_time_unix_nano = 7;
+  fixed64 end_time_unix_nano = 8;
+  repeated opentelemetry.proto.common.v1.KeyValue attributes = 9;
+  uint32 dropped_attributes_count = 10;
+  repeated Event events = 11;
+  uint32 dropped_events_count = 12;
+  repeated Link links = 13;
+  uint32 dropped_links_count = 14;
+  Status status = 15;
+
+  enum SpanKind {
+    SPAN_KIND_UNSPECIFIED = 0;
+    SPAN_KIND_INTERNAL = 1;
+    SPAN_KIND_SERVER = 2;
+    SPAN_KIND_CLIENT = 3;
+    SPAN_KIND_PRODUCER = 4;
+    SPAN_KIND_CONSUMER = 5;
+  }
+  message Event {
+    fixed64 time_unix_nano = 1;
+    string name = 2;
+    repeated opentelemetry.proto.common.v1.KeyValue attributes = 3;
+    uint32 dropped_attributes_count = 4;
+  }
+  message Link {
+    bytes trace_id = 1;
+    bytes span_id = 2;
+    string trace_state = 3;
+    repeated opentelemetry.proto.common.v1.KeyValue attributes = 4;
+    uint32 dropped_attributes_count = 5;
+    fixed32 flags = 6;
+  }
+}
+message Status {
+  reserved 1;
+  string message = 2;
+  StatusCode code = 3;
+
+  enum StatusCode {
+    STATUS_CODE_UNSET = 0;
+    STATUS_CODE_OK = 1;
+    STATUS_CODE_ERROR = 2;
+  }
+}
+message ExportTraceServiceRequest {
+  repeated ResourceSpans resource_spans = 1;
+}
+`;
+var LOGS_PROTO = `
+syntax = "proto3";
+package opentelemetry.proto.logs.v1;
+
+enum SeverityNumber {
+  SEVERITY_NUMBER_UNSPECIFIED = 0;
+  SEVERITY_NUMBER_TRACE = 1;
+  SEVERITY_NUMBER_TRACE2 = 2;
+  SEVERITY_NUMBER_TRACE3 = 3;
+  SEVERITY_NUMBER_TRACE4 = 4;
+  SEVERITY_NUMBER_DEBUG = 5;
+  SEVERITY_NUMBER_DEBUG2 = 6;
+  SEVERITY_NUMBER_DEBUG3 = 7;
+  SEVERITY_NUMBER_DEBUG4 = 8;
+  SEVERITY_NUMBER_INFO = 9;
+  SEVERITY_NUMBER_INFO2 = 10;
+  SEVERITY_NUMBER_INFO3 = 11;
+  SEVERITY_NUMBER_INFO4 = 12;
+  SEVERITY_NUMBER_WARN = 13;
+  SEVERITY_NUMBER_WARN2 = 14;
+  SEVERITY_NUMBER_WARN3 = 15;
+  SEVERITY_NUMBER_WARN4 = 16;
+  SEVERITY_NUMBER_ERROR = 17;
+  SEVERITY_NUMBER_ERROR2 = 18;
+  SEVERITY_NUMBER_ERROR3 = 19;
+  SEVERITY_NUMBER_ERROR4 = 20;
+  SEVERITY_NUMBER_FATAL = 21;
+  SEVERITY_NUMBER_FATAL2 = 22;
+  SEVERITY_NUMBER_FATAL3 = 23;
+  SEVERITY_NUMBER_FATAL4 = 24;
+}
+message ResourceLogs {
+  opentelemetry.proto.resource.v1.Resource resource = 1;
+  repeated ScopeLogs scope_logs = 2;
+  string schema_url = 3;
+}
+message ScopeLogs {
+  opentelemetry.proto.common.v1.InstrumentationScope scope = 1;
+  repeated LogRecord log_records = 2;
+  string schema_url = 3;
+}
+message LogRecord {
+  reserved 4;
+  fixed64 time_unix_nano = 1;
+  fixed64 observed_time_unix_nano = 11;
+  SeverityNumber severity_number = 2;
+  string severity_text = 3;
+  opentelemetry.proto.common.v1.AnyValue body = 5;
+  repeated opentelemetry.proto.common.v1.KeyValue attributes = 6;
+  uint32 dropped_attributes_count = 7;
+  fixed32 flags = 8;
+  bytes trace_id = 9;
+  bytes span_id = 10;
+}
+message ExportLogsServiceRequest {
+  repeated ResourceLogs resource_logs = 1;
+}
+`;
+var METRICS_PROTO = `
+syntax = "proto3";
+package opentelemetry.proto.metrics.v1;
+
+message ResourceMetrics {
+  opentelemetry.proto.resource.v1.Resource resource = 1;
+  repeated ScopeMetrics scope_metrics = 2;
+  string schema_url = 3;
+}
+message ScopeMetrics {
+  opentelemetry.proto.common.v1.InstrumentationScope scope = 1;
+  repeated Metric metrics = 2;
+  string schema_url = 3;
+}
+message Metric {
+  string name = 1;
+  string description = 2;
+  string unit = 3;
+}
+message ExportMetricsServiceRequest {
+  repeated ResourceMetrics resource_metrics = 1;
+}
+`;
+var TO_OBJECT_OPTIONS = {
+  longs: String,
+  bytes: String,
+  defaults: false
+};
+var cachedRoot = null;
+function getRoot() {
+  if (cachedRoot) return cachedRoot;
+  const root = new protobuf__namespace.Root();
+  for (const source of [COMMON_PROTO, RESOURCE_PROTO, TRACE_PROTO, LOGS_PROTO, METRICS_PROTO]) {
+    protobuf__namespace.parse(source, root, { keepCase: false });
+  }
+  root.resolveAll();
+  cachedRoot = root;
+  return root;
+}
+function decodeRequest(typeName, body) {
+  const messageType = getRoot().lookupType(typeName);
+  const message = messageType.decode(body);
+  return messageType.toObject(message, TO_OBJECT_OPTIONS);
+}
+function decodeOtlpTraceRequest(body) {
+  return decodeRequest("opentelemetry.proto.trace.v1.ExportTraceServiceRequest", body);
+}
+function decodeOtlpLogsRequest(body) {
+  return decodeRequest("opentelemetry.proto.logs.v1.ExportLogsServiceRequest", body);
+}
+function decodeOtlpMetricsRequest(body) {
+  return decodeRequest("opentelemetry.proto.metrics.v1.ExportMetricsServiceRequest", body);
+}
 
 // src/server/http.ts
+var PROTOBUF_DECODERS = {
+  traces: decodeOtlpTraceRequest,
+  logs: decodeOtlpLogsRequest,
+  metrics: decodeOtlpMetricsRequest
+};
+async function readOtlpPayload(req, signal) {
+  if (isProtobufContentType(req.headers["content-type"])) {
+    return PROTOBUF_DECODERS[signal](await readRawBody(req));
+  }
+  return readJsonBody(req);
+}
 function findPackageRoot() {
   let dir = path.dirname(url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli.cjs', document.baseURI).href))));
   for (let i = 0; i < 5; i++) {
@@ -700,7 +963,7 @@ function getWidgetJs() {
 function attachDevtoolsRoutes(httpServer, devtools) {
   httpServer.on("request", async (req, res) => {
     res.setHeader("Access-Control-Allow-Origin", "*");
-    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
     res.setHeader("Access-Control-Allow-Headers", "Content-Type");
     if (req.method === "OPTIONS") {
       res.writeHead(204);
@@ -723,41 +986,99 @@ function attachDevtoolsRoutes(httpServer, devtools) {
       sendJson(res, 200, { ok: true, clients: devtools.clientCount });
       return;
     }
+    if (req.method === "GET" && url === "/v1/traces") {
+      const data = devtools.getCurrentData();
+      sendJson(res, 200, { traces: data.traces, count: data.traces.length });
+      return;
+    }
+    if (req.method === "DELETE" && url === "/v1/traces") {
+      devtools.clearData();
+      sendJson(res, 200, { cleared: true });
+      return;
+    }
     if (req.method === "POST" && url === "/v1/traces") {
       try {
-        const payload = await readJsonBody(req);
+        const payload = await readOtlpPayload(req, "traces");
         const traces = parseOtlpTraces(payload);
         devtools.addTraces(traces);
         sendJson(res, 200, { acceptedTraces: traces.length });
       } catch (e) {
-        sendJson(res, 400, { error: "Invalid OTLP JSON", message: e instanceof Error ? e.message : String(e) });
+        sendJson(res, 400, { error: "Invalid OTLP payload", message: e instanceof Error ? e.message : String(e) });
       }
       return;
     }
     if (req.method === "POST" && url === "/v1/logs") {
       try {
-        const payload = await readJsonBody(req);
+        const payload = await readOtlpPayload(req, "logs");
         const logs = parseOtlpLogs(payload);
         devtools.addLogs(logs);
         sendJson(res, 200, { acceptedLogs: logs.length });
       } catch (e) {
-        sendJson(res, 400, { error: "Invalid OTLP JSON", message: e instanceof Error ? e.message : String(e) });
+        sendJson(res, 400, { error: "Invalid OTLP payload", message: e instanceof Error ? e.message : String(e) });
       }
       return;
     }
     if (req.method === "POST" && url === "/v1/metrics") {
       try {
-        const payload = await readJsonBody(req);
+        const payload = await readOtlpPayload(req, "metrics");
         const count = countOtlpMetrics(payload);
         sendJson(res, 200, { acceptedMetrics: count });
       } catch (e) {
-        sendJson(res, 400, { error: "Invalid OTLP JSON", message: e instanceof Error ? e.message : String(e) });
+        sendJson(res, 400, { error: "Invalid OTLP payload", message: e instanceof Error ? e.message : String(e) });
       }
       return;
     }
     sendJson(res, 404, { error: "Not found" });
   });
 }
+var LOOPBACK = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1"]);
+function formatAddress(host, port) {
+  return host.includes(":") ? `[${host}]:${port}` : `${host}:${port}`;
+}
+function listenLoopbackDualStack(args) {
+  const { primary, port, host, attachSecondary } = args;
+  let sibling;
+  const ready = new Promise(
+    (resolve3) => {
+      const addresses = [];
+      const warnings = [];
+      const primaryHost = host === "localhost" ? "127.0.0.1" : host;
+      primary.listen(port, primaryHost, () => {
+        const addr = primary.address();
+        const resolvedPort = addr && typeof addr === "object" ? addr.port : port;
+        addresses.push(formatAddress(primaryHost, resolvedPort));
+        if (!LOOPBACK.has(host)) {
+          resolve3({ addresses, warnings });
+          return;
+        }
+        const siblingHost = primaryHost === "::1" ? "127.0.0.1" : "::1";
+        const s = http.createServer();
+        attachSecondary(s);
+        const onError = (e) => {
+          s.close();
+          warnings.push(
+            `could not also bind ${formatAddress(siblingHost, resolvedPort)} (${e.message}); clients using the ${siblingHost === "::1" ? "IPv6" : "IPv4"} form of "localhost" may not connect.`
+          );
+          resolve3({ addresses, warnings });
+        };
+        s.once("error", onError);
+        s.listen(resolvedPort, siblingHost, () => {
+          s.off("error", onError);
+          sibling = s;
+          addresses.push(formatAddress(siblingHost, resolvedPort));
+          resolve3({ addresses, warnings });
+        });
+      });
+    }
+  );
+  return {
+    ready,
+    closeSibling: () => new Promise((res) => {
+      if (!sibling) return res();
+      sibling.close(() => res());
+    })
+  };
+}
 
 // src/cli.ts
 function printHelp() {
@@ -775,13 +1096,15 @@ Options:
   -v, --version        Show version number
 
 Endpoints:
-  GET  /               Web devtools UI (fullpage)
-  GET  /widget.js      Widget bundle (embed in your app)
-  POST /v1/traces      Receive OTLP JSON trace data
-  POST /v1/logs        Receive OTLP JSON log data
-  POST /v1/metrics     Receive OTLP JSON metric data
-  WS   /ws             WebSocket stream for real-time updates
-  GET  /healthz        Health check
+  GET    /             Web devtools UI (fullpage)
+  GET    /widget.js    Widget bundle (embed in your app)
+  POST   /v1/traces    Receive OTLP JSON trace data
+  GET    /v1/traces    Read back received traces (verify ingestion in tests)
+  DELETE /v1/traces    Clear captured telemetry (test reset)
+  POST   /v1/logs      Receive OTLP JSON log data
+  POST   /v1/metrics   Receive OTLP JSON metric data
+  WS     /ws           WebSocket stream for real-time updates
+  GET    /healthz      Health check
 
 Examples:
   npx autotel-devtools
@@ -853,29 +1176,47 @@ async function main() {
   const httpServer = http.createServer();
   const wsServer = new DevtoolsServer({ server: httpServer, verbose: true });
   attachDevtoolsRoutes(httpServer, wsServer);
-  httpServer.listen(options.port, options.host, () => {
-    const title = options.title || "autotel-devtools";
-    process.stdout.write(`
+  const listeners = listenLoopbackDualStack({
+    primary: httpServer,
+    port: options.port,
+    host: options.host,
+    attachSecondary: (s) => attachDevtoolsRoutes(s, wsServer)
+  });
+  const { addresses, warnings } = await listeners.ready;
+  const uiBase = `http://${options.host === "localhost" ? "127.0.0.1" : options.host}:${options.port}`;
+  const title = options.title || "autotel-devtools";
+  process.stdout.write(`
   ${title}
 
 `);
-    process.stdout.write(`  UI:        http://${options.host}:${options.port}
+  process.stdout.write(`  Listening: ${addresses.join("  +  ")}
+`);
+  process.stdout.write(`  UI:        ${uiBase}
 `);
-    process.stdout.write(`  Widget:    <script src="http://${options.host}:${options.port}/widget.js"></script>
+  process.stdout.write(`  Widget:    <script src="${uiBase}/widget.js"></script>
 `);
-    process.stdout.write(`  WebSocket: ws://${options.host}:${options.port}/ws
+  process.stdout.write(`  WebSocket: ${uiBase.replace("http", "ws")}/ws
 `);
-    process.stdout.write(`  OTLP:      http://${options.host}:${options.port}/v1/traces
+  process.stdout.write(`  OTLP:      ${uiBase}/v1/traces
 
 `);
-    process.stdout.write(`  Set OTEL_EXPORTER_OTLP_PROTOCOL=http/json
+  process.stdout.write(`  Set OTEL_EXPORTER_OTLP_PROTOCOL=http/json
 `);
-    process.stdout.write(`  Set OTEL_EXPORTER_OTLP_ENDPOINT=http://${options.host}:${options.port}
+  process.stdout.write(`  Set OTEL_EXPORTER_OTLP_ENDPOINT=${uiBase}
 
 `);
-  });
+  process.stdout.write(`  Verify ingestion: curl -s ${uiBase}/v1/traces
+
+`);
+  for (const w of warnings) {
+    process.stdout.write(`  \u26A0 ${w}
+`);
+  }
+  if (warnings.length > 0) process.stdout.write("\n");
   const shutdown = () => {
-    wsServer.close().then(() => process.exit(0));
+    Promise.all([wsServer.close(), listeners.closeSibling()]).then(
+      () => process.exit(0)
+    );
   };
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);