@kitlangton/motel 0.2.0 → 0.2.4

package/src/motelClient.ts

@@ -13,6 +13,7 @@ export class MotelHttpError extends Error {
 
 type QueryValue = string | number | boolean | null | undefined
 type Query = Readonly<Record<string, QueryValue>>
+type AttributeFilters = Readonly<Record<string, string>>
 
 const appendQuery = (url: URL, query: Query | undefined) => {
 	if (!query) return url
@@ -23,14 +24,20 @@ const appendQuery = (url: URL, query: Query | undefined) => {
 	return url
 }
 
-const appendAttributes = (url: URL, attributes: Readonly<Record<string, string>> | undefined) => {
+const appendAttributes = (url: URL, prefix: "attr" | "attrContains", attributes: AttributeFilters | undefined) => {
 	if (!attributes) return url
 	for (const [key, value] of Object.entries(attributes)) {
-		url.searchParams.set(`attr.${key}`, value)
+		url.searchParams.set(`${prefix}.${key}`, value)
 	}
 	return url
 }
 
+const appendAllAttributes = (
+	url: URL,
+	attributes: AttributeFilters | undefined,
+	attributeContains: AttributeFilters | undefined,
+) => appendAttributes(appendAttributes(url, "attr", attributes), "attrContains", attributeContains)
+
 export type SearchTracesInput = {
 	readonly service?: string
 	readonly operation?: string
@@ -39,18 +46,33 @@ export type SearchTracesInput = {
 	readonly lookback?: string
 	readonly limit?: number
 	readonly cursor?: string
-	readonly attributes?: Readonly<Record<string, string>>
+	readonly attributes?: AttributeFilters
+	readonly attributeContains?: AttributeFilters
+}
+
+export type SearchSpansInput = {
+	readonly service?: string
+	readonly traceId?: string
+	readonly operation?: string
+	readonly parentOperation?: string
+	readonly status?: "ok" | "error"
+	readonly lookback?: string
+	readonly limit?: number
+	readonly attributes?: AttributeFilters
+	readonly attributeContains?: AttributeFilters
 }
 
 export type SearchLogsInput = {
 	readonly service?: string
+	readonly severity?: string
 	readonly traceId?: string
 	readonly spanId?: string
 	readonly body?: string
 	readonly lookback?: string
 	readonly limit?: number
 	readonly cursor?: string
-	readonly attributes?: Readonly<Record<string, string>>
+	readonly attributes?: AttributeFilters
+	readonly attributeContains?: AttributeFilters
 }
 
 export type TraceStatsInput = {
@@ -62,7 +84,7 @@ export type TraceStatsInput = {
 	readonly minDurationMs?: number
 	readonly lookback?: string
 	readonly limit?: number
-	readonly attributes?: Readonly<Record<string, string>>
+	readonly attributes?: AttributeFilters
 }
 
 export type LogStatsInput = {
@@ -73,32 +95,77 @@ export type LogStatsInput = {
 	readonly body?: string
 	readonly lookback?: string
 	readonly limit?: number
-	readonly attributes?: Readonly<Record<string, string>>
+	readonly attributes?: AttributeFilters
 }
 
 export type FacetsInput = {
 	readonly type: "traces" | "logs"
 	readonly field: string
+	readonly key?: string
 	readonly service?: string
 	readonly lookback?: string
 	readonly limit?: number
 }
 
+export type TraceLogOptions = {
+	readonly lookback?: string
+	readonly limit?: number
+	readonly cursor?: string
+}
+
+export type AiCallSearchInput = {
+	readonly service?: string
+	readonly traceId?: string
+	readonly sessionId?: string
+	readonly functionId?: string
+	readonly provider?: string
+	readonly model?: string
+	readonly operation?: string
+	readonly status?: "ok" | "error"
+	readonly minDurationMs?: number
+	readonly text?: string
+	readonly lookback?: string
+	readonly limit?: number
+}
+
+export type AiCallStatsInput = {
+	readonly groupBy: "provider" | "model" | "functionId" | "sessionId" | "status"
+	readonly agg: "count" | "avg_duration" | "p95_duration" | "total_input_tokens" | "total_output_tokens"
+	readonly service?: string
+	readonly traceId?: string
+	readonly sessionId?: string
+	readonly functionId?: string
+	readonly provider?: string
+	readonly model?: string
+	readonly operation?: string
+	readonly status?: "ok" | "error"
+	readonly minDurationMs?: number
+	readonly lookback?: string
+	readonly limit?: number
+}
+
 export class MotelClient extends Context.Service<
 	MotelClient,
 	{
 		readonly searchTraces: (input: SearchTracesInput) => Effect.Effect<unknown, MotelHttpError>
+		readonly searchSpans: (input: SearchSpansInput) => Effect.Effect<unknown, MotelHttpError>
 		readonly getTrace: (traceId: string) => Effect.Effect<unknown, MotelHttpError>
-		readonly getTraceLogs: (
-			traceId: string,
-			options: { readonly lookback?: string; readonly limit?: number; readonly cursor?: string },
-		) => Effect.Effect<unknown, MotelHttpError>
+		readonly getTraceSpans: (traceId: string) => Effect.Effect<unknown, MotelHttpError>
+		readonly getTraceLogs: (traceId: string, options: TraceLogOptions) => Effect.Effect<unknown, MotelHttpError>
+		readonly getSpan: (spanId: string) => Effect.Effect<unknown, MotelHttpError>
+		readonly getSpanLogs: (spanId: string, options: TraceLogOptions) => Effect.Effect<unknown, MotelHttpError>
 		readonly searchLogs: (input: SearchLogsInput) => Effect.Effect<unknown, MotelHttpError>
+		readonly searchAiCalls: (input: AiCallSearchInput) => Effect.Effect<unknown, MotelHttpError>
+		readonly getAiCall: (spanId: string) => Effect.Effect<unknown, MotelHttpError>
+		readonly aiCallStats: (input: AiCallStatsInput) => Effect.Effect<unknown, MotelHttpError>
 		readonly traceStats: (input: TraceStatsInput) => Effect.Effect<unknown, MotelHttpError>
 		readonly logStats: (input: LogStatsInput) => Effect.Effect<unknown, MotelHttpError>
 		readonly facets: (input: FacetsInput) => Effect.Effect<unknown, MotelHttpError>
 		readonly services: Effect.Effect<unknown, MotelHttpError>
 		readonly health: Effect.Effect<unknown, MotelHttpError>
+		readonly docs: Effect.Effect<unknown, MotelHttpError>
+		readonly getDoc: (name: string) => Effect.Effect<string, MotelHttpError>
+		readonly openapi: Effect.Effect<unknown, MotelHttpError>
 	}
 >()("motel/MotelClient") {}
 
@@ -107,13 +174,18 @@ export const MotelClientLive = Layer.effect(
 	Effect.gen(function* () {
 		const locator = yield* Locator
 
-		const get = <A = unknown>(path: string, query?: Query, attributes?: Readonly<Record<string, string>>) =>
+		const get = <A = unknown>(
+			path: string,
+			query?: Query,
+			attributes?: AttributeFilters,
+			attributeContains?: AttributeFilters,
+		) =>
 			Effect.gen(function* () {
 				const { url } = yield* Effect.mapError(
 					locator.resolve,
 					(err) => new MotelHttpError(0, err.message),
 				)
-				const target = appendAttributes(appendQuery(new URL(path, url), query), attributes)
+				const target = appendAllAttributes(appendQuery(new URL(path, url), query), attributes, attributeContains)
 				return yield* Effect.tryPromise({
 					try: async () => {
 						const res = await fetch(target, { signal: AbortSignal.timeout(5000) })
@@ -138,10 +210,23 @@ export const MotelClientLive = Layer.effect(
 					lookback: input.lookback,
 					limit: input.limit,
 					cursor: input.cursor,
-				}, input.attributes),
+				}, input.attributes, input.attributeContains),
+
+			searchSpans: (input) =>
+				get("/api/spans/search", {
+					service: input.service,
+					traceId: input.traceId,
+					operation: input.operation,
+					parentOperation: input.parentOperation,
+					status: input.status,
+					lookback: input.lookback,
+					limit: input.limit,
+				}, input.attributes, input.attributeContains),
 
 			getTrace: (traceId) => get(`/api/traces/${encodeURIComponent(traceId)}`),
 
+			getTraceSpans: (traceId) => get(`/api/traces/${encodeURIComponent(traceId)}/spans`),
+
 			getTraceLogs: (traceId, options) =>
 				get(`/api/traces/${encodeURIComponent(traceId)}/logs`, {
 					lookback: options.lookback,
@@ -149,16 +234,61 @@ export const MotelClientLive = Layer.effect(
 					cursor: options.cursor,
 				}),
 
+			getSpan: (spanId) => get(`/api/spans/${encodeURIComponent(spanId)}`),
+
+			getSpanLogs: (spanId, options) =>
+				get(`/api/spans/${encodeURIComponent(spanId)}/logs`, {
+					lookback: options.lookback,
+					limit: options.limit,
+					cursor: options.cursor,
+				}),
+
 			searchLogs: (input) =>
 				get("/api/logs/search", {
 					service: input.service,
+					severity: input.severity,
 					traceId: input.traceId,
 					spanId: input.spanId,
 					body: input.body,
 					lookback: input.lookback,
 					limit: input.limit,
 					cursor: input.cursor,
-				}, input.attributes),
+				}, input.attributes, input.attributeContains),
+
+			searchAiCalls: (input) =>
+				get("/api/ai/calls", {
+					service: input.service,
+					traceId: input.traceId,
+					sessionId: input.sessionId,
+					functionId: input.functionId,
+					provider: input.provider,
+					model: input.model,
+					operation: input.operation,
+					status: input.status,
+					minDurationMs: input.minDurationMs,
+					text: input.text,
+					lookback: input.lookback,
+					limit: input.limit,
+				}),
+
+			getAiCall: (spanId) => get(`/api/ai/calls/${encodeURIComponent(spanId)}`),
+
+			aiCallStats: (input) =>
+				get("/api/ai/stats", {
+					groupBy: input.groupBy,
+					agg: input.agg,
+					service: input.service,
+					traceId: input.traceId,
+					sessionId: input.sessionId,
+					functionId: input.functionId,
+					provider: input.provider,
+					model: input.model,
+					operation: input.operation,
+					status: input.status,
+					minDurationMs: input.minDurationMs,
+					lookback: input.lookback,
+					limit: input.limit,
+				}),
 
 			traceStats: (input) =>
 				get("/api/traces/stats", {
@@ -188,6 +318,7 @@ export const MotelClientLive = Layer.effect(
 				get("/api/facets", {
 					type: input.type,
 					field: input.field,
+					key: input.key,
 					service: input.service,
 					lookback: input.lookback,
 					limit: input.limit,
@@ -196,6 +327,27 @@ export const MotelClientLive = Layer.effect(
 			services: get("/api/services"),
 
 			health: get("/api/health"),
+
+			docs: get("/api/docs"),
+
+			getDoc: (name) =>
+				Effect.gen(function* () {
+					const { url } = yield* Effect.mapError(locator.resolve, (err) => new MotelHttpError(0, err.message))
+					return yield* Effect.tryPromise({
+						try: async () => {
+							const res = await fetch(new URL(`/api/docs/${encodeURIComponent(name)}`, url), {
+								signal: AbortSignal.timeout(5000),
+							})
+							const body = await res.text()
+							if (!res.ok) throw new MotelHttpError(res.status, body)
+							return body
+						},
+						catch: (err) =>
+							err instanceof MotelHttpError ? err : new MotelHttpError(0, (err as Error).message),
+					}).pipe(Effect.tapError((err) => (err.status === 0 ? locator.invalidate : Effect.void)))
+				}),
+
+			openapi: get("/openapi.json"),
 		}
 	}),
 )

package/src/registry.ts

@@ -16,23 +16,18 @@ export type RegistryEntry = {
 	readonly workdir: string
 	readonly startedAt: string
 	readonly version: string
+	/**
+	 * The SQLite database path the daemon is serving. Optional because
+	 * older daemon builds omit it; consumers should treat a missing
+	 * value as "unknown" and fall back to whatever validation path
+	 * they would have used before this field existed (typically an
+	 * HTTP /api/health probe).
+	 */
+	readonly databasePath?: string
 }
 
 const entryPath = (pid: number) => path.join(registryDir(), `${pid}.json`)
 
-let currentEntryPath: string | null = null
-let signalHandlersRegistered = false
-
-const cleanup = () => {
-	if (!currentEntryPath) return
-	try {
-		fs.unlinkSync(currentEntryPath)
-	} catch {
-		// already gone — ignore
-	}
-	currentEntryPath = null
-}
-
 export const isAlive = (pid: number): boolean => {
 	try {
 		process.kill(pid, 0)
@@ -72,15 +67,23 @@ export const writeRegistryEntry = (entry: RegistryEntry) => {
 	fs.mkdirSync(registryDir(), { recursive: true })
 	const file = entryPath(entry.pid)
 	fs.writeFileSync(file, JSON.stringify(entry, null, 2), "utf8")
-	currentEntryPath = file
-	if (!signalHandlersRegistered) {
-		signalHandlersRegistered = true
-		process.on("exit", cleanup)
-		for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
-			process.on(sig, () => {
-				cleanup()
-				process.exit(0)
-			})
-		}
+}
+
+/**
+ * Remove this daemon's registry entry. Intended to be called from a
+ * Layer release so the scope-managed server shutdown removes the entry
+ * in the same finalizer chain that stops the socket. Historically this
+ * was done via ad-hoc process-signal handlers installed here that ran
+ * `process.exit(0)` — which races with the Effect runtime's own SIGINT
+ * handling and short-circuits the Bun server's graceful stop. The
+ * server (via BunRuntime.runMain) now owns signal handling; registry
+ * cleanup rides along on scope release.
+ */
+export const removeRegistryEntry = (pid: number) => {
+	try {
+		fs.unlinkSync(entryPath(pid))
+	} catch {
+		// Already gone — another cleanup path won the race, or the entry
+		// was never written.
 	}
 }

package/src/runtime.ts

@@ -6,7 +6,7 @@ import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base"
 import { Layer, ManagedRuntime } from "effect"
 import { config } from "./config.js"
 import { LogQueryServiceLive } from "./services/LogQueryService.js"
-import { TelemetryStoreLive } from "./services/TelemetryStore.js"
+import { TelemetryStoreLive, TelemetryStoreReadonlyLive } from "./services/TelemetryStore.js"
 import { TraceQueryServiceLive } from "./services/TraceQueryService.js"
 
 const telemetryLayer = NodeSdk.layer(() => ({
@@ -30,9 +30,15 @@ const telemetryLayer = NodeSdk.layer(() => ({
 	},
 }))
 
-const QueryServicesLive = Layer.mergeAll(TraceQueryServiceLive, LogQueryServiceLive).pipe(Layer.provideMerge(TelemetryStoreLive))
+// TUI-side services are readonly — a daemon/worker writer owns the DB
+// lock while ingests are in flight, and trying to grab the write lock
+// for schema init on startup causes "database is locked" on bun dev.
+const QueryServicesLive = Layer.mergeAll(TraceQueryServiceLive, LogQueryServiceLive).pipe(Layer.provideMerge(TelemetryStoreReadonlyLive))
 
 const QueryRuntimeLive = config.otel.enabled ? Layer.mergeAll(QueryServicesLive, telemetryLayer) : QueryServicesLive
 
 export const queryRuntime = ManagedRuntime.make(QueryRuntimeLive)
+// `storeRuntime` is the full writer runtime, exposed for the telemetry
+// test suite (and any future tooling that needs the ingest side). The
+// TUI itself only consumes `queryRuntime`, which is readonly.
 export const storeRuntime = ManagedRuntime.make(TelemetryStoreLive)

package/src/server.ts

@@ -1,10 +1,11 @@
-import { config } from "./config.js"
-import { startLocalServer } from "./localServer.js"
+import { BunRuntime } from "@effect/platform-bun"
+import { Layer } from "effect"
+import { ServerLive } from "./localServer.js"
 
-await startLocalServer()
-
-console.log(`motel local telemetry server listening on ${config.otel.queryUrl}`)
-
-await new Promise(() => {
-	// keep process alive
-})
+// `BunRuntime.runMain` installs signal handlers that interrupt the root
+// fiber on SIGINT/SIGTERM; `Layer.launch` holds the scope open until
+// then. On interruption the scope closes top-down: RegistryLayer's
+// release removes the daemon's registry entry, BunHttpServer's release
+// calls server.stop(), SQLite connections close — all through layer
+// finalizers instead of ad-hoc process.exit handlers.
+Layer.launch(ServerLive).pipe(BunRuntime.runMain)

package/src/services/AsyncIngest.ts

@@ -0,0 +1,68 @@
+/**
+ * Main-thread client for the telemetry worker's ingest RPCs.
+ *
+ * The HTTP handlers for POST /v1/traces and POST /v1/logs call into
+ * this service instead of `TelemetryStore.ingestTraces/Logs`. Each
+ * method sends a typed message to the worker, awaits the reply, and
+ * returns the worker's result as an Effect. While the worker is
+ * serialising a big batch into SQLite, the main thread's event loop
+ * is FREE to answer /api/* queries — that's the whole point of the
+ * offload. Without this, /api/health and friends queued behind long
+ * ingests and reported p95 latencies of 3-5 seconds; after, they
+ * stay responsive regardless of ingest load.
+ *
+ * The worker is spawned as a scope'd resource inside the layer. The
+ * protocol pool is sized at 1 because SQLite only supports a single
+ * writer at a time anyway — running N concurrent workers would just
+ * queue them on SQLite's lock. When the outer scope closes (server
+ * shutdown), `BunWorker.layer`'s finalizer sends a close message and
+ * terminates the worker if it doesn't exit gracefully in 5s.
+ */
+
+import * as BunWorker from "@effect/platform-bun/BunWorker"
+import { Context, Effect, Layer, Scope } from "effect"
+import * as RpcClient from "effect/unstable/rpc/RpcClient"
+import type { RpcClientError } from "effect/unstable/rpc/RpcClientError"
+import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization"
+import type { WorkerError } from "effect/unstable/workers/WorkerError"
+import { IngestRpcs } from "./ingestRpc.ts"
+
+// RpcClient.make always surfaces RpcClientError in addition to the
+// group's declared errors (transport failures, worker crashes, etc.),
+// so the service shape has to mirror that. Without the explicit error
+// type param, TS treats the declared and observed client types as
+// unrelated structural mismatches.
+export class AsyncIngest extends Context.Service<
+	AsyncIngest,
+	RpcClient.FromGroup<typeof IngestRpcs, RpcClientError | WorkerError>
+>()("@motel/AsyncIngest") {}
+
+// Protocol: RpcClient.layerProtocolWorker manages a worker pool and
+// speaks msgpack over structured-clone messages. `size: 1` matches
+// SQLite's single-writer constraint.
+const WorkerProtocol = RpcClient.layerProtocolWorker({ size: 1 }).pipe(
+	Layer.provide(RpcSerialization.layerMsgPack),
+	Layer.provide(
+		BunWorker.layer(() => new Worker(new URL("./telemetryWorker.ts", import.meta.url))),
+	),
+)
+
+export const AsyncIngestLive = Layer.effect(
+	AsyncIngest,
+	Effect.gen(function*() {
+		const scope = yield* Scope.Scope
+		// Keep daemon startup cheap: creating the RPC client here would eagerly
+		// spawn the worker and make /api/health wait on the worker's SQLite
+		// bootstrap. Cache a lazy initializer instead so the worker only starts
+		// on the first ingest request, but is still shared thereafter.
+		const getClient = yield* RpcClient.make(IngestRpcs).pipe(
+			Effect.provide(WorkerProtocol),
+			Effect.cached,
+		)
+		const withScope = <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.provideService(effect, Scope.Scope, scope)
+		return {
+			ingestTraces: (input, options) => Effect.flatMap(withScope(getClient), (client) => client.ingestTraces(input, options)),
+			ingestLogs: (input, options) => Effect.flatMap(withScope(getClient), (client) => client.ingestLogs(input, options)),
+		}
+	}),
+)