@brizz/sdk 0.1.3-rc.1 → 0.1.4

package/README.md

@@ -50,6 +50,7 @@ pnpm add @brizz/sdk
 ## Quick Start
 
 First, set up your environment variables:
+
 ```bash
 BRIZZ_API_KEY=your-api-key
 BRIZZ_BASE_URL=https://telemetry.brizz.dev  # Optional
@@ -60,6 +61,7 @@ BRIZZ_LOG_LEVEL=info                        # Optional: debug, info, warn, error
 ### CommonJS Projects
 
 **Option 1: Preload Only (Zero Config)**
+
 ```bash
 node --require @brizz/sdk/preload your-app.js
 ```
@@ -73,10 +75,12 @@ const { openai } = require('@ai-sdk/openai');
 generateText({
   model: openai('gpt-3.5-turbo'),
   prompt: 'Hello, world!',
-}).then(result => console.log(result.text));
+  experimental_telemetry: { isEnabled: true },
+}).then((result) => console.log(result.text));
 ```
 
 **Option 2: Preload + Initialize (Custom Config)**
+
 ```bash
 node --require @brizz/sdk/preload your-app.js
 ```
@@ -96,6 +100,7 @@ const { generateText } = require('ai');
 ```
 
 **Option 3: Manual Import + Initialize**
+
 ```javascript
 // Must be first import
 const { Brizz } = require('@brizz/sdk');
@@ -112,9 +117,11 @@ const { openai } = require('@ai-sdk/openai');
 
 ### ESM Projects
 
-> ⚠️ **ESM Requirement**: ESM projects **must** use the `--import @brizz/sdk/loader` flag for instrumentation to work. Manual import without the loader will not instrument AI libraries.
+> ⚠️ **ESM Requirement**: ESM projects **must** use the `--import @brizz/sdk/loader` flag for
+> instrumentation to work. Manual import without the loader will not instrument AI libraries.
 
 **Loader + Initialize (Required for ESM)**
+
 ```bash
 node --import @brizz/sdk/loader your-app.mjs
 ```
@@ -136,6 +143,7 @@ import { openai } from '@ai-sdk/openai';
 const result = await generateText({
   model: openai('gpt-3.5-turbo'),
   prompt: 'Hello, world!',
+  experimental_telemetry: { isEnabled: true },
 });
 ```
 
@@ -145,10 +153,12 @@ const result = await generateText({
 ## Module System Support
 
 ### CommonJS
+
 - **Preload**: `node --require @brizz/sdk/preload app.js` ⭐ (with optional `Brizz.initialize()`)
 - **Manual**: Require `@brizz/sdk` first, then `Brizz.initialize()`, then AI libraries
 
 ### ESM (ES Modules)
+
 - **Loader**: `node --import @brizz/sdk/loader app.mjs` + `Brizz.initialize()` ⭐
 - **Manual**: Import `@brizz/sdk` first, then `Brizz.initialize()`, then AI libraries
 
@@ -174,6 +184,7 @@ The SDK automatically instruments:
 - **OpenAI** - `openai` package
 - **Anthropic** - `@anthropic-ai/sdk` package
 - **Vercel AI SDK** - `ai` package (generateText, streamText, etc.)
+  - Requires `experimental_telemetry: { isEnabled: true }` in function calls
 - **LangChain** - `langchain` and `@langchain/*` packages
 - **LlamaIndex** - `llamaindex` package
 - **AWS Bedrock** - `@aws-sdk/client-bedrock-runtime`
@@ -181,6 +192,36 @@ The SDK automatically instruments:
 - **Vector Databases** - Pinecone, Qdrant, ChromaDB
 - **HTTP/Fetch** - Automatic network request tracing
 
+### Vercel AI SDK Integration
+
+For Vercel AI SDK instrumentation, you need to enable telemetry in your function calls:
+
+```typescript
+import { generateText, streamText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+// For generateText
+const result = await generateText({
+  model: openai('gpt-4'),
+  prompt: 'Hello, world!',
+  experimental_telemetry: { isEnabled: true }, // Required for instrumentation
+});
+
+// For streamText
+const stream = streamText({
+  model: openai('gpt-4'),
+  messages: [{ role: 'user', content: 'Hello!' }],
+  experimental_telemetry: { isEnabled: true }, // Required for instrumentation
+});
+```
+
+This enables automatic tracing of:
+
+- Model calls and responses
+- Token usage and costs
+- Tool calls and executions
+- Streaming data
+
 ## PII Protection & Data Masking
 
 Automatically protects sensitive data in traces and logs:
@@ -218,24 +259,81 @@ API keys, crypto addresses, IPs, and more.
 
 Group related operations under a session context:
 
+### Function Wrapper Pattern
+
 ```typescript
-import { WithSessionId, emitEvent } from '@brizz/sdk';
+import { withSessionId, emitEvent } from '@brizz/sdk';
 
 async function processUserWorkflow(userId: string) {
-  // All traces within this function will include session-123
+  // All traces within this function will include the session ID
   const result = await generateText({
     model: openai('gpt-4'),
     messages: [{ role: 'user', content: 'Hello' }],
+    experimental_telemetry: { isEnabled: true },
   });
 
-  emitEvent('workflow.completed', { userId, result: result.text });
   return result;
 }
 
-// Wrap function with session context
-await WithSessionId('session-123', processUserWorkflow, null, 'user-456');
+// Create a wrapped function that always executes with session context
+const sessionedWorkflow = withSessionId('session-123', processUserWorkflow);
+
+// Call multiple times, each with the same session context
+await sessionedWorkflow('user-456');
+await sessionedWorkflow('user-789');
+```
+
+### Immediate Execution Pattern
+
+```typescript
+import { callWithSessionId } from '@brizz/sdk';
+
+// Execute function immediately with session context
+await callWithSessionId('session-123', processUserWorkflow, null, 'user-456');
+```
+
+### Handling Method Context
+
+When wrapping methods that use `this`, you have several options:
+
+#### Option 1: Arrow Function (Recommended)
+
+```typescript
+class ChatService {
+  async processMessage(userId: string, message: string) {
+    // This method uses 'this' context
+    return `Processed by ${this.serviceName}: ${message}`;
+  }
+}
+
+const service = new ChatService();
+// Wrap with arrow function to preserve 'this' context
+const sessionedProcess = withSessionId('session-123', (userId: string, message: string) =>
+  service.processMessage(userId, message),
+);
+```
+
+#### Option 2: Using bind()
+
+```typescript
+// Pre-bind the method to preserve 'this' context
+const sessionedProcess = withSessionId('session-123', service.processMessage.bind(service));
 ```
 
+#### Option 3: Explicit thisArg Parameter
+
+```typescript
+// Pass 'this' context explicitly as third parameter
+const sessionedProcess = withSessionId(
+  'session-123',
+  service.processMessage,
+  service, // explicit 'this' context
+);
+```
+
+**Note:** The arrow function approach (Option 1) is recommended as it's more explicit, avoids lint
+warnings, and is less prone to `this` binding issues.
+
 ## Custom Events & Logging
 
 Emit custom events and structured logs:
@@ -380,6 +478,7 @@ Check out the [examples](./examples/) directory for complete working examples:
 - For ESM, use loader + `Brizz.initialize()`
 - For CommonJS, use preload (with optional `Brizz.initialize()`)
 - Check that `BRIZZ_API_KEY` is set
+- For Vercel AI SDK: Add `experimental_telemetry: { isEnabled: true }` to function calls
 
 **CJS/ESM compatibility issues**
 

package/dist/index.cjs

@@ -34,7 +34,7 @@ __export(src_exports, {
   DEFAULT_PII_PATTERNS: () => DEFAULT_PII_PATTERNS,
   LogLevel: () => LogLevel,
   SeverityNumber: () => import_api_logs2.SeverityNumber,
-  WithSessionId: () => WithSessionId,
+  callWithSessionId: () => callWithSessionId,
   detectRuntime: () => detectRuntime,
   emitEvent: () => emitEvent,
   getLogLevel: () => getLogLevel,
@@ -46,7 +46,8 @@ __export(src_exports, {
   logger: () => logger,
   maskAttributes: () => maskAttributes,
   maskValue: () => maskValue,
-  setLogLevel: () => setLogLevel
+  setLogLevel: () => setLogLevel,
+  withSessionId: () => withSessionId
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -1469,7 +1470,7 @@ var HANDLED_SPAN_NAMES = {
   "ai.streamText": "ai.streamText",
   "ai.toolCall": (span) => {
     const toolName = span.attributes["ai.toolCall.name"];
-    return `${toolName}.tool`;
+    return `${String(toolName ?? "unknown")}.tool`;
   }
 };
 var AI_RESPONSE_TEXT = "ai.response.text";
@@ -1479,10 +1480,11 @@ var AI_USAGE_COMPLETION_TOKENS = "ai.usage.completionTokens";
 var AI_MODEL_PROVIDER = "ai.model.provider";
 var transformAiSdkSpanName = (span) => {
   if (span.name in HANDLED_SPAN_NAMES) {
-    if (typeof HANDLED_SPAN_NAMES[span.name] === "function") {
-      span.name = HANDLED_SPAN_NAMES[span.name](span);
-    } else {
-      span.name = HANDLED_SPAN_NAMES[span.name];
+    const handler = HANDLED_SPAN_NAMES[span.name];
+    if (typeof handler === "function") {
+      span.name = handler(span);
+    } else if (handler) {
+      span.name = handler;
     }
   }
 };
@@ -1497,26 +1499,30 @@ var transformPromptMessages = (attributes) => {
   if (AI_PROMPT_MESSAGES in attributes) {
     try {
       const messages = JSON.parse(attributes[AI_PROMPT_MESSAGES]);
-      messages.forEach((msg, index) => {
-        logger.debug("Transforming prompt message", { msg, type: typeof msg.content });
-        if (typeof msg.content === "string") {
-          attributes[`${import_ai_semantic_conventions.SpanAttributes.LLM_PROMPTS}.${index}.content`] = msg.content;
+      for (const [index, msg] of messages.entries()) {
+        const message = msg;
+        logger.debug("Transforming prompt message", { msg: message, type: typeof message.content });
+        if (typeof message.content === "string") {
+          attributes[`${import_ai_semantic_conventions.SpanAttributes.LLM_PROMPTS}.${index}.content`] = message.content;
         } else {
-          if (Array.isArray(msg.content) && msg.content.length > 0) {
-            const lastContent = msg.content[msg.content.length - 1];
-            if (lastContent.text) {
+          if (Array.isArray(message.content) && message.content.length > 0) {
+            const lastContent = message.content.at(-1);
+            if (lastContent?.text) {
               attributes[`${import_ai_semantic_conventions.SpanAttributes.LLM_PROMPTS}.${index}.content`] = lastContent.text;
             }
           } else {
             attributes[`${import_ai_semantic_conventions.SpanAttributes.LLM_PROMPTS}.${index}.content`] = JSON.stringify(
-              msg.content
+              message.content
             );
           }
         }
-        attributes[`${import_ai_semantic_conventions.SpanAttributes.LLM_PROMPTS}.${index}.role`] = msg.role;
-      });
+        attributes[`${import_ai_semantic_conventions.SpanAttributes.LLM_PROMPTS}.${index}.role`] = message.role;
+      }
       delete attributes[AI_PROMPT_MESSAGES];
-    } catch {
+    } catch (error) {
+      logger.debug("Skipping prompt messages transformation because of JSON parsing error", {
+        e: error
+      });
     }
   }
 };
@@ -1542,11 +1548,7 @@ var calculateTotalTokens = (attributes) => {
 var transformVendor = (attributes) => {
   if (AI_MODEL_PROVIDER in attributes) {
     const vendor = attributes[AI_MODEL_PROVIDER];
-    if (vendor && vendor.startsWith("openai")) {
-      attributes[import_ai_semantic_conventions.SpanAttributes.LLM_SYSTEM] = "OpenAI";
-    } else {
-      attributes[import_ai_semantic_conventions.SpanAttributes.LLM_SYSTEM] = vendor;
-    }
+    attributes[import_ai_semantic_conventions.SpanAttributes.LLM_SYSTEM] = vendor && vendor.startsWith("openai") ? "OpenAI" : vendor;
     delete attributes[AI_MODEL_PROVIDER];
   }
 };
@@ -1562,6 +1564,10 @@ var shouldHandleSpan = (span) => {
   return span.name in HANDLED_SPAN_NAMES;
 };
 var transformAiSdkSpan = (span) => {
+  if (!shouldHandleSpan(span)) {
+    logger.debug("Skipping span transformation", { spanName: span.name });
+    return;
+  }
   for (const key in span.attributes) {
     if (Number.isNaN(span.attributes[key])) {
       span.attributes[key] = 0;
@@ -1572,10 +1578,6 @@ var transformAiSdkSpan = (span) => {
     spanContext: span.spanContext(),
     attributes: span.attributes
   });
-  if (!shouldHandleSpan(span)) {
-    logger.debug("Skipping span transformation", { spanName: span.name });
-    return;
-  }
   transformAiSdkSpanName(span);
   transformAiSdkAttributes(span.attributes);
 };
@@ -1790,7 +1792,15 @@ function withProperties(properties, fn, thisArg, ...args) {
   const newContext = import_api5.context.active().setValue(PROPERTIES_CONTEXT_KEY, properties);
   return import_api5.context.with(newContext, fn, thisArg, ...args);
 }
-function WithSessionId(sessionId, fn, thisArg, ...args) {
+function withSessionId(sessionId, fn, thisArg) {
+  return function wrapped(...args) {
+    const base = import_api5.context.active();
+    const prev = base.getValue(PROPERTIES_CONTEXT_KEY);
+    const next = base.setValue(PROPERTIES_CONTEXT_KEY, prev ? { ...prev, [SESSION_ID]: sessionId } : { [SESSION_ID]: sessionId });
+    return import_api5.context.with(next, fn, thisArg ?? this, ...args);
+  };
+}
+function callWithSessionId(sessionId, fn, thisArg, ...args) {
   return withProperties({ [SESSION_ID]: sessionId }, fn, thisArg, ...args);
 }
 
@@ -2034,7 +2044,7 @@ var init_exports = {};
   DEFAULT_PII_PATTERNS,
   LogLevel,
   SeverityNumber,
-  WithSessionId,
+  callWithSessionId,
   detectRuntime,
   emitEvent,
   getLogLevel,
@@ -2046,6 +2056,7 @@ var init_exports = {};
   logger,
   maskAttributes,
   maskValue,
-  setLogLevel
+  setLogLevel,
+  withSessionId
 });
 //# sourceMappingURL=index.cjs.map