@brizz/sdk 0.1.3 → 0.1.5

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
 ```
@@ -74,10 +76,11 @@ generateText({
   model: openai('gpt-3.5-turbo'),
   prompt: 'Hello, world!',
   experimental_telemetry: { isEnabled: true },
-}).then(result => console.log(result.text));
+}).then((result) => console.log(result.text));
 ```
 
 **Option 2: Preload + Initialize (Custom Config)**
+
 ```bash
 node --require @brizz/sdk/preload your-app.js
 ```
@@ -97,6 +100,7 @@ const { generateText } = require('ai');
 ```
 
 **Option 3: Manual Import + Initialize**
+
 ```javascript
 // Must be first import
 const { Brizz } = require('@brizz/sdk');
@@ -113,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
 ```
@@ -147,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
 
@@ -208,6 +216,7 @@ const stream = streamText({
 ```
 
 This enables automatic tracing of:
+
 - Model calls and responses
 - Token usage and costs
 - Tool calls and executions
@@ -250,23 +259,91 @@ 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.
+
+## Deployment Environment
+
+Optionally specify the deployment environment for better filtering and organization:
+
+```typescript
+Brizz.initialize({
+  apiKey: 'your-api-key',
+  appName: 'my-app',
+  environment: 'production', // Optional: 'dev', 'staging', 'production', etc.
+});
 ```
 
 ## Custom Events & Logging

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);
 
@@ -325,6 +326,7 @@ function resolveConfig(options) {
     headers: { ...options.headers },
     apiKey: process.env["BRIZZ_API_KEY"] || options.apiKey,
     disableBatch: process.env["BRIZZ_DISABLE_BATCH"] === "true" || !!options.disableBatch,
+    environment: process.env["BRIZZ_ENVIRONMENT"] || options.environment,
     logLevel: resolvedLogLevel,
     masking: resolvedMasking
   };
@@ -1019,7 +1021,7 @@ function maskStringByPattern(value, pattern, mode = "full") {
     logger.warn("Regex execution failed, skipping masking", error);
     return value;
   }
-  for (const matchInfo of matches.reverse()) {
+  for (const matchInfo of matches.toReversed()) {
     let patternName = "unknown";
     if (matchInfo.groups) {
       for (const [groupName, groupValue] of Object.entries(matchInfo.groups)) {
@@ -1265,9 +1267,13 @@ var LoggingModule = class _LoggingModule {
     logger.debug("Creating resource with service name", {
       serviceName: config.appName
     });
-    const resource = (0, import_resources.resourceFromAttributes)({
+    const resourceAttributes = {
       "service.name": config.appName
-    });
+    };
+    if (config.environment) {
+      resourceAttributes["deployment.environment"] = config.environment;
+    }
+    const resource = (0, import_resources.resourceFromAttributes)(resourceAttributes);
     logger.debug("Creating logger provider with resource");
     this.loggerProvider = new import_sdk_logs2.LoggerProvider({
       resource,
@@ -1458,130 +1464,6 @@ var import_exporter_trace_otlp_http = require("@opentelemetry/exporter-trace-otl
 // src/internal/trace/processors/span-processor.ts
 var import_api4 = require("@opentelemetry/api");
 var import_sdk_trace_base = require("@opentelemetry/sdk-trace-base");
-
-// src/internal/trace/transformations/vercel-ai.ts
-var import_ai_semantic_conventions = require("@traceloop/ai-semantic-conventions");
-var AI_GENERATE_TEXT_DO_GENERATE = "ai.generateText.doGenerate";
-var AI_STREAM_TEXT_DO_STREAM = "ai.streamText.doStream";
-var HANDLED_SPAN_NAMES = {
-  [AI_GENERATE_TEXT_DO_GENERATE]: "gen_ai.chat",
-  [AI_STREAM_TEXT_DO_STREAM]: "gen_ai.chat",
-  "ai.streamText": "ai.streamText",
-  "ai.toolCall": (span) => {
-    const toolName = span.attributes["ai.toolCall.name"];
-    return `${String(toolName ?? "unknown")}.tool`;
-  }
-};
-var AI_RESPONSE_TEXT = "ai.response.text";
-var AI_PROMPT_MESSAGES = "ai.prompt.messages";
-var AI_USAGE_PROMPT_TOKENS = "ai.usage.promptTokens";
-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) {
-    const handler = HANDLED_SPAN_NAMES[span.name];
-    if (typeof handler === "function") {
-      span.name = handler(span);
-    } else if (handler) {
-      span.name = handler;
-    }
-  }
-};
-var transformResponseText = (attributes) => {
-  if (AI_RESPONSE_TEXT in attributes) {
-    attributes[`${import_ai_semantic_conventions.SpanAttributes.LLM_COMPLETIONS}.0.content`] = attributes[AI_RESPONSE_TEXT];
-    attributes[`${import_ai_semantic_conventions.SpanAttributes.LLM_COMPLETIONS}.0.role`] = "assistant";
-    delete attributes[AI_RESPONSE_TEXT];
-  }
-};
-var transformPromptMessages = (attributes) => {
-  if (AI_PROMPT_MESSAGES in attributes) {
-    try {
-      const messages = JSON.parse(attributes[AI_PROMPT_MESSAGES]);
-      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(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(
-              message.content
-            );
-          }
-        }
-        attributes[`${import_ai_semantic_conventions.SpanAttributes.LLM_PROMPTS}.${index}.role`] = message.role;
-      }
-      delete attributes[AI_PROMPT_MESSAGES];
-    } catch (error) {
-      logger.debug("Skipping prompt messages transformation because of JSON parsing error", {
-        e: error
-      });
-    }
-  }
-};
-var transformPromptTokens = (attributes) => {
-  if (AI_USAGE_PROMPT_TOKENS in attributes) {
-    attributes[`${import_ai_semantic_conventions.SpanAttributes.LLM_USAGE_PROMPT_TOKENS}`] = attributes[AI_USAGE_PROMPT_TOKENS];
-    delete attributes[AI_USAGE_PROMPT_TOKENS];
-  }
-};
-var transformCompletionTokens = (attributes) => {
-  if (AI_USAGE_COMPLETION_TOKENS in attributes) {
-    attributes[`${import_ai_semantic_conventions.SpanAttributes.LLM_USAGE_COMPLETION_TOKENS}`] = attributes[AI_USAGE_COMPLETION_TOKENS];
-    delete attributes[AI_USAGE_COMPLETION_TOKENS];
-  }
-};
-var calculateTotalTokens = (attributes) => {
-  const promptTokens = attributes[`${import_ai_semantic_conventions.SpanAttributes.LLM_USAGE_PROMPT_TOKENS}`];
-  const completionTokens = attributes[`${import_ai_semantic_conventions.SpanAttributes.LLM_USAGE_COMPLETION_TOKENS}`];
-  if (promptTokens && completionTokens) {
-    attributes[`${import_ai_semantic_conventions.SpanAttributes.LLM_USAGE_TOTAL_TOKENS}`] = Number(promptTokens) + Number(completionTokens);
-  }
-};
-var transformVendor = (attributes) => {
-  if (AI_MODEL_PROVIDER in attributes) {
-    const vendor = attributes[AI_MODEL_PROVIDER];
-    attributes[import_ai_semantic_conventions.SpanAttributes.LLM_SYSTEM] = vendor && vendor.startsWith("openai") ? "OpenAI" : vendor;
-    delete attributes[AI_MODEL_PROVIDER];
-  }
-};
-var transformAiSdkAttributes = (attributes) => {
-  transformResponseText(attributes);
-  transformPromptMessages(attributes);
-  transformPromptTokens(attributes);
-  transformCompletionTokens(attributes);
-  calculateTotalTokens(attributes);
-  transformVendor(attributes);
-};
-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;
-    }
-  }
-  logger.debug("Transforming AI SDK span", {
-    spanName: span.name,
-    spanContext: span.spanContext(),
-    attributes: span.attributes
-  });
-  transformAiSdkSpanName(span);
-  transformAiSdkAttributes(span.attributes);
-};
-
-// src/internal/trace/processors/span-processor.ts
 var DEFAULT_MASKING_RULES = [
   {
     mode: "partial",
@@ -1624,10 +1506,6 @@ var BrizzSimpleSpanProcessor = class extends import_sdk_trace_base.SimpleSpanPro
     }
     super.onStart(span, parentContext);
   }
-  onEnd(span) {
-    transformAiSdkSpan(span);
-    super.onEnd(span);
-  }
 };
 var BrizzBatchSpanProcessor = class extends import_sdk_trace_base.BatchSpanProcessor {
   config;
@@ -1648,10 +1526,6 @@ var BrizzBatchSpanProcessor = class extends import_sdk_trace_base.BatchSpanProce
     }
     super.onStart(span, parentContext);
   }
-  onEnd(span) {
-    transformAiSdkSpan(span);
-    super.onEnd(span);
-  }
 };
 function maskSpan(span, config) {
   if (!span.attributes || Object.keys(span.attributes).length === 0) {
@@ -1791,7 +1665,18 @@ 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);
 }
 
@@ -1865,12 +1750,16 @@ var _Brizz = class __Brizz {
     }
     const registry = InstrumentationRegistry.getInstance();
     const manualInstrumentations = registry.getManualInstrumentations();
+    const resourceAttributes = {
+      "service.name": resolvedConfig.appName
+    };
+    if (resolvedConfig.environment) {
+      resourceAttributes["deployment.environment"] = resolvedConfig.environment;
+    }
     this._sdk = new import_sdk_node.NodeSDK({
       spanProcessors: [getSpanProcessor()],
       metricReader: getMetricsReader(),
-      resource: (0, import_resources2.resourceFromAttributes)({
-        "service.name": resolvedConfig.appName
-      }),
+      resource: (0, import_resources2.resourceFromAttributes)(resourceAttributes),
       instrumentations: manualInstrumentations
     });
     this._sdk.start();
@@ -1994,7 +1883,10 @@ function detectRuntime() {
   const isESM = noNodeJSGlobals && noModuleSystem;
   const isCJS = hasRequire && typeof module !== "undefined" && typeof exports !== "undefined" && typeof __filename === "string" && typeof __dirname === "string";
   const supportsLoaderAPI = (major ?? 0) >= 21 || (major ?? 0) === 20 && (minor ?? 0) >= 6 || (major ?? 0) === 18 && (minor ?? 0) >= 19;
-  const supportsRegister = !!process.features?.typescript || !!globalThis.module?.register;
+  const supportsRegister = (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    !!process.features?.typescript || !!globalThis.module?.register
+  );
   logger.debug("Runtime detection results:", {
     nodeVersion: `${major ?? 0}.${minor ?? 0}`,
     isESM,
@@ -2015,6 +1907,7 @@ function detectRuntime() {
       module: typeof module,
       exports: typeof exports,
       "process.features": process.features,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
       "globalThis.module": globalThis.module
     }
   });
@@ -2035,7 +1928,7 @@ var init_exports = {};
   DEFAULT_PII_PATTERNS,
   LogLevel,
   SeverityNumber,
-  WithSessionId,
+  callWithSessionId,
   detectRuntime,
   emitEvent,
   getLogLevel,
@@ -2047,6 +1940,7 @@ var init_exports = {};
   logger,
   maskAttributes,
   maskValue,
-  setLogLevel
+  setLogLevel,
+  withSessionId
 });
 //# sourceMappingURL=index.cjs.map