tokviz 0.1.0

package/dist/client/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>tokviz</title>
+    <script type="module" crossorigin src="/assets/index-SNGqhtM5.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-R0O4p4a7.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/dist/server/index.js

@@ -0,0 +1,416 @@
+#!/usr/bin/env node
+
+// src/server/index.ts
+import express from "express";
+import { createServer } from "http";
+import { WebSocketServer, WebSocket } from "ws";
+import { parseArgs } from "util";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { existsSync } from "fs";
+import open from "open";
+
+// src/server/otlp.ts
+import protobuf from "protobufjs";
+
+// src/server/store.ts
+var Store = class {
+  spans = [];
+  add(span) {
+    this.spans.push(span);
+  }
+  getAll() {
+    return { spans: this.spans };
+  }
+};
+var store = new Store();
+
+// src/server/proto.ts
+var protoDescriptor = {
+  nested: {
+    opentelemetry: {
+      nested: {
+        proto: {
+          nested: {
+            collector: {
+              nested: {
+                trace: {
+                  nested: {
+                    v1: {
+                      nested: {
+                        ExportTraceServiceRequest: {
+                          fields: {
+                            resourceSpans: {
+                              rule: "repeated",
+                              type: "opentelemetry.proto.trace.v1.ResourceSpans",
+                              id: 1
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            },
+            trace: {
+              nested: {
+                v1: {
+                  nested: {
+                    ResourceSpans: {
+                      fields: {
+                        resource: {
+                          type: "opentelemetry.proto.resource.v1.Resource",
+                          id: 1
+                        },
+                        scopeSpans: {
+                          rule: "repeated",
+                          type: "ScopeSpans",
+                          id: 2
+                        },
+                        schemaUrl: { type: "string", id: 3 }
+                      }
+                    },
+                    ScopeSpans: {
+                      fields: {
+                        scope: {
+                          type: "opentelemetry.proto.common.v1.InstrumentationScope",
+                          id: 1
+                        },
+                        spans: { rule: "repeated", type: "Span", id: 2 },
+                        schemaUrl: { type: "string", id: 3 }
+                      }
+                    },
+                    Span: {
+                      fields: {
+                        traceId: { type: "bytes", id: 1 },
+                        spanId: { type: "bytes", id: 2 },
+                        traceState: { type: "string", id: 3 },
+                        parentSpanId: { type: "bytes", id: 4 },
+                        name: { type: "string", id: 5 },
+                        kind: { type: "SpanKind", id: 6 },
+                        startTimeUnixNano: { type: "fixed64", id: 7 },
+                        endTimeUnixNano: { type: "fixed64", id: 8 },
+                        attributes: {
+                          rule: "repeated",
+                          type: "opentelemetry.proto.common.v1.KeyValue",
+                          id: 9
+                        },
+                        droppedAttributesCount: { type: "uint32", id: 10 },
+                        events: { rule: "repeated", type: "Event", id: 11 },
+                        droppedEventsCount: { type: "uint32", id: 12 },
+                        links: { rule: "repeated", type: "Link", id: 13 },
+                        droppedLinksCount: { type: "uint32", id: 14 },
+                        status: { type: "Status", id: 15 }
+                      }
+                    },
+                    SpanKind: {
+                      values: {
+                        SPAN_KIND_UNSPECIFIED: 0,
+                        SPAN_KIND_INTERNAL: 1,
+                        SPAN_KIND_SERVER: 2,
+                        SPAN_KIND_CLIENT: 3,
+                        SPAN_KIND_PRODUCER: 4,
+                        SPAN_KIND_CONSUMER: 5
+                      }
+                    },
+                    Status: {
+                      fields: {
+                        message: { type: "string", id: 2 },
+                        code: { type: "StatusCode", id: 3 }
+                      }
+                    },
+                    StatusCode: {
+                      values: {
+                        STATUS_CODE_UNSET: 0,
+                        STATUS_CODE_OK: 1,
+                        STATUS_CODE_ERROR: 2
+                      }
+                    },
+                    Event: {
+                      fields: {
+                        timeUnixNano: { type: "fixed64", id: 1 },
+                        name: { type: "string", id: 2 },
+                        attributes: {
+                          rule: "repeated",
+                          type: "opentelemetry.proto.common.v1.KeyValue",
+                          id: 3
+                        },
+                        droppedAttributesCount: { type: "uint32", id: 4 }
+                      }
+                    },
+                    Link: {
+                      fields: {
+                        traceId: { type: "bytes", id: 1 },
+                        spanId: { type: "bytes", id: 2 },
+                        traceState: { type: "string", id: 3 },
+                        attributes: {
+                          rule: "repeated",
+                          type: "opentelemetry.proto.common.v1.KeyValue",
+                          id: 4
+                        },
+                        droppedAttributesCount: { type: "uint32", id: 5 }
+                      }
+                    }
+                  }
+                }
+              }
+            },
+            common: {
+              nested: {
+                v1: {
+                  nested: {
+                    InstrumentationScope: {
+                      fields: {
+                        name: { type: "string", id: 1 },
+                        version: { type: "string", id: 2 },
+                        attributes: {
+                          rule: "repeated",
+                          type: "KeyValue",
+                          id: 3
+                        },
+                        droppedAttributesCount: { type: "uint32", id: 4 }
+                      }
+                    },
+                    KeyValue: {
+                      fields: {
+                        key: { type: "string", id: 1 },
+                        value: { type: "AnyValue", id: 2 }
+                      }
+                    },
+                    AnyValue: {
+                      oneofs: {
+                        value: {
+                          oneof: [
+                            "stringValue",
+                            "boolValue",
+                            "intValue",
+                            "doubleValue",
+                            "arrayValue",
+                            "kvlistValue",
+                            "bytesValue"
+                          ]
+                        }
+                      },
+                      fields: {
+                        stringValue: { type: "string", id: 1 },
+                        boolValue: { type: "bool", id: 2 },
+                        intValue: { type: "int64", id: 3 },
+                        doubleValue: { type: "double", id: 4 },
+                        arrayValue: { type: "ArrayValue", id: 5 },
+                        kvlistValue: { type: "KeyValueList", id: 6 },
+                        bytesValue: { type: "bytes", id: 7 }
+                      }
+                    },
+                    ArrayValue: {
+                      fields: {
+                        values: { rule: "repeated", type: "AnyValue", id: 1 }
+                      }
+                    },
+                    KeyValueList: {
+                      fields: {
+                        values: { rule: "repeated", type: "KeyValue", id: 1 }
+                      }
+                    }
+                  }
+                }
+              }
+            },
+            resource: {
+              nested: {
+                v1: {
+                  nested: {
+                    Resource: {
+                      fields: {
+                        attributes: {
+                          rule: "repeated",
+                          type: "opentelemetry.proto.common.v1.KeyValue",
+                          id: 1
+                        },
+                        droppedAttributesCount: { type: "uint32", id: 2 }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+};
+
+// src/server/otlp.ts
+var root = protobuf.Root.fromJSON(protoDescriptor);
+var ExportTraceServiceRequest = root.lookupType(
+  "opentelemetry.proto.collector.trace.v1.ExportTraceServiceRequest"
+);
+function handleTraces(body, contentType) {
+  let request;
+  if (contentType.includes("application/x-protobuf")) {
+    const message = ExportTraceServiceRequest.decode(
+      body instanceof Buffer ? new Uint8Array(body) : body
+    );
+    request = ExportTraceServiceRequest.toObject(message, {
+      longs: String,
+      bytes: Buffer,
+      defaults: true
+    });
+  } else {
+    request = body;
+  }
+  return extractGenAISpans(request);
+}
+function extractGenAISpans(request) {
+  const spans = [];
+  for (const resourceSpan of request.resourceSpans || []) {
+    for (const scopeSpan of resourceSpan.scopeSpans || []) {
+      for (const span of scopeSpan.spans || []) {
+        const attrs = extractAttributes(span.attributes || []);
+        const hasGenAI = Object.keys(attrs).some(
+          (k) => k.startsWith("gen_ai.")
+        );
+        if (!hasGenAI) continue;
+        const inputTokens = toNumber(attrs["gen_ai.usage.input_tokens"]);
+        const outputTokens = toNumber(attrs["gen_ai.usage.output_tokens"]);
+        const genAISpan = {
+          id: toHex(span.spanId),
+          traceId: toHex(span.traceId),
+          name: span.name || "",
+          startTime: nanoToMs(span.startTimeUnixNano),
+          endTime: nanoToMs(span.endTimeUnixNano),
+          duration: nanoToMs(span.endTimeUnixNano) - nanoToMs(span.startTimeUnixNano),
+          model: String(
+            attrs["gen_ai.response.model"] || attrs["gen_ai.request.model"] || "unknown"
+          ),
+          requestModel: attrs["gen_ai.request.model"] != null ? String(attrs["gen_ai.request.model"]) : void 0,
+          responseModel: attrs["gen_ai.response.model"] != null ? String(attrs["gen_ai.response.model"]) : void 0,
+          inputTokens,
+          outputTokens,
+          totalTokens: attrs["gen_ai.usage.total_tokens"] != null ? toNumber(attrs["gen_ai.usage.total_tokens"]) : inputTokens + outputTokens,
+          cost: toFloat(attrs["gen_ai.usage.cost"]),
+          operationName: String(
+            attrs["gen_ai.operation.name"] || span.name || ""
+          ),
+          attributes: attrs
+        };
+        store.add(genAISpan);
+        spans.push(genAISpan);
+      }
+    }
+  }
+  return spans;
+}
+function extractAttributes(attributes) {
+  const result = {};
+  for (const attr of attributes) {
+    const key = attr.key;
+    const value = attr.value;
+    if (!value) continue;
+    if (value.stringValue != null) result[key] = value.stringValue;
+    else if (value.intValue != null) result[key] = Number(value.intValue);
+    else if (value.doubleValue != null) result[key] = value.doubleValue;
+    else if (value.boolValue != null) result[key] = value.boolValue;
+  }
+  return result;
+}
+function toHex(value) {
+  if (typeof value === "string") {
+    if (/^[0-9a-f]+$/i.test(value)) return value.toLowerCase();
+    return Buffer.from(value, "base64").toString("hex");
+  }
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    return Buffer.from(value).toString("hex");
+  }
+  return String(value);
+}
+function nanoToMs(nano) {
+  if (typeof nano === "string") {
+    return Number(BigInt(nano) / BigInt(1e6));
+  }
+  if (typeof nano === "number") return nano / 1e6;
+  return 0;
+}
+function toNumber(value) {
+  if (value == null) return 0;
+  const n = Number(value);
+  return isNaN(n) ? 0 : n;
+}
+function toFloat(value) {
+  if (value == null) return 0;
+  const n = parseFloat(String(value));
+  return isNaN(n) ? 0 : n;
+}
+
+// src/server/index.ts
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname(__filename);
+var { values } = parseArgs({
+  options: {
+    port: { type: "string", default: "4318" },
+    "no-open": { type: "boolean", default: false }
+  },
+  strict: false
+});
+var port = parseInt(values.port || "4318", 10);
+var app = express();
+var server = createServer(app);
+var wss = new WebSocketServer({ server, path: "/ws" });
+app.use("/v1", express.raw({ type: "*/*", limit: "10mb" }));
+app.post("/v1/traces", (req, res) => {
+  try {
+    const contentType = req.headers["content-type"] || "";
+    const body = contentType.includes("application/json") ? JSON.parse(req.body.toString()) : req.body;
+    const spans = handleTraces(body, contentType);
+    if (spans.length > 0) {
+      broadcast({ type: "spans", data: spans });
+    }
+  } catch (err) {
+    console.error("Error processing traces:", err);
+  }
+  res.status(200).json({});
+});
+app.post("/v1/metrics", (_req, res) => {
+  res.status(200).json({});
+});
+var clientDir = join(__dirname, "..", "client");
+if (existsSync(join(clientDir, "assets"))) {
+  app.use(express.static(clientDir));
+  app.get("*", (_req, res) => {
+    res.sendFile(join(clientDir, "index.html"));
+  });
+}
+wss.on("connection", (ws) => {
+  ws.send(JSON.stringify({ type: "init", data: store.getAll() }));
+});
+function broadcast(data) {
+  const message = JSON.stringify(data);
+  wss.clients.forEach((client) => {
+    if (client.readyState === WebSocket.OPEN) {
+      client.send(message);
+    }
+  });
+}
+server.on("error", (err) => {
+  if (err.code === "EADDRINUSE") {
+    console.error(
+      `
+Port ${port} is already in use. Try: npx tokviz --port <other-port>
+`
+    );
+    process.exit(1);
+  }
+  throw err;
+});
+server.listen(port, () => {
+  console.log(`
+  tokviz running at http://localhost:${port}
+`);
+  console.log(`  OTLP endpoint: http://localhost:${port}/v1/traces`);
+  console.log(`  Set OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:${port}
+`);
+  if (!values["no-open"]) {
+    open(`http://localhost:${port}`);
+  }
+});

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "tokviz",
+  "version": "0.1.0",
+  "description": "Real-time, local-only web dashboard that visualizes LLM token usage and costs from standard OpenTelemetry data",
+  "type": "module",
+  "bin": {
+    "tokviz": "dist/server/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "concurrently -n server,client \"tsx watch src/server/index.ts --no-open\" \"vite\"",
+    "dev:server": "tsx watch src/server/index.ts --no-open",
+    "dev:client": "vite",
+    "build": "npm run build:client && npm run build:server",
+    "build:client": "vite build",
+    "build:server": "tsup",
+    "start": "node dist/server/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "opentelemetry",
+    "otlp",
+    "llm",
+    "tokens",
+    "cost",
+    "dashboard",
+    "gen-ai",
+    "observability"
+  ],
+  "author": "Waldek Mastykarz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/waldekmastykarz/tokviz.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "express": "^4.21.2",
+    "open": "^10.1.0",
+    "protobufjs": "^7.4.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@types/ws": "^8.5.13",
+    "@vitejs/plugin-react": "^4.3.4",
+    "concurrently": "^9.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "recharts": "^2.15.0",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0"
+  }
+}