otelly 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Darna Digital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# otelly
+
+Local OpenTelemetry inspector. One command, one port, no infrastructure.
+
+```bash
+npx otelly
+```
+
+Boots an OTLP/HTTP collector + a dashboard on `http://localhost:4319`, stores
+spans in `./otelly.sqlite`, opens your browser. Like `drizzle-kit studio` —
+for traces.
+
+## Use it
+
+Point any OpenTelemetry SDK at `http://localhost:4319` (the **base URL** —
+the SDK appends `/v1/traces` itself):
+
+```ts
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+
+new NodeSDK({
+  serviceName: "my-app",
+  traceExporter: new OTLPTraceExporter({
+    url: "http://localhost:4319/v1/traces",
+  }),
+}).start();
+```
+
+Or `curl` a hand-crafted OTLP payload:
+
+```bash
+curl -X POST http://localhost:4319/v1/traces \
+  -H 'content-type: application/json' \
+  -d '{"resourceSpans":[{"resource":{"attributes":[
+    {"key":"service.name","value":{"stringValue":"demo"}}]},
+    "scopeSpans":[{"spans":[{
+      "traceId":"00000000000000000000000000000001",
+      "spanId":"0000000000000001","name":"hello","kind":1,
+      "startTimeUnixNano":"1700000000000000000",
+      "endTimeUnixNano":"1700000000005000000",
+      "status":{"code":1}}]}]}]}'
+```
+
+Refresh the browser — span shows up.
+
+## Options
+
+```
+otelly                       # all defaults
+otelly --port 4500           # different port
+otelly --db ./traces.sqlite  # different SQLite file
+otelly --no-open             # skip browser auto-open
+otelly -h                    # full help
+```
+
+All flags are also env vars (`OTELLY_PORT`, `OTELLY_DB`).
+
+## API
+
+- `POST /v1/traces` — OTLP/HTTP JSON ingest
+- `GET /api/spans?limit=200` — recent spans
+- `GET /api/traces/:id` — all spans for one trace
+- `GET /health` — health probe
+- `GET /openapi` — OpenAPI spec
+- `GET /` — dashboard UI
+
+## What this isn't
+
+The CLI is for **local development inspection** — one user, one machine,
+one project. For team observability or multi-tenant deployments, see
+[self-hosting docs](https://github.com/Darna-Digital/otelly#self-host).
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { setTimeout } from "node:timers/promises";
+
+//#region src/args.ts
+const HELP = `otelly — local OpenTelemetry inspector
+
+USAGE
+  otelly [command] [options]
+
+COMMANDS
+  dev      (default) start the UI + server with hot reload
+  start    start the UI + server in production mode (requires build)
+
+OPTIONS
+  --port <number>      UI port (default 4319)
+  --api-port <number>  OTLP + /api/* port (default 4318)
+  --db <path>          SQLite file path (default ./otelly.sqlite)
+  --no-open            do not open the UI in a browser
+  -h, --help           show this help
+
+ENV
+  OTELLY_DB            same as --db
+  OTELLY_PORT          same as --port
+  OTELLY_API_PORT      same as --api-port
+
+EXAMPLES
+  otelly
+  otelly --port 4000 --api-port 4001 --db ./traces.sqlite
+`;
+const parseInt10 = (s) => {
+	const n = Number(s);
+	if (!Number.isInteger(n) || n <= 0) return null;
+	return n;
+};
+const parseArgs = (argv) => {
+	let command = "dev";
+	let port = 4319;
+	let apiPort = 4318;
+	let dbPath;
+	let open = true;
+	let showHelp = false;
+	const positional = [];
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === void 0) continue;
+		if (arg === "-h" || arg === "--help") {
+			showHelp = true;
+			continue;
+		}
+		if (arg === "--port") {
+			const next = argv[i + 1];
+			if (next === void 0) return { error: "--port requires a value" };
+			const n = parseInt10(next);
+			if (n === null) return { error: `invalid --port: ${next}` };
+			port = n;
+			i += 1;
+			continue;
+		}
+		if (arg.startsWith("--port=")) {
+			const n = parseInt10(arg.slice(7));
+			if (n === null) return { error: `invalid --port: ${arg}` };
+			port = n;
+			continue;
+		}
+		if (arg === "--api-port") {
+			const next = argv[i + 1];
+			if (next === void 0) return { error: "--api-port requires a value" };
+			const n = parseInt10(next);
+			if (n === null) return { error: `invalid --api-port: ${next}` };
+			apiPort = n;
+			i += 1;
+			continue;
+		}
+		if (arg.startsWith("--api-port=")) {
+			const n = parseInt10(arg.slice(11));
+			if (n === null) return { error: `invalid --api-port: ${arg}` };
+			apiPort = n;
+			continue;
+		}
+		if (arg === "--db") {
+			const next = argv[i + 1];
+			if (next === void 0) return { error: "--db requires a value" };
+			dbPath = next;
+			i += 1;
+			continue;
+		}
+		if (arg.startsWith("--db=")) {
+			dbPath = arg.slice(5);
+			continue;
+		}
+		if (arg === "--no-open") {
+			open = false;
+			continue;
+		}
+		if (arg === "--open") {
+			open = true;
+			continue;
+		}
+		if (arg.startsWith("--")) return { error: `unknown option: ${arg}` };
+		positional.push(arg);
+	}
+	const envPort = process.env.OTELLY_PORT;
+	if (envPort !== void 0) {
+		const n = parseInt10(envPort);
+		if (n !== null) port = n;
+	}
+	const envApiPort = process.env.OTELLY_API_PORT;
+	if (envApiPort !== void 0) {
+		const n = parseInt10(envApiPort);
+		if (n !== null) apiPort = n;
+	}
+	if (dbPath === void 0 && process.env.OTELLY_DB) dbPath = process.env.OTELLY_DB;
+	if (positional.length > 0) {
+		const cmd = positional[0];
+		if (cmd === "dev" || cmd === "start") command = cmd;
+		else return { error: `unknown command: ${cmd}` };
+	}
+	return {
+		command,
+		port,
+		apiPort,
+		dbPath,
+		open,
+		showHelp
+	};
+};
+const helpText = HELP;
+
+//#endregion
+//#region src/cli.ts
+const here = path.dirname(fileURLToPath(import.meta.url));
+const resolveDbPath = (override) => {
+	if (override !== void 0) return path.resolve(override);
+	return path.resolve(process.cwd(), "otelly.sqlite");
+};
+const resolveStaticDir = () => {
+	const bundled = path.join(here, "static");
+	if (existsSync(bundled)) return bundled;
+	const source = path.resolve(here, "../../local/out");
+	if (existsSync(source)) return source;
+	throw new Error("otelly: static UI not found. Did you run `pnpm build` in apps/cli?");
+};
+const resolveServerPath = () => {
+	const bundled = path.join(here, "server.js");
+	if (existsSync(bundled)) return bundled;
+	throw new Error("otelly: server bundle not found. Did you run `pnpm build` in apps/cli?");
+};
+const waitForReady = async (url, timeoutMs = 3e4) => {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		try {
+			if ((await fetch(url, { method: "GET" })).status < 500) return true;
+		} catch {}
+		await setTimeout(200);
+	}
+	return false;
+};
+const openBrowser = (url) => {
+	const platform = process.platform;
+	const [cmd, args] = platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", [
+		"/c",
+		"start",
+		"",
+		url
+	]] : ["xdg-open", [url]];
+	const child = spawn(cmd, [...args], {
+		stdio: "ignore",
+		detached: true
+	});
+	child.on("error", () => {
+		process.stderr.write(`otelly: could not open browser (${cmd}). Visit ${url} manually.\n`);
+	});
+	child.unref();
+};
+const main = async () => {
+	const parsed = parseArgs(process.argv.slice(2));
+	if ("error" in parsed) {
+		process.stderr.write(`otelly: ${parsed.error}\n\n${helpText}`);
+		process.exit(2);
+	}
+	if (parsed.showHelp) {
+		process.stdout.write(helpText);
+		return;
+	}
+	const dbPath = resolveDbPath(parsed.dbPath);
+	const staticDir = resolveStaticDir();
+	const serverPath = resolveServerPath();
+	const url = `http://localhost:${parsed.port}/`;
+	process.stdout.write(`otelly · ${url} · db=${dbPath}\n`);
+	const env = {
+		...process.env,
+		OTELLY_MODE: "embedded",
+		OTELLY_DB: dbPath,
+		OTELLY_STATIC_DIR: staticDir,
+		PORT: String(parsed.port)
+	};
+	const child = spawn("node", [serverPath], {
+		env,
+		stdio: "inherit"
+	});
+	let shuttingDown = false;
+	const shutdown = (signal) => {
+		if (shuttingDown) return;
+		shuttingDown = true;
+		if (!child.killed) child.kill(signal);
+	};
+	process.on("SIGINT", () => shutdown("SIGINT"));
+	process.on("SIGTERM", () => shutdown("SIGTERM"));
+	child.on("exit", (code, signal) => {
+		if (signal) process.kill(process.pid, signal);
+		else process.exit(code ?? 0);
+	});
+	if (parsed.open) waitForReady(url).then((ready) => {
+		if (ready && !shuttingDown) openBrowser(url);
+	});
+};
+await main();
+
+//#endregion
+export {  };