convex-tracer 0.1.0

package/src/client/tracer-api/index.ts

@@ -0,0 +1,235 @@
+import type {
+  GenericActionCtx,
+  GenericDataModel,
+  GenericMutationCtx,
+} from "convex/server";
+
+import type { ComponentApi } from "../../component/_generated/component";
+import type { TracerConfig } from "../types";
+import type { SpanAPI, TraceAPI } from "./types";
+
+export default class TracingAPI implements TraceAPI {
+  constructor(
+    private ctx:
+      | GenericMutationCtx<GenericDataModel>
+      | GenericActionCtx<GenericDataModel>,
+    private component: ComponentApi,
+    private traceId: string,
+    private spanId: string,
+    private config: TracerConfig,
+  ) {}
+
+  private async addLog(
+    severity: "info" | "warn" | "error",
+    message: string,
+    metadata?: Record<string, any>,
+  ): Promise<void> {
+    await this.ctx
+      .runMutation(this.component.lib.addLog, {
+        spanId: this.spanId,
+        log: { timestamp: Date.now(), severity, message, metadata },
+      })
+      .catch((err) =>
+        console.error(`[Tracer] Failed to add ${severity} log:`, err),
+      );
+  }
+
+  getTraceId(): string {
+    return this.traceId;
+  }
+
+  getSpanId(): string {
+    return this.spanId;
+  }
+
+  async info(message: string, metadata?: Record<string, any>): Promise<void> {
+    await this.addLog("info", message, metadata);
+  }
+  async warn(message: string, metadata?: Record<string, any>): Promise<void> {
+    await this.addLog("warn", message, metadata);
+  }
+  async error(message: string, metadata?: Record<string, any>): Promise<void> {
+    await this.addLog("error", message, metadata);
+  }
+
+  async preserve(): Promise<void> {
+    await this.ctx
+      .runMutation(this.component.lib.updateTracePreserve, {
+        traceId: this.traceId,
+        preserve: true,
+      })
+      .catch((err) => console.error("[Tracer] Failed to preserve trace:", err));
+  }
+
+  async discard(): Promise<void> {
+    await this.ctx
+      .runMutation(this.component.lib.updateTracePreserve, {
+        traceId: this.traceId,
+        preserve: false,
+      })
+      .catch((err) => console.error("[Tracer] Failed to discard trace:", err));
+  }
+
+  async sample(sampleRate?: number): Promise<void> {
+    await this.ctx
+      .runMutation(this.component.lib.updateTracePreserve, {
+        traceId: this.traceId,
+        preserve: undefined,
+        sampleRate,
+      })
+      .catch((err) =>
+        console.error("[Tracer] Failed to reset trace sampling:", err),
+      );
+  }
+
+  async withSpan<T>(
+    spanName: string,
+    fn: (span: SpanAPI) => Promise<T>,
+  ): Promise<T> {
+    return await this.createAndRunSpan(this.spanId, spanName, fn);
+  }
+
+  async updateMetadata(metadata: Record<string, any>): Promise<void> {
+    await this.ctx
+      .runMutation(this.component.lib.updateSpanMetadata, {
+        spanId: this.spanId,
+        metadata,
+      })
+      .catch((err) => console.error("[Tracer] Failed to set metadata:", err));
+  }
+
+  private createSpanAPI(spanId: string): SpanAPI {
+    return {
+      info: async (message: string, metadata?: Record<string, any>) => {
+        await this.ctx
+          .runMutation(this.component.lib.addLog, {
+            spanId,
+            log: { timestamp: Date.now(), severity: "info", message, metadata },
+          })
+          .catch((err) =>
+            console.error(
+              "[Tracer] Failed to add info log to child span:",
+              err,
+            ),
+          );
+      },
+      warn: async (message: string, metadata?: Record<string, any>) => {
+        await this.ctx
+          .runMutation(this.component.lib.addLog, {
+            spanId,
+            log: { timestamp: Date.now(), severity: "warn", message, metadata },
+          })
+          .catch((err) =>
+            console.error(
+              "[Tracer] Failed to add warn log to child span:",
+              err,
+            ),
+          );
+      },
+      error: async (message: string, metadata?: Record<string, any>) => {
+        await this.ctx
+          .runMutation(this.component.lib.addLog, {
+            spanId,
+            log: {
+              timestamp: Date.now(),
+              severity: "error",
+              message,
+              metadata,
+            },
+          })
+          .catch((err) =>
+            console.error(
+              "[Tracer] Failed to add error log to child span:",
+              err,
+            ),
+          );
+      },
+      updateMetadata: async (metadata: Record<string, any>) => {
+        await this.ctx
+          .runMutation(this.component.lib.updateSpanMetadata, {
+            spanId,
+            metadata,
+          })
+          .catch((err) =>
+            console.error("[Tracer] Failed to set child span metadata:", err),
+          );
+      },
+      withSpan: async <T>(
+        spanName: string,
+        fn: (span: SpanAPI) => Promise<T>,
+      ): Promise<T> => {
+        return await this.createAndRunSpan(spanId, spanName, fn);
+      },
+    };
+  }
+
+  private async createAndRunSpan<T>(
+    parentSpanId: string,
+    spanName: string,
+    fn: (span: SpanAPI) => Promise<T>,
+  ): Promise<T> {
+    let childSpanId: string;
+    try {
+      childSpanId = await this.ctx.runMutation(this.component.lib.createSpan, {
+        traceId: this.traceId,
+        span: {
+          parentSpanId,
+          spanName,
+          source: "backend",
+          startTime: Date.now(),
+          status: "pending",
+        },
+      });
+    } catch (err) {
+      console.error("[Tracer] Failed to create child span:", err);
+      return await fn(this.createNoOpSpanAPI());
+    }
+
+    const spanAPI = this.createSpanAPI(childSpanId);
+    const startTime = Date.now();
+
+    try {
+      const result = await fn(spanAPI);
+      await this.ctx
+        .runMutation(this.component.lib.completeSpan, {
+          spanId: childSpanId,
+          endTime: Date.now(),
+          duration: Date.now() - startTime,
+          status: "success",
+        })
+        .catch((err) =>
+          console.error("[Tracer] Failed to complete span:", err),
+        );
+      return result;
+    } catch (error) {
+      await this.ctx
+        .runMutation(this.component.lib.completeSpan, {
+          spanId: childSpanId,
+          endTime: Date.now(),
+          duration: Date.now() - startTime,
+          status: "error",
+          error: error instanceof Error ? error.message : String(error),
+        })
+        .catch((err) =>
+          console.error("[Tracer] Failed to complete span with error:", err),
+        );
+
+      if (this.config.preserveErrors) {
+        await this.preserve();
+      }
+      throw error;
+    }
+  }
+
+  private createNoOpSpanAPI(): SpanAPI {
+    return {
+      info: async () => {},
+      warn: async () => {},
+      error: async () => {},
+      updateMetadata: async () => {},
+      withSpan: async <T>(): Promise<T> => {
+        return undefined as any;
+      },
+    };
+  }
+}

package/src/client/tracer-api/types.ts

@@ -0,0 +1,168 @@
+import { sourceValidator, statusValidator } from "../../component/schema";
+
+export interface SpanAPI {
+  /**
+   * Adds an info log to the current span.
+   * @param {string} message - The message to log.
+   * @param {Record<string, any>} metadata - Optional metadata to include with the log.
+   * @returns {Promise<void>}
+   * @example
+   * ```ts
+   * ctx.tracer.info("User created", { userId: user._id });
+   * ```
+   */
+  info(message: string, metadata?: Record<string, any>): Promise<void>;
+
+  /**
+   * Adds a warning log to the current span.
+   * @param {string} message - The message to log.
+   * @param {Record<string, any>} metadata - Optional metadata to include with the log.
+   * @returns {Promise<void>}
+   * @example
+   * ```ts
+   * ctx.tracer.warn("User not found", { userId: user._id });
+   * ```
+   */
+  warn(message: string, metadata?: Record<string, any>): Promise<void>;
+
+  /**
+   * Adds an error log to the current span.
+   * @param {string} message - The message to log.
+   * @param {Record<string, any>} metadata - Optional metadata to include with the log.
+   * @returns {Promise<void>}
+   * @example
+   * ```ts
+   * ctx.tracer.error("User not found", { userId: user._id });
+   * ```
+   */
+  error(message: string, metadata?: Record<string, any>): Promise<void>;
+
+  /**
+   * Sets the metadata for the current span.
+   * @param {Record<string, any>} metadata - The metadata to set.
+   * @returns {Promise<void>}
+   * @example
+   * ```ts
+   * ctx.tracer.updateMetadata({ userId: user._id });
+   * ```
+   */
+  updateMetadata(metadata: Record<string, any>): Promise<void>;
+
+  /**
+   * Creates a new span within the current trace.
+   * @param {string} name - The name of the span.
+   * @param {(span: SpanAPI) => Promise<T>} fn - The function to run within the span.
+   * @returns {Promise<T>} The result of the function.
+   * @example
+   * ```ts
+   * const result = await span.withSpan("createPost", async (span) => {
+   *   await span.info("Creating post");
+   *   return await ctx.db.insert("posts", args);
+   * });
+   * ```
+   */
+  withSpan<T>(name: string, fn: (span: SpanAPI) => Promise<T>): Promise<T>;
+}
+
+export interface TraceAPI extends SpanAPI {
+  /**
+   * Preserves the current trace.
+   * This will prevent the trace from being discarded or sampled.
+   * @returns {Promise<void>}
+   * @example
+   * ```ts
+   * await ctx.tracer.preserve();
+   * ```
+   */
+  preserve(): Promise<void>;
+
+  /**
+   * Discards the current trace.
+   * This will prevent the trace from being preserved.
+   * @returns {Promise<void>}
+   * @example
+   * ```ts
+   * await ctx.tracer.discard();
+   * ```
+   */
+  discard(): Promise<void>;
+
+  /**
+   * Makes sure the current trace will get sampled.
+   * This will undo any preserve() or discard() calls.
+   * @param {number} sampleRate - The sample rate to use. (optional)
+   * @returns {Promise<void>}
+   * @example
+   * ```ts
+   * await ctx.tracer.sample();
+   * ```
+   */
+  sample(sampleRate?: number): Promise<void>;
+
+  /**
+   * Creates a new span within the current trace.
+   * @param {string} name - The name of the span.
+   * @param {(span: SpanAPI) => Promise<T>} fn - The function to run within the span.
+   * @returns {Promise<T>} The result of the function.
+   * @example
+   * ```ts
+   * const result = await ctx.tracer.withSpan("createPost", async (span) => {
+   *   await span.info("Creating post");
+   *   return await ctx.db.insert("posts", args);
+   * });
+   * ```
+   */
+  withSpan<T>(name: string, fn: (span: SpanAPI) => Promise<T>): Promise<T>;
+
+  /**
+   * The Trace ID of the current trace.
+   */
+  getTraceId(): string;
+
+  /**
+   * The Span ID of the current span.
+   */
+  getSpanId(): string;
+}
+
+export interface TracerAPI {
+  /**
+   * Creates a new trace in the database.
+   * @param {string} traceId - The ID of the trace to create.
+   * @param {"pending" | "success" | "error"} status - The status of the trace.
+   * @param {number} sampleRate - The sample rate for the trace.
+   * @param {any} metadata - The metadata for the trace.
+   * @param {typeof statusValidator.type} source - The source of the trace.
+   * @returns {Promise<string>} A promise that resolves to the ID of the created trace.
+   */
+  createTrace: (
+    traceId: string,
+    status: typeof statusValidator.type,
+    sampleRate: number,
+    metadata: any,
+    source: typeof sourceValidator.type,
+  ) => Promise<string>;
+
+  /**
+   * Updates the status of a trace.
+   * @param {string} traceId - The ID of the trace to update.
+   * @param {typeof statusValidator.type} status - The new status of the trace.
+   * @returns {Promise<void>} A promise that resolves when the trace is updated.
+   */
+  updateTraceStatus: (
+    traceId: string,
+    status: typeof statusValidator.type,
+  ) => Promise<void>;
+
+  /**
+   * Updates the preserve flag of a trace.
+   * @param {string} traceId - The ID of the trace to update.
+   * @param {boolean | undefined} preserve - The new preserve flag of the trace.
+   * @returns {Promise<void>} A promise that resolves when the trace is updated.
+   */
+  updateTracePreserve: (
+    traceId: string,
+    preserve: boolean | undefined,
+  ) => Promise<void>;
+  updateTraceMetadata: (traceId: string, metadata: any) => Promise<void>;
+}

package/src/client/types.ts

@@ -0,0 +1,257 @@
+import type {
+  FunctionReference,
+  FunctionType,
+  GenericActionCtx,
+  GenericDatabaseReader,
+  GenericDataModel,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  StorageReader,
+} from "convex/server";
+import type {
+  ObjectType,
+  OptionalProperty,
+  PropertyValidators,
+  Validator,
+} from "convex/values";
+import type { EmptyObject } from "../react/types";
+import type { TraceAPI } from "./tracer-api/types";
+
+export type AnyFunctionReference = FunctionReference<any, any>;
+
+export type OptionalArgsObject<Args extends PropertyValidators> =
+  keyof Args extends never ? EmptyObject : ObjectType<Args>;
+
+export type IfArgs<
+  Args extends PropertyValidators,
+  T,
+  F,
+> = keyof Args extends never ? F : T;
+
+export type ExtractOutput<T> = T extends (
+  ctx: any,
+  args: any,
+) => Promise<infer R>
+  ? R
+  : never;
+
+export interface TraceContext extends Required<TracerConfig> {
+  traceId: string; // Id<"traces"> from component
+  spanId: string; // Id<"spans"> from component
+}
+
+export type ArgsWithTraceContext<Args> = Args & {
+  __traceContext?: TraceContext;
+};
+
+export interface TracerConfig {
+  /**
+   * The sample rate for the trace.
+   * This is used to determine whether to sample the trace or not.
+   * @default - 0.1
+   */
+  sampleRate?: number;
+
+  /**
+   * Whether to preserve errors.
+   * If true, the trace will be preserved on error.
+   * If false, the trace will get sampled.
+   * @default - true
+   */
+  preserveErrors?: boolean;
+
+  /**
+   * The amount of time to wait before sampling or deleting the trace.
+   * This is used to prevent tracing of long-running functions.
+   * @default - 120
+   */
+  retentionMinutes?: number;
+}
+
+export type LogArgs<Args extends PropertyValidators> = IfArgs<
+  Args,
+  boolean | Array<keyof ObjectType<Args>> | undefined,
+  EmptyObject
+>;
+
+export interface TracedFunctionOptions<
+  Ctx,
+  Args extends PropertyValidators,
+  Output,
+> {
+  /**
+   * The name of the traced function.
+   * This is used to identify the function in the DB or UI.
+   * @default - anonymous_function
+   */
+  name?: string;
+
+  /**
+   * Whether to log the arguments of the function.
+   * This can be a boolean or an array of argument names to log.
+   * @default - false
+   * @example
+   * ```ts
+   * logArgs: true, // Logs all arguments
+   * logArgs: ["userId", "title"], // Logs only the userId and title arguments
+   * ```
+   */
+  logArgs?: LogArgs<Args>;
+
+  /**
+   * Whether to log the return value of the function.
+   * @default - false
+   */
+  logReturn?: boolean;
+
+  /**
+   * The sample rate for the trace.
+   * This is used to determine whether to sample the trace or not.
+   * If undefined, the Tracer config will be used
+   * @default - 0.1
+   */
+  sampleRate?: number;
+
+  /** The retention minutes for the trace.
+   * This is used to determine how long to keep the trace.
+   * If undefined, the Tracer config will be used
+   * @default - 120
+   */
+  retentionMinutes?: number;
+
+  /** Whether to preserve errors.
+   * If true, the trace will be preserved on error.
+   * If undefined, the Tracer config will be used
+   * @default - undefined
+   */
+  preserveErrors?: boolean;
+
+  /**
+   * A callback to run before the function starts.
+   * @param {any} ctx - The context object.
+   * @param {ObjectType<Args>} args - The arguments object.
+   * @returns {void | Promise<void>}
+   * @example
+   * ```ts
+   * onStart: async (ctx, args) => {
+   *   // do something before the function starts
+   *   await ctx.tracer.info("Starting Processing...");
+   * }
+   * ```
+   */
+  onStart?: (ctx: Ctx, args: OptionalArgsObject<Args>) => void | Promise<void>;
+
+  /**
+   * A callback to run after the function succeeds.
+   * @param {any} ctx - The context object.
+   * @param {ObjectType<Args>} args - The arguments object.
+   * @param {unknown} result - The result of the function.
+   * @returns {void | Promise<void>}
+   * @example
+   * ```ts
+   * onSuccess: async (ctx, args, result) => {
+   *   // do something with the result
+   *   await ctx.tracer.info("Successfully processed");
+   * }
+   * ```
+   */
+  onSuccess?: (
+    ctx: Ctx,
+    args: OptionalArgsObject<Args>,
+    result: Output,
+  ) => void | Promise<void>;
+
+  /**
+   * A callback to run after the function fails.
+   * @param {any} ctx - The context object.
+   * @param {ObjectType<Args>} args - The arguments object.
+   * @param {Error} error - The error that occurred.
+   * @returns {void | Promise<void>}
+   * @example
+   * ```ts
+   * onError: async (ctx, args, error) => {
+   *   // do something to handle the error
+   *   await ctx.tracer.error("Failed to process", { error: error.message });
+   * }
+   * ```
+   */
+  onError?: (
+    ctx: Ctx,
+    args: OptionalArgsObject<Args>,
+    error: Error,
+  ) => void | Promise<void>;
+}
+
+export type TracerHandler<Ctx, Args extends PropertyValidators> = (
+  ctx: Ctx,
+  args: OptionalArgsObject<Args>,
+) => Promise<any>;
+
+export type TracedFunctionConfig<
+  Ctx,
+  Args extends PropertyValidators,
+  Handler extends TracerHandler<Ctx, Args>,
+  Output extends ExtractOutput<Handler>,
+> = TracedFunctionOptions<Ctx, Args, Output> & {
+  args?: Args;
+  handler: Handler;
+  returns?: Validator<Output, OptionalProperty, any>;
+};
+
+export type TracerArgs<Args extends PropertyValidators> = ObjectType<
+  Args & { __traceContext?: TraceContext }
+>;
+
+export type TracedFunctionTypes = Exclude<FunctionType, "query">;
+
+export type TracedFunction<Type extends TracedFunctionTypes> = <
+  FuncRef extends FunctionReference<Type, any, any, any>,
+>(
+  funcRef: FuncRef,
+  args?: Omit<FuncRef["_args"], "__traceContext">,
+) => Promise<FuncRef["_returnType"]>;
+
+type RestrictedQueryContext<DataModel extends GenericDataModel> = Omit<
+  GenericMutationCtx<DataModel>,
+  "runMutation" | "scheduler" | "db" | "storage"
+> & {
+  db: GenericDatabaseReader<DataModel>;
+  storage: StorageReader;
+};
+
+export type QueryCtxWithTracer<DataModel extends GenericDataModel> =
+  RestrictedQueryContext<DataModel> & {
+    tracer: TraceAPI;
+    runTracedQuery: TracedFunction<"mutation">;
+  };
+
+export type MutationCtxWithTracer<DataModel extends GenericDataModel> =
+  GenericMutationCtx<DataModel> & {
+    tracer: TraceAPI;
+    runTracedQuery: TracedFunction<"mutation">;
+    runTracedMutation: TracedFunction<"mutation">;
+  };
+
+export type ActionCtxWithTracer<DataModel extends GenericDataModel> =
+  GenericActionCtx<DataModel> & {
+    tracer: TraceAPI;
+    runTracedQuery: TracedFunction<"mutation">;
+    runTracedMutation: TracedFunction<"mutation">;
+    runTracedAction: TracedFunction<"action">;
+  };
+
+export type TracedFunctionContext<DataModel extends GenericDataModel> =
+  | QueryCtxWithTracer<DataModel>
+  | MutationCtxWithTracer<DataModel>
+  | ActionCtxWithTracer<DataModel>;
+
+export type StrippedGenericFunctionContext<DataModel extends GenericDataModel> =
+  GenericMutationCtx<DataModel> | GenericActionCtx<DataModel>;
+
+export type GenericFunctionContext<DataModel extends GenericDataModel> =
+  | GenericQueryCtx<DataModel>
+  | StrippedGenericFunctionContext<DataModel>;
+
+export type TracedResult<Output> =
+  | { success: true; data: Output; error: undefined }
+  | { success: false; data: undefined; error: string };

package/src/component/_generated/api.ts

@@ -0,0 +1,52 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as lib from "../lib.js";
+import type * as types from "../types.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  lib: typeof lib;
+  types: typeof types;
+}> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+> = anyApi as any;
+
+export const components = componentsGeneric() as unknown as {};