@statly/observe 1.1.0 → 1.2.1

package/README.md

@@ -12,6 +12,7 @@ Error tracking and monitoring for JavaScript and TypeScript applications. Captur
 ## Features
 
 - Automatic error capturing with stack traces
+- **Structured Logging**: Production-grade logging with automatic scrubbing
 - **Distributed Tracing**: Visualize function execution and call hierarchies
 - **Performance Metrics**: Automated capture of latency and success rates
 - Breadcrumbs for debugging context
@@ -127,6 +128,109 @@ try {
 }
 ```
 
+## Structured Logging
+
+The Logger class provides production-grade structured logging with automatic secret scrubbing, session management, and batching.
+
+### Quick Start
+
+```typescript
+import { Logger } from '@statly/observe';
+
+const logger = Logger.create({
+  dsn: 'https://sk_live_xxx@statly.live/your-org',
+  environment: 'production',
+  loggerName: 'api-server',
+});
+
+// Log at different levels
+logger.trace('Entering function', { args: [1, 2, 3] });
+logger.debug('Processing request', { requestId: 'req_123' });
+logger.info('User logged in', { userId: 'user_123' });
+logger.warn('Rate limit approaching', { current: 95, limit: 100 });
+logger.error('Payment failed', { orderId: 'ord_456', error: 'Card declined' });
+logger.fatal('Database connection lost', { host: 'db.example.com' });
+logger.audit('User role changed', { userId: 'user_123', newRole: 'admin' });
+
+// Always close before exit
+await logger.close();
+```
+
+### Child Loggers
+
+Create child loggers with inherited context:
+
+```typescript
+const requestLogger = logger.child({
+  context: { requestId: 'req_123' },
+  loggerName: 'request-handler',
+});
+
+requestLogger.info('Processing request'); // Includes requestId automatically
+```
+
+### User Context
+
+Associate logs with users:
+
+```typescript
+logger.setUser({
+  id: 'user_123',
+  email: 'jane@example.com',
+  name: 'Jane Doe',
+});
+```
+
+### Secret Scrubbing
+
+The logger automatically scrubs sensitive data (API keys, passwords, credit cards, etc.). Add custom patterns:
+
+```typescript
+const logger = Logger.create({
+  dsn: '...',
+  scrubPatterns: [
+    /my-custom-secret-[a-z0-9]+/gi,
+    /internal-token-\d+/g,
+  ],
+});
+```
+
+### Sample Rates
+
+Control log volume with per-level sampling:
+
+```typescript
+const logger = Logger.create({
+  dsn: '...',
+  sampleRates: {
+    trace: 0.01,  // 1% of trace logs
+    debug: 0.1,   // 10% of debug logs
+    info: 0.5,    // 50% of info logs
+    warn: 1.0,    // 100% of warnings
+    error: 1.0,   // 100% of errors
+    fatal: 1.0,   // 100% of fatal
+  },
+});
+```
+
+### Logger Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `dsn` | `string` | required | Your project's Data Source Name |
+| `environment` | `string` | `undefined` | Environment name |
+| `release` | `string` | `undefined` | Release/version identifier |
+| `loggerName` | `string` | `undefined` | Logger name for filtering |
+| `sessionId` | `string` | auto-generated | Session ID for grouping logs |
+| `user` | `object` | `undefined` | User context |
+| `defaultContext` | `object` | `{}` | Default context for all logs |
+| `minLevel` | `LogLevel` | `'trace'` | Minimum level to log |
+| `sampleRates` | `object` | all 1.0 | Per-level sample rates |
+| `scrubPatterns` | `RegExp[]` | `[]` | Additional patterns to scrub |
+| `batchSize` | `number` | `50` | Batch size before flush |
+| `flushInterval` | `number` | `5000` | Flush interval in ms |
+| `maxQueueSize` | `number` | `1000` | Max queue size |
+
 ## Framework Integrations
 
 ### Express

package/dist/{chunk-HYFH22G6.mjs → chunk-RLSLJL6N.js}

@@ -1,6 +1,6 @@
 import {
   TelemetryProvider
-} from "./chunk-J5AHUFP2.mjs";
+} from "./chunk-NKQPBSKX.js";
 
 // src/transport.ts
 var Transport = class {
@@ -62,10 +62,10 @@ var Transport = class {
     this.queue = [];
     try {
       await this.sendBatch(events);
-    } catch (error) {
+    } catch (error2) {
       this.queue = [...events, ...this.queue].slice(0, this.maxQueueSize);
       if (this.debug) {
-        console.error("[Statly] Failed to send events:", error);
+        console.error("[Statly] Failed to send events:", error2);
       }
     } finally {
       this.isSending = false;
@@ -105,13 +105,13 @@ var Transport = class {
         console.log(`[Statly] Sent ${events.length} event(s)`);
       }
       return { success: true, status: response.status };
-    } catch (error) {
+    } catch (error2) {
       if (this.debug) {
-        console.error("[Statly] Network error:", error);
+        console.error("[Statly] Network error:", error2);
       }
       return {
         success: false,
-        error: error instanceof Error ? error.message : "Network error"
+        error: error2 instanceof Error ? error2.message : "Network error"
       };
     }
   }
@@ -178,16 +178,16 @@ var GlobalHandlers = class {
       if (!this.errorCallback) {
         return;
       }
-      let error;
+      let error2;
       if (event.reason instanceof Error) {
-        error = event.reason;
+        error2 = event.reason;
       } else if (typeof event.reason === "string") {
-        error = new Error(event.reason);
+        error2 = new Error(event.reason);
       } else {
-        error = new Error("Unhandled Promise Rejection");
-        error.reason = event.reason;
+        error2 = new Error("Unhandled Promise Rejection");
+        error2.reason = event.reason;
       }
-      this.errorCallback(error, {
+      this.errorCallback(error2, {
         mechanism: { type: "onunhandledrejection", handled: false }
       });
     };
@@ -230,13 +230,13 @@ var GlobalHandlers = class {
   }
   installOnError() {
     this.originalOnError = window.onerror;
-    window.onerror = (message, source, lineno, colno, error) => {
+    window.onerror = (message, source, lineno, colno, error2) => {
       if (this.originalOnError) {
-        this.originalOnError.call(window, message, source, lineno, colno, error);
+        this.originalOnError.call(window, message, source, lineno, colno, error2);
       }
       if (this.errorCallback) {
-        const errorObj = error || new Error(String(message));
-        if (!error && source) {
+        const errorObj = error2 || new Error(String(message));
+        if (!error2 && source) {
           errorObj.filename = source;
           errorObj.lineno = lineno;
           errorObj.colno = colno;
@@ -300,13 +300,12 @@ var ConsoleIntegration = class {
       return;
     }
     this.originalMethods[level] = originalMethod;
-    const self = this;
-    console[level] = function(...args) {
-      if (self.callback) {
-        self.callback({
+    console[level] = (...args) => {
+      if (this.callback) {
+        this.callback({
           category: "console",
-          message: self.formatArgs(args),
-          level: self.mapLevel(level),
+          message: this.formatArgs(args),
+          level: this.mapLevel(level),
           data: args.length > 1 ? { arguments: args } : void 0
         });
       }
@@ -400,8 +399,8 @@ var StatlyClient = class {
     }
     this.initialized = true;
     if (this.options.autoCapture) {
-      this.globalHandlers.install((error, context) => {
-        this.captureError(error, context);
+      this.globalHandlers.install((error2, context) => {
+        this.captureError(error2, context);
       });
     }
     if (this.options.captureConsole) {
@@ -424,15 +423,15 @@ var StatlyClient = class {
   /**
    * Capture an exception/error
    */
-  captureException(error, context) {
+  captureException(error2, context) {
     let errorObj;
-    if (error instanceof Error) {
-      errorObj = error;
-    } else if (typeof error === "string") {
-      errorObj = new Error(error);
+    if (error2 instanceof Error) {
+      errorObj = error2;
+    } else if (typeof error2 === "string") {
+      errorObj = new Error(error2);
     } else {
       errorObj = new Error("Unknown error");
-      errorObj.originalError = error;
+      errorObj.originalError = error2;
     }
     return this.captureError(errorObj, context);
   }
@@ -467,24 +466,24 @@ var StatlyClient = class {
    * Execute a function within a trace span
    */
   async trace(name, operation, tags) {
-    const { trace: traceFn } = await import("./telemetry-CXHOTW3Y.mjs");
+    const { trace: traceFn } = await import("./telemetry-JOMOMZ25.js");
     return traceFn(name, operation, tags);
   }
   /**
    * Internal method to capture an error
    */
-  captureError(error, context) {
+  captureError(error2, context) {
     if (Math.random() > this.options.sampleRate) {
       return "";
     }
     const event = this.buildEvent({
-      message: error.message,
+      message: error2.message,
       level: "error",
-      stack: error.stack,
+      stack: error2.stack,
       exception: {
-        type: error.name,
-        value: error.message,
-        stacktrace: this.parseStackTrace(error.stack)
+        type: error2.name,
+        value: error2.message,
+        stacktrace: this.parseStackTrace(error2.stack)
       },
       extra: context
     });
@@ -697,7 +696,7 @@ function withStatlyPagesApi(handler) {
       try {
         const result = await handler(req, res);
         return result;
-      } catch (error) {
+      } catch (error2) {
         const context = {
           request: {
             method: req.method,
@@ -706,8 +705,8 @@ function withStatlyPagesApi(handler) {
             query: req.query
           }
         };
-        Statly.captureException(error, context);
-        throw error;
+        Statly.captureException(error2, context);
+        throw error2;
       }
     });
   };
@@ -733,7 +732,7 @@ function withStatly(handler) {
           span.setTag("http.status_code", result.status.toString());
         }
         return result;
-      } catch (error) {
+      } catch (error2) {
         const headers = {};
         request.headers.forEach((value, key) => {
           headers[key] = value;
@@ -752,17 +751,17 @@ function withStatly(handler) {
           } catch {
           }
         }
-        Statly.captureException(error, errorContext);
-        throw error;
+        Statly.captureException(error2, errorContext);
+        throw error2;
       }
     });
   };
   return wrappedHandler;
 }
-function captureNextJsError(error, context) {
-  return Statly.captureException(error, {
+function captureNextJsError(error2, context) {
+  return Statly.captureException(error2, {
     ...context,
-    digest: error.digest,
+    digest: error2.digest,
     source: "nextjs-error-boundary"
   });
 }
@@ -770,12 +769,12 @@ function withStatlyGetServerSideProps(handler) {
   return async (context) => {
     try {
       return await handler(context);
-    } catch (error) {
-      Statly.captureException(error, {
+    } catch (error2) {
+      Statly.captureException(error2, {
         source: "getServerSideProps",
         url: context.req?.url || context.resolvedUrl
       });
-      throw error;
+      throw error2;
     }
   };
 }
@@ -783,12 +782,12 @@ function withStatlyGetStaticProps(handler) {
   return async (context) => {
     try {
       return await handler(context);
-    } catch (error) {
-      Statly.captureException(error, {
+    } catch (error2) {
+      Statly.captureException(error2, {
         source: "getStaticProps",
         params: context.params
       });
-      throw error;
+      throw error2;
     }
   };
 }
@@ -804,12 +803,12 @@ function withStatlyServerAction(action, actionName) {
       });
       try {
         return await action(...args);
-      } catch (error) {
-        Statly.captureException(error, {
+      } catch (error2) {
+        Statly.captureException(error2, {
           source: "server-action",
           actionName
         });
-        throw error;
+        throw error2;
       }
     });
   };
@@ -864,16 +863,16 @@ function statlyFastifyPlugin(fastify, options, done) {
     });
     hookDone();
   });
-  fastify.setErrorHandler((error, request, reply) => {
-    const statusCode = error.statusCode || 500;
+  fastify.setErrorHandler((error2, request, reply) => {
+    const statusCode = error2.statusCode || 500;
     if (skipStatusCodes.includes(statusCode)) {
-      throw error;
+      throw error2;
     }
-    if (!captureValidationErrors && error.validation) {
-      throw error;
+    if (!captureValidationErrors && error2.validation) {
+      throw error2;
     }
-    if (shouldCapture && !shouldCapture(error)) {
-      throw error;
+    if (shouldCapture && !shouldCapture(error2)) {
+      throw error2;
     }
     const context = {
       request: {
@@ -886,27 +885,27 @@ function statlyFastifyPlugin(fastify, options, done) {
         params: request.params
       },
       error: {
-        statusCode: error.statusCode,
-        code: error.code
+        statusCode: error2.statusCode,
+        code: error2.code
       }
     };
     if (request.ip) {
       context.ip = request.ip;
     }
-    if (error.validation) {
-      context.validation = error.validation;
+    if (error2.validation) {
+      context.validation = error2.validation;
     }
     Statly.setTag("http.method", request.method);
     Statly.setTag("http.url", request.routerPath || request.url);
     Statly.setTag("http.status_code", String(statusCode));
-    Statly.captureException(error, context);
-    throw error;
+    Statly.captureException(error2, context);
+    throw error2;
   });
   done();
 }
 var statlyPlugin = statlyFastifyPlugin;
 function createRequestCapture(request) {
-  return (error, additionalContext) => {
+  return (error2, additionalContext) => {
     const context = {
       request: {
         id: request.id,
@@ -916,7 +915,7 @@ function createRequestCapture(request) {
       },
       ...additionalContext
     };
-    return Statly.captureException(error, context);
+    return Statly.captureException(error2, context);
   };
 }
 function sanitizeHeaders2(headers) {
@@ -966,12 +965,12 @@ function init(options) {
   client = new StatlyClient(finalOptions);
   client.init();
 }
-function captureException(error, context) {
+function captureException(error2, context) {
   if (!client) {
     console.warn("[Statly] SDK not initialized. Call Statly.init() first.");
     return "";
   }
-  return client.captureException(error, context);
+  return client.captureException(error2, context);
 }
 function captureMessage(message, level = "info") {
   if (!client) {
@@ -1024,7 +1023,7 @@ async function close() {
 function getClient() {
   return client;
 }
-async function trace(name, operation, tags) {
+async function trace2(name, operation, tags) {
   if (!client) {
     return operation(null);
   }
@@ -1049,7 +1048,7 @@ var Statly = {
   flush,
   close,
   getClient,
-  trace,
+  trace: trace2,
   startSpan,
   captureSpan
 };
@@ -1093,8 +1092,8 @@ function requestHandler() {
 }
 function expressErrorHandler(options = {}) {
   return (err, req, res, next) => {
-    const error = err instanceof Error ? err : new Error(String(err));
-    if (options.shouldHandleError && !options.shouldHandleError(error)) {
+    const error2 = err instanceof Error ? err : new Error(String(err));
+    if (options.shouldHandleError && !options.shouldHandleError(error2)) {
       return next(err);
     }
     const context = {
@@ -1118,7 +1117,7 @@ function expressErrorHandler(options = {}) {
     if (req.statlyContext?.transactionName) {
       Statly.setTag("transaction", req.statlyContext.transactionName);
     }
-    Statly.captureException(error, context);
+    Statly.captureException(error2, context);
     next(err);
   };
 }
@@ -1175,7 +1174,7 @@ export {
   flush,
   close,
   getClient,
-  trace,
+  trace2 as trace,
   startSpan,
   captureSpan,
   Statly