@brizz/sdk 0.1.15 → 0.1.17

package/README.md

@@ -20,6 +20,7 @@ libraries including OpenAI, Anthropic, Vercel AI SDK, and more.
 - [Session Tracking](#session-tracking)
 - [Custom Events & Logging](#custom-events--logging)
 - [Environment Variables](#environment-variables)
+- [Disable Span Export](#disable-span-export)
 - [Advanced Configuration](#advanced-configuration)
 - [Testing & Development](#testing--development)
 - [Package.json Examples](#packagejson-examples)
@@ -288,6 +289,7 @@ const result = await startSession(
 - `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
+- `session.setTitle(text)` - Set a session title (typically used with `mode: 'title'`)
 
 **When to use manual input/output tracking:**
 
@@ -313,6 +315,38 @@ await startSession('session-456', async (session) => {
 });
 ```
 
+### Session Title Generation
+
+If you use an LLM call to generate session titles, wrap it so those spans don't appear as part of the conversation:
+
+```typescript
+import { startSession, startSessionTitle } from '@brizz/sdk';
+
+await startSession('session-123', async (session) => {
+  const response = await openai.chat.completions.create({...});
+
+  // Title generation — excluded from conversation view
+  await startSessionTitle(async (title) => {
+    const t = await openai.chat.completions.create({
+      model: 'gpt-4',
+      messages: [{ role: 'user', content: 'Summarize this chat in 3 words' }],
+    });
+    title.setTitle(t.choices[0].message.content);
+  });
+});
+
+// Or use mode: 'title' on startSession directly
+await startSession('session-123', async (session) => {
+  const t = await openai.chat.completions.create({...});
+  session.setTitle(t.choices[0].message.content);
+}, undefined, { mode: 'title' });
+
+// Or use startSessionTitle outside a session (pass sessionId explicitly)
+await startSessionTitle(async (title) => {
+  title.setTitle('My Title');
+}, { sessionId: 'session-123' });
+```
+
 ### Accessing the Active Session
 
 Use `getActiveSession()` to retrieve the current session from anywhere within a `startSession` scope — no need to pass the session object through your call stack:
@@ -474,13 +508,26 @@ BRIZZ_BASE_URL=https://telemetry.brizz.dev    # Default telemetry endpoint
 BRIZZ_APP_NAME=my-app                         # Application name
 BRIZZ_APP_VERSION=1.0.0                       # Application version
 BRIZZ_ENVIRONMENT=production                  # Environment (dev, staging, prod)
-BRIZZ_LOG_LEVEL=info                         # SDK log level
+BRIZZ_LOG_LEVEL=info                          # SDK log level
+BRIZZ_DISABLE_SPAN_EXPORTER=true              # Skip span export (see "Disable Span Export")
 
 # OpenTelemetry Standard Variables
 OTEL_SERVICE_NAME=my-service                               # Service name
 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true    # Capture AI content
 ```
 
+## Disable Span Export
+
+Keep `Brizz.initialize()` in your code without sending any spans — useful for dev/test
+environments. When enabled, the SDK skips span exporter and processor setup, so no
+spans are exported. Metrics and logs continue to work.
+
+```typescript
+Brizz.initialize({ apiKey: 'your-api-key', disableSpanExporter: true });
+```
+
+Or via env var: `BRIZZ_DISABLE_SPAN_EXPORTER=true`.
+
 ## Advanced Configuration
 
 ```typescript

package/dist/index.cjs

@@ -34,6 +34,7 @@ __export(src_exports, {
   DEFAULT_PII_PATTERNS: () => DEFAULT_PII_PATTERNS,
   LogLevel: () => LogLevel,
   Session: () => Session,
+  SessionTitle: () => SessionTitle,
   SeverityNumber: () => import_api_logs2.SeverityNumber,
   callWithProperties: () => callWithProperties,
   callWithSessionId: () => callWithSessionId,
@@ -51,6 +52,7 @@ __export(src_exports, {
   maskValue: () => maskValue,
   setLogLevel: () => setLogLevel,
   startSession: () => startSession,
+  startSessionTitle: () => startSessionTitle,
   withProperties: () => withProperties,
   withSessionId: () => withSessionId
 });
@@ -329,6 +331,7 @@ function resolveConfig(options) {
     headers: { ...options.headers },
     apiKey: process.env["BRIZZ_API_KEY"] || options.apiKey,
     disableBatch: process.env["BRIZZ_DISABLE_BATCH"] === "true" || !!options.disableBatch,
+    disableSpanExporter: process.env["BRIZZ_DISABLE_SPAN_EXPORTER"] === "true" || !!options.disableSpanExporter,
     environment: process.env["BRIZZ_ENVIRONMENT"] || options.environment,
     logLevel: resolvedLogLevel,
     masking: resolvedMasking
@@ -494,7 +497,7 @@ var import_sdk_logs2 = require("@opentelemetry/sdk-logs");
 
 // src/internal/version.ts
 function getSDKVersion() {
-  return "0.1.15";
+  return "0.1.17";
 }
 
 // src/internal/log/processors/log-processor.ts
@@ -1135,6 +1138,9 @@ var SESSION_OBJECT_CONTEXT_KEY = (0, import_api2.createContextKey)("brizz.sessio
 var SESSION_INPUT = "brizz.session.input";
 var SESSION_OUTPUT = "brizz.session.output";
 var SESSION_SPAN_NAME = "brizz.start_session";
+var SESSION_TITLE_SPAN_NAME = "brizz.session_title";
+var SESSION_TITLE_GENERATION = "session.title_generation";
+var SESSION_TITLE = "brizz.session.title";
 
 // src/internal/log/processors/log-processor.ts
 var DEFAULT_LOG_MASKING_RULES = [
@@ -1638,6 +1644,15 @@ var TracingModule = class _TracingModule {
    */
   setup(config) {
     logger.info("Setting up tracing module");
+    if (config.disableSpanExporter) {
+      logger.info(
+        "Span exporter disabled via disableSpanExporter; skipping exporter and processor setup"
+      );
+      this.spanExporter = null;
+      this.spanProcessor = null;
+      _TracingModule.instance = this;
+      return;
+    }
     this.initSpanExporter(config);
     this.initSpanProcessor(config);
     _TracingModule.instance = this;
@@ -1781,6 +1796,14 @@ var Session = class {
     this.outputs.push(text);
     this.span.setAttribute(SESSION_OUTPUT, JSON.stringify(this.outputs));
   }
+  /**
+   * Set the session title on the span.
+   *
+   * @param title - The generated title string
+   */
+  setTitle(title) {
+    this.span.setAttribute(SESSION_TITLE, title);
+  }
   /**
    * Update custom properties on the session span.
    * Properties are prefixed with 'brizz.'.
@@ -1793,12 +1816,28 @@ var Session = class {
     }
   }
 };
+var SessionTitle = class {
+  span;
+  constructor(span) {
+    this.span = span;
+  }
+  /**
+   * Set the generated title on the wrapper span.
+   *
+   * @param title - The generated title string
+   */
+  setTitle(title) {
+    this.span.setAttribute(SESSION_TITLE, title);
+  }
+};
 function getActiveSession() {
   return import_api5.context.active().getValue(SESSION_OBJECT_CONTEXT_KEY);
 }
-function startSession(sessionId, callback, extraProperties) {
+function startSession(sessionId, callback, extraProperties, options) {
+  const isTitle = options?.mode === "title";
+  const spanName = isTitle ? SESSION_TITLE_SPAN_NAME : SESSION_SPAN_NAME;
   const tracer = import_api5.trace.getTracer("@brizz/sdk");
-  return tracer.startActiveSpan(SESSION_SPAN_NAME, (span) => {
+  return tracer.startActiveSpan(spanName, (span) => {
     span.setAttribute(`${BRIZZ}.${SESSION_ID}`, sessionId);
     if (extraProperties) {
       for (const [key, value] of Object.entries(extraProperties)) {
@@ -1807,6 +1846,9 @@ function startSession(sessionId, callback, extraProperties) {
     }
     const session = new Session(sessionId, span);
     const contextProperties = { [SESSION_ID]: sessionId };
+    if (isTitle) {
+      contextProperties[SESSION_TITLE_GENERATION] = "true";
+    }
     if (extraProperties) {
       for (const [key, value] of Object.entries(extraProperties)) {
         contextProperties[key] = String(value);
@@ -1840,6 +1882,43 @@ function startSession(sessionId, callback, extraProperties) {
     });
   });
 }
+function startSessionTitle(callback, options) {
+  const resolvedSessionId = options?.sessionId ?? getActiveSession()?.sessionId;
+  const tracer = import_api5.trace.getTracer("@brizz/sdk");
+  return tracer.startActiveSpan(SESSION_TITLE_SPAN_NAME, (span) => {
+    if (resolvedSessionId) {
+      span.setAttribute(`${BRIZZ}.${SESSION_ID}`, resolvedSessionId);
+    }
+    const sessionTitle = new SessionTitle(span);
+    const properties = { [SESSION_TITLE_GENERATION]: "true" };
+    if (resolvedSessionId) {
+      properties[SESSION_ID] = resolvedSessionId;
+    }
+    return callWithProperties(properties, () => {
+      try {
+        const result = callback(sessionTitle);
+        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 {
@@ -1920,7 +1999,7 @@ var _Brizz = class __Brizz {
       resourceAttributes["deployment.environment"] = resolvedConfig.environment;
     }
     this._sdk = new import_sdk_node.NodeSDK({
-      spanProcessors: [getSpanProcessor()],
+      spanProcessors: resolvedConfig.disableSpanExporter ? [] : [getSpanProcessor()],
       metricReader: getMetricsReader(),
       resource: (0, import_resources3.resourceFromAttributes)(resourceAttributes),
       instrumentations: manualInstrumentations
@@ -2091,6 +2170,7 @@ var init_exports = {};
   DEFAULT_PII_PATTERNS,
   LogLevel,
   Session,
+  SessionTitle,
   SeverityNumber,
   callWithProperties,
   callWithSessionId,
@@ -2108,6 +2188,7 @@ var init_exports = {};
   maskValue,
   setLogLevel,
   startSession,
+  startSessionTitle,
   withProperties,
   withSessionId
 });