convex-tracer 0.1.0

package/dist/client/helpers.js

@@ -0,0 +1,177 @@
+import TracerAPI from "./tracer-api/index";
+function pick(obj, keys) {
+    return Object.fromEntries(Object.entries(obj).filter(([k]) => keys.includes(k)));
+}
+export function extractTraceContext(allArgs) {
+    const existingContext = allArgs.__traceContext;
+    const args = { ...allArgs };
+    delete args.__traceContext;
+    return { existingContext, args };
+}
+export function prepareLogArgs(args, logArgs) {
+    if (!logArgs)
+        return undefined;
+    if (logArgs === true)
+        return args;
+    if (Array.isArray(logArgs)) {
+        return pick(args, logArgs);
+    }
+    return undefined;
+}
+export async function setupTraceContext(ctx, component, existingContext, startTime, functionName, sampleRate, retentionMinutes, preserveErrors, spanData) {
+    if (existingContext?.traceId) {
+        const spanId = await ctx.runMutation(component.lib.createSpan, {
+            traceId: existingContext.traceId,
+            span: {
+                parentSpanId: existingContext.spanId,
+                spanName: functionName,
+                source: "backend",
+                startTime,
+                status: "pending",
+                functionName: spanData.functionName,
+                args: spanData.args,
+            },
+        });
+        return {
+            traceId: existingContext.traceId,
+            spanId,
+            traceContext: {
+                traceId: existingContext.traceId,
+                spanId,
+                sampleRate: existingContext.sampleRate,
+                retentionMinutes: existingContext.retentionMinutes,
+                preserveErrors: existingContext.preserveErrors,
+            },
+            isRoot: false,
+        };
+    }
+    const traceId = await ctx.runMutation(component.lib.createTrace, {
+        status: "pending",
+        sampleRate,
+        metadata: {},
+        source: "backend",
+    });
+    const spanId = await ctx.runMutation(component.lib.createSpan, {
+        traceId,
+        span: {
+            spanName: functionName,
+            source: "backend",
+            startTime: Date.now(),
+            status: "pending",
+            functionName: spanData.functionName,
+            args: spanData.args,
+        },
+    });
+    return {
+        traceId,
+        spanId,
+        traceContext: {
+            traceId,
+            spanId,
+            sampleRate,
+            retentionMinutes,
+            preserveErrors,
+        },
+        isRoot: true,
+    };
+}
+export async function executeTracedHandler(params) {
+    const { ctx, component, traceId, spanId, startTime, config, args, handler, enhancedCtx, isRoot, } = params;
+    const defaultConfig = enhancedCtx.tracer
+        .config;
+    try {
+        // Reject any functions that pass a traceId that doesn't exist
+        // These params can be passed from the frontend to break tracing
+        // Running a tracedFunction without passing ids will create a new trace
+        if (traceId) {
+            const traceExists = await ctx.runQuery(component.lib.verifyTrace, {
+                traceId,
+            });
+            if (!traceExists)
+                throw new Error("Cannot pass a traceId for a trace that doesn't exist");
+        }
+        // Reject any functions that pass a spanId that doesn't exist
+        // These params can be passed from the frontend to break tracing
+        if (spanId) {
+            const spanExists = await ctx.runQuery(component.lib.verifySpan, {
+                spanId,
+            });
+            if (!spanExists)
+                throw new Error("Cannot pass a spanId for a span that doesn't exist");
+        }
+        if (config.onStart) {
+            await config.onStart(enhancedCtx, args);
+        }
+        const result = await handler(enhancedCtx, args);
+        if (config.onSuccess) {
+            await config.onSuccess(enhancedCtx, args, result);
+        }
+        const now = Date.now();
+        await ctx
+            .runMutation(component.lib.completeSpan, {
+            spanId,
+            endTime: now,
+            duration: now - startTime,
+            status: "success",
+            result: config.logReturn ? result : undefined,
+        })
+            .catch((err) => console.error("[Tracer] Failed to complete span with success:", err));
+        if (isRoot) {
+            await ctx
+                .runMutation(component.lib.updateTraceStatus, {
+                traceId,
+                status: "success",
+            })
+                .catch((err) => console.error("[Tracer] Failed to update trace status:", err));
+        }
+        return { success: true, data: result, error: undefined };
+    }
+    catch (e) {
+        const error = e;
+        if (config.onError) {
+            await config.onError(enhancedCtx, args, error);
+        }
+        const preserveErrors = config.preserveErrors ?? defaultConfig.preserveErrors;
+        if (preserveErrors) {
+            const tracerAPI = new TracerAPI(ctx, component, traceId, spanId, config);
+            await tracerAPI.preserve();
+        }
+        await ctx
+            .runMutation(component.lib.completeSpan, {
+            spanId,
+            endTime: Date.now(),
+            duration: Date.now() - startTime,
+            status: "error",
+            error: error.message,
+        })
+            .catch((err) => console.error("[Tracer] Failed to complete span with error:", err));
+        if (isRoot) {
+            await ctx
+                .runMutation(component.lib.updateTraceStatus, {
+                traceId,
+                status: "error",
+            })
+                .catch((err) => console.error("[Tracer] Failed to update trace status:", err));
+        }
+        return { success: false, data: undefined, error: error.message };
+    }
+    finally {
+        const retMins = config.retentionMinutes ?? defaultConfig.retentionMinutes;
+        if (!retMins) {
+            console.error("[Tracer] retentionMinutes is not defined");
+        }
+        const sampleRate = config.sampleRate ?? defaultConfig.sampleRate;
+        if (!sampleRate) {
+            console.error("[Tracer] sampleRate is not defined");
+        }
+        else if (sampleRate && sampleRate < 1) {
+            const MINUTE = 60 * 1000;
+            const delayMins = retMins ?? 120;
+            const delay = delayMins * MINUTE;
+            await ctx.scheduler.runAfter(delay, component.lib.cleanupTrace, {
+                traceId,
+            });
+        }
+    }
+}
+//# sourceMappingURL=helpers.js.map

package/dist/client/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/client/helpers.ts"],"names":[],"mappings":"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"}

package/dist/client/index.d.ts

@@ -0,0 +1,210 @@
+import { type GenericDataModel, type RegisteredAction, type RegisteredMutation } from "convex/server";
+import type { Infer, PropertyValidators } from "convex/values";
+import type { ComponentApi } from "../component/_generated/component";
+import { statusValidator } from "../component/schema";
+import type { CompleteTrace, Trace } from "../component/types";
+import type { EmptyObject } from "../react/types";
+import type { ActionCtxWithTracer, ExtractOutput, GenericFunctionContext, MutationCtxWithTracer, QueryCtxWithTracer, TracedFunctionConfig, TracedResult, TracerArgs, TracerConfig, TracerHandler } from "./types";
+export * from "../component/types";
+/**
+ * @example
+ * ```typescript
+ * import { components } from "./_generated/api";
+ * import { mutation, action } from "./_generated/server";
+ * import { Tracer } from "@convex-dev/tracer";
+ *
+ * export const { tracedQuery, tracedMutation, tracedAction } = new Tracer(components.tracer, {
+ *   sampleRate: 0.1,
+ *   preserveErrors: true,
+ * });
+ *
+ * export const createPost = tracedMutation({
+ *   name: "createPost",
+ *   args: { title: v.string() },
+ *   handler: async (ctx, args) => {
+ *     await ctx.tracer.info("Creating post");
+ *     return await ctx.db.insert("posts", args);
+ *   },
+ * });
+ * ```
+ */
+export declare class Tracer<DataModel extends GenericDataModel> {
+    readonly component: ComponentApi;
+    readonly sampleRate: number;
+    readonly preserveErrors: boolean;
+    readonly retentionMinutes: number;
+    constructor(component: ComponentApi, config?: TracerConfig);
+    private createRunTracedFunction;
+    private createRestrictedQueryContext;
+    private createEnhancedContext;
+    private createTracedHandler;
+    /**
+     * Creates a traced query (runs as mutation internally).
+     * @example
+     * ```ts
+     * export const getUser = tracedQuery({
+     *   name: "getUser",
+     *   args: { userId: v.id("users") },
+     *   onSuccess: async (ctx, args, result) => {
+     *     await ctx.tracer.info("Succeeded user fetch", { userId: args.userId });
+     *   },
+     *   handler: async (ctx, args) => {
+     *     await ctx.tracer.info("fetching user", { title: args.userId });
+     *     const user = await ctx.db.get(args.userId);
+     *     await ctx.tracer.info("user fetched", { userId: args.userId });
+     *     return user;
+     *   },
+     * });
+     * ```
+     */
+    tracedQuery: <Ctx extends QueryCtxWithTracer<DataModel>, Args extends PropertyValidators | EmptyObject, Handler extends TracerHandler<Ctx, Args>, Output extends ExtractOutput<Handler>>(tConfig: TracedFunctionConfig<Ctx, Args, Handler, Output>) => RegisteredMutation<"public", TracerArgs<Args>, TracedResult<ExtractOutput<Handler>>>;
+    /**
+     * Creates a traced query (runs as mutation internally).
+     * @example
+     * ```ts
+     * export const getUser = internalTracedQuery({
+     *   name: "getUser",
+     *   args: { userId: v.id("users") },
+     *   onSuccess: async (ctx, args, result) => {
+     *     await ctx.tracer.info("Succeeded user fetch", { userId: args.userId });
+     *   },
+     *   handler: async (ctx, args) => {
+     *     await ctx.tracer.info("fetching user", { title: args.userId });
+     *     const user = await ctx.db.get(args.userId);
+     *     await ctx.tracer.info("user fetched", { userId: args.userId });
+     *     return user;
+     *   },
+     * });
+     * ```
+     */
+    internalTracedQuery: <Ctx extends QueryCtxWithTracer<DataModel>, Args extends PropertyValidators | EmptyObject, Handler extends TracerHandler<Ctx, Args>, Output extends ExtractOutput<Handler>>(tConfig: TracedFunctionConfig<Ctx, Args, Handler, Output>) => RegisteredMutation<"internal", TracerArgs<Args>, TracedResult<ExtractOutput<Handler>>>;
+    /**
+     * Creates a traced mutation.
+     * @example
+     * ```ts
+     * export const createUser = tracedMutation({
+     *   name: "createUser",
+     *   args: { user: v.object({ name: v.string(), email: v.string() }) },
+     *   handler: async (ctx, args) => {
+     *     const existing = await ctx.db
+     *       .query("users")
+     *       .withIndex("by_email", (q) => q.eq("email", args.user.email))
+     *       .first();
+     *
+     *     if (existing) {
+     *       ctx.tracer.info("User already exists", { user: args.user });
+     *       return existing._id;
+     *     }
+     *
+     *     ctx.tracer.info("Adding user", { ...args.user });
+     *
+     *     const userId = await ctx.db.insert("users", { ...args.user });
+     *     ctx.tracer.info("User added", { userId });
+     *
+     *     await ctx.tracer.withSpan("syncUser", async (span) => {
+     *       span.info("Syncing user");
+     *       // do something
+     *       span.info("User synced");
+     *     });
+     *
+     *     return userId;
+     *   },
+     * });
+     * ```
+     */
+    tracedMutation: <Ctx extends MutationCtxWithTracer<DataModel>, Args extends PropertyValidators | EmptyObject, Handler extends TracerHandler<Ctx, Args>, Output extends ExtractOutput<Handler>>(tConfig: TracedFunctionConfig<Ctx, Args, Handler, Output>) => RegisteredMutation<"public", TracerArgs<Args>, TracedResult<ExtractOutput<Handler>>>;
+    /**
+     * Creates a traced mutation.
+     * @example
+     * ```ts
+     * export const createUser = internalTracedMutation({
+     *   name: "createUser",
+     *   args: { user: v.object({ name: v.string(), email: v.string() }) },
+     *   handler: async (ctx, args) => {
+     *     const existing = await ctx.db
+     *       .query("users")
+     *       .withIndex("by_email", (q) => q.eq("email", args.user.email))
+     *       .first();
+     *
+     *     if (existing) {
+     *       await ctx.tracer.info("User already exists", { user: args.user });
+     *       return existing._id;
+     *     }
+     *
+     *     await ctx.tracer.info("Adding user", { ...args.user });
+     *
+     *     const userId = await ctx.db.insert("users", { ...args.user });
+     *     ctx.tracer.info("User added", { userId });
+     *
+     *     await ctx.tracer.withSpan("syncUser", async (span) => {
+     *       await span.info("Syncing user");
+     *       // do something
+     *       await span.info("User synced");
+     *     });
+     *
+     *     return userId;
+     *   },
+     * });
+     * ```
+     */
+    internalTracedMutation: <Ctx extends MutationCtxWithTracer<DataModel>, Args extends PropertyValidators | EmptyObject, Handler extends TracerHandler<Ctx, Args>, Output extends ExtractOutput<Handler>>(tConfig: TracedFunctionConfig<Ctx, Args, Handler, Output>) => RegisteredMutation<"internal", TracerArgs<Args>, TracedResult<ExtractOutput<Handler>>>;
+    /**
+     * Creates a traced action.
+     * @example
+     * ```ts
+     * export const someAction = tracedAction({
+     *   name: "someAction",
+     *   args: { userId: v.id("users") },
+     *   handler: async (ctx, args) => {
+     *     // do something
+     *   },
+     * });
+     * ```
+     */
+    tracedAction: <Ctx extends ActionCtxWithTracer<DataModel>, Args extends PropertyValidators | EmptyObject, Handler extends TracerHandler<Ctx, Args>, Output extends ExtractOutput<Handler>>(tConfig: TracedFunctionConfig<Ctx, Args, Handler, Output>) => RegisteredAction<"public", TracerArgs<Args>, TracedResult<Output>>;
+    /**
+     * Creates a traced action.
+     * @example
+     * ```ts
+     * export const someAction = internalTracedAction({
+     *   name: "someAction",
+     *   args: { userId: v.id("users") },
+     *   handler: async (ctx, args) => {
+     *     // do something
+     *   },
+     * });
+     * ```
+     */
+    internalTracedAction: <Ctx extends ActionCtxWithTracer<DataModel>, Args extends PropertyValidators | EmptyObject, Handler extends TracerHandler<Ctx, Args>, Output extends ExtractOutput<Handler>>(tConfig: TracedFunctionConfig<Ctx, Args, Handler, Output>) => RegisteredAction<"internal", TracerArgs<Args>, TracedResult<Output>>;
+    get tracer(): {
+        /**
+         * Retrieves a trace by its ID.
+         * @param traceId - The ID of the trace to retrieve.
+         * @example
+         * ```ts
+         * // In a convex function (query, mutation, or action)
+         * // Or in a traced function
+         * const trace = await tracer.getTrace("123")
+         * ```
+         */
+        getTrace: (ctx: GenericFunctionContext<DataModel>, traceId: string) => Promise<CompleteTrace | null>;
+        /**
+         * Lists traces with optional filtering by status.
+         * @param status - The status of the traces to retrieve.
+         * @param limit - The maximum number of traces to retrieve.
+         * @param userId - The ID of the user to retrieve traces for.
+         * @example
+         * ```ts
+         * // In a convex function (query, mutation, or action)
+         * // Or in a traced function
+         * const traces = await tracer.listTraces({ status: "success", limit: 10 })
+         * ```
+         */
+        listTraces: (ctx: GenericFunctionContext<DataModel>, args?: {
+            status?: Infer<typeof statusValidator>;
+            limit?: number;
+            userId?: string;
+        }) => Promise<Trace[]>;
+    };
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}