@arivlabs/logger 1.5.0 → 2.0.0

package/CHANGELOG.md

@@ -5,6 +5,76 @@ All notable changes to `@arivlabs/logger` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - 2026-01-21
+
+### Added
+
+- **Async logging mode** (default in production) for high-throughput, non-blocking logging
+  - Configurable via `enableAsync: true/false` option
+  - `asyncBufferSize` option to control buffer size (default: 4096 bytes)
+  - Automatic sync mode for development, local, and test environments
+- **Crash-safe logging** with synchronous flush for guaranteed delivery on exceptions
+  - Opt-in via `handleExceptions: true` config option
+  - Uses SonicBoom's `flushSync()` to ensure logs are written before process exit
+- **Graceful shutdown API**
+  - `logger.flush()` - Synchronously flush buffered logs
+  - `logger.shutdown()` - Flush and close destinations (call before process exit)
+- **Flexible types** - Define your own service/domain types locally, no more package updates
+- **Custom base fields** - Add fields to every log via `base` config option
+- **Direct pino access** - `logger.pino` property for advanced use cases
+
+### Changed
+
+- **BREAKING**: Upgraded Pino from v9.6.0 to v10.2.0
+  - Drops Node.js 18 support (already required Node >=20)
+  - Fixes memory leak when using transports with `--import preload`
+- **BREAKING**: Async logging is now default in production environments
+  - **Action required**: Add `await logger.shutdown()` to your SIGTERM handlers
+  - Use `enableAsync: false` to opt out if needed
+- **BREAKING**: Exception handling is now opt-in via `handleExceptions: true`
+  - Previously registered handlers automatically; now explicit for safety
+- Simplified API: removed generic type parameters (use TypeScript's type inference)
+- Improved flush/shutdown reliability using proper SonicBoom methods
+
+### Removed
+
+- **BREAKING**: `ServiceName` type - Define your own service types locally
+- **BREAKING**: `LogDomain` type - Define your own domain types locally
+- All hard-coded service and domain names removed from the package
+
+### Deprecated
+
+- `createDomainLogger()` function - Use `logger.domain()` instead
+- `createRequestLogger()` function - Use `logger.withContext()` instead
+
+### Migration Guide
+
+```typescript
+// 1. Create logger (service/domain are now plain strings)
+const logger = createLogger({ service: 'my-service' });
+
+// 2. Add shutdown handler (required for async mode in production)
+process.on('SIGTERM', async () => {
+  await logger.shutdown();
+  process.exit(0);
+});
+
+// 3. (Optional) Enable exception handling
+const logger = createLogger({
+  service: 'my-service',
+  handleExceptions: true, // Opt-in for crash-safe logging
+});
+
+// 4. (Optional) Opt out of async mode
+const logger = createLogger({ service: 'my-service', enableAsync: false });
+```
+
+## [1.5.0] - 2025-01-10
+
+### Added
+
+- Added `feature-flags` to `LogDomain` type
+
 ## [1.4.1] - 2024-12-29
 
 ### Added

package/README.md

@@ -1,6 +1,16 @@
 # @arivlabs/logger
 
-Structured logging for ArivLabs services with CloudWatch support.
+Structured, high-performance logging for Node.js services with CloudWatch support.
+
+## Features
+
+- **Async by default in production** - Non-blocking logging for maximum throughput
+- **Crash-safe logging** - Uses `pino.final()` for guaranteed delivery on exceptions
+- **Flexible types** - Define your own service and domain types locally
+- **Automatic redaction** - Sensitive data masked by default
+- **Child loggers** - Domain-specific and request-scoped logging
+- **CloudWatch-friendly** - JSON output optimized for AWS CloudWatch Insights
+- **Pino v10** - Built on the fastest Node.js logger
 
 ## Installation
 
@@ -11,88 +21,142 @@ pnpm add @arivlabs/logger
 pnpm add -D pino-pretty
 ```
 
-## Usage
+## Quick Start
 
 ```typescript
 import { createLogger } from '@arivlabs/logger';
 
-// Create a logger for your service
-const logger = createLogger({ service: 'api-gateway' });
+const logger = createLogger({ service: 'my-service' });
 
-// Basic logging - intuitive style (recommended)
+// Basic logging (intuitive style)
 logger.info('Server started', { port: 3000 });
 
 // Error logging - both { err } and { error } work
-logger.error('Request failed', { err: error }); // ✅ Works
-logger.error('Request failed', { error: error }); // ✅ Also works (auto-converted)
-// logger.error('Request failed', { error: err.message }); // ❌ Bad - pass the Error object, not .message
-
-// Also works: pino native style
-logger.info({ msg: 'Server started', port: 3000 });
+logger.error('Request failed', { err: error });
+logger.error('Request failed', { error }); // Also works (auto-converted)
 
 // Domain-specific logging
-const discoveryLog = logger.domain('discovery');
-discoveryLog.info('Job created', { jobId: '123' });
+const authLogger = logger.domain('auth');
+authLogger.info('User logged in', { userId: '123' });
 
 // Request context logging
-const reqLog = logger.withContext({
+const reqLogger = logger.withContext({
   correlationId: 'abc-123',
   tenantId: 'tenant-1',
   domain: 'discovery',
 });
-reqLog.info('Processing request');
+reqLogger.info('Processing request');
+
+// IMPORTANT: Graceful shutdown (required for async mode)
+process.on('SIGTERM', async () => {
+  await logger.shutdown();
+  process.exit(0);
+});
 ```
 
-## CloudWatch Insights Queries
+## Async Logging
 
-```sql
--- Filter by service
-fields @timestamp, @message
-| filter service = "api-gateway"
+By default, the logger uses **async mode in production** for high throughput:
 
--- Filter by domain
-fields @timestamp, @message
-| filter domain = "discovery"
+```typescript
+const logger = createLogger({
+  service: 'my-service',
+  // enableAsync: true is default in production
+});
 
--- Filter errors
-fields @timestamp, @message
-| filter level = "error"
+// Logs are buffered and written asynchronously
+logger.info('High volume log', { requestId: '123' });
 
--- Filter by tenant
-fields @timestamp, @message
-| filter tenant_id = "xxx"
+// CRITICAL: Always flush on shutdown!
+process.on('SIGTERM', async () => {
+  await logger.shutdown();
+  process.exit(0);
+});
+```
 
--- Combine filters
-fields @timestamp, service, domain, @message
-| filter service = "api-gateway" and domain = "discovery"
-| sort @timestamp desc
-| limit 100
+### Async Defaults by Environment
+
+| Environment | `enableAsync` Default | Why                           |
+| ----------- | --------------------- | ----------------------------- |
+| production  | `true`                | High throughput, non-blocking |
+| development | `false`               | Immediate feedback during dev |
+| local       | `false`               | Immediate feedback            |
+| test        | `false`               | Predictable test output       |
+
+### Disabling Async Mode
+
+```typescript
+const logger = createLogger({
+  service: 'my-service',
+  enableAsync: false, // All logs written synchronously
+});
 ```
 
+### Async Configuration
+
+```typescript
+const logger = createLogger({
+  service: 'my-service',
+  enableAsync: true,
+  asyncBufferSize: 4096, // Buffer size before auto-flush (default: 4096)
+});
+```
+
+## Exception Handling (Opt-in)
+
+For crash-safe logging of uncaught exceptions, enable `handleExceptions`:
+
+```typescript
+const logger = createLogger({
+  service: 'my-service',
+  handleExceptions: true, // Registers uncaughtException/unhandledRejection handlers
+});
+```
+
+When enabled, the logger:
+
+1. Logs the error at `fatal` level
+2. Calls `flushSync()` on the SonicBoom destination to ensure the log is written
+3. Exits the process with code 1
+
+**Note:** This is opt-in because automatic process exit behavior may not be desired in all applications.
+
 ## Configuration
 
 ```typescript
 const logger = createLogger({
-  service: 'api-gateway', // Required: service name
-  environment: 'production', // Optional: defaults to NODE_ENV
-  level: 'info', // Optional: debug, info, warn, error
-  pretty: false, // Optional: defaults to true in development
+  // Required
+  service: 'my-service',
+
+  // Optional
+  environment: 'production', // defaults to ENV or NODE_ENV
+  level: 'info', // defaults to 'debug' in dev, 'info' in prod
+  pretty: false, // defaults to true in development/local
+  enableAsync: true, // defaults to true in production
+  asyncBufferSize: 4096, // buffer size for async mode
+  handleExceptions: false, // opt-in for crash-safe logging
+
+  // Custom base fields (added to every log)
+  base: {
+    version: '2.0.0',
+    region: 'us-east-1',
+  },
+
+  // Custom redaction paths (in addition to defaults)
   redact: {
-    // Optional: add custom paths to redact (in addition to defaults)
-    paths: ['user.ssn', 'customSecret'],
-    censor: '[MASKED]', // Optional: default is '[REDACTED]'
+    paths: ['user.ssn', 'payment.cardNumber'],
+    censor: '[MASKED]', // default: '[REDACTED]'
+    remove: false, // set true to remove key entirely
   },
 });
 ```
 
 ## Sensitive Data Redaction
 
-The logger automatically redacts common sensitive fields from logs. This protects against accidental credential exposure.
+The logger automatically masks common sensitive fields:
 
 ### Default Redacted Fields
 
-These fields are **automatically masked** (shown as `[REDACTED]`):
-
 | Category            | Fields                                                |
 | ------------------- | ----------------------------------------------------- |
 | **Secrets**         | `password`, `secret`, `token`, `apiKey`, `privateKey` |
@@ -101,63 +165,76 @@ These fields are **automatically masked** (shown as `[REDACTED]`):
 | **Request Headers** | `req.headers.authorization`, `req.headers.cookie`     |
 | **Nested**          | `*.password`, `*.secret`, `*.token`, `*.apiKey`       |
 
-### Adding Custom Redaction Paths
+### Adding Custom Redaction
 
 ```typescript
 const logger = createLogger({
-  service: 'api-gateway',
+  service: 'my-service',
   redact: {
-    // Add project-specific sensitive fields
-    paths: [
-      'user.ssn', // Exact path
-      'customer.creditCard', // Exact path
-      '*.bankAccount', // Any object with bankAccount
-    ],
-    censor: '[MASKED]', // Custom mask text
-    remove: false, // Set true to remove key entirely
+    paths: ['user.ssn', 'payment.cardNumber', '*.bankAccount'],
   },
 });
 ```
 
-## Log Format
+## Log Output Format
 
-JSON output (production):
+**JSON (production):**
 
 ```json
 {
   "level": 30,
-  "timestamp": "2024-01-15T10:30:00.000Z",
-  "service": "api-gateway",
+  "timestamp": "2026-01-21T10:30:00.000Z",
+  "service": "my-service",
   "environment": "production",
-  "domain": "discovery",
+  "domain": "auth",
   "correlation_id": "abc-123",
   "tenant_id": "tenant-1",
-  "msg": "Job created",
-  "jobId": "job-456"
+  "msg": "User logged in",
+  "userId": "user-456"
 }
 ```
 
-Pretty output (development):
+**Pretty (development):**
 
 ```
-10:30:00 Z [api-gateway:discovery] abc-123 Job created
+10:30:00 Z [my-service:auth] abc-123 User logged in
 ```
 
-## Error Logging Best Practices
+## CloudWatch Insights Queries
+
+```sql
+-- Filter by service
+fields @timestamp, @message | filter service = "my-service"
+
+-- Filter by domain
+fields @timestamp, @message | filter domain = "auth"
 
-Pass the Error object directly - both `err` and `error` keys work:
+-- Filter errors (level 50 = error)
+fields @timestamp, @message | filter level >= 50
+
+-- Filter by tenant
+fields @timestamp, @message | filter tenant_id = "tenant-123"
+
+-- Trace a request
+fields @timestamp, service, domain, @message
+| filter correlation_id = "abc-123"
+| sort @timestamp asc
+```
+
+## Error Logging
+
+Pass the Error object directly:
 
 ```typescript
 try {
   await someOperation();
 } catch (error) {
-  // ✅ Both work - error is auto-converted to err for pino
+  // Both work - error is auto-converted to err
   logger.error('Operation failed', { err: error });
   logger.error('Operation failed', { error }); // Same result
 
-  // ❌ Bad - loses error type, stack, and custom properties
-  logger.error('Operation failed', { error: error.message });
-  logger.error('Operation failed', { message: error.message, stack: error.stack });
+  // Bad - loses error type, stack, and custom properties
+  logger.error('Operation failed', { message: error.message });
 }
 ```
 
@@ -165,22 +242,97 @@ Pino's error serializer captures:
 
 - Error name/type (e.g., `TypeError`, `ValidationError`)
 - Error message
-- Stack trace
+- Full stack trace
 - Custom error properties
 
-## Available Domains
-
-- `discovery` - Discovery scanning
-- `auth` - Authentication
-- `connectors` - Cloud connectors
-- `inventory` - Resource inventory
-- `lineage` - Data lineage
-- `onboarding` - Customer onboarding
-- `proxy` - AI proxy
-- `users` - User management
-- `dashboard` - Analytics dashboard
-- `internal` - Internal APIs
-- `storage` - File storage
-- `email` - Email service
-- `queue` - Queue processing
-- `system` - System-level logs
+## API Reference
+
+### `createLogger(config)`
+
+Creates a new logger instance.
+
+### `ArivLogger` Interface
+
+| Method                  | Description                                |
+| ----------------------- | ------------------------------------------ |
+| `trace(msg, data?)`     | Log at trace level                         |
+| `debug(msg, data?)`     | Log at debug level                         |
+| `info(msg, data?)`      | Log at info level                          |
+| `warn(msg, data?)`      | Log at warn level                          |
+| `error(msg, data?)`     | Log at error level                         |
+| `fatal(msg, data?)`     | Log at fatal level                         |
+| `domain(name)`          | Create child logger for domain             |
+| `withContext(ctx)`      | Create child logger with request context   |
+| `child(bindings)`       | Create child logger with custom bindings   |
+| `isLevelEnabled(level)` | Check if level is enabled                  |
+| `flush()`               | Synchronously flush buffered logs          |
+| `shutdown()`            | Flush and close (call before process exit) |
+| `pino`                  | Access underlying Pino logger              |
+
+## Migration from v1.x
+
+### Breaking Changes
+
+1. **Async logging is now default in production**
+   - Add shutdown handler: `await logger.shutdown()`
+
+2. **`ServiceName` and `LogDomain` types removed**
+   - Define your own types locally
+
+3. **Config option renamed**: `async` → `enableAsync`
+
+4. **Exception handling is now opt-in**
+   - Use `handleExceptions: true` if needed
+
+### Migration Steps
+
+```typescript
+// Before (v1.x)
+const logger = createLogger({ service: 'api-gateway' });
+
+// After (v2.x)
+const logger = createLogger({ service: 'my-service' });
+
+// Add shutdown handler (required for async mode)
+process.on('SIGTERM', async () => {
+  await logger.shutdown();
+  process.exit(0);
+});
+```
+
+## Performance Tips
+
+1. **Use `isLevelEnabled` for expensive computations:**
+
+   ```typescript
+   if (logger.isLevelEnabled('debug')) {
+     logger.debug('Details', { data: computeExpensiveData() });
+   }
+   ```
+
+2. **Keep log messages short** - data goes in the object:
+
+   ```typescript
+   // Good
+   logger.info('Request processed', { userId, duration, status });
+
+   // Bad
+   logger.info(`Request for user ${userId} took ${duration}ms with status ${status}`);
+   ```
+
+3. **Reuse domain loggers:**
+
+   ```typescript
+   // Good - create once, reuse
+   const authLogger = logger.domain('auth');
+   authLogger.info('Login');
+   authLogger.info('Logout');
+
+   // Bad - wasteful
+   logger.domain('auth').info('Login');
+   logger.domain('auth').info('Logout');
+   ```
+
+## License
+
+MIT