convex-tracer 0.1.1 → 0.1.2

package/dist/client/_generated/_ignore.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=_ignore.d.ts.map

package/dist/client/_generated/_ignore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_ignore.d.ts","sourceRoot":"","sources":["../../../src/client/_generated/_ignore.ts"],"names":[],"mappings":""}

package/dist/client/_generated/_ignore.js

@@ -0,0 +1,3 @@
+"use strict";
+// This is only here so convex-test can detect a _generated folder
+//# sourceMappingURL=_ignore.js.map

package/dist/client/_generated/_ignore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_ignore.js","sourceRoot":"","sources":["../../../src/client/_generated/_ignore.ts"],"names":[],"mappings":";AAAA,kEAAkE"}

package/dist/client/helpers.d.ts

@@ -0,0 +1,31 @@
+import type { GenericDataModel } from "convex/server";
+import type { ObjectType, PropertyValidators } from "convex/values";
+import type { ComponentApi } from "../component/_generated/component";
+import type { ArgsWithTraceContext, LogArgs, OptionalArgsObject, StrippedGenericFunctionContext, TraceContext, TracedFunctionOptions, TracedResult, TracerConfig, TracerHandler } from "./types";
+export declare function extractTraceContext<Args extends Record<string, unknown>>(allArgs: ArgsWithTraceContext<Args>): {
+    existingContext?: TraceContext;
+    args: Args;
+};
+export declare function prepareLogArgs<Args extends PropertyValidators>(args: ObjectType<Args>, logArgs: LogArgs<Args>): unknown | undefined;
+export declare function setupTraceContext(ctx: StrippedGenericFunctionContext<GenericDataModel>, component: ComponentApi, existingContext: TraceContext | undefined, startTime: number, functionName: string, sampleRate: number, retentionMinutes: number, preserveErrors: boolean, spanData: {
+    functionName?: string;
+    args?: unknown;
+}): Promise<{
+    traceId: string;
+    spanId: string;
+    traceContext: TraceContext;
+    isRoot: boolean;
+}>;
+export declare function executeTracedHandler<Args extends PropertyValidators, Output, EnhancedCtx>(params: {
+    ctx: StrippedGenericFunctionContext<GenericDataModel>;
+    component: ComponentApi;
+    traceId: string;
+    spanId: string;
+    startTime: number;
+    config: TracedFunctionOptions<EnhancedCtx, Args, Output> & TracerConfig;
+    args: OptionalArgsObject<Args>;
+    handler: TracerHandler<EnhancedCtx, Args>;
+    enhancedCtx: EnhancedCtx;
+    isRoot: boolean;
+}): Promise<TracedResult<Output>>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/client/helpers.js

@@ -0,0 +1,186 @@
+import TracerAPI from "./tracer-api/index";
+function pick(obj, keys) {
+    return Object.fromEntries(Object.entries(obj).filter(([k]) => keys.includes(k)));
+}
+async function getAuthUserId(ctx) {
+    const identity = await ctx.auth.getUserIdentity();
+    if (identity === null)
+        return "anonymous";
+    const [userId] = identity.subject.split("|");
+    return userId;
+}
+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 userId = await getAuthUserId(ctx);
+    const traceId = await ctx.runMutation(component.lib.createTrace, {
+        status: "pending",
+        sampleRate,
+        metadata: {},
+        source: "backend",
+        userId,
+    });
+    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":"AAGA,OAAO,SAAS,MAAM,oBAAoB,CAAC;AAa3C,SAAS,IAAI,CACX,GAAM,EACN,IAAU;IAEV,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAiB,CAAC,CAAC,CAGtE,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,GAAmB;IAC9C,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;IAClD,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,WAAW,CAAC;IAE1C,MAAM,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,OAAmC;IAEnC,MAAM,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAC/C,MAAM,IAAI,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC;IAC5B,OAAQ,IAAmC,CAAC,cAAc,CAAC;IAC3D,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,IAAsB,EACtB,OAAsB;IAEtB,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAAqD,EACrD,SAAuB,EACvB,eAAyC,EACzC,SAAiB,EACjB,YAAoB,EACpB,UAAkB,EAClB,gBAAwB,EACxB,cAAuB,EACvB,QAAmD;IAOnD,IAAI,eAAe,EAAE,OAAO,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,EAAE;YAC7D,OAAO,EAAE,eAAe,CAAC,OAAO;YAChC,IAAI,EAAE;gBACJ,YAAY,EAAE,eAAe,CAAC,MAAM;gBACpC,QAAQ,EAAE,YAAY;gBACtB,MAAM,EAAE,SAAS;gBACjB,SAAS;gBACT,MAAM,EAAE,SAAS;gBACjB,YAAY,EAAE,QAAQ,CAAC,YAAY;gBACnC,IAAI,EAAE,QAAQ,CAAC,IAAI;aACpB;SACF,CAAC,CAAC;QAEH,OAAO;YACL,OAAO,EAAE,eAAe,CAAC,OAAO;YAChC,MAAM;YACN,YAAY,EAAE;gBACZ,OAAO,EAAE,eAAe,CAAC,OAAO;gBAChC,MAAM;gBACN,UAAU,EAAE,eAAe,CAAC,UAAU;gBACtC,gBAAgB,EAAE,eAAe,CAAC,gBAAgB;gBAClD,cAAc,EAAE,eAAe,CAAC,cAAc;aAC/C;YACD,MAAM,EAAE,KAAK;SACd,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,EAAE;QAC/D,MAAM,EAAE,SAAS;QACjB,UAAU;QACV,QAAQ,EAAE,EAAE;QACZ,MAAM,EAAE,SAAS;QACjB,MAAM;KACP,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,EAAE;QAC7D,OAAO;QACP,IAAI,EAAE;YACJ,QAAQ,EAAE,YAAY;YACtB,MAAM,EAAE,SAAS;YACjB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,MAAM,EAAE,SAAS;YACjB,YAAY,EAAE,QAAQ,CAAC,YAAY;YACnC,IAAI,EAAE,QAAQ,CAAC,IAAI;SACpB;KACF,CAAC,CAAC;IAEH,OAAO;QACL,OAAO;QACP,MAAM;QACN,YAAY,EAAE;YACZ,OAAO;YACP,MAAM;YACN,UAAU;YACV,gBAAgB;YAChB,cAAc;SACf;QACD,MAAM,EAAE,IAAI;KACb,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAIxC,MAWD;IACC,MAAM,EACJ,GAAG,EACH,SAAS,EACT,OAAO,EACP,MAAM,EACN,SAAS,EACT,MAAM,EACN,IAAI,EACJ,OAAO,EACP,WAAW,EACX,MAAM,GACP,GAAG,MAAM,CAAC;IAEX,MAAM,aAAa,GAAI,WAAmB,CAAC,MAAM;SAC9C,MAAgC,CAAC;IAEpC,IAAI,CAAC;QACH,8DAA8D;QAC9D,gEAAgE;QAChE,uEAAuE;QACvE,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,WAAW,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,EAAE;gBAChE,OAAO;aACR,CAAC,CAAC;YAEH,IAAI,CAAC,WAAW;gBACd,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC5E,CAAC;QAED,6DAA6D;QAC7D,gEAAgE;QAChE,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,UAAU,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,EAAE;gBAC9D,MAAM;aACP,CAAC,CAAC;YAEH,IAAI,CAAC,UAAU;gBACb,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QAC1E,CAAC;QAED,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,MAAM,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QAC1C,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QAEhD,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACrB,MAAM,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QACpD,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,MAAM,GAAG;aACN,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,EAAE;YACvC,MAAM;YACN,OAAO,EAAE,GAAG;YACZ,QAAQ,EAAE,GAAG,GAAG,SAAS;YACzB,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;SAC9C,CAAC;aACD,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CACb,OAAO,CAAC,KAAK,CAAC,gDAAgD,EAAE,GAAG,CAAC,CACrE,CAAC;QAEJ,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,GAAG;iBACN,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,iBAAiB,EAAE;gBAC5C,OAAO;gBACP,MAAM,EAAE,SAAS;aAClB,CAAC;iBACD,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CACb,OAAO,CAAC,KAAK,CAAC,yCAAyC,EAAE,GAAG,CAAC,CAC9D,CAAC;QACN,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAC3D,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,KAAK,GAAG,CAAqB,CAAC;QAEpC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,MAAM,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QACjD,CAAC;QAED,MAAM,cAAc,GAClB,MAAM,CAAC,cAAc,IAAI,aAAa,CAAC,cAAc,CAAC;QAExD,IAAI,cAAc,EAAE,CAAC;YACnB,MAAM,SAAS,GAAG,IAAI,SAAS,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;YACzE,MAAM,SAAS,CAAC,QAAQ,EAAE,CAAC;QAC7B,CAAC;QAED,MAAM,GAAG;aACN,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,EAAE;YACvC,MAAM;YACN,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE;YACnB,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;YAChC,MAAM,EAAE,OAAO;YACf,KAAK,EAAE,KAAK,CAAC,OAAO;SACrB,CAAC;aACD,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CACb,OAAO,CAAC,KAAK,CAAC,8CAA8C,EAAE,GAAG,CAAC,CACnE,CAAC;QAEJ,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,GAAG;iBACN,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,iBAAiB,EAAE;gBAC5C,OAAO;gBACP,MAAM,EAAE,OAAO;aAChB,CAAC;iBACD,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CACb,OAAO,CAAC,KAAK,CAAC,yCAAyC,EAAE,GAAG,CAAC,CAC9D,CAAC;QACN,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;IACnE,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,GAAG,MAAM,CAAC,gBAAgB,IAAI,aAAa,CAAC,gBAAgB,CAAC;QAE1E,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC5D,CAAC;QAED,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,aAAa,CAAC,UAAU,CAAC;QACjE,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACtD,CAAC;aAAM,IAAI,UAAU,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;YACxC,MAAM,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC;YACzB,MAAM,SAAS,GAAG,OAAO,IAAI,GAAG,CAAC;YAEjC,MAAM,KAAK,GAAG,SAAS,GAAG,MAAM,CAAC;YAEjC,MAAM,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,CAAC,YAAY,EAAE;gBAC9D,OAAO;aACR,CAAC,CAAC;QACL,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/client/tracer-api/index.d.ts

@@ -0,0 +1,27 @@
+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 {
+    private ctx;
+    private component;
+    private traceId;
+    private spanId;
+    private config;
+    constructor(ctx: GenericMutationCtx<GenericDataModel> | GenericActionCtx<GenericDataModel>, component: ComponentApi, traceId: string, spanId: string, config: TracerConfig);
+    private addLog;
+    getTraceId(): string;
+    getSpanId(): string;
+    info(message: string, metadata?: Record<string, any>): Promise<void>;
+    warn(message: string, metadata?: Record<string, any>): Promise<void>;
+    error(message: string, metadata?: Record<string, any>): Promise<void>;
+    preserve(): Promise<void>;
+    discard(): Promise<void>;
+    sample(sampleRate?: number): Promise<void>;
+    withSpan<T>(spanName: string, fn: (span: SpanAPI) => Promise<T>): Promise<T>;
+    updateMetadata(metadata: Record<string, any>): Promise<void>;
+    private createSpanAPI;
+    private createAndRunSpan;
+    private createNoOpSpanAPI;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/client/tracer-api/index.js

@@ -0,0 +1,177 @@
+export default class TracingAPI {
+    ctx;
+    component;
+    traceId;
+    spanId;
+    config;
+    constructor(ctx, component, traceId, spanId, config) {
+        this.ctx = ctx;
+        this.component = component;
+        this.traceId = traceId;
+        this.spanId = spanId;
+        this.config = config;
+    }
+    async addLog(severity, message, metadata) {
+        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() {
+        return this.traceId;
+    }
+    getSpanId() {
+        return this.spanId;
+    }
+    async info(message, metadata) {
+        await this.addLog("info", message, metadata);
+    }
+    async warn(message, metadata) {
+        await this.addLog("warn", message, metadata);
+    }
+    async error(message, metadata) {
+        await this.addLog("error", message, metadata);
+    }
+    async preserve() {
+        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() {
+        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) {
+        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(spanName, fn) {
+        return await this.createAndRunSpan(this.spanId, spanName, fn);
+    }
+    async updateMetadata(metadata) {
+        await this.ctx
+            .runMutation(this.component.lib.updateSpanMetadata, {
+            spanId: this.spanId,
+            metadata,
+        })
+            .catch((err) => console.error("[Tracer] Failed to set metadata:", err));
+    }
+    createSpanAPI(spanId) {
+        return {
+            info: async (message, metadata) => {
+                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, metadata) => {
+                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, metadata) => {
+                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) => {
+                await this.ctx
+                    .runMutation(this.component.lib.updateSpanMetadata, {
+                    spanId,
+                    metadata,
+                })
+                    .catch((err) => console.error("[Tracer] Failed to set child span metadata:", err));
+            },
+            withSpan: async (spanName, fn) => {
+                return await this.createAndRunSpan(spanId, spanName, fn);
+            },
+        };
+    }
+    async createAndRunSpan(parentSpanId, spanName, fn) {
+        let childSpanId;
+        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;
+        }
+    }
+    createNoOpSpanAPI() {
+        return {
+            info: async () => { },
+            warn: async () => { },
+            error: async () => { },
+            updateMetadata: async () => { },
+            withSpan: async () => {
+                return undefined;
+            },
+        };
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/client/tracer-api/index.js.map

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

package/dist/client/tracer-api/types.d.ts

@@ -0,0 +1,143 @@
+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>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/client/tracer-api/types.js

@@ -0,0 +1,2 @@
+import { sourceValidator, statusValidator } from "../../component/schema";
+//# sourceMappingURL=types.js.map

package/dist/client/tracer-api/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/client/tracer-api/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC"}