observa-sdk 0.0.21 → 0.0.22

package/README.md

@@ -118,7 +118,19 @@ const response = await wrappedAnthropic.messages.create({
 
 ### Auto-Capture with Vercel AI SDK
 
-Vercel AI SDK is a unified SDK that works with multiple providers:
+Vercel AI SDK is a unified SDK that works with multiple providers (OpenAI, Anthropic, Google, etc.).
+
+#### Installation
+
+First, install the required packages:
+
+```bash
+npm install observa-sdk ai @ai-sdk/openai @ai-sdk/anthropic
+# or for other providers:
+npm install @ai-sdk/google @ai-sdk/cohere
+```
+
+#### Basic Example (Node.js/Server)
 
 ```typescript
 import { init } from "observa-sdk";
@@ -152,6 +164,124 @@ for await (const chunk of stream.textStream) {
 }
 ```
 
+#### Next.js App Router Example
+
+For Next.js applications, use the route handler pattern:
+
+```typescript
+// app/api/chat/route.ts
+import { streamText, UIMessage, convertToModelMessages } from "ai";
+import { init } from "observa-sdk";
+import { openai } from "@ai-sdk/openai";
+
+const observa = init({
+  apiKey: process.env.OBSERVA_API_KEY!,
+  apiUrl: process.env.OBSERVA_API_URL,
+});
+
+const ai = observa.observeVercelAI({ streamText }, {
+  name: "my-nextjs-app",
+});
+
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+
+  const result = await ai.streamText({
+    model: openai("gpt-4"),
+    messages: await convertToModelMessages(messages),
+  });
+
+  // Return streaming response for Next.js
+  return result.toUIMessageStreamResponse();
+}
+```
+
+#### Client-Side with React (useChat Hook)
+
+```typescript
+// app/page.tsx
+"use client";
+import { useChat } from "@ai-sdk/react";
+
+export default function Chat() {
+  const { messages, input, handleInputChange, handleSubmit } = useChat({
+    api: "/api/chat",
+  });
+
+  return (
+    <div>
+      {messages.map((message) => (
+        <div key={message.id}>{message.content}</div>
+      ))}
+      <form onSubmit={handleSubmit}>
+        <input value={input} onChange={handleInputChange} />
+        <button type="submit">Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+#### With Tools/Function Calling
+
+Observa automatically tracks tool calls:
+
+```typescript
+import { z } from "zod";
+
+const result = await ai.streamText({
+  model: openai("gpt-4"),
+  messages: [...],
+  tools: {
+    getWeather: {
+      description: "Get the weather for a location",
+      parameters: z.object({
+        location: z.string(),
+      }),
+      execute: async ({ location }) => {
+        // Tool implementation - automatically tracked by Observa
+        return { temperature: 72, condition: "sunny" };
+      },
+    },
+  },
+});
+```
+
+#### Model Format Options
+
+Vercel AI SDK supports two model formats:
+
+1. **Provider function** (recommended):
+```typescript
+import { openai } from "@ai-sdk/openai";
+import { anthropic } from "@ai-sdk/anthropic";
+
+model: openai("gpt-4")
+model: anthropic("claude-3-opus-20240229")
+```
+
+2. **String format** (for AI Gateway):
+```typescript
+model: "openai/gpt-4"
+model: "anthropic/claude-3-opus-20240229"
+```
+
+#### Error Handling
+
+Errors are automatically tracked:
+
+```typescript
+try {
+  const result = await ai.generateText({
+    model: openai("gpt-4"),
+    prompt: "Hello!",
+  });
+} catch (error) {
+  // Error is automatically tracked in Observa
+  console.error("LLM call failed:", error);
+}
+```
+
 ### Legacy Manual Tracking
 
 For more control, you can still use the manual `track()` method:

package/dist/index.cjs

@@ -320,6 +320,11 @@ function observeOpenAI(client, options) {
   if (proxyCache.has(client)) {
     return proxyCache.get(client);
   }
+  if (!options?.observa) {
+    console.error(
+      "[Observa] \u26A0\uFE0F CRITICAL ERROR: observa instance not provided!\n\nTracking will NOT work. You must use observa.observeOpenAI() instead.\n\n\u274C WRONG (importing directly):\n  import { observeOpenAI } from 'observa-sdk/instrumentation';\n  const wrapped = observeOpenAI(openai);\n\n\u2705 CORRECT (using instance method):\n  import { init } from 'observa-sdk';\n  const observa = init({ apiKey: '...' });\n  const wrapped = observa.observeOpenAI(openai);\n"
+    );
+  }
   try {
     const wrapped = new Proxy(client, {
       get(target, prop, receiver) {
@@ -402,7 +407,13 @@ function recordTrace(req, res, start, opts, timeToFirstToken, streamingDuration)
     const sanitizedReq = opts?.redact ? opts.redact(req) : req;
     const sanitizedRes = opts?.redact ? opts.redact(res) : res;
     const otelAttributes = mapOpenAIToOTEL(sanitizedReq, sanitizedRes);
-    if (opts?.observa) {
+    if (!opts?.observa) {
+      console.error(
+        "[Observa] \u26A0\uFE0F CRITICAL: observa instance not provided to observeOpenAI(). Tracking is disabled. Make sure you're using observa.observeOpenAI() instead of importing observeOpenAI directly from 'observa-sdk/instrumentation'."
+      );
+      return;
+    }
+    if (opts.observa) {
       const inputText = sanitizedReq.messages?.map((m) => m.content).filter(Boolean).join("\n") || null;
       const outputText = sanitizedRes?.choices?.[0]?.message?.content || null;
       const finishReason = sanitizedRes?.choices?.[0]?.finish_reason || null;
@@ -480,7 +491,13 @@ function recordError(req, error, start, opts, preExtractedInputText, preExtracte
   try {
     console.error("[Observa] \u26A0\uFE0F Error Captured:", error?.message || error);
     const sanitizedReq = opts?.redact ? opts.redact(req) : req;
-    if (opts?.observa) {
+    if (!opts?.observa) {
+      console.error(
+        "[Observa] \u26A0\uFE0F CRITICAL: observa instance not provided to observeOpenAI(). Error tracking is disabled. Make sure you're using observa.observeOpenAI() instead of importing observeOpenAI directly from 'observa-sdk/instrumentation'."
+      );
+      return;
+    }
+    if (opts.observa) {
       const model = preExtractedModel || sanitizedReq.model || "unknown";
       let inputText = preExtractedInputText || null;
       let inputMessages = preExtractedInputMessages || null;
@@ -537,6 +554,11 @@ function observeAnthropic(client, options) {
   if (proxyCache2.has(client)) {
     return proxyCache2.get(client);
   }
+  if (!options?.observa) {
+    console.error(
+      "[Observa] \u26A0\uFE0F CRITICAL ERROR: observa instance not provided!\n\nTracking will NOT work. You must use observa.observeAnthropic() instead.\n\n\u274C WRONG (importing directly):\n  import { observeAnthropic } from 'observa-sdk/instrumentation';\n  const wrapped = observeAnthropic(anthropic);\n\n\u2705 CORRECT (using instance method):\n  import { init } from 'observa-sdk';\n  const observa = init({ apiKey: '...' });\n  const wrapped = observa.observeAnthropic(anthropic);\n"
+    );
+  }
   try {
     const wrapped = new Proxy(client, {
       get(target, prop, receiver) {
@@ -624,7 +646,13 @@ function recordTrace2(req, res, start, opts, timeToFirstToken, streamingDuration
     const context = getTraceContext();
     const sanitizedReq = opts?.redact ? opts.redact(req) : req;
     const sanitizedRes = opts?.redact ? opts.redact(res) : res;
-    if (opts?.observa) {
+    if (!opts?.observa) {
+      console.error(
+        "[Observa] \u26A0\uFE0F CRITICAL: observa instance not provided to observeAnthropic(). Tracking is disabled. Make sure you're using observa.observeAnthropic() instead of importing observeAnthropic directly from 'observa-sdk/instrumentation'."
+      );
+      return;
+    }
+    if (opts.observa) {
       const inputText = sanitizedReq.messages?.map((m) => {
         if (typeof m.content === "string") return m.content;
         if (Array.isArray(m.content)) {
@@ -708,7 +736,13 @@ function recordError2(req, error, start, opts, preExtractedInputText, preExtract
   try {
     console.error("[Observa] \u26A0\uFE0F Error Captured:", error?.message || error);
     const sanitizedReq = opts?.redact ? opts.redact(req) : req;
-    if (opts?.observa) {
+    if (!opts?.observa) {
+      console.error(
+        "[Observa] \u26A0\uFE0F CRITICAL: observa instance not provided to observeAnthropic(). Error tracking is disabled. Make sure you're using observa.observeAnthropic() instead of importing observeAnthropic directly from 'observa-sdk/instrumentation'."
+      );
+      return;
+    }
+    if (opts.observa) {
       const model = preExtractedModel || sanitizedReq.model || "unknown";
       let inputText = preExtractedInputText || null;
       let inputMessages = preExtractedInputMessages || null;
@@ -905,7 +939,11 @@ function wrapReadableStream(stream, onComplete, onError) {
       const timeoutPromise = new Promise((_, reject) => {
         timeoutId = setTimeout(() => {
           reader.cancel();
-          reject(new Error(`Stream timeout after ${timeoutMs}ms - no response received`));
+          reject(
+            new Error(
+              `Stream timeout after ${timeoutMs}ms - no response received`
+            )
+          );
         }, timeoutMs);
       });
       while (true) {
@@ -945,7 +983,10 @@ function wrapReadableStream(stream, onComplete, onError) {
       }
       const fullText = chunks.join("");
       if (chunks.length === 0 || !fullText || fullText.trim().length === 0) {
-        console.error("[Observa] Empty response detected:", { chunks: chunks.length, fullTextLength: fullText?.length || 0 });
+        console.error("[Observa] Empty response detected:", {
+          chunks: chunks.length,
+          fullTextLength: fullText?.length || 0
+        });
         onError({
           name: "EmptyResponseError",
           message: "AI returned empty response",
@@ -956,11 +997,16 @@ function wrapReadableStream(stream, onComplete, onError) {
         });
         return;
       }
-      onComplete({
-        text: fullText,
-        timeToFirstToken: firstTokenTime ? firstTokenTime - streamStartTime : null,
-        streamingDuration: firstTokenTime ? Date.now() - firstTokenTime : null,
-        totalLatency: Date.now() - streamStartTime
+      Promise.resolve(
+        onComplete({
+          text: fullText,
+          timeToFirstToken: firstTokenTime ? firstTokenTime - streamStartTime : null,
+          streamingDuration: firstTokenTime ? Date.now() - firstTokenTime : null,
+          totalLatency: Date.now() - streamStartTime
+        })
+      ).catch((e) => {
+        console.error("[Observa] Error in onComplete callback:", e);
+        onError(e);
       });
     } catch (error) {
       if (timeoutId) {
@@ -1003,14 +1049,33 @@ async function traceStreamText(originalFn, args, options) {
       if (isReadableStream) {
         const wrappedStream = wrapReadableStream(
           originalTextStream,
-          (fullResponse) => {
+          async (fullResponse) => {
+            let usage = {};
+            try {
+              if (result.usage) {
+                usage = await Promise.resolve(result.usage);
+              }
+              if (!usage || Object.keys(usage).length === 0) {
+                if (result.fullResponse?.usage) {
+                  usage = await Promise.resolve(result.fullResponse.usage);
+                }
+              }
+            } catch (e) {
+              console.warn("[Observa] Failed to extract usage from result:", e);
+            }
             recordTrace3(
               {
                 model: modelIdentifier,
                 prompt: requestParams.prompt || requestParams.messages || null,
                 messages: requestParams.messages || null
               },
-              fullResponse,
+              {
+                ...fullResponse,
+                usage,
+                finishReason: result.finishReason || null,
+                responseId: result.response?.id || null,
+                model: result.model ? extractModelIdentifier(result.model) : modelIdentifier
+              },
               startTime,
               options,
               fullResponse.timeToFirstToken,
@@ -1083,76 +1148,37 @@ function recordTrace3(req, res, start, opts, timeToFirstToken, streamingDuration
   try {
     const sanitizedReq = opts?.redact ? opts.redact(req) : req;
     const sanitizedRes = opts?.redact ? opts.redact(res) : res;
-    if (opts?.observa) {
-      let inputText = null;
-      if (sanitizedReq.prompt) {
-        inputText = typeof sanitizedReq.prompt === "string" ? sanitizedReq.prompt : JSON.stringify(sanitizedReq.prompt);
-      } else if (sanitizedReq.messages) {
-        inputText = sanitizedReq.messages.map((m) => m.content || m.text || "").filter(Boolean).join("\n");
-      }
-      const outputText = sanitizedRes.text || sanitizedRes.content || null;
-      const finishReason = sanitizedRes.finishReason || null;
-      const isEmptyResponse = !outputText || typeof outputText === "string" && outputText.trim().length === 0;
-      const isFailureFinishReason = finishReason === "content_filter" || finishReason === "length" || finishReason === "max_tokens";
-      if (isEmptyResponse || isFailureFinishReason) {
-        const usage2 = sanitizedRes.usage || {};
-        const inputTokens2 = usage2.promptTokens || usage2.inputTokens || null;
-        const outputTokens2 = usage2.completionTokens || usage2.outputTokens || null;
-        const totalTokens2 = usage2.totalTokens || null;
-        opts.observa.trackLLMCall({
-          model: sanitizedReq.model || sanitizedRes.model || "unknown",
-          input: inputText,
-          output: null,
-          // No output on error
-          inputMessages: sanitizedReq.messages || null,
-          outputMessages: null,
-          inputTokens: inputTokens2,
-          outputTokens: outputTokens2,
-          totalTokens: totalTokens2,
-          latencyMs: duration,
-          timeToFirstTokenMs: timeToFirstToken || null,
-          streamingDurationMs: streamingDuration || null,
-          finishReason,
-          responseId: sanitizedRes.responseId || sanitizedRes.id || null,
-          operationName: "generate_text",
-          providerName: provider || "vercel-ai",
-          responseModel: sanitizedRes.model || sanitizedReq.model || null,
-          temperature: sanitizedReq.temperature || null,
-          maxTokens: sanitizedReq.maxTokens || sanitizedReq.max_tokens || null
-        });
-        const errorType = isEmptyResponse ? "empty_response" : finishReason === "content_filter" ? "content_filtered" : "response_truncated";
-        const errorMessage = isEmptyResponse ? "AI returned empty response" : finishReason === "content_filter" ? "AI response was filtered due to content policy" : "AI response was truncated due to token limit";
-        opts.observa.trackError({
-          errorType,
-          errorMessage,
-          stackTrace: null,
-          context: {
-            request: sanitizedReq,
-            response: sanitizedRes,
-            model: sanitizedReq.model || sanitizedRes.model || "unknown",
-            input: inputText,
-            finish_reason: finishReason,
-            provider: provider || "vercel-ai",
-            duration_ms: duration
-          },
-          errorCategory: finishReason === "content_filter" ? "validation_error" : finishReason === "length" || finishReason === "max_tokens" ? "model_error" : "unknown_error",
-          errorCode: isEmptyResponse ? "empty_response" : finishReason
-        });
-        return;
-      }
-      const usage = sanitizedRes.usage || {};
-      const inputTokens = usage.promptTokens || usage.inputTokens || null;
-      const outputTokens = usage.completionTokens || usage.outputTokens || null;
-      const totalTokens = usage.totalTokens || null;
+    if (!opts?.observa) {
+      console.error(
+        "[Observa] \u26A0\uFE0F CRITICAL: observa instance not provided to observeVercelAI(). Tracking is disabled. Make sure you're using observa.observeVercelAI() instead of importing observeVercelAI directly from 'observa-sdk/instrumentation'."
+      );
+      return;
+    }
+    let inputText = null;
+    if (sanitizedReq.prompt) {
+      inputText = typeof sanitizedReq.prompt === "string" ? sanitizedReq.prompt : JSON.stringify(sanitizedReq.prompt);
+    } else if (sanitizedReq.messages) {
+      inputText = sanitizedReq.messages.map((m) => m.content || m.text || "").filter(Boolean).join("\n");
+    }
+    const outputText = sanitizedRes.text || sanitizedRes.content || null;
+    const finishReason = sanitizedRes.finishReason || null;
+    const isEmptyResponse = !outputText || typeof outputText === "string" && outputText.trim().length === 0;
+    const isFailureFinishReason = finishReason === "content_filter" || finishReason === "length" || finishReason === "max_tokens";
+    if (isEmptyResponse || isFailureFinishReason) {
+      const usage2 = sanitizedRes.usage || {};
+      const inputTokens2 = usage2.promptTokens || usage2.inputTokens || null;
+      const outputTokens2 = usage2.completionTokens || usage2.outputTokens || null;
+      const totalTokens2 = usage2.totalTokens || null;
       opts.observa.trackLLMCall({
         model: sanitizedReq.model || sanitizedRes.model || "unknown",
         input: inputText,
-        output: outputText,
+        output: null,
+        // No output on error
         inputMessages: sanitizedReq.messages || null,
-        outputMessages: sanitizedRes.messages || null,
-        inputTokens,
-        outputTokens,
-        totalTokens,
+        outputMessages: null,
+        inputTokens: inputTokens2,
+        outputTokens: outputTokens2,
+        totalTokens: totalTokens2,
         latencyMs: duration,
         timeToFirstTokenMs: timeToFirstToken || null,
         streamingDurationMs: streamingDuration || null,
@@ -1164,7 +1190,50 @@ function recordTrace3(req, res, start, opts, timeToFirstToken, streamingDuration
         temperature: sanitizedReq.temperature || null,
         maxTokens: sanitizedReq.maxTokens || sanitizedReq.max_tokens || null
       });
+      const errorType = isEmptyResponse ? "empty_response" : finishReason === "content_filter" ? "content_filtered" : "response_truncated";
+      const errorMessage = isEmptyResponse ? "AI returned empty response" : finishReason === "content_filter" ? "AI response was filtered due to content policy" : "AI response was truncated due to token limit";
+      opts.observa.trackError({
+        errorType,
+        errorMessage,
+        stackTrace: null,
+        context: {
+          request: sanitizedReq,
+          response: sanitizedRes,
+          model: sanitizedReq.model || sanitizedRes.model || "unknown",
+          input: inputText,
+          finish_reason: finishReason,
+          provider: provider || "vercel-ai",
+          duration_ms: duration
+        },
+        errorCategory: finishReason === "content_filter" ? "validation_error" : finishReason === "length" || finishReason === "max_tokens" ? "model_error" : "unknown_error",
+        errorCode: isEmptyResponse ? "empty_response" : finishReason
+      });
+      return;
     }
+    const usage = sanitizedRes.usage || {};
+    const inputTokens = usage.promptTokens || usage.inputTokens || null;
+    const outputTokens = usage.completionTokens || usage.outputTokens || null;
+    const totalTokens = usage.totalTokens || null;
+    opts.observa.trackLLMCall({
+      model: sanitizedReq.model || sanitizedRes.model || "unknown",
+      input: inputText,
+      output: outputText,
+      inputMessages: sanitizedReq.messages || null,
+      outputMessages: sanitizedRes.messages || null,
+      inputTokens,
+      outputTokens,
+      totalTokens,
+      latencyMs: duration,
+      timeToFirstTokenMs: timeToFirstToken || null,
+      streamingDurationMs: streamingDuration || null,
+      finishReason,
+      responseId: sanitizedRes.responseId || sanitizedRes.id || null,
+      operationName: "generate_text",
+      providerName: provider || "vercel-ai",
+      responseModel: sanitizedRes.model || sanitizedReq.model || null,
+      temperature: sanitizedReq.temperature || null,
+      maxTokens: sanitizedReq.maxTokens || sanitizedReq.max_tokens || null
+    });
   } catch (e) {
     console.error("[Observa] Failed to record trace", e);
   }
@@ -1174,63 +1243,72 @@ function recordError3(req, error, start, opts, provider, preExtractedInputText,
   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";
-      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");
-        }
+    if (!opts?.observa) {
+      console.error(
+        "[Observa] \u26A0\uFE0F CRITICAL: observa instance not provided to observeVercelAI(). Error tracking is disabled. Make sure you're using observa.observeVercelAI() instead of importing observeVercelAI directly from 'observa-sdk/instrumentation'."
+      );
+      return;
+    }
+    const model = sanitizedReq.model || "unknown";
+    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({
+    }
+    const providerName = provider || "vercel-ai";
+    const extractedError = extractProviderError(error, providerName);
+    opts.observa.trackLLMCall({
+      model,
+      input: inputText,
+      output: null,
+      // No output on error
+      inputMessages,
+      outputMessages: null,
+      inputTokens: null,
+      outputTokens: null,
+      totalTokens: null,
+      latencyMs: duration,
+      timeToFirstTokenMs: null,
+      streamingDurationMs: null,
+      finishReason: null,
+      responseId: null,
+      operationName: "generate_text",
+      providerName,
+      responseModel: model,
+      temperature: sanitizedReq.temperature || null,
+      maxTokens: sanitizedReq.maxTokens || sanitizedReq.max_tokens || null
+    });
+    opts.observa.trackError({
+      errorType: error?.name || extractedError.code || "UnknownError",
+      errorMessage: extractedError.message,
+      stackTrace: error?.stack || null,
+      context: {
+        request: sanitizedReq,
         model,
         input: inputText,
-        output: null,
-        // No output on error
-        inputMessages,
-        outputMessages: null,
-        inputTokens: null,
-        outputTokens: null,
-        totalTokens: null,
-        latencyMs: duration,
-        timeToFirstTokenMs: null,
-        streamingDurationMs: null,
-        finishReason: null,
-        responseId: null,
-        operationName: "generate_text",
-        providerName,
-        responseModel: model,
-        temperature: sanitizedReq.temperature || null,
-        maxTokens: sanitizedReq.maxTokens || sanitizedReq.max_tokens || null
-      });
-      opts.observa.trackError({
-        errorType: error?.name || extractedError.code || "UnknownError",
-        errorMessage: extractedError.message,
-        stackTrace: error?.stack || null,
-        context: {
-          request: sanitizedReq,
-          model,
-          input: inputText,
-          provider: providerName,
-          duration_ms: duration,
-          status_code: extractedError.statusCode || null
-        },
-        errorCategory: extractedError.category,
-        errorCode: extractedError.code
-      });
-    }
+        provider: providerName,
+        duration_ms: duration,
+        status_code: extractedError.statusCode || null
+      },
+      errorCategory: extractedError.category,
+      errorCode: extractedError.code
+    });
   } catch (e) {
     console.error("[Observa] Failed to record error", e);
   }
 }
 function observeVercelAI(aiSdk, options) {
   try {
+    if (!options?.observa) {
+      console.error(
+        "[Observa] \u26A0\uFE0F CRITICAL ERROR: observa instance not provided!\n\nTracking will NOT work. You must use observa.observeVercelAI() instead.\n\n\u274C WRONG (importing directly):\n  import { observeVercelAI } from 'observa-sdk/instrumentation';\n  const ai = observeVercelAI({ generateText, streamText });\n\n\u2705 CORRECT (using instance method):\n  import { init } from 'observa-sdk';\n  const observa = init({ apiKey: '...' });\n  const ai = observa.observeVercelAI({ generateText, streamText });\n"
+      );
+    }
     const wrapped = { ...aiSdk };
     if (aiSdk.generateText && typeof aiSdk.generateText === "function") {
       wrapped.generateText = async function(...args) {
@@ -1663,7 +1741,7 @@ var Observa = class {
       }
     }
     const operationName = options.operationName || "chat";
-    const isError = options.output === null || typeof options.output === "string" && options.output.trim().length === 0 || (options.finishReason === "content_filter" || options.finishReason === "length" || options.finishReason === "max_tokens");
+    const isError = options.output === null || typeof options.output === "string" && options.output.trim().length === 0 || options.finishReason === "content_filter" || options.finishReason === "length" || options.finishReason === "max_tokens";
     this.addEvent({
       event_type: "llm_call",
       span_id: spanId,

package/dist/index.js

@@ -300,6 +300,11 @@ function observeOpenAI(client, options) {
   if (proxyCache.has(client)) {
     return proxyCache.get(client);
   }
+  if (!options?.observa) {
+    console.error(
+      "[Observa] \u26A0\uFE0F CRITICAL ERROR: observa instance not provided!\n\nTracking will NOT work. You must use observa.observeOpenAI() instead.\n\n\u274C WRONG (importing directly):\n  import { observeOpenAI } from 'observa-sdk/instrumentation';\n  const wrapped = observeOpenAI(openai);\n\n\u2705 CORRECT (using instance method):\n  import { init } from 'observa-sdk';\n  const observa = init({ apiKey: '...' });\n  const wrapped = observa.observeOpenAI(openai);\n"
+    );
+  }
   try {
     const wrapped = new Proxy(client, {
       get(target, prop, receiver) {
@@ -382,7 +387,13 @@ function recordTrace(req, res, start, opts, timeToFirstToken, streamingDuration)
     const sanitizedReq = opts?.redact ? opts.redact(req) : req;
     const sanitizedRes = opts?.redact ? opts.redact(res) : res;
     const otelAttributes = mapOpenAIToOTEL(sanitizedReq, sanitizedRes);
-    if (opts?.observa) {
+    if (!opts?.observa) {
+      console.error(
+        "[Observa] \u26A0\uFE0F CRITICAL: observa instance not provided to observeOpenAI(). Tracking is disabled. Make sure you're using observa.observeOpenAI() instead of importing observeOpenAI directly from 'observa-sdk/instrumentation'."
+      );
+      return;
+    }
+    if (opts.observa) {
       const inputText = sanitizedReq.messages?.map((m) => m.content).filter(Boolean).join("\n") || null;
       const outputText = sanitizedRes?.choices?.[0]?.message?.content || null;
       const finishReason = sanitizedRes?.choices?.[0]?.finish_reason || null;
@@ -460,7 +471,13 @@ function recordError(req, error, start, opts, preExtractedInputText, preExtracte
   try {
     console.error("[Observa] \u26A0\uFE0F Error Captured:", error?.message || error);
     const sanitizedReq = opts?.redact ? opts.redact(req) : req;
-    if (opts?.observa) {
+    if (!opts?.observa) {
+      console.error(
+        "[Observa] \u26A0\uFE0F CRITICAL: observa instance not provided to observeOpenAI(). Error tracking is disabled. Make sure you're using observa.observeOpenAI() instead of importing observeOpenAI directly from 'observa-sdk/instrumentation'."
+      );
+      return;
+    }
+    if (opts.observa) {
       const model = preExtractedModel || sanitizedReq.model || "unknown";
       let inputText = preExtractedInputText || null;
       let inputMessages = preExtractedInputMessages || null;
@@ -517,6 +534,11 @@ function observeAnthropic(client, options) {
   if (proxyCache2.has(client)) {
     return proxyCache2.get(client);
   }
+  if (!options?.observa) {
+    console.error(
+      "[Observa] \u26A0\uFE0F CRITICAL ERROR: observa instance not provided!\n\nTracking will NOT work. You must use observa.observeAnthropic() instead.\n\n\u274C WRONG (importing directly):\n  import { observeAnthropic } from 'observa-sdk/instrumentation';\n  const wrapped = observeAnthropic(anthropic);\n\n\u2705 CORRECT (using instance method):\n  import { init } from 'observa-sdk';\n  const observa = init({ apiKey: '...' });\n  const wrapped = observa.observeAnthropic(anthropic);\n"
+    );
+  }
   try {
     const wrapped = new Proxy(client, {
       get(target, prop, receiver) {
@@ -604,7 +626,13 @@ function recordTrace2(req, res, start, opts, timeToFirstToken, streamingDuration
     const context = getTraceContext();
     const sanitizedReq = opts?.redact ? opts.redact(req) : req;
     const sanitizedRes = opts?.redact ? opts.redact(res) : res;
-    if (opts?.observa) {
+    if (!opts?.observa) {
+      console.error(
+        "[Observa] \u26A0\uFE0F CRITICAL: observa instance not provided to observeAnthropic(). Tracking is disabled. Make sure you're using observa.observeAnthropic() instead of importing observeAnthropic directly from 'observa-sdk/instrumentation'."
+      );
+      return;
+    }
+    if (opts.observa) {
       const inputText = sanitizedReq.messages?.map((m) => {
         if (typeof m.content === "string") return m.content;
         if (Array.isArray(m.content)) {
@@ -688,7 +716,13 @@ function recordError2(req, error, start, opts, preExtractedInputText, preExtract
   try {
     console.error("[Observa] \u26A0\uFE0F Error Captured:", error?.message || error);
     const sanitizedReq = opts?.redact ? opts.redact(req) : req;
-    if (opts?.observa) {
+    if (!opts?.observa) {
+      console.error(
+        "[Observa] \u26A0\uFE0F CRITICAL: observa instance not provided to observeAnthropic(). Error tracking is disabled. Make sure you're using observa.observeAnthropic() instead of importing observeAnthropic directly from 'observa-sdk/instrumentation'."
+      );
+      return;
+    }
+    if (opts.observa) {
       const model = preExtractedModel || sanitizedReq.model || "unknown";
       let inputText = preExtractedInputText || null;
       let inputMessages = preExtractedInputMessages || null;
@@ -885,7 +919,11 @@ function wrapReadableStream(stream, onComplete, onError) {
       const timeoutPromise = new Promise((_, reject) => {
         timeoutId = setTimeout(() => {
           reader.cancel();
-          reject(new Error(`Stream timeout after ${timeoutMs}ms - no response received`));
+          reject(
+            new Error(
+              `Stream timeout after ${timeoutMs}ms - no response received`
+            )
+          );
         }, timeoutMs);
       });
       while (true) {
@@ -925,7 +963,10 @@ function wrapReadableStream(stream, onComplete, onError) {
       }
       const fullText = chunks.join("");
       if (chunks.length === 0 || !fullText || fullText.trim().length === 0) {
-        console.error("[Observa] Empty response detected:", { chunks: chunks.length, fullTextLength: fullText?.length || 0 });
+        console.error("[Observa] Empty response detected:", {
+          chunks: chunks.length,
+          fullTextLength: fullText?.length || 0
+        });
         onError({
           name: "EmptyResponseError",
           message: "AI returned empty response",
@@ -936,11 +977,16 @@ function wrapReadableStream(stream, onComplete, onError) {
         });
         return;
       }
-      onComplete({
-        text: fullText,
-        timeToFirstToken: firstTokenTime ? firstTokenTime - streamStartTime : null,
-        streamingDuration: firstTokenTime ? Date.now() - firstTokenTime : null,
-        totalLatency: Date.now() - streamStartTime
+      Promise.resolve(
+        onComplete({
+          text: fullText,
+          timeToFirstToken: firstTokenTime ? firstTokenTime - streamStartTime : null,
+          streamingDuration: firstTokenTime ? Date.now() - firstTokenTime : null,
+          totalLatency: Date.now() - streamStartTime
+        })
+      ).catch((e) => {
+        console.error("[Observa] Error in onComplete callback:", e);
+        onError(e);
       });
     } catch (error) {
       if (timeoutId) {
@@ -983,14 +1029,33 @@ async function traceStreamText(originalFn, args, options) {
       if (isReadableStream) {
         const wrappedStream = wrapReadableStream(
           originalTextStream,
-          (fullResponse) => {
+          async (fullResponse) => {
+            let usage = {};
+            try {
+              if (result.usage) {
+                usage = await Promise.resolve(result.usage);
+              }
+              if (!usage || Object.keys(usage).length === 0) {
+                if (result.fullResponse?.usage) {
+                  usage = await Promise.resolve(result.fullResponse.usage);
+                }
+              }
+            } catch (e) {
+              console.warn("[Observa] Failed to extract usage from result:", e);
+            }
             recordTrace3(
               {
                 model: modelIdentifier,
                 prompt: requestParams.prompt || requestParams.messages || null,
                 messages: requestParams.messages || null
               },
-              fullResponse,
+              {
+                ...fullResponse,
+                usage,
+                finishReason: result.finishReason || null,
+                responseId: result.response?.id || null,
+                model: result.model ? extractModelIdentifier(result.model) : modelIdentifier
+              },
               startTime,
               options,
               fullResponse.timeToFirstToken,
@@ -1063,76 +1128,37 @@ function recordTrace3(req, res, start, opts, timeToFirstToken, streamingDuration
   try {
     const sanitizedReq = opts?.redact ? opts.redact(req) : req;
     const sanitizedRes = opts?.redact ? opts.redact(res) : res;
-    if (opts?.observa) {
-      let inputText = null;
-      if (sanitizedReq.prompt) {
-        inputText = typeof sanitizedReq.prompt === "string" ? sanitizedReq.prompt : JSON.stringify(sanitizedReq.prompt);
-      } else if (sanitizedReq.messages) {
-        inputText = sanitizedReq.messages.map((m) => m.content || m.text || "").filter(Boolean).join("\n");
-      }
-      const outputText = sanitizedRes.text || sanitizedRes.content || null;
-      const finishReason = sanitizedRes.finishReason || null;
-      const isEmptyResponse = !outputText || typeof outputText === "string" && outputText.trim().length === 0;
-      const isFailureFinishReason = finishReason === "content_filter" || finishReason === "length" || finishReason === "max_tokens";
-      if (isEmptyResponse || isFailureFinishReason) {
-        const usage2 = sanitizedRes.usage || {};
-        const inputTokens2 = usage2.promptTokens || usage2.inputTokens || null;
-        const outputTokens2 = usage2.completionTokens || usage2.outputTokens || null;
-        const totalTokens2 = usage2.totalTokens || null;
-        opts.observa.trackLLMCall({
-          model: sanitizedReq.model || sanitizedRes.model || "unknown",
-          input: inputText,
-          output: null,
-          // No output on error
-          inputMessages: sanitizedReq.messages || null,
-          outputMessages: null,
-          inputTokens: inputTokens2,
-          outputTokens: outputTokens2,
-          totalTokens: totalTokens2,
-          latencyMs: duration,
-          timeToFirstTokenMs: timeToFirstToken || null,
-          streamingDurationMs: streamingDuration || null,
-          finishReason,
-          responseId: sanitizedRes.responseId || sanitizedRes.id || null,
-          operationName: "generate_text",
-          providerName: provider || "vercel-ai",
-          responseModel: sanitizedRes.model || sanitizedReq.model || null,
-          temperature: sanitizedReq.temperature || null,
-          maxTokens: sanitizedReq.maxTokens || sanitizedReq.max_tokens || null
-        });
-        const errorType = isEmptyResponse ? "empty_response" : finishReason === "content_filter" ? "content_filtered" : "response_truncated";
-        const errorMessage = isEmptyResponse ? "AI returned empty response" : finishReason === "content_filter" ? "AI response was filtered due to content policy" : "AI response was truncated due to token limit";
-        opts.observa.trackError({
-          errorType,
-          errorMessage,
-          stackTrace: null,
-          context: {
-            request: sanitizedReq,
-            response: sanitizedRes,
-            model: sanitizedReq.model || sanitizedRes.model || "unknown",
-            input: inputText,
-            finish_reason: finishReason,
-            provider: provider || "vercel-ai",
-            duration_ms: duration
-          },
-          errorCategory: finishReason === "content_filter" ? "validation_error" : finishReason === "length" || finishReason === "max_tokens" ? "model_error" : "unknown_error",
-          errorCode: isEmptyResponse ? "empty_response" : finishReason
-        });
-        return;
-      }
-      const usage = sanitizedRes.usage || {};
-      const inputTokens = usage.promptTokens || usage.inputTokens || null;
-      const outputTokens = usage.completionTokens || usage.outputTokens || null;
-      const totalTokens = usage.totalTokens || null;
+    if (!opts?.observa) {
+      console.error(
+        "[Observa] \u26A0\uFE0F CRITICAL: observa instance not provided to observeVercelAI(). Tracking is disabled. Make sure you're using observa.observeVercelAI() instead of importing observeVercelAI directly from 'observa-sdk/instrumentation'."
+      );
+      return;
+    }
+    let inputText = null;
+    if (sanitizedReq.prompt) {
+      inputText = typeof sanitizedReq.prompt === "string" ? sanitizedReq.prompt : JSON.stringify(sanitizedReq.prompt);
+    } else if (sanitizedReq.messages) {
+      inputText = sanitizedReq.messages.map((m) => m.content || m.text || "").filter(Boolean).join("\n");
+    }
+    const outputText = sanitizedRes.text || sanitizedRes.content || null;
+    const finishReason = sanitizedRes.finishReason || null;
+    const isEmptyResponse = !outputText || typeof outputText === "string" && outputText.trim().length === 0;
+    const isFailureFinishReason = finishReason === "content_filter" || finishReason === "length" || finishReason === "max_tokens";
+    if (isEmptyResponse || isFailureFinishReason) {
+      const usage2 = sanitizedRes.usage || {};
+      const inputTokens2 = usage2.promptTokens || usage2.inputTokens || null;
+      const outputTokens2 = usage2.completionTokens || usage2.outputTokens || null;
+      const totalTokens2 = usage2.totalTokens || null;
       opts.observa.trackLLMCall({
         model: sanitizedReq.model || sanitizedRes.model || "unknown",
         input: inputText,
-        output: outputText,
+        output: null,
+        // No output on error
         inputMessages: sanitizedReq.messages || null,
-        outputMessages: sanitizedRes.messages || null,
-        inputTokens,
-        outputTokens,
-        totalTokens,
+        outputMessages: null,
+        inputTokens: inputTokens2,
+        outputTokens: outputTokens2,
+        totalTokens: totalTokens2,
         latencyMs: duration,
         timeToFirstTokenMs: timeToFirstToken || null,
         streamingDurationMs: streamingDuration || null,
@@ -1144,7 +1170,50 @@ function recordTrace3(req, res, start, opts, timeToFirstToken, streamingDuration
         temperature: sanitizedReq.temperature || null,
         maxTokens: sanitizedReq.maxTokens || sanitizedReq.max_tokens || null
       });
+      const errorType = isEmptyResponse ? "empty_response" : finishReason === "content_filter" ? "content_filtered" : "response_truncated";
+      const errorMessage = isEmptyResponse ? "AI returned empty response" : finishReason === "content_filter" ? "AI response was filtered due to content policy" : "AI response was truncated due to token limit";
+      opts.observa.trackError({
+        errorType,
+        errorMessage,
+        stackTrace: null,
+        context: {
+          request: sanitizedReq,
+          response: sanitizedRes,
+          model: sanitizedReq.model || sanitizedRes.model || "unknown",
+          input: inputText,
+          finish_reason: finishReason,
+          provider: provider || "vercel-ai",
+          duration_ms: duration
+        },
+        errorCategory: finishReason === "content_filter" ? "validation_error" : finishReason === "length" || finishReason === "max_tokens" ? "model_error" : "unknown_error",
+        errorCode: isEmptyResponse ? "empty_response" : finishReason
+      });
+      return;
     }
+    const usage = sanitizedRes.usage || {};
+    const inputTokens = usage.promptTokens || usage.inputTokens || null;
+    const outputTokens = usage.completionTokens || usage.outputTokens || null;
+    const totalTokens = usage.totalTokens || null;
+    opts.observa.trackLLMCall({
+      model: sanitizedReq.model || sanitizedRes.model || "unknown",
+      input: inputText,
+      output: outputText,
+      inputMessages: sanitizedReq.messages || null,
+      outputMessages: sanitizedRes.messages || null,
+      inputTokens,
+      outputTokens,
+      totalTokens,
+      latencyMs: duration,
+      timeToFirstTokenMs: timeToFirstToken || null,
+      streamingDurationMs: streamingDuration || null,
+      finishReason,
+      responseId: sanitizedRes.responseId || sanitizedRes.id || null,
+      operationName: "generate_text",
+      providerName: provider || "vercel-ai",
+      responseModel: sanitizedRes.model || sanitizedReq.model || null,
+      temperature: sanitizedReq.temperature || null,
+      maxTokens: sanitizedReq.maxTokens || sanitizedReq.max_tokens || null
+    });
   } catch (e) {
     console.error("[Observa] Failed to record trace", e);
   }
@@ -1154,63 +1223,72 @@ function recordError3(req, error, start, opts, provider, preExtractedInputText,
   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";
-      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");
-        }
+    if (!opts?.observa) {
+      console.error(
+        "[Observa] \u26A0\uFE0F CRITICAL: observa instance not provided to observeVercelAI(). Error tracking is disabled. Make sure you're using observa.observeVercelAI() instead of importing observeVercelAI directly from 'observa-sdk/instrumentation'."
+      );
+      return;
+    }
+    const model = sanitizedReq.model || "unknown";
+    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({
+    }
+    const providerName = provider || "vercel-ai";
+    const extractedError = extractProviderError(error, providerName);
+    opts.observa.trackLLMCall({
+      model,
+      input: inputText,
+      output: null,
+      // No output on error
+      inputMessages,
+      outputMessages: null,
+      inputTokens: null,
+      outputTokens: null,
+      totalTokens: null,
+      latencyMs: duration,
+      timeToFirstTokenMs: null,
+      streamingDurationMs: null,
+      finishReason: null,
+      responseId: null,
+      operationName: "generate_text",
+      providerName,
+      responseModel: model,
+      temperature: sanitizedReq.temperature || null,
+      maxTokens: sanitizedReq.maxTokens || sanitizedReq.max_tokens || null
+    });
+    opts.observa.trackError({
+      errorType: error?.name || extractedError.code || "UnknownError",
+      errorMessage: extractedError.message,
+      stackTrace: error?.stack || null,
+      context: {
+        request: sanitizedReq,
         model,
         input: inputText,
-        output: null,
-        // No output on error
-        inputMessages,
-        outputMessages: null,
-        inputTokens: null,
-        outputTokens: null,
-        totalTokens: null,
-        latencyMs: duration,
-        timeToFirstTokenMs: null,
-        streamingDurationMs: null,
-        finishReason: null,
-        responseId: null,
-        operationName: "generate_text",
-        providerName,
-        responseModel: model,
-        temperature: sanitizedReq.temperature || null,
-        maxTokens: sanitizedReq.maxTokens || sanitizedReq.max_tokens || null
-      });
-      opts.observa.trackError({
-        errorType: error?.name || extractedError.code || "UnknownError",
-        errorMessage: extractedError.message,
-        stackTrace: error?.stack || null,
-        context: {
-          request: sanitizedReq,
-          model,
-          input: inputText,
-          provider: providerName,
-          duration_ms: duration,
-          status_code: extractedError.statusCode || null
-        },
-        errorCategory: extractedError.category,
-        errorCode: extractedError.code
-      });
-    }
+        provider: providerName,
+        duration_ms: duration,
+        status_code: extractedError.statusCode || null
+      },
+      errorCategory: extractedError.category,
+      errorCode: extractedError.code
+    });
   } catch (e) {
     console.error("[Observa] Failed to record error", e);
   }
 }
 function observeVercelAI(aiSdk, options) {
   try {
+    if (!options?.observa) {
+      console.error(
+        "[Observa] \u26A0\uFE0F CRITICAL ERROR: observa instance not provided!\n\nTracking will NOT work. You must use observa.observeVercelAI() instead.\n\n\u274C WRONG (importing directly):\n  import { observeVercelAI } from 'observa-sdk/instrumentation';\n  const ai = observeVercelAI({ generateText, streamText });\n\n\u2705 CORRECT (using instance method):\n  import { init } from 'observa-sdk';\n  const observa = init({ apiKey: '...' });\n  const ai = observa.observeVercelAI({ generateText, streamText });\n"
+      );
+    }
     const wrapped = { ...aiSdk };
     if (aiSdk.generateText && typeof aiSdk.generateText === "function") {
       wrapped.generateText = async function(...args) {
@@ -1643,7 +1721,7 @@ var Observa = class {
       }
     }
     const operationName = options.operationName || "chat";
-    const isError = options.output === null || typeof options.output === "string" && options.output.trim().length === 0 || (options.finishReason === "content_filter" || options.finishReason === "length" || options.finishReason === "max_tokens");
+    const isError = options.output === null || typeof options.output === "string" && options.output.trim().length === 0 || options.finishReason === "content_filter" || options.finishReason === "length" || options.finishReason === "max_tokens";
     this.addEvent({
       event_type: "llm_call",
       span_id: spanId,

package/package.json

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