@brizz/sdk 0.1.0 → 0.1.2-rc.0

package/README.md

@@ -4,7 +4,16 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
-Brizz observability SDK for AI applications.
+OpenTelemetry-based observability SDK for AI applications. Automatically instruments popular AI libraries including OpenAI, Anthropic, Vercel AI SDK, and more.
+
+## Features
+
+- 🔍 **Automatic Instrumentation** - Zero-code setup for popular AI libraries
+- 📊 **OpenTelemetry Native** - Standards-compliant tracing, metrics, and logs
+- 🛡️ **PII Protection** - Built-in masking for sensitive data
+- 🔄 **Session Tracking** - Group related operations and traces
+- 📦 **Dual Module Support** - Works with both ESM and CommonJS
+- ⚡ **Multiple Initialization Methods** - Preload, ESM loader, or manual setup
 
 ## Installation
 
@@ -18,25 +27,147 @@ pnpm add @brizz/sdk
 
 ## Quick Start
 
+### Method 1: Preload (Recommended for Production)
+
+The preload method automatically initializes the SDK and instruments libraries at startup using Node.js preload hooks.
+
+**Environment Variables:**
+```bash
+BRIZZ_API_KEY=your-api-key
+BRIZZ_BASE_URL=https://telemetry.brizz.dev  # Optional
+BRIZZ_APP_NAME=my-app                       # Optional
+BRIZZ_LOG_LEVEL=info                        # Optional: debug, info, warn, error, none
+```
+
+**ESM Usage:**
+```bash
+# Run with ESM preload
+node --import @brizz/sdk/preload your-app.mjs
+```
+
+**CommonJS Usage:**
+```bash
+# Run with CJS preload
+node --require @brizz/sdk/preload your-app.js
+```
+
+**Package.json Scripts:**
+```json
+{
+  "scripts": {
+    "start": "node --import @brizz/sdk/preload src/index.js",
+    "dev": "node --import @brizz/sdk/preload --watch src/index.js"
+  }
+}
+```
+
+Your application code remains clean:
 ```typescript
-import { Brizz, emitEvent } from '@brizz/sdk';
+// your-app.js - No SDK setup needed!
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
 
-// Initialize
+// Just use your AI libraries - they're automatically instrumented
+const result = await generateText({
+  model: openai('gpt-3.5-turbo'),
+  prompt: 'Hello, world!',
+});
+```
+
+### Method 2: ESM Loader Hook
+
+For ESM projects, you can use the ESM loader for automatic instrumentation by using the `--import` flag:
+
+```bash
+node --import @brizz/sdk/loader your-app.mjs
+```
+
+```typescript
+// your-app.mjs
+import { Brizz } from '@brizz/sdk';
+
+// Initialize SDK
 Brizz.initialize({
-  apiKey: 'your-brizzai-api-key',
+  apiKey: 'your-api-key',
   appName: 'my-app',
 });
+
+// Import AI libraries - they'll be automatically instrumented
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const result = await generateText({
+  model: openai('gpt-3.5-turbo'),
+  prompt: 'Hello, world!',
+});
 ```
 
-> **Important**: Initialize Brizz before importing any libraries you want to instrument (e.g.,
-> OpenAI). If using `dotenv`, use `import "dotenv/config"` before importing `@brizz/sdk`.
+### Method 3: Manual Initialization
 
-## PII Masking
+For CommonJS or custom setups:
 
-Automatically protects sensitive data in traces:
+```typescript
+import { Brizz } from '@brizz/sdk';
+
+// Initialize before importing AI libraries
+Brizz.initialize({
+  apiKey: 'your-api-key',
+  appName: 'my-app',
+  baseUrl: 'https://telemetry.brizz.dev', // Optional
+  logLevel: 'info', // Optional: debug, info, warn, error, none
+});
+
+// Import AI libraries after initialization
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+```
+
+> **Important**: Initialize Brizz before importing any libraries you want to instrument. If using `dotenv`, use `import "dotenv/config"` before importing `@brizz/sdk`.
+
+## Module System Support
+
+### ESM (ES Modules)
+- **Preload**: `node --import @brizz/sdk/preload app.mjs` ⭐
+- **Loader**: `node --import @brizz/sdk/loader app.mjs`
+- **Manual**: Import and initialize manually
+
+### CommonJS
+- **Preload**: `node --require @brizz/sdk/preload app.js` ⭐
+- **Manual**: Require and initialize manually
+
+For Next.js and Webpack environments that don't support automatic instrumentation, use manual instrumentation:
+
+```typescript
+// For problematic bundlers
+const aiModule = await import('ai');
+
+Brizz.initialize({
+  apiKey: 'your-api-key',
+  instrumentModules: {
+    vercelAI: aiModule, // Manual instrumentation
+  },
+});
+```
+
+## Supported Libraries
+
+The SDK automatically instruments:
+
+- **OpenAI** - `openai` package
+- **Anthropic** - `@anthropic-ai/sdk` package
+- **Vercel AI SDK** - `ai` package (generateText, streamText, etc.)
+- **LangChain** - `langchain` and `@langchain/*` packages
+- **LlamaIndex** - `llamaindex` package
+- **AWS Bedrock** - `@aws-sdk/client-bedrock-runtime`
+- **Google Vertex AI** - `@google-cloud/vertexai`
+- **Vector Databases** - Pinecone, Qdrant, ChromaDB
+- **HTTP/Fetch** - Automatic network request tracing
+
+## PII Protection & Data Masking
+
+Automatically protects sensitive data in traces and logs:
 
 ```typescript
-// Configure masking rules
 Brizz.initialize({
   apiKey: 'your-api-key',
   masking: {
@@ -45,7 +176,16 @@ Brizz.initialize({
         {
           attributePattern: 'gen_ai\\.(prompt|completion)',
           mode: 'partial', // 'partial' or 'full'
-          patterns: ['sk-[a-zA-Z0-9]{32}'], // Custom regex patterns
+          patterns: ['sk-[a-zA-Z0-9]{48}'], // Custom API key pattern
+        },
+      ],
+    },
+    logMasking: {
+      rules: [
+        {
+          attributePattern: 'message',
+          mode: 'full',
+          patterns: ['\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b'],
         },
       ],
     },
@@ -53,24 +193,204 @@ Brizz.initialize({
 });
 ```
 
-**Built-in patterns**: emails, phone numbers, SSNs, credit cards, API keys, crypto addresses, and
-more.
+**Built-in PII patterns** automatically detect and mask:
+- Email addresses
+- Phone numbers
+- Social Security Numbers
+- Credit card numbers
+- API keys (OpenAI, Anthropic, etc.)
+- Cryptocurrency addresses
+- IP addresses
+- And more...
+
+## Session Tracking
+
+Group related operations under a session context:
+
+```typescript
+import { WithSessionId, emitEvent } from '@brizz/sdk';
+
+async function processUserWorkflow(userId: string) {
+  // All traces within this function will include session-123
+  const result = await generateText({
+    model: openai('gpt-4'),
+    messages: [{ role: 'user', content: 'Hello' }],
+  });
+
+  emitEvent('workflow.completed', { userId, result: result.text });
+  return result;
+}
+
+// Wrap function with session context
+await WithSessionId('session-123', processUserWorkflow, null, 'user-456');
+```
+
+## Custom Events & Logging
 
-## Event Examples
+Emit custom events and structured logs:
 
 ```typescript
-emitEvent('user.signup', { user_id: '123', plan: 'pro' });
-emitEvent('user.payment', { amount: 99, currency: 'USD' });
+import { emitEvent, logger } from '@brizz/sdk';
+
+// Emit custom events
+emitEvent('user.signup', {
+  userId: '123',
+  plan: 'pro',
+  source: 'website'
+});
+
+emitEvent('ai.request.completed', {
+  model: 'gpt-4',
+  tokens: 150,
+  latency: 1200
+});
+
+// Structured logging
+logger.info('Processing user request', { userId: '123', requestId: 'req-456' });
+logger.error('AI request failed', { error: err.message, model: 'gpt-4' });
 ```
 
 ## Environment Variables
 
 ```bash
-BRIZZ_API_KEY=your-api-key          # Required
-BRIZZ_BASE_URL=https://api.brizz.ai # Optional
-BRIZZ_APP_NAME=my-app               # Optional
+# Required
+BRIZZ_API_KEY=your-api-key
+
+# Optional Configuration
+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
+
+# OpenTelemetry Standard Variables
+OTEL_SERVICE_NAME=my-service                               # Service name
+OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true    # Capture AI content
 ```
 
+## Advanced Configuration
+
+```typescript
+Brizz.initialize({
+  apiKey: 'your-api-key',
+  appName: 'my-app',
+  baseUrl: 'https://telemetry.brizz.dev',
+
+  // Custom headers for authentication
+  headers: {
+    'X-API-Version': '2024-01',
+    'X-Environment': 'production'
+  },
+
+  // Disable batching for immediate export (testing)
+  disableBatch: false,
+
+  // Custom exporters for testing
+  customSpanExporter: new InMemorySpanExporter(),
+  customLogExporter: new InMemoryLogExporter(),
+
+  // Disable internal NodeSDK (advanced usage)
+  disableNodeSdk: false,
+
+  // Log level for SDK diagnostics
+  logLevel: 'info' // debug, info, warn, error, none
+});
+```
+
+## Testing & Development
+
+For testing and development, you can use in-memory exporters:
+
+```typescript
+import { InMemorySpanExporter } from '@opentelemetry/sdk-trace-base';
+
+const spanExporter = new InMemorySpanExporter();
+
+Brizz.initialize({
+  apiKey: 'test-key',
+  customSpanExporter: spanExporter,
+  logLevel: 'debug'
+});
+
+// Later in tests
+const spans = spanExporter.getFinishedSpans();
+expect(spans).toHaveLength(1);
+expect(spans[0].name).toBe('openai.chat');
+```
+
+## Package.json Examples
+
+**ESM with Preload (Recommended):**
+```json
+{
+  "type": "module",
+  "scripts": {
+    "start": "node --import @brizz/sdk/preload src/index.js",
+    "dev": "node --import @brizz/sdk/preload --watch src/index.js",
+    "debug": "node --import @brizz/sdk/preload --inspect src/index.js"
+  }
+}
+```
+
+**CommonJS with Preload:**
+```json
+{
+  "scripts": {
+    "start": "node --require @brizz/sdk/preload src/index.js",
+    "dev": "node --require @brizz/sdk/preload --watch src/index.js"
+  }
+}
+```
+
+**ESM with Loader:**
+```json
+{
+  "type": "module",
+  "scripts": {
+    "start": "node --import @brizz/sdk/loader src/index.js"
+  }
+}
+```
+
+## Examples
+
+Check out the [examples](./examples/) directory for complete working examples:
+
+- **Basic Usage** - Simple AI application setup
+- **Vercel AI SDK** - Integration with Vercel's AI SDK
+- **Session Tracking** - Grouping related operations
+- **Custom Events** - Emitting business metrics
+- **PII Masking** - Data protection configuration
+
+## Troubleshooting
+
+### Common Issues
+
+**"Could not find declaration file"**
+- Make sure to build the SDK: `pnpm build`
+- Check that `dist/` contains `.d.ts` files
+
+**Instrumentation not working**
+- Ensure SDK is initialized before importing AI libraries
+- For ESM, use preload or loader methods
+- Check that `BRIZZ_API_KEY` is set
+
+**CJS/ESM compatibility issues**
+- Use dynamic imports in CommonJS: `const ai = await import('ai')`
+- For bundlers, use manual instrumentation with `instrumentModules`
+
+### Debug Mode
+
+Enable debug logging to troubleshoot issues:
+
+```bash
+BRIZZ_LOG_LEVEL=debug node --import @brizz/sdk/preload your-app.js
+```
+
+## Contributing
+
+See our [Contributing Guide](../../CONTRIBUTING.md) for development setup and guidelines.
+
 ## License
 
-MIT - see [LICENSE](LICENSE) file.
+Apache-2.0 - see [LICENSE](LICENSE) file.