observa-sdk 0.0.6 → 0.0.7

package/dist/index.js

@@ -1,4 +1,12 @@
 // src/index.ts
+var contextModule = null;
+try {
+  const requireFn = globalThis.require;
+  if (typeof requireFn !== "undefined") {
+    contextModule = requireFn("./context.js");
+  }
+} catch {
+}
 function getNodeEnv() {
   try {
     const proc = globalThis.process;
@@ -221,6 +229,20 @@ var Observa = class {
   isProduction;
   sampleRate;
   maxResponseChars;
+  // Buffering and retry (now stores canonical events)
+  eventBuffer = [];
+  flushPromise = null;
+  flushInProgress = false;
+  maxBufferSize = 100;
+  flushIntervalMs = 5e3;
+  // Flush every 5 seconds
+  flushIntervalId = null;
+  // Span hierarchy tracking (for manual trace management)
+  currentTraceId = null;
+  rootSpanId = null;
+  spanStack = [];
+  // Stack for tracking parent-child relationships
+  traceStartTime = null;
   constructor(config) {
     this.apiKey = config.apiKey;
     let apiUrlEnv;
@@ -265,35 +287,465 @@ var Observa = class {
         `\u{1F517} [Observa] Auth: ${jwtContext ? "JWT (auto-extracted)" : "Legacy (config)"}`
       );
     }
+    try {
+      if (typeof setInterval !== "undefined") {
+        this.flushIntervalId = setInterval(() => {
+          this.flush().catch((err) => {
+            console.error("[Observa] Periodic flush failed:", err);
+          });
+        }, this.flushIntervalMs);
+      }
+    } catch {
+    }
+  }
+  /**
+   * Flush buffered events to the API
+   * Returns a promise that resolves when all events are sent
+   */
+  async flush() {
+    if (this.flushInProgress || this.eventBuffer.length === 0) {
+      return this.flushPromise || Promise.resolve();
+    }
+    this.flushInProgress = true;
+    this.flushPromise = this._doFlush();
+    try {
+      await this.flushPromise;
+    } finally {
+      this.flushInProgress = false;
+      this.flushPromise = null;
+    }
+  }
+  /**
+   * Helper: Create base event properties
+   */
+  createBaseEventProperties() {
+    const traceId = this.currentTraceId || crypto.randomUUID();
+    return {
+      tenant_id: this.tenantId,
+      project_id: this.projectId,
+      environment: this.environment,
+      trace_id: traceId
+    };
+  }
+  /**
+   * Helper: Add event to buffer with proper span hierarchy
+   */
+  addEvent(eventData) {
+    const baseProps = this.createBaseEventProperties();
+    const parentSpanId = this.spanStack.length > 0 ? this.spanStack[this.spanStack.length - 1] : null;
+    const event = {
+      ...baseProps,
+      span_id: eventData.span_id || crypto.randomUUID(),
+      parent_span_id: (eventData.parent_span_id !== void 0 ? eventData.parent_span_id : parentSpanId) ?? null,
+      timestamp: eventData.timestamp || (/* @__PURE__ */ new Date()).toISOString(),
+      event_type: eventData.event_type,
+      conversation_id: eventData.conversation_id ?? null,
+      session_id: eventData.session_id ?? null,
+      user_id: eventData.user_id ?? null,
+      agent_name: eventData.agent_name ?? null,
+      version: eventData.version ?? null,
+      route: eventData.route ?? null,
+      attributes: eventData.attributes
+    };
+    this.eventBuffer.push(event);
+    if (this.eventBuffer.length >= this.maxBufferSize) {
+      this.flush().catch((err) => {
+        console.error("[Observa] Auto-flush failed:", err);
+      });
+    }
+  }
+  /**
+   * Start a new trace (manual trace management)
+   */
+  startTrace(options = {}) {
+    if (this.currentTraceId) {
+      console.warn("[Observa] Ending previous trace before starting new one");
+      this.endTrace().catch(console.error);
+    }
+    this.currentTraceId = crypto.randomUUID();
+    this.rootSpanId = crypto.randomUUID();
+    this.spanStack = [this.rootSpanId];
+    this.traceStartTime = Date.now();
+    this.addEvent({
+      event_type: "trace_start",
+      span_id: this.rootSpanId,
+      parent_span_id: null,
+      conversation_id: options.conversationId || null,
+      session_id: options.sessionId || null,
+      user_id: options.userId || null,
+      attributes: {
+        trace_start: {
+          name: options.name || null,
+          metadata: options.metadata || null
+        }
+      }
+    });
+    return this.currentTraceId;
+  }
+  /**
+   * Track a tool call
+   */
+  trackToolCall(options) {
+    const spanId = crypto.randomUUID();
+    this.addEvent({
+      event_type: "tool_call",
+      span_id: spanId,
+      attributes: {
+        tool_call: {
+          tool_name: options.toolName,
+          args: options.args || null,
+          result: options.result || null,
+          result_status: options.resultStatus,
+          latency_ms: options.latencyMs,
+          error_message: options.errorMessage || null
+        }
+      }
+    });
+    return spanId;
+  }
+  /**
+   * Track a retrieval operation
+   */
+  trackRetrieval(options) {
+    const spanId = crypto.randomUUID();
+    this.addEvent({
+      event_type: "retrieval",
+      span_id: spanId,
+      attributes: {
+        retrieval: {
+          retrieval_context_ids: options.contextIds || null,
+          retrieval_context_hashes: options.contextHashes || null,
+          k: options.k || null,
+          top_k: options.k || null,
+          similarity_scores: options.similarityScores || null,
+          latency_ms: options.latencyMs
+        }
+      }
+    });
+    return spanId;
+  }
+  /**
+   * Track an error with stack trace support
+   */
+  trackError(options) {
+    const spanId = crypto.randomUUID();
+    let stackTrace = options.stackTrace;
+    if (!stackTrace && options.error instanceof Error && options.error.stack) {
+      stackTrace = options.error.stack;
+    }
+    this.addEvent({
+      event_type: "error",
+      span_id: spanId,
+      attributes: {
+        error: {
+          error_type: options.errorType,
+          error_message: options.errorMessage,
+          stack_trace: stackTrace || null,
+          context: options.context || null
+        }
+      }
+    });
+    return spanId;
+  }
+  /**
+   * Track user feedback
+   */
+  trackFeedback(options) {
+    const spanId = options.spanId || crypto.randomUUID();
+    const parentSpanId = options.parentSpanId ?? (this.spanStack.length > 0 ? this.spanStack[this.spanStack.length - 1] : null);
+    let rating = options.rating;
+    if (rating !== void 0 && rating !== null) {
+      rating = Math.max(1, Math.min(5, rating));
+    }
+    this.addEvent({
+      event_type: "feedback",
+      span_id: spanId,
+      parent_span_id: parentSpanId ?? null,
+      conversation_id: options.conversationId ?? null,
+      session_id: options.sessionId ?? null,
+      user_id: options.userId ?? null,
+      agent_name: options.agentName ?? null,
+      version: options.version ?? null,
+      route: options.route ?? null,
+      attributes: {
+        feedback: {
+          type: options.type,
+          rating: rating ?? null,
+          comment: options.comment || null,
+          outcome: options.outcome || null
+        }
+      }
+    });
+    return spanId;
+  }
+  /**
+   * Track final output
+   */
+  trackOutput(options) {
+    const spanId = crypto.randomUUID();
+    this.addEvent({
+      event_type: "output",
+      span_id: spanId,
+      attributes: {
+        output: {
+          final_output: options.finalOutput || null,
+          output_length: options.outputLength || null
+        }
+      }
+    });
+    return spanId;
+  }
+  /**
+   * Execute a function within a span context (for nested operations)
+   * This allows tool calls to be nested under LLM calls, etc.
+   */
+  withSpan(spanId, fn) {
+    this.spanStack.push(spanId);
+    try {
+      return fn();
+    } finally {
+      this.spanStack.pop();
+    }
+  }
+  /**
+   * Execute an async function within a span context (for nested operations)
+   */
+  async withSpanAsync(spanId, fn) {
+    this.spanStack.push(spanId);
+    try {
+      return await fn();
+    } finally {
+      this.spanStack.pop();
+    }
+  }
+  /**
+   * End trace and send events (manual trace management)
+   */
+  async endTrace(options = {}) {
+    if (!this.currentTraceId || !this.rootSpanId) {
+      throw new Error("[Observa] No active trace. Call startTrace() first.");
+    }
+    const traceEvents = this.eventBuffer.filter(
+      (e) => e.trace_id === this.currentTraceId
+    );
+    const llmEvents = traceEvents.filter((e) => e.event_type === "llm_call");
+    const totalTokens = llmEvents.reduce(
+      (sum, e) => sum + (e.attributes.llm_call?.total_tokens || 0),
+      0
+    );
+    const totalCost = llmEvents.reduce(
+      (sum, e) => sum + (e.attributes.llm_call?.cost || 0),
+      0
+    );
+    const totalLatency = this.traceStartTime !== null ? Date.now() - this.traceStartTime : null;
+    this.addEvent({
+      event_type: "trace_end",
+      span_id: this.rootSpanId,
+      parent_span_id: null,
+      attributes: {
+        trace_end: {
+          total_latency_ms: totalLatency,
+          total_tokens: totalTokens || null,
+          total_cost: totalCost || null,
+          outcome: options.outcome || "success"
+        }
+      }
+    });
+    const traceEventsToSend = this.eventBuffer.filter(
+      (e) => e.trace_id === this.currentTraceId
+    );
+    if (traceEventsToSend.length > 0) {
+      await this._sendEventsWithRetry(traceEventsToSend);
+      this.eventBuffer = this.eventBuffer.filter(
+        (e) => e.trace_id !== this.currentTraceId
+      );
+    }
+    const traceId = this.currentTraceId;
+    this.currentTraceId = null;
+    this.rootSpanId = null;
+    this.spanStack = [];
+    this.traceStartTime = null;
+    return traceId;
+  }
+  /**
+   * Convert legacy TraceData to canonical events
+   */
+  traceDataToCanonicalEvents(trace) {
+    const events = [];
+    const baseEvent = {
+      tenant_id: trace.tenantId,
+      project_id: trace.projectId,
+      environment: trace.environment,
+      trace_id: trace.traceId,
+      conversation_id: trace.conversationId || null,
+      session_id: trace.sessionId || null,
+      user_id: trace.userId || null
+    };
+    events.push({
+      ...baseEvent,
+      span_id: trace.spanId,
+      parent_span_id: trace.parentSpanId || null,
+      timestamp: trace.timestamp,
+      event_type: "trace_start",
+      attributes: {
+        trace_start: {
+          metadata: trace.metadata || null
+        }
+      }
+    });
+    if (trace.model) {
+      const llmSpanId = crypto.randomUUID();
+      events.push({
+        ...baseEvent,
+        span_id: llmSpanId,
+        parent_span_id: trace.spanId,
+        timestamp: trace.timestamp,
+        event_type: "llm_call",
+        attributes: {
+          llm_call: {
+            model: trace.model,
+            input: trace.query || null,
+            output: trace.response || null,
+            input_tokens: trace.tokensPrompt || null,
+            output_tokens: trace.tokensCompletion || null,
+            total_tokens: trace.tokensTotal || null,
+            latency_ms: trace.latencyMs,
+            time_to_first_token_ms: trace.timeToFirstTokenMs || null,
+            streaming_duration_ms: trace.streamingDurationMs || null,
+            finish_reason: trace.finishReason || null,
+            response_id: trace.responseId || null,
+            system_fingerprint: trace.systemFingerprint || null,
+            cost: null
+            // Cost calculation handled by backend
+          }
+        }
+      });
+    }
+    events.push({
+      ...baseEvent,
+      span_id: crypto.randomUUID(),
+      parent_span_id: trace.spanId,
+      timestamp: trace.timestamp,
+      event_type: "output",
+      attributes: {
+        output: {
+          final_output: trace.response || null,
+          output_length: trace.responseLength || null
+        }
+      }
+    });
+    events.push({
+      ...baseEvent,
+      span_id: trace.spanId,
+      parent_span_id: trace.parentSpanId || null,
+      timestamp: trace.timestamp,
+      event_type: "trace_end",
+      attributes: {
+        trace_end: {
+          total_latency_ms: trace.latencyMs,
+          total_tokens: trace.tokensTotal || null,
+          total_cost: null,
+          // Cost calculation handled by backend
+          outcome: trace.status && trace.status >= 200 && trace.status < 300 ? "success" : "error"
+        }
+      }
+    });
+    return events;
   }
-  async track(event, action) {
+  /**
+   * Internal flush implementation
+   */
+  async _doFlush() {
+    const eventsToFlush = [...this.eventBuffer];
+    this.eventBuffer = [];
+    if (eventsToFlush.length === 0) {
+      return;
+    }
+    const eventsByTrace = /* @__PURE__ */ new Map();
+    for (const event of eventsToFlush) {
+      if (!eventsByTrace.has(event.trace_id)) {
+        eventsByTrace.set(event.trace_id, []);
+      }
+      eventsByTrace.get(event.trace_id).push(event);
+    }
+    for (const [traceId, events] of eventsByTrace.entries()) {
+      await this._sendEventsWithRetry(events);
+    }
+  }
+  /**
+   * Send canonical events with exponential backoff retry
+   */
+  async _sendEventsWithRetry(events, maxRetries = 3) {
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        await this.sendEvents(events);
+        return;
+      } catch (error) {
+        if (attempt === maxRetries) {
+          console.error(
+            `[Observa] Failed to send events after ${maxRetries + 1} attempts, re-buffering:`,
+            error
+          );
+          this.eventBuffer.push(...events);
+          if (this.eventBuffer.length > this.maxBufferSize * 2) {
+            const toDrop = this.eventBuffer.length - this.maxBufferSize;
+            this.eventBuffer.splice(0, toDrop);
+          }
+          return;
+        }
+        const delayMs = 100 * Math.pow(2, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+    }
+  }
+  /**
+   * Cleanup (call when shutting down)
+   */
+  async end() {
+    if (this.flushIntervalId) {
+      clearInterval(this.flushIntervalId);
+      this.flushIntervalId = null;
+    }
+    await this.flush();
+  }
+  async track(event, action, options) {
     if (this.sampleRate < 1 && Math.random() > this.sampleRate) {
       return action();
     }
     const startTime = Date.now();
     const traceId = crypto.randomUUID();
     const spanId = traceId;
-    const originalResponse = await action();
+    const runWithContext = contextModule?.runInTraceContextAsync || ((ctx, fn) => fn());
+    const context = contextModule?.createSpanContext?.(
+      traceId,
+      spanId,
+      null
+    ) || { traceId, spanId, parentSpanId: null };
+    const originalResponse = await runWithContext(context, action);
     if (!originalResponse.body) return originalResponse;
     const responseHeaders = {};
     originalResponse.headers.forEach((value, key) => {
       responseHeaders[key] = value;
     });
     const [stream1, stream2] = originalResponse.body.tee();
-    console.log(`[Observa] Starting captureStream for trace ${traceId}`);
-    this.captureStream({
+    const capturePromise = this.captureStream({
       stream: stream2,
       event,
       traceId,
       spanId,
-      parentSpanId: null,
+      parentSpanId: context.parentSpanId,
       startTime,
       status: originalResponse.status,
       statusText: originalResponse.statusText,
       headers: responseHeaders
-    }).catch((err) => {
-      console.error("[Observa] captureStream promise rejected:", err);
     });
+    if (options?.trackBlocking) {
+      await capturePromise;
+    } else {
+      capturePromise.catch((err) => {
+        console.error("[Observa] captureStream promise rejected:", err);
+      });
+    }
     return new Response(stream1, {
       headers: originalResponse.headers,
       status: originalResponse.status,
@@ -395,17 +847,40 @@ var Observa = class {
         systemFingerprint: extracted.systemFingerprint ?? null,
         ...headers !== void 0 && { headers },
         // Conversation tracking fields
-        ...event.conversationId !== void 0 && { conversationId: event.conversationId },
+        ...event.conversationId !== void 0 && {
+          conversationId: event.conversationId
+        },
         ...event.sessionId !== void 0 && { sessionId: event.sessionId },
         ...event.userId !== void 0 && { userId: event.userId },
-        ...event.messageIndex !== void 0 && { messageIndex: event.messageIndex },
-        ...event.parentMessageId !== void 0 && { parentMessageId: event.parentMessageId }
+        ...event.messageIndex !== void 0 && {
+          messageIndex: event.messageIndex
+        },
+        ...event.parentMessageId !== void 0 && {
+          parentMessageId: event.parentMessageId
+        }
       };
       console.log(
-        `[Observa] Trace data prepared, calling sendTrace for ${traceId}, response length: ${fullResponse.length}`
+        `[Observa] Trace data prepared, converting to canonical events for ${traceId}, response length: ${fullResponse.length}`
       );
-      await this.sendTrace(traceData);
-      console.log(`[Observa] sendTrace completed for ${traceId}`);
+      const canonicalEvents = this.traceDataToCanonicalEvents(traceData);
+      this.eventBuffer.push(...canonicalEvents);
+      if (this.eventBuffer.length >= this.maxBufferSize) {
+        this.flush().catch((err) => {
+          console.error("[Observa] Auto-flush failed:", err);
+        });
+      } else {
+        this._sendEventsWithRetry(canonicalEvents).catch((err) => {
+          console.error("[Observa] Failed to send events:", err);
+        });
+      }
+      if (!this.isProduction) {
+        const traceUrl = `${this.apiUrl.replace(
+          /\/api.*$/,
+          ""
+        )}/traces/${traceId}`;
+        console.log(`[Observa] \u{1F54A}\uFE0F Trace captured: ${traceUrl}`);
+      }
+      console.log(`[Observa] Trace queued for sending: ${traceId}`);
     } catch (err) {
       console.error("[Observa] Error capturing stream:", err);
       if (err instanceof Error) {
@@ -417,15 +892,57 @@ var Observa = class {
       }
     }
   }
-  async sendTrace(trace) {
-    if (!this.isProduction) {
-      formatBeautifulLog(trace);
+  /**
+   * Send canonical events to Observa backend
+   * (internal method, use _sendEventsWithRetry for retry logic)
+   */
+  async sendEvents(events) {
+    if (events.length === 0) {
+      return;
+    }
+    const traceId = events[0]?.trace_id;
+    if (!this.isProduction && traceId) {
+      const llmEvent = events.find((e) => e.event_type === "llm_call");
+      const outputEvent = events.find((e) => e.event_type === "output");
+      const traceEndEvent = events.find((e) => e.event_type === "trace_end");
+      if (llmEvent && outputEvent) {
+        const llmAttrs = llmEvent.attributes.llm_call;
+        const outputAttrs = outputEvent.attributes.output;
+        const traceData = {
+          traceId: llmEvent.trace_id,
+          spanId: llmEvent.parent_span_id || llmEvent.span_id,
+          parentSpanId: llmEvent.parent_span_id || null,
+          timestamp: llmEvent.timestamp,
+          tenantId: llmEvent.tenant_id,
+          projectId: llmEvent.project_id,
+          environment: llmEvent.environment,
+          query: llmAttrs?.input || "",
+          response: outputAttrs?.final_output || "",
+          responseLength: outputAttrs?.output_length || 0,
+          ...llmAttrs?.model && { model: llmAttrs.model },
+          tokensPrompt: llmAttrs?.input_tokens ?? null,
+          tokensCompletion: llmAttrs?.output_tokens ?? null,
+          tokensTotal: llmAttrs?.total_tokens ?? null,
+          latencyMs: llmAttrs?.latency_ms || 0,
+          timeToFirstTokenMs: llmAttrs?.time_to_first_token_ms ?? null,
+          streamingDurationMs: llmAttrs?.streaming_duration_ms ?? null,
+          finishReason: llmAttrs?.finish_reason ?? null,
+          responseId: llmAttrs?.response_id ?? null,
+          systemFingerprint: llmAttrs?.system_fingerprint ?? null,
+          ...llmEvent.conversation_id && {
+            conversationId: llmEvent.conversation_id
+          },
+          ...llmEvent.session_id && { sessionId: llmEvent.session_id },
+          ...llmEvent.user_id && { userId: llmEvent.user_id }
+        };
+        formatBeautifulLog(traceData);
+      }
     }
     try {
       const baseUrl = this.apiUrl.replace(/\/+$/, "");
-      const url = `${baseUrl}/api/v1/traces/ingest`;
+      const url = `${baseUrl}/api/v1/events/ingest`;
       console.log(
-        `[Observa] Sending trace - URL: ${url}, TraceID: ${trace.traceId}, Tenant: ${trace.tenantId}, Project: ${trace.projectId}, APIKey: ${this.apiKey ? `Yes(${this.apiKey.length} chars)` : "No"}`
+        `[Observa] Sending ${events.length} canonical events - URL: ${url}, TraceID: ${traceId}, Tenant: ${events[0]?.tenant_id}, Project: ${events[0]?.project_id}, APIKey: ${this.apiKey ? `Yes(${this.apiKey.length} chars)` : "No"}`
       );
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), 1e4);
@@ -436,7 +953,7 @@ var Observa = class {
             Authorization: `Bearer ${this.apiKey}`,
             "Content-Type": "application/json"
           },
-          body: JSON.stringify(trace),
+          body: JSON.stringify(events),
           signal: controller.signal
         });
         clearTimeout(timeoutId);
@@ -455,9 +972,13 @@ var Observa = class {
             `[Observa] Backend API error: ${response.status} ${response.statusText}`,
             errorJson.error || errorText
           );
+          throw new Error(
+            `Observa API error: ${response.status} ${errorJson.error?.message || errorText}`
+          );
         } else {
+          const result = await response.json().catch(() => ({}));
           console.log(
-            `\u2705 [Observa] Trace sent successfully - Trace ID: ${trace.traceId}`
+            `\u2705 [Observa] Events sent successfully - Trace ID: ${traceId}, Event count: ${result.event_count || events.length}`
           );
         }
       } catch (fetchError) {
@@ -468,7 +989,7 @@ var Observa = class {
         throw fetchError;
       }
     } catch (error) {
-      console.error("[Observa] Failed to send trace:", error);
+      console.error("[Observa] Failed to send events:", error);
       if (error instanceof Error) {
         console.error("[Observa] Error message:", error.message);
         console.error("[Observa] Error name:", error.name);
@@ -481,6 +1002,7 @@ var Observa = class {
           console.error("[Observa] Error stack:", error.stack);
         }
       }
+      throw error;
     }
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "observa-sdk",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Enterprise-grade observability SDK for AI applications. Track and monitor LLM interactions with zero friction.",
   "type": "module",
   "main": "./dist/index.cjs",