observa-sdk 0.0.17 → 0.0.19

package/dist/index.cjs

@@ -194,6 +194,96 @@ function getTraceContext() {
   }
 }
 
+// src/instrumentation/error-utils.ts
+function extractErrorCode(error, provider) {
+  if (!error) return null;
+  if (provider === "openai" || provider === "vercel-ai") {
+    if (error.code) return error.code;
+    if (error.type) return error.type;
+    if (error.status === 401) return "invalid_api_key";
+    if (error.status === 429) return "rate_limit_exceeded";
+    if (error.status === 400) return "invalid_request";
+    if (error.status === 403) return "insufficient_quota";
+    if (error.status === 404) return "model_not_found";
+    if (error.status === 500) return "internal_server_error";
+    if (error.status === 502) return "bad_gateway";
+    if (error.status === 503) return "service_unavailable";
+  }
+  if (provider === "anthropic") {
+    if (error.error?.type) return error.error.type;
+    if (error.status === 401) return "invalid_api_key";
+    if (error.status === 429) return "rate_limit_error";
+    if (error.status === 400) return "invalid_request";
+    if (error.status === 500) return "internal_server_error";
+  }
+  if (error.status) {
+    if (error.status === 401) return "unauthorized";
+    if (error.status === 403) return "forbidden";
+    if (error.status === 404) return "not_found";
+    if (error.status === 429) return "rate_limit_exceeded";
+    if (error.status >= 500) return "server_error";
+  }
+  const message = String(error.message || error);
+  if (message.toLowerCase().includes("timeout")) return "timeout_error";
+  if (message.toLowerCase().includes("network")) return "network_error";
+  if (message.toLowerCase().includes("connection")) return "connection_error";
+  return null;
+}
+function categorizeError(error, provider) {
+  if (!error) return "unknown_error";
+  const statusCode = error.status || error.statusCode || error.status_code;
+  const errorCode = extractErrorCode(error, provider);
+  const message = String(error.message || error.error?.message || error || "").toLowerCase();
+  if (statusCode === 401 || statusCode === 403 || errorCode === "invalid_api_key" || errorCode === "unauthorized" || errorCode === "forbidden" || message.includes("authentication") || message.includes("unauthorized") || message.includes("invalid api key") || message.includes("invalid api_token")) {
+    return "authentication_error";
+  }
+  if (statusCode === 429 || errorCode === "rate_limit_exceeded" || errorCode === "rate_limit_error" || message.includes("rate limit") || message.includes("too many requests")) {
+    return "rate_limit_error";
+  }
+  if (statusCode === 400 || errorCode === "invalid_request" || message.includes("validation") || message.includes("invalid") || message.includes("bad request")) {
+    return "validation_error";
+  }
+  if (errorCode === "timeout_error" || message.includes("timeout") || message.includes("timed out") || message.includes("request timeout")) {
+    return "timeout_error";
+  }
+  if (errorCode === "network_error" || errorCode === "connection_error" || message.includes("network") || message.includes("connection") || message.includes("econn") || message.includes("enotfound") || message.includes("eai_again")) {
+    return "network_error";
+  }
+  if (statusCode >= 500 || errorCode === "internal_server_error" || errorCode === "server_error" || errorCode === "bad_gateway" || errorCode === "service_unavailable" || message.includes("server error") || message.includes("internal error")) {
+    return "server_error";
+  }
+  if (errorCode === "insufficient_quota" || message.includes("quota") || message.includes("billing") || message.includes("credits")) {
+    return "quota_error";
+  }
+  if (statusCode === 404 || errorCode === "model_not_found" || errorCode === "not_found" || message.includes("model not found") || message.includes("model unavailable")) {
+    return "model_error";
+  }
+  return "unknown_error";
+}
+function extractProviderError(error, provider) {
+  const code = extractErrorCode(error, provider) || "unknown_error";
+  const category = categorizeError(error, provider);
+  const statusCode = error.status || error.statusCode || error.status_code;
+  let message = "An unknown error occurred";
+  if (error.message) {
+    message = error.message;
+  } else if (error.error?.message) {
+    message = error.error.message;
+  } else if (error.response?.data?.error?.message) {
+    message = error.response.data.error.message;
+  } else if (typeof error === "string") {
+    message = error;
+  } else if (error.toString && error.toString() !== "[object Object]") {
+    message = error.toString();
+  }
+  return {
+    code,
+    category,
+    message,
+    statusCode
+  };
+}
+
 // src/instrumentation/openai.ts
 var proxyCache = /* @__PURE__ */ new WeakMap();
 function observeOpenAI(client, options) {
@@ -229,6 +319,9 @@ async function traceOpenAICall(originalFn, args, options) {
   const startTime = Date.now();
   const requestParams = args[0] || {};
   const isStreaming = requestParams.stream === true;
+  const inputText = requestParams.messages?.map((m) => m.content).filter(Boolean).join("\n") || null;
+  const inputMessages = requestParams.messages || null;
+  const model = requestParams.model || "unknown";
   try {
     const result = await originalFn(...args);
     if (isStreaming) {
@@ -244,7 +337,15 @@ async function traceOpenAICall(originalFn, args, options) {
             fullResponse.streamingDuration
           );
         },
-        (err) => recordError(requestParams, err, startTime, options),
+        (err) => recordError(
+          requestParams,
+          err,
+          startTime,
+          options,
+          inputText,
+          inputMessages,
+          model
+        ),
         "openai"
       );
     } else {
@@ -252,7 +353,15 @@ async function traceOpenAICall(originalFn, args, options) {
       return result;
     }
   } catch (error) {
-    recordError(requestParams, error, startTime, options);
+    recordError(
+      requestParams,
+      error,
+      startTime,
+      options,
+      inputText,
+      inputMessages,
+      model
+    );
     throw error;
   }
 }
@@ -291,20 +400,26 @@ function recordTrace(req, res, start, opts, timeToFirstToken, streamingDuration)
     console.error("[Observa] Failed to record trace", e);
   }
 }
-function recordError(req, error, start, opts) {
+function recordError(req, error, start, opts, preExtractedInputText, preExtractedInputMessages, preExtractedModel) {
   const duration = Date.now() - start;
   try {
     console.error("[Observa] \u26A0\uFE0F Error Captured:", error?.message || error);
     const sanitizedReq = opts?.redact ? opts.redact(req) : req;
     if (opts?.observa) {
-      const model = sanitizedReq.model || "unknown";
-      const inputText = sanitizedReq.messages?.map((m) => m.content).filter(Boolean).join("\n") || null;
+      const model = preExtractedModel || sanitizedReq.model || "unknown";
+      let inputText = preExtractedInputText || null;
+      let inputMessages = preExtractedInputMessages || null;
+      if (!inputText) {
+        inputMessages = sanitizedReq.messages || null;
+        inputText = sanitizedReq.messages?.map((m) => m.content).filter(Boolean).join("\n") || null;
+      }
+      const extractedError = extractProviderError(error, "openai");
       opts.observa.trackLLMCall({
         model,
         input: inputText,
         output: null,
         // No output on error
-        inputMessages: sanitizedReq.messages || null,
+        inputMessages,
         outputMessages: null,
         inputTokens: null,
         outputTokens: null,
@@ -321,17 +436,19 @@ function recordError(req, error, start, opts) {
         maxTokens: sanitizedReq.max_tokens || null
       });
       opts.observa.trackError({
-        errorType: "openai_api_error",
-        errorMessage: error?.message || String(error),
+        errorType: error?.name || extractedError.code || "openai_api_error",
+        errorMessage: extractedError.message,
         stackTrace: error?.stack || null,
         context: {
           request: sanitizedReq,
           model,
           input: inputText,
           provider: "openai",
-          duration_ms: duration
+          duration_ms: duration,
+          status_code: extractedError.statusCode || null
         },
-        errorCategory: "llm_error"
+        errorCategory: extractedError.category,
+        errorCode: extractedError.code
       });
     }
   } catch (e) {
@@ -374,6 +491,15 @@ async function traceAnthropicCall(originalFn, args, options) {
   const startTime = Date.now();
   const requestParams = args[0] || {};
   const isStreaming = requestParams.stream === true;
+  const inputText = requestParams.messages?.map((m) => {
+    if (typeof m.content === "string") return m.content;
+    if (Array.isArray(m.content)) {
+      return m.content.map((c) => c.text || c.type).filter(Boolean).join("\n");
+    }
+    return null;
+  }).filter(Boolean).join("\n") || null;
+  const inputMessages = requestParams.messages || null;
+  const model = requestParams.model || "unknown";
   try {
     const result = await originalFn(...args);
     if (isStreaming) {
@@ -389,7 +515,15 @@ async function traceAnthropicCall(originalFn, args, options) {
             fullResponse.streamingDuration
           );
         },
-        (err) => recordError2(requestParams, err, startTime, options),
+        (err) => recordError2(
+          requestParams,
+          err,
+          startTime,
+          options,
+          inputText,
+          inputMessages,
+          model
+        ),
         "anthropic"
       );
     } else {
@@ -397,7 +531,15 @@ async function traceAnthropicCall(originalFn, args, options) {
       return result;
     }
   } catch (error) {
-    recordError2(requestParams, error, startTime, options);
+    recordError2(
+      requestParams,
+      error,
+      startTime,
+      options,
+      inputText,
+      inputMessages,
+      model
+    );
     throw error;
   }
 }
@@ -441,26 +583,32 @@ function recordTrace2(req, res, start, opts, timeToFirstToken, streamingDuration
     console.error("[Observa] Failed to record trace", e);
   }
 }
-function recordError2(req, error, start, opts) {
+function recordError2(req, error, start, opts, preExtractedInputText, preExtractedInputMessages, preExtractedModel) {
   const duration = Date.now() - start;
   try {
     console.error("[Observa] \u26A0\uFE0F Error Captured:", error?.message || error);
     const sanitizedReq = opts?.redact ? opts.redact(req) : req;
     if (opts?.observa) {
-      const model = sanitizedReq.model || "unknown";
-      const inputText = sanitizedReq.messages?.map((m) => {
-        if (typeof m.content === "string") return m.content;
-        if (Array.isArray(m.content)) {
-          return m.content.map((c) => c.text || c.type).filter(Boolean).join("\n");
-        }
-        return null;
-      }).filter(Boolean).join("\n") || null;
+      const model = preExtractedModel || sanitizedReq.model || "unknown";
+      let inputText = preExtractedInputText || null;
+      let inputMessages = preExtractedInputMessages || null;
+      if (!inputText) {
+        inputMessages = sanitizedReq.messages || null;
+        inputText = sanitizedReq.messages?.map((m) => {
+          if (typeof m.content === "string") return m.content;
+          if (Array.isArray(m.content)) {
+            return m.content.map((c) => c.text || c.type).filter(Boolean).join("\n");
+          }
+          return null;
+        }).filter(Boolean).join("\n") || null;
+      }
+      const extractedError = extractProviderError(error, "anthropic");
       opts.observa.trackLLMCall({
         model,
         input: inputText,
         output: null,
         // No output on error
-        inputMessages: sanitizedReq.messages || null,
+        inputMessages,
         outputMessages: null,
         inputTokens: null,
         outputTokens: null,
@@ -477,17 +625,19 @@ function recordError2(req, error, start, opts) {
         maxTokens: sanitizedReq.max_tokens || null
       });
       opts.observa.trackError({
-        errorType: "anthropic_api_error",
-        errorMessage: error?.message || String(error),
+        errorType: error?.name || extractedError.code || "anthropic_api_error",
+        errorMessage: extractedError.message,
         stackTrace: error?.stack || null,
         context: {
           request: sanitizedReq,
           model,
           input: inputText,
           provider: "anthropic",
-          duration_ms: duration
+          duration_ms: duration,
+          status_code: extractedError.statusCode || null
         },
-        errorCategory: "llm_error"
+        errorCategory: extractedError.category,
+        errorCode: extractedError.code
       });
     }
   } catch (e) {
@@ -566,6 +716,14 @@ async function traceGenerateText(originalFn, args, options) {
   const model = requestParams.model || "unknown";
   const provider = extractProviderFromModel(model);
   const modelIdentifier = extractModelIdentifier(model);
+  let inputText = null;
+  let inputMessages = null;
+  if (requestParams.prompt) {
+    inputText = typeof requestParams.prompt === "string" ? requestParams.prompt : JSON.stringify(requestParams.prompt);
+  } else if (requestParams.messages) {
+    inputMessages = requestParams.messages;
+    inputText = requestParams.messages.map((m) => m.content || m.text || "").filter(Boolean).join("\n");
+  }
   try {
     const result = await originalFn(...args);
     const responseText = result.text || "";
@@ -606,7 +764,9 @@ async function traceGenerateText(originalFn, args, options) {
       error,
       startTime,
       options,
-      provider
+      provider,
+      inputText,
+      inputMessages
     );
     throw error;
   }
@@ -664,6 +824,14 @@ async function traceStreamText(originalFn, args, options) {
   const model = requestParams.model || "unknown";
   const provider = extractProviderFromModel(model);
   const modelIdentifier = extractModelIdentifier(model);
+  let inputText = null;
+  let inputMessages = null;
+  if (requestParams.prompt) {
+    inputText = typeof requestParams.prompt === "string" ? requestParams.prompt : JSON.stringify(requestParams.prompt);
+  } else if (requestParams.messages) {
+    inputMessages = requestParams.messages;
+    inputText = requestParams.messages.map((m) => m.content || m.text || "").filter(Boolean).join("\n");
+  }
   try {
     const result = await originalFn(...args);
     if (result.textStream) {
@@ -698,7 +866,9 @@ async function traceStreamText(originalFn, args, options) {
             err,
             startTime,
             options,
-            provider
+            provider,
+            inputText,
+            inputMessages
           )
         );
         const wrappedResult = Object.create(Object.getPrototypeOf(result));
@@ -738,7 +908,9 @@ async function traceStreamText(originalFn, args, options) {
       error,
       startTime,
       options,
-      provider
+      provider,
+      inputText,
+      inputMessages
     );
     throw error;
   }
@@ -785,21 +957,25 @@ function recordTrace3(req, res, start, opts, timeToFirstToken, streamingDuration
     console.error("[Observa] Failed to record trace", e);
   }
 }
-function recordError3(req, error, start, opts, provider) {
+function recordError3(req, error, start, opts, provider, preExtractedInputText, preExtractedInputMessages) {
   const duration = Date.now() - start;
   try {
-    console.error("[Observa] \u26A0\uFE0F Error Captured:", error.message);
+    console.error("[Observa] \u26A0\uFE0F Error Captured:", error?.message || error);
     const sanitizedReq = opts?.redact ? opts.redact(req) : req;
     if (opts?.observa) {
       const model = sanitizedReq.model || "unknown";
-      let inputText = null;
-      let inputMessages = null;
-      if (sanitizedReq.prompt) {
-        inputText = typeof sanitizedReq.prompt === "string" ? sanitizedReq.prompt : JSON.stringify(sanitizedReq.prompt);
-      } else if (sanitizedReq.messages) {
-        inputMessages = sanitizedReq.messages;
-        inputText = sanitizedReq.messages.map((m) => m.content || m.text || "").filter(Boolean).join("\n");
+      let inputText = preExtractedInputText || null;
+      let inputMessages = preExtractedInputMessages || null;
+      if (!inputText) {
+        if (sanitizedReq.prompt) {
+          inputText = typeof sanitizedReq.prompt === "string" ? sanitizedReq.prompt : JSON.stringify(sanitizedReq.prompt);
+        } else if (sanitizedReq.messages) {
+          inputMessages = sanitizedReq.messages;
+          inputText = sanitizedReq.messages.map((m) => m.content || m.text || "").filter(Boolean).join("\n");
+        }
       }
+      const providerName = provider || "vercel-ai";
+      const extractedError = extractProviderError(error, providerName);
       opts.observa.trackLLMCall({
         model,
         input: inputText,
@@ -816,23 +992,25 @@ function recordError3(req, error, start, opts, provider) {
         finishReason: null,
         responseId: null,
         operationName: "generate_text",
-        providerName: provider || "vercel-ai",
+        providerName,
         responseModel: model,
         temperature: sanitizedReq.temperature || null,
         maxTokens: sanitizedReq.maxTokens || sanitizedReq.max_tokens || null
       });
       opts.observa.trackError({
-        errorType: error.name || "UnknownError",
-        errorMessage: error.message || "An unknown error occurred",
-        stackTrace: error.stack,
+        errorType: error?.name || extractedError.code || "UnknownError",
+        errorMessage: extractedError.message,
+        stackTrace: error?.stack || null,
         context: {
           request: sanitizedReq,
           model,
           input: inputText,
-          provider: provider || "vercel-ai",
-          duration_ms: duration
+          provider: providerName,
+          duration_ms: duration,
+          status_code: extractedError.statusCode || null
         },
-        errorCategory: "llm_error"
+        errorCategory: extractedError.category,
+        errorCode: extractedError.code
       });
     }
   } catch (e) {
@@ -1104,6 +1282,10 @@ var Observa = class {
   spanStack = [];
   // Stack for tracking parent-child relationships
   traceStartTime = null;
+  // Track traces with errors (for automatic trace_end generation when using instrumentation)
+  tracesWithErrors = /* @__PURE__ */ new Set();
+  // Track root span IDs for traces (for automatic trace_end generation)
+  traceRootSpanIds = /* @__PURE__ */ new Map();
   constructor(config) {
     this.apiKey = config.apiKey;
     let apiUrlEnv;
@@ -1194,9 +1376,13 @@ var Observa = class {
   addEvent(eventData) {
     const baseProps = this.createBaseEventProperties();
     const parentSpanId = this.spanStack.length > 0 ? this.spanStack[this.spanStack.length - 1] : null;
+    const spanId = eventData.span_id || crypto.randomUUID();
+    if (!this.currentTraceId && !this.traceRootSpanIds.has(baseProps.trace_id)) {
+      this.traceRootSpanIds.set(baseProps.trace_id, spanId);
+    }
     const event = {
       ...baseProps,
-      span_id: eventData.span_id || crypto.randomUUID(),
+      span_id: spanId,
       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,
@@ -1381,6 +1567,8 @@ var Observa = class {
     if (!stackTrace && options.error instanceof Error && options.error.stack) {
       stackTrace = options.error.stack;
     }
+    const baseProps = this.createBaseEventProperties();
+    this.tracesWithErrors.add(baseProps.trace_id);
     this.addEvent({
       event_type: "error",
       span_id: spanId,
@@ -1748,6 +1936,65 @@ var Observa = class {
       eventsByTrace.get(event.trace_id).push(event);
     }
     for (const [traceId, events] of eventsByTrace.entries()) {
+      const hasTraceStart = events.some((e) => e.event_type === "trace_start");
+      const hasTraceEnd = events.some((e) => e.event_type === "trace_end");
+      const hasError = this.tracesWithErrors.has(traceId);
+      const rootSpanId = this.traceRootSpanIds.get(traceId) || events[0]?.span_id || crypto.randomUUID();
+      const firstEvent = events[0];
+      if (!firstEvent) continue;
+      if (!hasTraceStart) {
+        const traceStartEvent = {
+          tenant_id: firstEvent.tenant_id,
+          project_id: firstEvent.project_id,
+          environment: firstEvent.environment,
+          trace_id: traceId,
+          span_id: rootSpanId,
+          parent_span_id: null,
+          timestamp: firstEvent.timestamp,
+          event_type: "trace_start",
+          attributes: {
+            trace_start: {
+              name: null,
+              metadata: null
+            }
+          }
+        };
+        events.unshift(traceStartEvent);
+      }
+      if (!hasTraceEnd) {
+        const llmEvents = events.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 timestamps = events.map((e) => new Date(e.timestamp).getTime()).filter(Boolean);
+        const totalLatency = timestamps.length > 0 ? Math.max(...timestamps) - Math.min(...timestamps) : null;
+        const traceEndEvent = {
+          tenant_id: firstEvent.tenant_id,
+          project_id: firstEvent.project_id,
+          environment: firstEvent.environment,
+          trace_id: traceId,
+          span_id: rootSpanId,
+          parent_span_id: null,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          event_type: "trace_end",
+          attributes: {
+            trace_end: {
+              total_latency_ms: totalLatency,
+              total_tokens: totalTokens || null,
+              total_cost: totalCost || null,
+              outcome: hasError ? "error" : "success"
+            }
+          }
+        };
+        events.push(traceEndEvent);
+      }
+      this.tracesWithErrors.delete(traceId);
+      this.traceRootSpanIds.delete(traceId);
       await this._sendEventsWithRetry(events);
     }
   }
@@ -1789,11 +2036,11 @@ var Observa = class {
   }
   /**
    * Observe OpenAI client - wraps client with automatic tracing
-   * 
+   *
    * @param client - OpenAI client instance
    * @param options - Observation options (name, tags, userId, sessionId, redact)
    * @returns Wrapped OpenAI client
-   * 
+   *
    * @example
    * ```typescript
    * import OpenAI from 'openai';
@@ -1814,11 +2061,11 @@ var Observa = class {
   }
   /**
    * Observe Anthropic client - wraps client with automatic tracing
-   * 
+   *
    * @param client - Anthropic client instance
    * @param options - Observation options (name, tags, userId, sessionId, redact)
    * @returns Wrapped Anthropic client
-   * 
+   *
    * @example
    * ```typescript
    * import Anthropic from '@anthropic-ai/sdk';
@@ -1839,21 +2086,21 @@ var Observa = class {
   }
   /**
    * Observe Vercel AI SDK - wraps generateText and streamText functions
-   * 
+   *
    * @param aiSdk - Vercel AI SDK module (imported from 'ai')
    * @param options - Observation options (name, tags, userId, sessionId, redact)
    * @returns Wrapped AI SDK with automatic tracing
-   * 
+   *
    * @example
    * ```typescript
    * import { generateText, streamText } from 'ai';
    * const observa = init({ apiKey: '...' });
-   * 
+   *
    * const ai = observa.observeVercelAI({ generateText, streamText }, {
    *   name: 'my-app',
    *   redact: (data) => ({ ...data, prompt: '[REDACTED]' })
    * });
-   * 
+   *
    * // Use wrapped functions - automatically tracked!
    * const result = await ai.generateText({
    *   model: 'openai/gpt-4',

package/dist/index.d.cts

@@ -38,6 +38,8 @@ declare class Observa {
     private rootSpanId;
     private spanStack;
     private traceStartTime;
+    private tracesWithErrors;
+    private traceRootSpanIds;
     constructor(config: ObservaInitConfig);
     /**
      * Flush buffered events to the API

package/dist/index.d.ts

@@ -38,6 +38,8 @@ declare class Observa {
     private rootSpanId;
     private spanStack;
     private traceStartTime;
+    private tracesWithErrors;
+    private traceRootSpanIds;
     constructor(config: ObservaInitConfig);
     /**
      * Flush buffered events to the API

package/dist/index.js

@@ -174,6 +174,96 @@ function getTraceContext() {
   }
 }
 
+// src/instrumentation/error-utils.ts
+function extractErrorCode(error, provider) {
+  if (!error) return null;
+  if (provider === "openai" || provider === "vercel-ai") {
+    if (error.code) return error.code;
+    if (error.type) return error.type;
+    if (error.status === 401) return "invalid_api_key";
+    if (error.status === 429) return "rate_limit_exceeded";
+    if (error.status === 400) return "invalid_request";
+    if (error.status === 403) return "insufficient_quota";
+    if (error.status === 404) return "model_not_found";
+    if (error.status === 500) return "internal_server_error";
+    if (error.status === 502) return "bad_gateway";
+    if (error.status === 503) return "service_unavailable";
+  }
+  if (provider === "anthropic") {
+    if (error.error?.type) return error.error.type;
+    if (error.status === 401) return "invalid_api_key";
+    if (error.status === 429) return "rate_limit_error";
+    if (error.status === 400) return "invalid_request";
+    if (error.status === 500) return "internal_server_error";
+  }
+  if (error.status) {
+    if (error.status === 401) return "unauthorized";
+    if (error.status === 403) return "forbidden";
+    if (error.status === 404) return "not_found";
+    if (error.status === 429) return "rate_limit_exceeded";
+    if (error.status >= 500) return "server_error";
+  }
+  const message = String(error.message || error);
+  if (message.toLowerCase().includes("timeout")) return "timeout_error";
+  if (message.toLowerCase().includes("network")) return "network_error";
+  if (message.toLowerCase().includes("connection")) return "connection_error";
+  return null;
+}
+function categorizeError(error, provider) {
+  if (!error) return "unknown_error";
+  const statusCode = error.status || error.statusCode || error.status_code;
+  const errorCode = extractErrorCode(error, provider);
+  const message = String(error.message || error.error?.message || error || "").toLowerCase();
+  if (statusCode === 401 || statusCode === 403 || errorCode === "invalid_api_key" || errorCode === "unauthorized" || errorCode === "forbidden" || message.includes("authentication") || message.includes("unauthorized") || message.includes("invalid api key") || message.includes("invalid api_token")) {
+    return "authentication_error";
+  }
+  if (statusCode === 429 || errorCode === "rate_limit_exceeded" || errorCode === "rate_limit_error" || message.includes("rate limit") || message.includes("too many requests")) {
+    return "rate_limit_error";
+  }
+  if (statusCode === 400 || errorCode === "invalid_request" || message.includes("validation") || message.includes("invalid") || message.includes("bad request")) {
+    return "validation_error";
+  }
+  if (errorCode === "timeout_error" || message.includes("timeout") || message.includes("timed out") || message.includes("request timeout")) {
+    return "timeout_error";
+  }
+  if (errorCode === "network_error" || errorCode === "connection_error" || message.includes("network") || message.includes("connection") || message.includes("econn") || message.includes("enotfound") || message.includes("eai_again")) {
+    return "network_error";
+  }
+  if (statusCode >= 500 || errorCode === "internal_server_error" || errorCode === "server_error" || errorCode === "bad_gateway" || errorCode === "service_unavailable" || message.includes("server error") || message.includes("internal error")) {
+    return "server_error";
+  }
+  if (errorCode === "insufficient_quota" || message.includes("quota") || message.includes("billing") || message.includes("credits")) {
+    return "quota_error";
+  }
+  if (statusCode === 404 || errorCode === "model_not_found" || errorCode === "not_found" || message.includes("model not found") || message.includes("model unavailable")) {
+    return "model_error";
+  }
+  return "unknown_error";
+}
+function extractProviderError(error, provider) {
+  const code = extractErrorCode(error, provider) || "unknown_error";
+  const category = categorizeError(error, provider);
+  const statusCode = error.status || error.statusCode || error.status_code;
+  let message = "An unknown error occurred";
+  if (error.message) {
+    message = error.message;
+  } else if (error.error?.message) {
+    message = error.error.message;
+  } else if (error.response?.data?.error?.message) {
+    message = error.response.data.error.message;
+  } else if (typeof error === "string") {
+    message = error;
+  } else if (error.toString && error.toString() !== "[object Object]") {
+    message = error.toString();
+  }
+  return {
+    code,
+    category,
+    message,
+    statusCode
+  };
+}
+
 // src/instrumentation/openai.ts
 var proxyCache = /* @__PURE__ */ new WeakMap();
 function observeOpenAI(client, options) {
@@ -209,6 +299,9 @@ async function traceOpenAICall(originalFn, args, options) {
   const startTime = Date.now();
   const requestParams = args[0] || {};
   const isStreaming = requestParams.stream === true;
+  const inputText = requestParams.messages?.map((m) => m.content).filter(Boolean).join("\n") || null;
+  const inputMessages = requestParams.messages || null;
+  const model = requestParams.model || "unknown";
   try {
     const result = await originalFn(...args);
     if (isStreaming) {
@@ -224,7 +317,15 @@ async function traceOpenAICall(originalFn, args, options) {
             fullResponse.streamingDuration
           );
         },
-        (err) => recordError(requestParams, err, startTime, options),
+        (err) => recordError(
+          requestParams,
+          err,
+          startTime,
+          options,
+          inputText,
+          inputMessages,
+          model
+        ),
         "openai"
       );
     } else {
@@ -232,7 +333,15 @@ async function traceOpenAICall(originalFn, args, options) {
       return result;
     }
   } catch (error) {
-    recordError(requestParams, error, startTime, options);
+    recordError(
+      requestParams,
+      error,
+      startTime,
+      options,
+      inputText,
+      inputMessages,
+      model
+    );
     throw error;
   }
 }
@@ -271,20 +380,26 @@ function recordTrace(req, res, start, opts, timeToFirstToken, streamingDuration)
     console.error("[Observa] Failed to record trace", e);
   }
 }
-function recordError(req, error, start, opts) {
+function recordError(req, error, start, opts, preExtractedInputText, preExtractedInputMessages, preExtractedModel) {
   const duration = Date.now() - start;
   try {
     console.error("[Observa] \u26A0\uFE0F Error Captured:", error?.message || error);
     const sanitizedReq = opts?.redact ? opts.redact(req) : req;
     if (opts?.observa) {
-      const model = sanitizedReq.model || "unknown";
-      const inputText = sanitizedReq.messages?.map((m) => m.content).filter(Boolean).join("\n") || null;
+      const model = preExtractedModel || sanitizedReq.model || "unknown";
+      let inputText = preExtractedInputText || null;
+      let inputMessages = preExtractedInputMessages || null;
+      if (!inputText) {
+        inputMessages = sanitizedReq.messages || null;
+        inputText = sanitizedReq.messages?.map((m) => m.content).filter(Boolean).join("\n") || null;
+      }
+      const extractedError = extractProviderError(error, "openai");
       opts.observa.trackLLMCall({
         model,
         input: inputText,
         output: null,
         // No output on error
-        inputMessages: sanitizedReq.messages || null,
+        inputMessages,
         outputMessages: null,
         inputTokens: null,
         outputTokens: null,
@@ -301,17 +416,19 @@ function recordError(req, error, start, opts) {
         maxTokens: sanitizedReq.max_tokens || null
       });
       opts.observa.trackError({
-        errorType: "openai_api_error",
-        errorMessage: error?.message || String(error),
+        errorType: error?.name || extractedError.code || "openai_api_error",
+        errorMessage: extractedError.message,
         stackTrace: error?.stack || null,
         context: {
           request: sanitizedReq,
           model,
           input: inputText,
           provider: "openai",
-          duration_ms: duration
+          duration_ms: duration,
+          status_code: extractedError.statusCode || null
         },
-        errorCategory: "llm_error"
+        errorCategory: extractedError.category,
+        errorCode: extractedError.code
       });
     }
   } catch (e) {
@@ -354,6 +471,15 @@ async function traceAnthropicCall(originalFn, args, options) {
   const startTime = Date.now();
   const requestParams = args[0] || {};
   const isStreaming = requestParams.stream === true;
+  const inputText = requestParams.messages?.map((m) => {
+    if (typeof m.content === "string") return m.content;
+    if (Array.isArray(m.content)) {
+      return m.content.map((c) => c.text || c.type).filter(Boolean).join("\n");
+    }
+    return null;
+  }).filter(Boolean).join("\n") || null;
+  const inputMessages = requestParams.messages || null;
+  const model = requestParams.model || "unknown";
   try {
     const result = await originalFn(...args);
     if (isStreaming) {
@@ -369,7 +495,15 @@ async function traceAnthropicCall(originalFn, args, options) {
             fullResponse.streamingDuration
           );
         },
-        (err) => recordError2(requestParams, err, startTime, options),
+        (err) => recordError2(
+          requestParams,
+          err,
+          startTime,
+          options,
+          inputText,
+          inputMessages,
+          model
+        ),
         "anthropic"
       );
     } else {
@@ -377,7 +511,15 @@ async function traceAnthropicCall(originalFn, args, options) {
       return result;
     }
   } catch (error) {
-    recordError2(requestParams, error, startTime, options);
+    recordError2(
+      requestParams,
+      error,
+      startTime,
+      options,
+      inputText,
+      inputMessages,
+      model
+    );
     throw error;
   }
 }
@@ -421,26 +563,32 @@ function recordTrace2(req, res, start, opts, timeToFirstToken, streamingDuration
     console.error("[Observa] Failed to record trace", e);
   }
 }
-function recordError2(req, error, start, opts) {
+function recordError2(req, error, start, opts, preExtractedInputText, preExtractedInputMessages, preExtractedModel) {
   const duration = Date.now() - start;
   try {
     console.error("[Observa] \u26A0\uFE0F Error Captured:", error?.message || error);
     const sanitizedReq = opts?.redact ? opts.redact(req) : req;
     if (opts?.observa) {
-      const model = sanitizedReq.model || "unknown";
-      const inputText = sanitizedReq.messages?.map((m) => {
-        if (typeof m.content === "string") return m.content;
-        if (Array.isArray(m.content)) {
-          return m.content.map((c) => c.text || c.type).filter(Boolean).join("\n");
-        }
-        return null;
-      }).filter(Boolean).join("\n") || null;
+      const model = preExtractedModel || sanitizedReq.model || "unknown";
+      let inputText = preExtractedInputText || null;
+      let inputMessages = preExtractedInputMessages || null;
+      if (!inputText) {
+        inputMessages = sanitizedReq.messages || null;
+        inputText = sanitizedReq.messages?.map((m) => {
+          if (typeof m.content === "string") return m.content;
+          if (Array.isArray(m.content)) {
+            return m.content.map((c) => c.text || c.type).filter(Boolean).join("\n");
+          }
+          return null;
+        }).filter(Boolean).join("\n") || null;
+      }
+      const extractedError = extractProviderError(error, "anthropic");
       opts.observa.trackLLMCall({
         model,
         input: inputText,
         output: null,
         // No output on error
-        inputMessages: sanitizedReq.messages || null,
+        inputMessages,
         outputMessages: null,
         inputTokens: null,
         outputTokens: null,
@@ -457,17 +605,19 @@ function recordError2(req, error, start, opts) {
         maxTokens: sanitizedReq.max_tokens || null
       });
       opts.observa.trackError({
-        errorType: "anthropic_api_error",
-        errorMessage: error?.message || String(error),
+        errorType: error?.name || extractedError.code || "anthropic_api_error",
+        errorMessage: extractedError.message,
         stackTrace: error?.stack || null,
         context: {
           request: sanitizedReq,
           model,
           input: inputText,
           provider: "anthropic",
-          duration_ms: duration
+          duration_ms: duration,
+          status_code: extractedError.statusCode || null
         },
-        errorCategory: "llm_error"
+        errorCategory: extractedError.category,
+        errorCode: extractedError.code
       });
     }
   } catch (e) {
@@ -546,6 +696,14 @@ async function traceGenerateText(originalFn, args, options) {
   const model = requestParams.model || "unknown";
   const provider = extractProviderFromModel(model);
   const modelIdentifier = extractModelIdentifier(model);
+  let inputText = null;
+  let inputMessages = null;
+  if (requestParams.prompt) {
+    inputText = typeof requestParams.prompt === "string" ? requestParams.prompt : JSON.stringify(requestParams.prompt);
+  } else if (requestParams.messages) {
+    inputMessages = requestParams.messages;
+    inputText = requestParams.messages.map((m) => m.content || m.text || "").filter(Boolean).join("\n");
+  }
   try {
     const result = await originalFn(...args);
     const responseText = result.text || "";
@@ -586,7 +744,9 @@ async function traceGenerateText(originalFn, args, options) {
       error,
       startTime,
       options,
-      provider
+      provider,
+      inputText,
+      inputMessages
     );
     throw error;
   }
@@ -644,6 +804,14 @@ async function traceStreamText(originalFn, args, options) {
   const model = requestParams.model || "unknown";
   const provider = extractProviderFromModel(model);
   const modelIdentifier = extractModelIdentifier(model);
+  let inputText = null;
+  let inputMessages = null;
+  if (requestParams.prompt) {
+    inputText = typeof requestParams.prompt === "string" ? requestParams.prompt : JSON.stringify(requestParams.prompt);
+  } else if (requestParams.messages) {
+    inputMessages = requestParams.messages;
+    inputText = requestParams.messages.map((m) => m.content || m.text || "").filter(Boolean).join("\n");
+  }
   try {
     const result = await originalFn(...args);
     if (result.textStream) {
@@ -678,7 +846,9 @@ async function traceStreamText(originalFn, args, options) {
             err,
             startTime,
             options,
-            provider
+            provider,
+            inputText,
+            inputMessages
           )
         );
         const wrappedResult = Object.create(Object.getPrototypeOf(result));
@@ -718,7 +888,9 @@ async function traceStreamText(originalFn, args, options) {
       error,
       startTime,
       options,
-      provider
+      provider,
+      inputText,
+      inputMessages
     );
     throw error;
   }
@@ -765,21 +937,25 @@ function recordTrace3(req, res, start, opts, timeToFirstToken, streamingDuration
     console.error("[Observa] Failed to record trace", e);
   }
 }
-function recordError3(req, error, start, opts, provider) {
+function recordError3(req, error, start, opts, provider, preExtractedInputText, preExtractedInputMessages) {
   const duration = Date.now() - start;
   try {
-    console.error("[Observa] \u26A0\uFE0F Error Captured:", error.message);
+    console.error("[Observa] \u26A0\uFE0F Error Captured:", error?.message || error);
     const sanitizedReq = opts?.redact ? opts.redact(req) : req;
     if (opts?.observa) {
       const model = sanitizedReq.model || "unknown";
-      let inputText = null;
-      let inputMessages = null;
-      if (sanitizedReq.prompt) {
-        inputText = typeof sanitizedReq.prompt === "string" ? sanitizedReq.prompt : JSON.stringify(sanitizedReq.prompt);
-      } else if (sanitizedReq.messages) {
-        inputMessages = sanitizedReq.messages;
-        inputText = sanitizedReq.messages.map((m) => m.content || m.text || "").filter(Boolean).join("\n");
+      let inputText = preExtractedInputText || null;
+      let inputMessages = preExtractedInputMessages || null;
+      if (!inputText) {
+        if (sanitizedReq.prompt) {
+          inputText = typeof sanitizedReq.prompt === "string" ? sanitizedReq.prompt : JSON.stringify(sanitizedReq.prompt);
+        } else if (sanitizedReq.messages) {
+          inputMessages = sanitizedReq.messages;
+          inputText = sanitizedReq.messages.map((m) => m.content || m.text || "").filter(Boolean).join("\n");
+        }
       }
+      const providerName = provider || "vercel-ai";
+      const extractedError = extractProviderError(error, providerName);
       opts.observa.trackLLMCall({
         model,
         input: inputText,
@@ -796,23 +972,25 @@ function recordError3(req, error, start, opts, provider) {
         finishReason: null,
         responseId: null,
         operationName: "generate_text",
-        providerName: provider || "vercel-ai",
+        providerName,
         responseModel: model,
         temperature: sanitizedReq.temperature || null,
         maxTokens: sanitizedReq.maxTokens || sanitizedReq.max_tokens || null
       });
       opts.observa.trackError({
-        errorType: error.name || "UnknownError",
-        errorMessage: error.message || "An unknown error occurred",
-        stackTrace: error.stack,
+        errorType: error?.name || extractedError.code || "UnknownError",
+        errorMessage: extractedError.message,
+        stackTrace: error?.stack || null,
         context: {
           request: sanitizedReq,
           model,
           input: inputText,
-          provider: provider || "vercel-ai",
-          duration_ms: duration
+          provider: providerName,
+          duration_ms: duration,
+          status_code: extractedError.statusCode || null
         },
-        errorCategory: "llm_error"
+        errorCategory: extractedError.category,
+        errorCode: extractedError.code
       });
     }
   } catch (e) {
@@ -1084,6 +1262,10 @@ var Observa = class {
   spanStack = [];
   // Stack for tracking parent-child relationships
   traceStartTime = null;
+  // Track traces with errors (for automatic trace_end generation when using instrumentation)
+  tracesWithErrors = /* @__PURE__ */ new Set();
+  // Track root span IDs for traces (for automatic trace_end generation)
+  traceRootSpanIds = /* @__PURE__ */ new Map();
   constructor(config) {
     this.apiKey = config.apiKey;
     let apiUrlEnv;
@@ -1174,9 +1356,13 @@ var Observa = class {
   addEvent(eventData) {
     const baseProps = this.createBaseEventProperties();
     const parentSpanId = this.spanStack.length > 0 ? this.spanStack[this.spanStack.length - 1] : null;
+    const spanId = eventData.span_id || crypto.randomUUID();
+    if (!this.currentTraceId && !this.traceRootSpanIds.has(baseProps.trace_id)) {
+      this.traceRootSpanIds.set(baseProps.trace_id, spanId);
+    }
     const event = {
       ...baseProps,
-      span_id: eventData.span_id || crypto.randomUUID(),
+      span_id: spanId,
       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,
@@ -1361,6 +1547,8 @@ var Observa = class {
     if (!stackTrace && options.error instanceof Error && options.error.stack) {
       stackTrace = options.error.stack;
     }
+    const baseProps = this.createBaseEventProperties();
+    this.tracesWithErrors.add(baseProps.trace_id);
     this.addEvent({
       event_type: "error",
       span_id: spanId,
@@ -1728,6 +1916,65 @@ var Observa = class {
       eventsByTrace.get(event.trace_id).push(event);
     }
     for (const [traceId, events] of eventsByTrace.entries()) {
+      const hasTraceStart = events.some((e) => e.event_type === "trace_start");
+      const hasTraceEnd = events.some((e) => e.event_type === "trace_end");
+      const hasError = this.tracesWithErrors.has(traceId);
+      const rootSpanId = this.traceRootSpanIds.get(traceId) || events[0]?.span_id || crypto.randomUUID();
+      const firstEvent = events[0];
+      if (!firstEvent) continue;
+      if (!hasTraceStart) {
+        const traceStartEvent = {
+          tenant_id: firstEvent.tenant_id,
+          project_id: firstEvent.project_id,
+          environment: firstEvent.environment,
+          trace_id: traceId,
+          span_id: rootSpanId,
+          parent_span_id: null,
+          timestamp: firstEvent.timestamp,
+          event_type: "trace_start",
+          attributes: {
+            trace_start: {
+              name: null,
+              metadata: null
+            }
+          }
+        };
+        events.unshift(traceStartEvent);
+      }
+      if (!hasTraceEnd) {
+        const llmEvents = events.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 timestamps = events.map((e) => new Date(e.timestamp).getTime()).filter(Boolean);
+        const totalLatency = timestamps.length > 0 ? Math.max(...timestamps) - Math.min(...timestamps) : null;
+        const traceEndEvent = {
+          tenant_id: firstEvent.tenant_id,
+          project_id: firstEvent.project_id,
+          environment: firstEvent.environment,
+          trace_id: traceId,
+          span_id: rootSpanId,
+          parent_span_id: null,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          event_type: "trace_end",
+          attributes: {
+            trace_end: {
+              total_latency_ms: totalLatency,
+              total_tokens: totalTokens || null,
+              total_cost: totalCost || null,
+              outcome: hasError ? "error" : "success"
+            }
+          }
+        };
+        events.push(traceEndEvent);
+      }
+      this.tracesWithErrors.delete(traceId);
+      this.traceRootSpanIds.delete(traceId);
       await this._sendEventsWithRetry(events);
     }
   }
@@ -1769,11 +2016,11 @@ var Observa = class {
   }
   /**
    * Observe OpenAI client - wraps client with automatic tracing
-   * 
+   *
    * @param client - OpenAI client instance
    * @param options - Observation options (name, tags, userId, sessionId, redact)
    * @returns Wrapped OpenAI client
-   * 
+   *
    * @example
    * ```typescript
    * import OpenAI from 'openai';
@@ -1794,11 +2041,11 @@ var Observa = class {
   }
   /**
    * Observe Anthropic client - wraps client with automatic tracing
-   * 
+   *
    * @param client - Anthropic client instance
    * @param options - Observation options (name, tags, userId, sessionId, redact)
    * @returns Wrapped Anthropic client
-   * 
+   *
    * @example
    * ```typescript
    * import Anthropic from '@anthropic-ai/sdk';
@@ -1819,21 +2066,21 @@ var Observa = class {
   }
   /**
    * Observe Vercel AI SDK - wraps generateText and streamText functions
-   * 
+   *
    * @param aiSdk - Vercel AI SDK module (imported from 'ai')
    * @param options - Observation options (name, tags, userId, sessionId, redact)
    * @returns Wrapped AI SDK with automatic tracing
-   * 
+   *
    * @example
    * ```typescript
    * import { generateText, streamText } from 'ai';
    * const observa = init({ apiKey: '...' });
-   * 
+   *
    * const ai = observa.observeVercelAI({ generateText, streamText }, {
    *   name: 'my-app',
    *   redact: (data) => ({ ...data, prompt: '[REDACTED]' })
    * });
-   * 
+   *
    * // Use wrapped functions - automatically tracked!
    * const result = await ai.generateText({
    *   model: 'openai/gpt-4',

package/package.json

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