@fallom/trace 0.2.26 → 0.2.28

package/dist/index.mjs

@@ -23,7 +23,7 @@ import {
   isCustomMetric,
   runGEval,
   uploadResultsPublic
-} from "./chunk-FTZVXPQN.mjs";
+} from "./chunk-MSI4HGK6.mjs";
 import {
   __export
 } from "./chunk-7P6ASYW6.mjs";
@@ -32,9 +32,11 @@ import {
 var trace_exports = {};
 __export(trace_exports, {
   FallomSession: () => FallomSession,
+  FallomSpan: () => FallomSpan,
   init: () => init3,
   session: () => session,
-  shutdown: () => shutdown
+  shutdown: () => shutdown,
+  wrapTraced: () => wrapTraced
 });
 
 // src/trace/core.ts
@@ -820,6 +822,109 @@ function generateHexId(length) {
   return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 
+// src/trace/span.ts
+var FallomSpan = class {
+  constructor(name, ctx, options = {}) {
+    this.name = name;
+    this.ctx = ctx;
+    this.attrs = {};
+    this.ended = false;
+    this._status = "OK";
+    this.spanId = generateHexId(16);
+    this.traceId = options.traceId || generateHexId(32);
+    this.parentSpanId = options.parentSpanId;
+    this.kind = options.kind || "custom";
+    this.startTime = Date.now();
+  }
+  /**
+   * Set attributes on the span.
+   * Can be called multiple times - attributes are merged.
+   */
+  set(attributes) {
+    if (this.ended) {
+      console.warn("[Fallom] Cannot set attributes on ended span");
+      return this;
+    }
+    Object.assign(this.attrs, attributes);
+    return this;
+  }
+  /**
+   * Mark the span as errored.
+   */
+  setError(error) {
+    this._status = "ERROR";
+    this._errorMessage = error instanceof Error ? error.message : error;
+    return this;
+  }
+  /**
+   * Get span context for creating child spans.
+   */
+  context() {
+    return {
+      traceId: this.traceId,
+      spanId: this.spanId
+    };
+  }
+  /**
+   * End the span and send it.
+   * Must be called for the span to be recorded.
+   */
+  end() {
+    if (this.ended) {
+      console.warn("[Fallom] Span already ended");
+      return;
+    }
+    this.ended = true;
+    if (!isInitialized()) {
+      return;
+    }
+    const endTime = Date.now();
+    sendTrace({
+      config_key: this.ctx.configKey,
+      session_id: this.ctx.sessionId,
+      customer_id: this.ctx.customerId,
+      metadata: this.ctx.metadata,
+      tags: this.ctx.tags,
+      trace_id: this.traceId,
+      span_id: this.spanId,
+      parent_span_id: this.parentSpanId,
+      name: this.name,
+      kind: this.kind,
+      start_time: new Date(this.startTime).toISOString(),
+      end_time: new Date(endTime).toISOString(),
+      duration_ms: endTime - this.startTime,
+      status: this._status,
+      error_message: this._errorMessage,
+      attributes: {
+        "fallom.sdk_version": "2",
+        "fallom.span_type": "manual",
+        ...this.attrs
+      }
+    }).catch(() => {
+    });
+  }
+};
+function wrapTraced(session2, name, fn, options = {}) {
+  return (async (...args) => {
+    const span = session2.span(name, options);
+    if (args.length === 1) {
+      span.set({ input: args[0] });
+    } else if (args.length > 1) {
+      span.set({ input: args });
+    }
+    try {
+      const result = await fn(...args);
+      span.set({ output: result });
+      span.end();
+      return result;
+    } catch (error) {
+      span.setError(error instanceof Error ? error : String(error));
+      span.end();
+      throw error;
+    }
+  });
+}
+
 // src/prompts.ts
 var prompts_exports = {};
 __export(prompts_exports, {
@@ -2689,6 +2794,26 @@ var FallomSession = class {
   getContext() {
     return { ...this.ctx };
   }
+  /**
+   * Create a manual span for custom operations.
+   *
+   * Use for non-LLM operations like RAG retrieval, preprocessing, tool execution, etc.
+   * The span uses the session's context (configKey, sessionId, etc.).
+   *
+   * @example
+   * ```typescript
+   * const span = session.span("rag.retrieve");
+   * span.set({ "rag.query": userQuery, "rag.topK": 5 });
+   *
+   * const docs = await retrieveDocuments(userQuery);
+   * span.set({ "rag.documents.count": docs.length });
+   *
+   * span.end(); // Must call to send the span
+   * ```
+   */
+  span(name, options) {
+    return new FallomSpan(name, this.ctx, options);
+  }
   /**
    * Get model assignment for this session (A/B testing).
    */
@@ -3168,6 +3293,7 @@ var index_default = {
 export {
   FallomExporter,
   FallomSession,
+  FallomSpan,
   buildGEvalPrompt,
   calculateAggregateScores,
   clearMastraPrompt,
@@ -3181,5 +3307,6 @@ export {
   session,
   setMastraPrompt,
   setMastraPromptAB,
-  trace_exports as trace
+  trace_exports as trace,
+  wrapTraced
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fallom/trace",
-  "version": "0.2.26",
+  "version": "0.2.28",
   "description": "Model A/B testing and tracing for LLM applications. Zero latency, production-ready.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -40,7 +40,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/fallom/fallom-js"
+    "url": "https://github.com/Fallomai/fallom-typescript-sdk"
   },
   "dependencies": {
     "@opentelemetry/api": "^1.7.0",