@brizz/sdk 0.1.8 → 0.1.10

package/README.md

@@ -259,8 +259,64 @@ API keys, crypto addresses, IPs, and more.
 
 Group related operations under a session context:
 
+### Session Context Manager (Recommended)
+
+The `startSession` function creates a session span and provides a `Session` object:
+
+```typescript
+import { startSession } from '@brizz/sdk';
+
+// Basic usage - all LLM calls within the callback are automatically linked
+const result = await startSession(
+  'session-123',
+  async (session) => {
+    // Add custom properties (optional)
+    session.updateProperties({ userId: 'user-456', model: 'gpt-4' });
+
+    const response = await openai.chat.completions.create({
+      model: 'gpt-4',
+      messages: [{ role: 'user', content: userQuery }],
+    });
+
+    return response;
+  },
+  { feature: 'chat' }, // optional: extraProperties propagated to all spans
+);
+```
+
+**Session Methods:**
+- `session.updateProperties({ key: value })` - Add custom properties to the session span
+- `session.setInput(text)` - (Optional) Manually track input text
+- `session.setOutput(text)` - (Optional) Manually track output text
+
+**When to use manual input/output tracking:**
+
+In most cases, Brizz automatically captures inputs and outputs from your LLM calls. Use `setInput`/`setOutput` for special scenarios:
+
+- **Multi-agent flows**: Track only user-facing input/output, not intermediate agent communications
+- **Structured data extraction**: Track a specific field from complex JSON requests
+- **Post-processing**: Track transformed responses before returning to the user
+
+```typescript
+await startSession('session-456', async (session) => {
+  // Extract just the query from a structured request
+  const requestData = { query: "What's the weather?", context: {...} };
+  session.setInput(requestData.query);
+
+  const response = await openai.chat.completions.create({...});
+
+  // Extract answer from structured response
+  const responseJson = JSON.parse(response.choices[0].message.content);
+  session.setOutput(responseJson.answer);
+
+  return responseJson;
+});
+```
+
 ### Function Wrapper Pattern
 
+For simpler cases where you just need to tag traces with a session ID:
+
 ```typescript
 import { withSessionId, emitEvent } from '@brizz/sdk';
 
@@ -276,7 +332,8 @@ async function processUserWorkflow(userId: string) {
 }
 
 // Create a wrapped function that always executes with session context
-const sessionedWorkflow = withSessionId('session-123', processUserWorkflow);
+// withSessionId(sessionId, fn, thisArg?, extraProperties?)
+const sessionedWorkflow = withSessionId('session-123', processUserWorkflow, undefined, { feature: 'workflow' });
 
 // Call multiple times, each with the same session context
 await sessionedWorkflow('user-456');

package/dist/index.cjs

@@ -33,6 +33,7 @@ __export(src_exports, {
   Brizz: () => Brizz,
   DEFAULT_PII_PATTERNS: () => DEFAULT_PII_PATTERNS,
   LogLevel: () => LogLevel,
+  Session: () => Session,
   SeverityNumber: () => import_api_logs2.SeverityNumber,
   callWithProperties: () => callWithProperties,
   callWithSessionId: () => callWithSessionId,
@@ -48,6 +49,7 @@ __export(src_exports, {
   maskAttributes: () => maskAttributes,
   maskValue: () => maskValue,
   setLogLevel: () => setLogLevel,
+  startSession: () => startSession,
   withProperties: () => withProperties,
   withSessionId: () => withSessionId
 });
@@ -480,7 +482,7 @@ var import_sdk_logs2 = require("@opentelemetry/sdk-logs");
 
 // src/internal/version.ts
 function getSDKVersion() {
-  return "0.1.8";
+  return "0.1.10";
 }
 
 // src/internal/log/processors/log-processor.ts
@@ -1115,6 +1117,9 @@ var BRIZZ = "brizz";
 var PROPERTIES = "properties";
 var SESSION_ID = "session.id";
 var PROPERTIES_CONTEXT_KEY = (0, import_api2.createContextKey)(PROPERTIES);
+var SESSION_INPUT = "brizz.session.input";
+var SESSION_OUTPUT = "brizz.session.output";
+var SESSION_SPAN_NAME = "brizz.start_session";
 
 // src/internal/log/processors/log-processor.ts
 var DEFAULT_LOG_MASKING_RULES = [
@@ -1473,7 +1478,7 @@ function getMetricsReader() {
 }
 
 // src/internal/trace/tracing.ts
-var import_exporter_trace_otlp_http = require("@opentelemetry/exporter-trace-otlp-http");
+var import_exporter_trace_otlp_proto = require("@opentelemetry/exporter-trace-otlp-proto");
 
 // src/internal/trace/processors/span-processor.ts
 var import_api4 = require("@opentelemetry/api");
@@ -1606,7 +1611,7 @@ var TracingModule = class _TracingModule {
     }
     const tracesUrl = config.baseUrl.replace(/\/$/, "") + "/v1/traces";
     logger.debug("Initializing default OTLP span exporter", { url: tracesUrl });
-    this.spanExporter = new import_exporter_trace_otlp_http.OTLPTraceExporter({
+    this.spanExporter = new import_exporter_trace_otlp_proto.OTLPTraceExporter({
       url: tracesUrl,
       headers: config.headers
     });
@@ -1689,12 +1694,97 @@ function withProperties(properties, fn, thisArg) {
     );
   };
 }
-function withSessionId(sessionId, fn, thisArg) {
-  return withProperties({ [SESSION_ID]: sessionId }, fn, thisArg);
+function withSessionId(sessionId, fn, thisArg, extraProperties) {
+  const properties = { [SESSION_ID]: sessionId, ...extraProperties };
+  return withProperties(properties, fn, thisArg);
 }
 function callWithSessionId(sessionId, fn, thisArg, ...args) {
   return callWithProperties({ [SESSION_ID]: sessionId }, fn, thisArg, ...args);
 }
+var Session = class {
+  sessionId;
+  span;
+  inputs = [];
+  outputs = [];
+  constructor(sessionId, span) {
+    this.sessionId = sessionId;
+    this.span = span;
+  }
+  /**
+   * (Optional) Append text to session input tracking.
+   * Use when you need to track specific input data that differs from what's sent to the LLM.
+   * Multiple calls accumulate in an array.
+   *
+   * @param text - Text to append to session input
+   */
+  setInput(text) {
+    this.inputs.push(text);
+    this.span.setAttribute(SESSION_INPUT, JSON.stringify(this.inputs));
+  }
+  /**
+   * (Optional) Append text to session output tracking.
+   * Use when you need to track specific output data that differs from what's received from the LLM.
+   * Multiple calls accumulate in an array.
+   *
+   * @param text - Text to append to session output
+   */
+  setOutput(text) {
+    this.outputs.push(text);
+    this.span.setAttribute(SESSION_OUTPUT, JSON.stringify(this.outputs));
+  }
+  /**
+   * Update custom properties on the session span.
+   * Properties are prefixed with 'brizz.'.
+   *
+   * @param properties - Key-value properties to set on the session
+   */
+  updateProperties(properties) {
+    for (const [key, value] of Object.entries(properties)) {
+      this.span.setAttribute(`${BRIZZ}.${key}`, value);
+    }
+  }
+};
+function startSession(sessionId, callback, extraProperties) {
+  const tracer = import_api5.trace.getTracer("@brizz/sdk");
+  return tracer.startActiveSpan(SESSION_SPAN_NAME, (span) => {
+    span.setAttribute(`${BRIZZ}.${SESSION_ID}`, sessionId);
+    if (extraProperties) {
+      for (const [key, value] of Object.entries(extraProperties)) {
+        span.setAttribute(`${BRIZZ}.${key}`, value);
+      }
+    }
+    const session = new Session(sessionId, span);
+    const contextProperties = { [SESSION_ID]: sessionId };
+    if (extraProperties) {
+      for (const [key, value] of Object.entries(extraProperties)) {
+        contextProperties[key] = String(value);
+      }
+    }
+    return callWithProperties(contextProperties, () => {
+      try {
+        const result = callback(session);
+        if (result && typeof result.then === "function") {
+          return result.then((value) => {
+            span.end();
+            return value;
+          }).catch((error) => {
+            span.recordException(error);
+            span.setStatus({ code: import_api5.SpanStatusCode.ERROR });
+            span.end();
+            throw error;
+          });
+        }
+        span.end();
+        return result;
+      } catch (error) {
+        span.recordException(error);
+        span.setStatus({ code: import_api5.SpanStatusCode.ERROR });
+        span.end();
+        throw error;
+      }
+    });
+  });
+}
 
 // src/internal/sdk.ts
 var _Brizz = class __Brizz {
@@ -1945,6 +2035,7 @@ var init_exports = {};
   Brizz,
   DEFAULT_PII_PATTERNS,
   LogLevel,
+  Session,
   SeverityNumber,
   callWithProperties,
   callWithSessionId,
@@ -1960,6 +2051,7 @@ var init_exports = {};
   maskAttributes,
   maskValue,
   setLogLevel,
+  startSession,
   withProperties,
   withSessionId
 });