convex-tracer 0.1.0

package/src/component/lib.ts

@@ -0,0 +1,399 @@
+/**
+ * Internal mutations for managing traces, spans, and logs.
+ * These are called automatically by the tracing system to persist data immediately.
+ */
+import { v } from "convex/values";
+import type { Id } from "./_generated/dataModel.js";
+import { mutation, query, type MutationCtx } from "./_generated/server.js";
+import schema, {
+  severityValidator,
+  sourceValidator,
+  statusValidator,
+} from "./schema.js";
+import { vCompleteTrace } from "./types.js";
+
+// ============================================================================
+// Trace Operations
+// ============================================================================
+
+/**
+ * Creates a new trace in the database.
+ * Called automatically when a traced function is invoked without an existing trace context.
+ */
+export const createTrace = mutation({
+  args: {
+    status: statusValidator,
+    sampleRate: v.number(),
+    metadata: v.optional(v.record(v.string(), v.any())),
+    source: sourceValidator,
+  },
+  returns: v.id("traces"),
+  handler: async (ctx, args): Promise<Id<"traces">> => {
+    return await ctx.db.insert("traces", {
+      status: args.status,
+      sampleRate: args.sampleRate,
+      updatedAt: Date.now(),
+      metadata: args.metadata,
+    });
+  },
+});
+
+/**
+ * Updates the status of an existing trace.
+ * Called when a root traced function completes or errors.
+ */
+export const updateTraceStatus = mutation({
+  args: {
+    traceId: v.string(),
+    status: statusValidator,
+  },
+  returns: v.null(),
+  handler: async (ctx, args): Promise<void> => {
+    await ctx.db.patch("traces", args.traceId as Id<"traces">, {
+      status: args.status,
+      updatedAt: Date.now(),
+    });
+  },
+});
+
+/**
+ * Updates the preserve flag on a trace.
+ * Called when tracer.preserve(), tracer.discard(), or tracer.sample() is invoked.
+ */
+export const updateTracePreserve = mutation({
+  args: {
+    traceId: v.string(),
+    preserve: v.optional(v.boolean()),
+    sampleRate: v.optional(v.number()),
+  },
+  returns: v.null(),
+  handler: async (ctx, { sampleRate, traceId, preserve }): Promise<void> => {
+    const srUpdate = {} as any;
+    if (sampleRate) srUpdate.sampleRate = sampleRate;
+
+    await ctx.db.patch("traces", traceId as Id<"traces">, {
+      preserve: preserve,
+      updatedAt: Date.now(),
+      ...srUpdate,
+    });
+  },
+});
+
+/**
+ * Updates the trace metadata.
+ * Called when tracer.setMetadata() is invoked.
+ */
+export const updateTraceMetadata = mutation({
+  args: {
+    traceId: v.string(),
+    metadata: v.record(v.string(), v.any()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args): Promise<void> => {
+    const trace = await ctx.db.get("traces", args.traceId as Id<"traces">);
+    if (!trace) throw new Error(`Trace not found: ${args.traceId}`);
+
+    await ctx.db.patch("traces", args.traceId as Id<"traces">, {
+      metadata: {
+        ...trace.metadata,
+        ...args.metadata,
+      },
+      updatedAt: Date.now(),
+    });
+  },
+});
+
+// ============================================================================
+// Span Operations
+// ============================================================================
+
+/**
+ * Creates a new span in the database.
+ * Called automatically when a traced function starts or when withSpan() is called.
+ */
+export const createSpan = mutation({
+  args: {
+    traceId: v.string(),
+    span: v.object({
+      parentSpanId: v.optional(v.string()),
+      spanName: v.string(),
+      source: sourceValidator,
+      startTime: v.number(),
+      status: statusValidator,
+      functionName: v.optional(v.string()),
+      args: v.optional(v.any()),
+    }),
+  },
+  returns: v.id("spans"),
+  handler: async (ctx, args): Promise<Id<"spans">> => {
+    return await ctx.db.insert("spans", {
+      ...args.span,
+      traceId: args.traceId as Id<"traces">,
+      parentSpanId: args.span.parentSpanId
+        ? (args.span.parentSpanId as Id<"spans">)
+        : undefined,
+    });
+  },
+});
+
+/**
+ * Completes a span by updating its end time, duration, status, and optional result/error.
+ * Called automatically when a traced function completes or when withSpan() finishes.
+ */
+export const completeSpan = mutation({
+  args: {
+    spanId: v.string(),
+    endTime: v.number(),
+    duration: v.number(),
+    status: v.union(v.literal("success"), v.literal("error")),
+    result: v.optional(v.any()),
+    error: v.optional(v.string()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args): Promise<void> => {
+    await ctx.db.patch("spans", args.spanId as Id<"spans">, {
+      endTime: args.endTime,
+      duration: args.duration,
+      status: args.status,
+      result: args.result,
+      error: args.error,
+    });
+  },
+});
+
+/**
+ * Updates the metadata of a span.
+ * Called when span.setMetadata() is invoked within withSpan().
+ */
+export const updateSpanMetadata = mutation({
+  args: {
+    spanId: v.string(),
+    metadata: v.record(v.string(), v.any()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args): Promise<void> => {
+    const span = await ctx.db.get("spans", args.spanId as Id<"spans">);
+    if (!span) throw new Error(`Span not found: ${args.spanId}`);
+
+    await ctx.db.patch(span._id, {
+      metadata: {
+        ...span.metadata,
+        ...args.metadata,
+      },
+    });
+  },
+});
+
+// ============================================================================
+// Log Operations
+// ============================================================================
+
+/**
+ * Adds a log entry to a specific span.
+ * Called when tracer.info(), tracer.warn(), or tracer.error() is invoked.
+ */
+export const addLog = mutation({
+  args: {
+    spanId: v.string(),
+    log: v.object({
+      timestamp: v.number(),
+      severity: severityValidator,
+      message: v.string(),
+      metadata: v.optional(v.record(v.string(), v.any())),
+    }),
+  },
+  returns: v.id("logs"),
+  handler: async (ctx, args): Promise<Id<"logs">> => {
+    const span = await ctx.db.get("spans", args.spanId as Id<"spans">);
+    if (!span) throw new Error(`Span not found: ${args.spanId}`);
+
+    return await ctx.db.insert("logs", {
+      spanId: span._id,
+      ...args.log,
+    });
+  },
+});
+
+// ============================================================================
+// Query Operations
+// ============================================================================
+
+/**
+ * Verify trace exists
+ */
+export const verifyTrace = query({
+  args: { traceId: v.string() },
+  returns: v.boolean(),
+  handler: async (ctx, { traceId }) => {
+    const trace = await ctx.db.get("traces", traceId as Id<"traces">);
+    if (!trace) return false;
+
+    return true;
+  },
+});
+
+export const verifySpan = query({
+  args: { spanId: v.string() },
+  returns: v.boolean(),
+  handler: async (ctx, { spanId }) => {
+    const span = await ctx.db.get("spans", spanId as Id<"spans">);
+    if (!span) return false;
+
+    return true;
+  },
+});
+
+/**
+ * Retrieves a complete trace with all its spans and logs.
+ */
+export const getTrace = query({
+  args: { traceId: v.string() },
+  returns: v.union(v.null(), vCompleteTrace),
+  handler: async (ctx, { traceId }) => {
+    const trace = await ctx.db.get("traces", traceId as Id<"traces">);
+    if (!trace) return null;
+
+    const spans = await ctx.db
+      .query("spans")
+      .withIndex("by_traceId", (q) => q.eq("traceId", traceId as Id<"traces">))
+      .collect();
+
+    const spansWithLogs = await Promise.all(
+      spans.map(async (span) => ({
+        ...span,
+        children: [],
+        logs: await ctx.db
+          .query("logs")
+          .withIndex("by_spanId", (q) => q.eq("spanId", span._id))
+          .collect(),
+      })),
+    );
+
+    const spanMap = new Map(spansWithLogs.map((span) => [span._id, span]));
+
+    spansWithLogs.forEach((span) => {
+      if (span.parentSpanId) {
+        const parentSpan = spanMap.get(span.parentSpanId);
+        if (parentSpan) {
+          (parentSpan.children as any[]).push(span);
+        }
+      }
+    });
+
+    const sortSpanChildren = (span: (typeof spansWithLogs)[0]) => {
+      if (span.children.length > 0) {
+        (span.children as any[]).sort(
+          (a, b) => a._creationTime - b._creationTime,
+        );
+        span.children.forEach(sortSpanChildren);
+      }
+    };
+
+    const rootSpans = spansWithLogs
+      .filter((span) => !span.parentSpanId)
+      .sort((a, b) => a._creationTime - b._creationTime);
+
+    rootSpans.forEach(sortSpanChildren);
+
+    return { ...trace, spans: rootSpans };
+  },
+});
+
+/**
+ * Lists traces with optional filtering by status.
+ */
+export const listTraces = query({
+  args: {
+    status: v.optional(statusValidator),
+    limit: v.optional(v.number()),
+    userId: v.optional(v.string()),
+  },
+  returns: v.array(
+    schema.tables.traces.validator.extend({
+      _id: v.id("traces"),
+      _creationTime: v.number(),
+    }),
+  ),
+  handler: async (ctx, { status, limit, userId }) => {
+    const query =
+      status && !userId
+        ? ctx.db
+            .query("traces")
+            .withIndex("by_status", (q) => q.eq("status", status))
+        : !status && userId
+          ? ctx.db
+              .query("traces")
+              .withIndex("by_userId", (q) => q.eq("userId", userId))
+          : status && userId
+            ? ctx.db
+                .query("traces")
+                .withIndex("by_status_and_userId", (q) =>
+                  q.eq("status", status).eq("userId", userId),
+                )
+            : ctx.db.query("traces");
+
+    return await query.order("desc").take(limit ?? 100);
+  },
+});
+
+// ============================================================================
+// Cleanup Operations
+// ============================================================================
+
+/**
+ * Cleans up old traces based on retention policy and sampling.
+ * Should be called periodically by a Convex scheduler.
+ */
+export const cleanupTrace = mutation({
+  args: {
+    traceId: v.string(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const trace = await ctx.db.get("traces", args.traceId as Id<"traces">);
+
+    if (!trace) return;
+
+    // Always keep explicitly preserved traces
+    if (trace.preserve === true) return;
+
+    // Always delete explicitly discarded traces
+    if (trace.preserve === false) {
+      return await deleteTrace(ctx, trace._id);
+    }
+
+    // Apply sampling for undefined preserve status
+    const random = Math.random();
+    if (random >= trace.sampleRate) await deleteTrace(ctx, trace._id);
+  },
+});
+
+/**
+ * Deletes a trace and all its associated spans and logs.
+ */
+async function deleteTrace(
+  ctx: MutationCtx,
+  traceId: Id<"traces">,
+): Promise<void> {
+  const spans = await ctx.db
+    .query("spans")
+    .withIndex("by_traceId", (q) => q.eq("traceId", traceId))
+    .collect();
+
+  const logsRequest = spans.map((span) =>
+    ctx.db
+      .query("logs")
+      .withIndex("by_spanId", (q) => q.eq("spanId", span._id))
+      .collect(),
+  );
+
+  const logs = await Promise.all(logsRequest);
+
+  const deletionRequests = [
+    ...logs.flat().map((log) => ctx.db.delete(log._id)),
+    ...spans.map((span) => ctx.db.delete(span._id)),
+    ctx.db.delete(traceId),
+  ];
+
+  await Promise.all(deletionRequests);
+}

package/src/component/schema.ts

@@ -0,0 +1,62 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export const statusValidator = v.union(
+  v.literal("pending"),
+  v.literal("success"),
+  v.literal("error"),
+);
+
+export const sourceValidator = v.union(
+  v.literal("frontend"),
+  v.literal("backend"),
+);
+
+export const severityValidator = v.union(
+  v.literal("info"),
+  v.literal("warn"),
+  v.literal("error"),
+);
+
+export default defineSchema({
+  traces: defineTable({
+    status: statusValidator,
+    sampleRate: v.number(),
+    preserve: v.optional(v.boolean()),
+    updatedAt: v.number(),
+    metadata: v.optional(v.record(v.string(), v.any())),
+    userId: v.optional(v.string()),
+  })
+    .index("by_status", ["status"])
+    .index("by_userId", ["userId"])
+    .index("by_status_and_userId", ["status", "userId"]),
+
+  spans: defineTable({
+    traceId: v.id("traces"),
+    parentSpanId: v.optional(v.id("spans")),
+    spanName: v.string(),
+    source: sourceValidator,
+    startTime: v.number(),
+    endTime: v.optional(v.number()),
+    duration: v.optional(v.number()),
+    status: statusValidator,
+    functionName: v.optional(v.string()),
+    args: v.optional(v.any()),
+    result: v.optional(v.any()),
+    error: v.optional(v.string()),
+    metadata: v.optional(v.record(v.string(), v.any())),
+  })
+    .index("by_traceId", ["traceId"])
+    .index("by_parentSpanId", ["parentSpanId"])
+    .index("by_status", ["status"]),
+
+  logs: defineTable({
+    spanId: v.id("spans"),
+    timestamp: v.number(),
+    severity: severityValidator,
+    message: v.string(),
+    metadata: v.optional(v.record(v.string(), v.any())),
+  })
+    .index("by_spanId", ["spanId"])
+    .index("by_severity", ["severity"]),
+});

package/src/component/setup.test.ts

@@ -0,0 +1,11 @@
+/// <reference types="vite/client" />
+import { convexTest } from "convex-test";
+import { test } from "vitest";
+import schema from "./schema.js";
+export const modules = import.meta.glob("./**/*.*s");
+
+export function initConvexTest() {
+  const t = convexTest(schema, modules);
+  return t;
+}
+test("setup", () => {});

package/src/component/types.ts

@@ -0,0 +1,38 @@
+import { v, type Infer } from "convex/values";
+import schema from "./schema";
+
+export const vTrace = schema.tables.traces.validator.extend({
+  _id: v.string(),
+  _creationTime: v.number(),
+});
+
+export const vSpan = schema.tables.spans.validator
+  .omit("parentSpanId")
+  .omit("traceId")
+  .extend({
+    _id: v.string(),
+    traceId: v.string(),
+    parentSpanId: v.optional(v.string()),
+    _creationTime: v.number(),
+  });
+
+export const vLog = schema.tables.logs.validator.omit("spanId").extend({
+  _id: v.string(),
+  spanId: v.string(),
+  _creationTime: v.number(),
+});
+
+export const vSpanWithLogs = vSpan.extend({
+  logs: v.optional(v.array(vLog)),
+  children: v.optional(v.array(v.any())),
+});
+
+export const vCompleteTrace = vTrace.extend({
+  spans: v.array(vSpanWithLogs),
+});
+
+export type Trace = Infer<typeof vTrace>;
+export type Span = Infer<typeof vSpan>;
+export type Log = Infer<typeof vLog>;
+export type SpanWithLogs = Infer<typeof vSpanWithLogs>;
+export type CompleteTrace = Infer<typeof vCompleteTrace>;

package/src/react/index.ts

@@ -0,0 +1,36 @@
+import { useAction, useMutation } from "convex/react";
+
+import type { FunctionReference, FunctionReturnType } from "convex/server";
+import type { EmptyObject, OptionalTracedArgs } from "./types";
+
+export function useTracedQuery<TQuery extends FunctionReference<"mutation">>(
+  fnRef: TQuery,
+): OptionalTracedArgs<TQuery> extends [args?: EmptyObject]
+  ? (args?: EmptyObject) => Promise<FunctionReturnType<TQuery>>
+  : OptionalTracedArgs<TQuery> extends [args: infer Args]
+    ? (args: Args) => Promise<FunctionReturnType<TQuery>>
+    : never {
+  return useMutation(fnRef) as any;
+}
+
+export function useTracedMutation<
+  TMutation extends FunctionReference<"mutation">,
+>(
+  fnRef: TMutation,
+): OptionalTracedArgs<TMutation> extends [args?: EmptyObject]
+  ? (args?: EmptyObject) => Promise<FunctionReturnType<TMutation>>
+  : OptionalTracedArgs<TMutation> extends [args: infer Args]
+    ? (args: Args) => Promise<FunctionReturnType<TMutation>>
+    : never {
+  return useMutation(fnRef) as any;
+}
+
+export function useTracedAction<TAction extends FunctionReference<"action">>(
+  fnRef: TAction,
+): OptionalTracedArgs<TAction> extends [args?: EmptyObject]
+  ? (args?: EmptyObject) => Promise<FunctionReturnType<TAction>>
+  : OptionalTracedArgs<TAction> extends [args: infer Args]
+    ? (args: Args) => Promise<FunctionReturnType<TAction>>
+    : never {
+  return useAction(fnRef) as any;
+}

package/src/react/types.ts

@@ -0,0 +1,15 @@
+import type { AnyFunctionReference } from "../client/types";
+
+export type EmptyObject = Record<string, never>;
+
+export type OmitTraceContext<T> = T extends { __traceContext?: any }
+  ? Omit<T, "__traceContext">
+  : T;
+
+export type ArgsWithoutTrace<Args> =
+  Args extends Record<string, any> ? OmitTraceContext<Args> : Args;
+
+export type OptionalTracedArgs<FuncRef extends AnyFunctionReference> =
+  keyof OmitTraceContext<FuncRef["_args"]> extends never
+    ? [args?: EmptyObject]
+    : [args: OmitTraceContext<FuncRef["_args"]>];

package/src/test.ts

@@ -0,0 +1,18 @@
+/// <reference types="vite/client" />
+import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+import schema from "./component/schema.js";
+const modules = import.meta.glob("./component/**/*.ts");
+
+/**
+ * Register the component with the test convex instance.
+ * @param t - The test convex instance, e.g. from calling `convexTest`.
+ * @param name - The name of the component, as registered in convex.config.ts.
+ */
+export function register(
+  t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
+  name: string = "sampleComponent",
+) {
+  t.registerComponent(name, schema, modules);
+}
+export default { register, schema, modules };