@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/03-PATTERN-GUIDES/error-handling/modules/error-handling-07-monitoring.md

@@ -1,653 +1,653 @@
-# Module 7: Monitoring
-
-**Level:** Advanced
-**Estimated Time:** 20 minutes
-
-## Overview
-
-This module covers effective logging and monitoring strategies for error handling, including structured logging, metrics collection, and alerting patterns.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Implement structured error logging with full context
-- ✅ Use `error.toJSON()` for complete error serialization
-- ✅ Build error metrics and monitoring dashboards
-- ✅ Set up alerting for high error rates
-- ✅ Integrate with external monitoring systems
-
-## Structured Logging
-
-### Logging Setup
-
-**First, configure logging based on your runtime:**
-
-```typescript
-// Standalone (Node.js/Deno)
-import { createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
-const logger = toStructuredLogger(createConsoleLogger(), {
-  service: 'ErrorMonitoring',
-  environment: process.env.NODE_ENV
-});
-
-// Versori Platform
-const { log: logger } = ctx;  // Use native platform log
-```
-
-### Using error.toJSON()
-
-All SDK errors provide a `toJSON()` method for structured logging:
-
-```typescript
-import {
-  IngestionError,
-  MappingError,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Standalone
-const logger = toStructuredLogger(createConsoleLogger(), { service: 'FileProcessor' });
-
-// Versori Platform
-// const { log: logger } = ctx;
-
-try {
-  await processFile(fileName);
-} catch (error) {
-  if (error instanceof IngestionError) {
-    // Full structured error data
-    const errorData = error.toJSON();
-
-    logger.error('File processing failed:', errorData);
-    /*
-    {
-      name: "FileParsingError",
-      message: "Failed to parse XML: Unclosed tag 'order'",
-      code: "PARSE_ERROR",
-      fileName: "order-12345.xml",
-      lineNumber: 42,
-      context: { ... },
-      timestamp: "2025-01-10T12:34:56.789Z",
-      correlationId: "abc-123-def",
-      stack: "Error: ...\n at ..."
-    }
-    */
-  }
-}
-```
-
-### Adding Business Context
-
-Enrich errors with business-specific information:
-
-```typescript
-try {
-  await processOrder(xmlContent);
-} catch (error) {
-  const enrichedLog = {
-    // Base error data
-    ...(error instanceof IngestionError ? error.toJSON() : { message: error.message }),
-
-    // Business context
-    orderId: metadata.orderId,
-    customerId: metadata.customerId,
-    source: metadata.source,
-    environment: process.env.NODE_ENV,
-    appVersion: process.env.APP_VERSION,
-
-    // Additional tracking
-    traceId: generateTraceId(),
-    sessionId: context.sessionId
-  };
-
-  logger.error('Order processing failed:', enrichedLog);
-}
-```
-
-### Correlation IDs
-
-Use correlation IDs to track errors across distributed systems:
-
-```typescript
-import { v4 as uuidv4 } from 'uuid';
-
-async function processWithCorrelation(data: any, correlationId?: string) {
-  const id = correlationId || uuidv4();
-
-  try {
-    logger.info('Processing started', { correlationId: id });
-
-    const result = await process(data);
-
-    logger.info('Processing completed', { correlationId: id });
-    return result;
-
-  } catch (error) {
-    const errorData = error instanceof IngestionError
-      ? error.toJSON()
-      : { message: error.message };
-
-    logger.error('Processing failed', {
-      ...errorData,
-      correlationId: id
-    });
-
-    throw error;
-  }
-}
-```
-
-## Error Metrics Collection
-
-### Basic Error Counter
-
-Track error counts by type:
-
-```typescript
-import {
-  IngestionError,
-  MappingError,
-  PathResolutionError,
-  FluentAPIError,
-  AuthenticationError,
-  GraphQLExecutionError
-} from '@fluentcommerce/fc-connect-sdk';
-
-class ErrorMetrics {
-  private errorCounts = new Map<string, number>();
-  private lastErrors = new Map<string, Date>();
-
-  recordError(error: Error): void {
-    let errorType = 'UNKNOWN';
-
-    if (error instanceof FluentAPIError) {
-      errorType = `API_ERROR_${error.statusCode}`;
-    } else if (error instanceof AuthenticationError) {
-      errorType = 'AUTH_ERROR';
-    } else if (error instanceof GraphQLExecutionError) {
-      errorType = 'GRAPHQL_ERROR';
-    } else if (error instanceof IngestionError) {
-      errorType = error.code;
-    } else if (error instanceof MappingError) {
-      errorType = 'MAPPING_ERROR';
-    } else if (error instanceof PathResolutionError) {
-      errorType = 'PATH_RESOLUTION_ERROR';
-    } else if (error instanceof FileParsingError) {
-      errorType = 'FILE_PARSING_ERROR';
-    }
-
-    // Increment counter
-    const count = this.errorCounts.get(errorType) || 0;
-    this.errorCounts.set(errorType, count + 1);
-
-    // Update last occurrence
-    this.lastErrors.set(errorType, new Date());
-  }
-
-  getMetrics() {
-    return {
-      errorCounts: Object.fromEntries(this.errorCounts),
-      lastErrors: Object.fromEntries(this.lastErrors),
-      timestamp: new Date().toISOString()
-    };
-  }
-
-  reset(): void {
-    this.errorCounts.clear();
-    this.lastErrors.clear();
-  }
-}
-
-// Usage
-const metrics = new ErrorMetrics();
-
-try {
-  await processFile(fileName);
-} catch (error) {
-  metrics.recordError(error);
-  throw error;
-}
-
-// Get metrics periodically
-setInterval(() => {
-  logger.info('Error metrics', metrics.getMetrics());
-}, 60000);  // Every minute
-```
-
-### Advanced Metrics with Rates
-
-Track error rates over time windows:
-
-```typescript
-interface TimeWindow {
-  start: Date;
-  end: Date;
-  errors: Map<string, number>;
-}
-
-class AdvancedErrorMetrics {
-  private windows: TimeWindow[] = [];
-  private windowSizeMs: number;
-  private maxWindows: number;
-
-  constructor(windowSizeMs = 60000, maxWindows = 60) {
-    this.windowSizeMs = windowSizeMs;
-    this.maxWindows = maxWindows;
-  }
-
-  recordError(error: Error): void {
-    const now = new Date();
-    const errorType = this.getErrorType(error);
-
-    // Get or create current window
-    let currentWindow = this.windows[this.windows.length - 1];
-
-    if (!currentWindow || now.getTime() - currentWindow.start.getTime() >= this.windowSizeMs) {
-      // Create new window
-      currentWindow = {
-        start: now,
-        end: new Date(now.getTime() + this.windowSizeMs),
-        errors: new Map()
-      };
-      this.windows.push(currentWindow);
-
-      // Trim old windows
-      if (this.windows.length > this.maxWindows) {
-        this.windows.shift();
-      }
-    }
-
-    // Increment error count in current window
-    const count = currentWindow.errors.get(errorType) || 0;
-    currentWindow.errors.set(errorType, count + 1);
-  }
-
-  getErrorRate(errorType: string, periodMinutes = 5): number {
-    const periodMs = periodMinutes * 60 * 1000;
-    const now = Date.now();
-    let totalErrors = 0;
-
-    for (const window of this.windows) {
-      if (now - window.start.getTime() <= periodMs) {
-        totalErrors += window.errors.get(errorType) || 0;
-      }
-    }
-
-    // Errors per minute
-    return totalErrors / periodMinutes;
-  }
-
-  getMetrics() {
-    const now = new Date();
-    const recentWindows = this.windows.filter(w =>
-      now.getTime() - w.start.getTime() <= 300000  // Last 5 minutes
-    );
-
-    const errorCounts = new Map<string, number>();
-    for (const window of recentWindows) {
-      for (const [type, count] of window.errors.entries()) {
-        const current = errorCounts.get(type) || 0;
-        errorCounts.set(type, current + count);
-      }
-    }
-
-    return {
-      last5Minutes: Object.fromEntries(errorCounts),
-      errorRates: {
-        parsing: this.getErrorRate('FILE_PARSING_ERROR', 5),
-        mapping: this.getErrorRate('MAPPING_ERROR', 5),
-        network: this.getErrorRate('NETWORK_ERROR', 5)
-      },
-      timestamp: now.toISOString()
-    };
-  }
-
-  private getErrorType(error: Error): string {
-    if (error instanceof FluentAPIError) return `API_ERROR_${error.statusCode}`;
-    if (error instanceof AuthenticationError) return 'AUTH_ERROR';
-    if (error instanceof GraphQLExecutionError) return 'GRAPHQL_ERROR';
-    if (error instanceof IngestionError) return error.code;
-    if (error instanceof MappingError) return 'MAPPING_ERROR';
-    if (error instanceof PathResolutionError) return 'PATH_RESOLUTION_ERROR';
-    if (error instanceof FileParsingError) return 'FILE_PARSING_ERROR';
-    return 'UNKNOWN';
-  }
-}
-```
-
-## Alerting Patterns
-
-### Threshold-Based Alerting
-
-Alert when error count exceeds threshold:
-
-```typescript
-class ErrorAlerting {
-  private metrics: ErrorMetrics;
-  private thresholds: Map<string, number>;
-
-  constructor(metrics: ErrorMetrics) {
-    this.metrics = metrics;
-    this.thresholds = new Map([
-      ['PARSE_ERROR', 10],
-      ['NETWORK_ERROR', 50],
-      ['MAPPING_ERROR', 10]
-    ]);
-  }
-
-  checkThresholds(): void {
-    const current = this.metrics.getMetrics();
-
-    for (const [errorType, threshold] of this.thresholds.entries()) {
-      const count = current.errorCounts[errorType] || 0;
-
-      if (count >= threshold) {
-        this.sendAlert({
-          severity: 'HIGH',
-          message: `Error threshold exceeded: ${errorType}`,
-          count,
-          threshold,
-          timestamp: new Date().toISOString()
-        });
-      }
-    }
-  }
-
-  private async sendAlert(alert: any): Promise<void> {
-    logger.error('ALERT: Error threshold exceeded', alert);
-
-    // Send to monitoring service
-    await this.sendToSlack(alert);
-    await this.sendToPagerDuty(alert);
-  }
-
-  private async sendToSlack(alert: any): Promise<void> {
-    // Slack webhook integration
-  }
-
-  private async sendToPagerDuty(alert: any): Promise<void> {
-    // PagerDuty integration
-  }
-}
-```
-
-### Rate-Based Alerting
-
-Alert when error rate exceeds threshold:
-
-```typescript
-class RateBasedAlerting {
-  private metrics: AdvancedErrorMetrics;
-
-  async checkRates(): Promise<void> {
-    const metrics = this.metrics.getMetrics();
-
-    // Alert if parsing errors > 2 per minute
-    if (metrics.errorRates.parsing > 2) {
-      await this.sendAlert({
-        type: 'PARSING_ERROR_RATE_HIGH',
-        rate: metrics.errorRates.parsing,
-        threshold: 2,
-        unit: 'per minute'
-      });
-    }
-
-    // Alert if network errors > 10 per minute
-    if (metrics.errorRates.network > 10) {
-      await this.sendAlert({
-        type: 'NETWORK_ERROR_RATE_HIGH',
-        rate: metrics.errorRates.network,
-        threshold: 10,
-        unit: 'per minute'
-      });
-    }
-  }
-
-  private async sendAlert(alert: any): Promise<void> {
-    logger.error('RATE ALERT: Error rate threshold exceeded', alert);
-    // Send to monitoring systems
-  }
-}
-```
-
-## Integration with Monitoring Systems
-
-### Datadog Integration
-
-```typescript
-import { IngestionError } from '@fluentcommerce/fc-connect-sdk';
-
-async function sendToDatadog(error: Error, context: any): Promise<void> {
-  const metric = {
-    metric: 'ingestion.error',
-    type: 'count',
-    points: [[Date.now() / 1000, 1]],
-    tags: []
-  };
-
-  if (error instanceof IngestionError) {
-    metric.tags.push(
-      `error_code:${error.code}`,
-      `retryable:${error.isRetryable()}`,
-      `environment:${process.env.NODE_ENV}`
-    );
-  }
-
-  metric.tags.push(
-    `source:${context.source}`,
-    `customer:${context.customerId}`
-  );
-
-  // Send to Datadog API
-  // await datadogClient.submitMetric(metric);
-}
-
-// Usage
-try {
-  await processFile(fileName);
-} catch (error) {
-  await sendToDatadog(error, context);
-  throw error;
-}
-```
-
-### Sentry Integration
-
-```typescript
-import * as Sentry from '@sentry/node';
-import { IngestionError } from '@fluentcommerce/fc-connect-sdk';
-
-function reportToSentry(error: Error, context: any): void {
-  Sentry.withScope(scope => {
-    // Add context
-    scope.setContext('business', {
-      orderId: context.orderId,
-      customerId: context.customerId,
-      source: context.source
-    });
-
-    // Add tags
-    if (error instanceof IngestionError) {
-      scope.setTag('error_code', error.code);
-      scope.setTag('retryable', error.isRetryable().toString());
-
-      // Add extra data
-      scope.setExtra('error_details', error.toJSON());
-    }
-
-    // Set fingerprint for grouping
-    scope.setFingerprint([
-      error instanceof IngestionError ? error.code : error.name,
-      context.source
-    ]);
-
-    // Capture exception
-    Sentry.captureException(error);
-  });
-}
-
-// Usage
-try {
-  await processFile(fileName);
-} catch (error) {
-  reportToSentry(error, context);
-  throw error;
-}
-```
-
-### CloudWatch Integration
-
-```typescript
-import { CloudWatchClient, PutMetricDataCommand } from '@aws-sdk/client-cloudwatch';
-import { IngestionError } from '@fluentcommerce/fc-connect-sdk';
-
-async function sendToCloudWatch(error: Error): Promise<void> {
-  const cloudwatch = new CloudWatchClient({ region: 'us-east-1' });
-
-  const dimensions = [
-    { Name: 'Environment', Value: process.env.NODE_ENV || 'unknown' }
-  ];
-
-  if (error instanceof IngestionError) {
-    dimensions.push(
-      { Name: 'ErrorCode', Value: error.code },
-      { Name: 'Retryable', Value: error.isRetryable().toString() }
-    );
-  }
-
-  const command = new PutMetricDataCommand({
-    Namespace: 'FluentCommerce/Ingestion',
-    MetricData: [
-      {
-        MetricName: 'ErrorCount',
-        Value: 1,
-        Unit: 'Count',
-        Timestamp: new Date(),
-        Dimensions: dimensions
-      }
-    ]
-  });
-
-  await cloudwatch.send(command);
-}
-```
-
-## Logging Best Practices
-
-### 1. Always Log Error Context
-
-```typescript
-// ❌ POOR - Missing context
-logger.error('Error occurred');
-
-// ✅ GOOD - Full context (Standalone)
-import { createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
-const logger = toStructuredLogger(createConsoleLogger(), { service: 'OrderProcessor' });
-
-// ✅ GOOD - Full context (Versori Platform)
-const { log: logger } = ctx;
-
-logger.error('Order processing failed', {
-  error: error instanceof IngestionError ? error.toJSON() : error.message,
-  orderId: metadata.orderId,
-  fileName,
-  attempt: retryAttempt,
-  correlationId
-});
-```
-
-### 2. Use Appropriate Log Levels
-
-```typescript
-// Debug: Detailed flow information
-logger.debug('Parsing XML file', { fileName, size });
-
-// Info: Normal operations
-logger.info('Order processed successfully', { orderId, duration });
-
-// Warn: Recoverable issues
-logger.warn('Retrying after transient error', { attempt, error: error.code });
-
-// Error: Failed operations
-logger.error('Order processing failed', { error: error.toJSON() });
-```
-
-### 3. Include Timestamps and IDs
-
-```typescript
-logger.error('Processing failed', {
-  timestamp: new Date().toISOString(),
-  correlationId: context.correlationId,
-  traceId: context.traceId,
-  error: error.toJSON()
-});
-```
-
-### 4. Sanitize Sensitive Data
-
-```typescript
-function sanitizeForLogging(data: any): any {
-  const sanitized = { ...data };
-
-  // Remove sensitive fields
-  delete sanitized.password;
-  delete sanitized.apiKey;
-  delete sanitized.creditCard;
-
-  // Mask email
-  if (sanitized.email) {
-    sanitized.email = sanitized.email.replace(/(.{2})(.*)(@.*)/, '$1***$3');
-  }
-
-  return sanitized;
-}
-
-logger.error('Processing failed', {
-  data: sanitizeForLogging(sourceData),
-  error: error.toJSON()
-});
-```
-
-## Dashboard Examples
-
-### Error Summary Dashboard
-
-Track key metrics:
-- Total errors (last hour, day, week)
-- Error rate trend
-- Top error types
-- Retryable vs non-retryable ratio
-- Mean time to resolution
-
-### Error Distribution
-
-Visualize error types:
-```
-Parsing Errors:    ████████░░ 42%
-Mapping Errors:    ██████░░░░ 31%
-Network Errors:    ████░░░░░░ 19%
-Validation Errors: ██░░░░░░░░  8%
-```
-
-### Error Heatmap
-
-Show error frequency by time of day and error type.
-
-## Key Takeaways
-
-- 🎯 **Use error.toJSON()** - Complete structured error data
-- 🎯 **Add business context** - Enrich with IDs, metadata
-- 🎯 **Track metrics** - Count errors, calculate rates
-- 🎯 **Set up alerts** - Threshold and rate-based alerting
-- 🎯 **Integrate monitoring** - Datadog, Sentry, CloudWatch
-- 🎯 **Sanitize logs** - Remove sensitive data before logging
-
-## Next Steps
-
-Continue to [Module 8: API Reference →](./error-handling-08-api-reference.md) for complete error class documentation and best practices checklist.
-
----
-
-**Previous:** [← Module 6: Retry Strategies](./error-handling-06-retry-strategies.md)
-**Next:** [Module 8: API Reference →](./error-handling-08-api-reference.md)
+# Module 7: Monitoring
+
+**Level:** Advanced
+**Estimated Time:** 20 minutes
+
+## Overview
+
+This module covers effective logging and monitoring strategies for error handling, including structured logging, metrics collection, and alerting patterns.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Implement structured error logging with full context
+- ✅ Use `error.toJSON()` for complete error serialization
+- ✅ Build error metrics and monitoring dashboards
+- ✅ Set up alerting for high error rates
+- ✅ Integrate with external monitoring systems
+
+## Structured Logging
+
+### Logging Setup
+
+**First, configure logging based on your runtime:**
+
+```typescript
+// Standalone (Node.js/Deno)
+import { createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
+const logger = toStructuredLogger(createConsoleLogger(), {
+  service: 'ErrorMonitoring',
+  environment: process.env.NODE_ENV
+});
+
+// Versori Platform
+const { log: logger } = ctx;  // Use native platform log
+```
+
+### Using error.toJSON()
+
+All SDK errors provide a `toJSON()` method for structured logging:
+
+```typescript
+import {
+  IngestionError,
+  MappingError,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Standalone
+const logger = toStructuredLogger(createConsoleLogger(), { service: 'FileProcessor' });
+
+// Versori Platform
+// const { log: logger } = ctx;
+
+try {
+  await processFile(fileName);
+} catch (error) {
+  if (error instanceof IngestionError) {
+    // Full structured error data
+    const errorData = error.toJSON();
+
+    logger.error('File processing failed:', errorData);
+    /*
+    {
+      name: "FileParsingError",
+      message: "Failed to parse XML: Unclosed tag 'order'",
+      code: "PARSE_ERROR",
+      fileName: "order-12345.xml",
+      lineNumber: 42,
+      context: { ... },
+      timestamp: "2025-01-10T12:34:56.789Z",
+      correlationId: "abc-123-def",
+      stack: "Error: ...\n at ..."
+    }
+    */
+  }
+}
+```
+
+### Adding Business Context
+
+Enrich errors with business-specific information:
+
+```typescript
+try {
+  await processOrder(xmlContent);
+} catch (error) {
+  const enrichedLog = {
+    // Base error data
+    ...(error instanceof IngestionError ? error.toJSON() : { message: error.message }),
+
+    // Business context
+    orderId: metadata.orderId,
+    customerId: metadata.customerId,
+    source: metadata.source,
+    environment: process.env.NODE_ENV,
+    appVersion: process.env.APP_VERSION,
+
+    // Additional tracking
+    traceId: generateTraceId(),
+    sessionId: context.sessionId
+  };
+
+  logger.error('Order processing failed:', enrichedLog);
+}
+```
+
+### Correlation IDs
+
+Use correlation IDs to track errors across distributed systems:
+
+```typescript
+import { v4 as uuidv4 } from 'uuid';
+
+async function processWithCorrelation(data: any, correlationId?: string) {
+  const id = correlationId || uuidv4();
+
+  try {
+    logger.info('Processing started', { correlationId: id });
+
+    const result = await process(data);
+
+    logger.info('Processing completed', { correlationId: id });
+    return result;
+
+  } catch (error) {
+    const errorData = error instanceof IngestionError
+      ? error.toJSON()
+      : { message: error.message };
+
+    logger.error('Processing failed', {
+      ...errorData,
+      correlationId: id
+    });
+
+    throw error;
+  }
+}
+```
+
+## Error Metrics Collection
+
+### Basic Error Counter
+
+Track error counts by type:
+
+```typescript
+import {
+  IngestionError,
+  MappingError,
+  PathResolutionError,
+  FluentAPIError,
+  AuthenticationError,
+  GraphQLExecutionError
+} from '@fluentcommerce/fc-connect-sdk';
+
+class ErrorMetrics {
+  private errorCounts = new Map<string, number>();
+  private lastErrors = new Map<string, Date>();
+
+  recordError(error: Error): void {
+    let errorType = 'UNKNOWN';
+
+    if (error instanceof FluentAPIError) {
+      errorType = `API_ERROR_${error.statusCode}`;
+    } else if (error instanceof AuthenticationError) {
+      errorType = 'AUTH_ERROR';
+    } else if (error instanceof GraphQLExecutionError) {
+      errorType = 'GRAPHQL_ERROR';
+    } else if (error instanceof IngestionError) {
+      errorType = error.code;
+    } else if (error instanceof MappingError) {
+      errorType = 'MAPPING_ERROR';
+    } else if (error instanceof PathResolutionError) {
+      errorType = 'PATH_RESOLUTION_ERROR';
+    } else if (error instanceof FileParsingError) {
+      errorType = 'FILE_PARSING_ERROR';
+    }
+
+    // Increment counter
+    const count = this.errorCounts.get(errorType) || 0;
+    this.errorCounts.set(errorType, count + 1);
+
+    // Update last occurrence
+    this.lastErrors.set(errorType, new Date());
+  }
+
+  getMetrics() {
+    return {
+      errorCounts: Object.fromEntries(this.errorCounts),
+      lastErrors: Object.fromEntries(this.lastErrors),
+      timestamp: new Date().toISOString()
+    };
+  }
+
+  reset(): void {
+    this.errorCounts.clear();
+    this.lastErrors.clear();
+  }
+}
+
+// Usage
+const metrics = new ErrorMetrics();
+
+try {
+  await processFile(fileName);
+} catch (error) {
+  metrics.recordError(error);
+  throw error;
+}
+
+// Get metrics periodically
+setInterval(() => {
+  logger.info('Error metrics', metrics.getMetrics());
+}, 60000);  // Every minute
+```
+
+### Advanced Metrics with Rates
+
+Track error rates over time windows:
+
+```typescript
+interface TimeWindow {
+  start: Date;
+  end: Date;
+  errors: Map<string, number>;
+}
+
+class AdvancedErrorMetrics {
+  private windows: TimeWindow[] = [];
+  private windowSizeMs: number;
+  private maxWindows: number;
+
+  constructor(windowSizeMs = 60000, maxWindows = 60) {
+    this.windowSizeMs = windowSizeMs;
+    this.maxWindows = maxWindows;
+  }
+
+  recordError(error: Error): void {
+    const now = new Date();
+    const errorType = this.getErrorType(error);
+
+    // Get or create current window
+    let currentWindow = this.windows[this.windows.length - 1];
+
+    if (!currentWindow || now.getTime() - currentWindow.start.getTime() >= this.windowSizeMs) {
+      // Create new window
+      currentWindow = {
+        start: now,
+        end: new Date(now.getTime() + this.windowSizeMs),
+        errors: new Map()
+      };
+      this.windows.push(currentWindow);
+
+      // Trim old windows
+      if (this.windows.length > this.maxWindows) {
+        this.windows.shift();
+      }
+    }
+
+    // Increment error count in current window
+    const count = currentWindow.errors.get(errorType) || 0;
+    currentWindow.errors.set(errorType, count + 1);
+  }
+
+  getErrorRate(errorType: string, periodMinutes = 5): number {
+    const periodMs = periodMinutes * 60 * 1000;
+    const now = Date.now();
+    let totalErrors = 0;
+
+    for (const window of this.windows) {
+      if (now - window.start.getTime() <= periodMs) {
+        totalErrors += window.errors.get(errorType) || 0;
+      }
+    }
+
+    // Errors per minute
+    return totalErrors / periodMinutes;
+  }
+
+  getMetrics() {
+    const now = new Date();
+    const recentWindows = this.windows.filter(w =>
+      now.getTime() - w.start.getTime() <= 300000  // Last 5 minutes
+    );
+
+    const errorCounts = new Map<string, number>();
+    for (const window of recentWindows) {
+      for (const [type, count] of window.errors.entries()) {
+        const current = errorCounts.get(type) || 0;
+        errorCounts.set(type, current + count);
+      }
+    }
+
+    return {
+      last5Minutes: Object.fromEntries(errorCounts),
+      errorRates: {
+        parsing: this.getErrorRate('FILE_PARSING_ERROR', 5),
+        mapping: this.getErrorRate('MAPPING_ERROR', 5),
+        network: this.getErrorRate('NETWORK_ERROR', 5)
+      },
+      timestamp: now.toISOString()
+    };
+  }
+
+  private getErrorType(error: Error): string {
+    if (error instanceof FluentAPIError) return `API_ERROR_${error.statusCode}`;
+    if (error instanceof AuthenticationError) return 'AUTH_ERROR';
+    if (error instanceof GraphQLExecutionError) return 'GRAPHQL_ERROR';
+    if (error instanceof IngestionError) return error.code;
+    if (error instanceof MappingError) return 'MAPPING_ERROR';
+    if (error instanceof PathResolutionError) return 'PATH_RESOLUTION_ERROR';
+    if (error instanceof FileParsingError) return 'FILE_PARSING_ERROR';
+    return 'UNKNOWN';
+  }
+}
+```
+
+## Alerting Patterns
+
+### Threshold-Based Alerting
+
+Alert when error count exceeds threshold:
+
+```typescript
+class ErrorAlerting {
+  private metrics: ErrorMetrics;
+  private thresholds: Map<string, number>;
+
+  constructor(metrics: ErrorMetrics) {
+    this.metrics = metrics;
+    this.thresholds = new Map([
+      ['PARSE_ERROR', 10],
+      ['NETWORK_ERROR', 50],
+      ['MAPPING_ERROR', 10]
+    ]);
+  }
+
+  checkThresholds(): void {
+    const current = this.metrics.getMetrics();
+
+    for (const [errorType, threshold] of this.thresholds.entries()) {
+      const count = current.errorCounts[errorType] || 0;
+
+      if (count >= threshold) {
+        this.sendAlert({
+          severity: 'HIGH',
+          message: `Error threshold exceeded: ${errorType}`,
+          count,
+          threshold,
+          timestamp: new Date().toISOString()
+        });
+      }
+    }
+  }
+
+  private async sendAlert(alert: any): Promise<void> {
+    logger.error('ALERT: Error threshold exceeded', alert);
+
+    // Send to monitoring service
+    await this.sendToSlack(alert);
+    await this.sendToPagerDuty(alert);
+  }
+
+  private async sendToSlack(alert: any): Promise<void> {
+    // Slack webhook integration
+  }
+
+  private async sendToPagerDuty(alert: any): Promise<void> {
+    // PagerDuty integration
+  }
+}
+```
+
+### Rate-Based Alerting
+
+Alert when error rate exceeds threshold:
+
+```typescript
+class RateBasedAlerting {
+  private metrics: AdvancedErrorMetrics;
+
+  async checkRates(): Promise<void> {
+    const metrics = this.metrics.getMetrics();
+
+    // Alert if parsing errors > 2 per minute
+    if (metrics.errorRates.parsing > 2) {
+      await this.sendAlert({
+        type: 'PARSING_ERROR_RATE_HIGH',
+        rate: metrics.errorRates.parsing,
+        threshold: 2,
+        unit: 'per minute'
+      });
+    }
+
+    // Alert if network errors > 10 per minute
+    if (metrics.errorRates.network > 10) {
+      await this.sendAlert({
+        type: 'NETWORK_ERROR_RATE_HIGH',
+        rate: metrics.errorRates.network,
+        threshold: 10,
+        unit: 'per minute'
+      });
+    }
+  }
+
+  private async sendAlert(alert: any): Promise<void> {
+    logger.error('RATE ALERT: Error rate threshold exceeded', alert);
+    // Send to monitoring systems
+  }
+}
+```
+
+## Integration with Monitoring Systems
+
+### Datadog Integration
+
+```typescript
+import { IngestionError } from '@fluentcommerce/fc-connect-sdk';
+
+async function sendToDatadog(error: Error, context: any): Promise<void> {
+  const metric = {
+    metric: 'ingestion.error',
+    type: 'count',
+    points: [[Date.now() / 1000, 1]],
+    tags: []
+  };
+
+  if (error instanceof IngestionError) {
+    metric.tags.push(
+      `error_code:${error.code}`,
+      `retryable:${error.isRetryable()}`,
+      `environment:${process.env.NODE_ENV}`
+    );
+  }
+
+  metric.tags.push(
+    `source:${context.source}`,
+    `customer:${context.customerId}`
+  );
+
+  // Send to Datadog API
+  // await datadogClient.submitMetric(metric);
+}
+
+// Usage
+try {
+  await processFile(fileName);
+} catch (error) {
+  await sendToDatadog(error, context);
+  throw error;
+}
+```
+
+### Sentry Integration
+
+```typescript
+import * as Sentry from '@sentry/node';
+import { IngestionError } from '@fluentcommerce/fc-connect-sdk';
+
+function reportToSentry(error: Error, context: any): void {
+  Sentry.withScope(scope => {
+    // Add context
+    scope.setContext('business', {
+      orderId: context.orderId,
+      customerId: context.customerId,
+      source: context.source
+    });
+
+    // Add tags
+    if (error instanceof IngestionError) {
+      scope.setTag('error_code', error.code);
+      scope.setTag('retryable', error.isRetryable().toString());
+
+      // Add extra data
+      scope.setExtra('error_details', error.toJSON());
+    }
+
+    // Set fingerprint for grouping
+    scope.setFingerprint([
+      error instanceof IngestionError ? error.code : error.name,
+      context.source
+    ]);
+
+    // Capture exception
+    Sentry.captureException(error);
+  });
+}
+
+// Usage
+try {
+  await processFile(fileName);
+} catch (error) {
+  reportToSentry(error, context);
+  throw error;
+}
+```
+
+### CloudWatch Integration
+
+```typescript
+import { CloudWatchClient, PutMetricDataCommand } from '@aws-sdk/client-cloudwatch';
+import { IngestionError } from '@fluentcommerce/fc-connect-sdk';
+
+async function sendToCloudWatch(error: Error): Promise<void> {
+  const cloudwatch = new CloudWatchClient({ region: 'us-east-1' });
+
+  const dimensions = [
+    { Name: 'Environment', Value: process.env.NODE_ENV || 'unknown' }
+  ];
+
+  if (error instanceof IngestionError) {
+    dimensions.push(
+      { Name: 'ErrorCode', Value: error.code },
+      { Name: 'Retryable', Value: error.isRetryable().toString() }
+    );
+  }
+
+  const command = new PutMetricDataCommand({
+    Namespace: 'FluentCommerce/Ingestion',
+    MetricData: [
+      {
+        MetricName: 'ErrorCount',
+        Value: 1,
+        Unit: 'Count',
+        Timestamp: new Date(),
+        Dimensions: dimensions
+      }
+    ]
+  });
+
+  await cloudwatch.send(command);
+}
+```
+
+## Logging Best Practices
+
+### 1. Always Log Error Context
+
+```typescript
+// ❌ POOR - Missing context
+logger.error('Error occurred');
+
+// ✅ GOOD - Full context (Standalone)
+import { createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
+const logger = toStructuredLogger(createConsoleLogger(), { service: 'OrderProcessor' });
+
+// ✅ GOOD - Full context (Versori Platform)
+const { log: logger } = ctx;
+
+logger.error('Order processing failed', {
+  error: error instanceof IngestionError ? error.toJSON() : error.message,
+  orderId: metadata.orderId,
+  fileName,
+  attempt: retryAttempt,
+  correlationId
+});
+```
+
+### 2. Use Appropriate Log Levels
+
+```typescript
+// Debug: Detailed flow information
+logger.debug('Parsing XML file', { fileName, size });
+
+// Info: Normal operations
+logger.info('Order processed successfully', { orderId, duration });
+
+// Warn: Recoverable issues
+logger.warn('Retrying after transient error', { attempt, error: error.code });
+
+// Error: Failed operations
+logger.error('Order processing failed', { error: error.toJSON() });
+```
+
+### 3. Include Timestamps and IDs
+
+```typescript
+logger.error('Processing failed', {
+  timestamp: new Date().toISOString(),
+  correlationId: context.correlationId,
+  traceId: context.traceId,
+  error: error.toJSON()
+});
+```
+
+### 4. Sanitize Sensitive Data
+
+```typescript
+function sanitizeForLogging(data: any): any {
+  const sanitized = { ...data };
+
+  // Remove sensitive fields
+  delete sanitized.password;
+  delete sanitized.apiKey;
+  delete sanitized.creditCard;
+
+  // Mask email
+  if (sanitized.email) {
+    sanitized.email = sanitized.email.replace(/(.{2})(.*)(@.*)/, '$1***$3');
+  }
+
+  return sanitized;
+}
+
+logger.error('Processing failed', {
+  data: sanitizeForLogging(sourceData),
+  error: error.toJSON()
+});
+```
+
+## Dashboard Examples
+
+### Error Summary Dashboard
+
+Track key metrics:
+- Total errors (last hour, day, week)
+- Error rate trend
+- Top error types
+- Retryable vs non-retryable ratio
+- Mean time to resolution
+
+### Error Distribution
+
+Visualize error types:
+```
+Parsing Errors:    ████████░░ 42%
+Mapping Errors:    ██████░░░░ 31%
+Network Errors:    ████░░░░░░ 19%
+Validation Errors: ██░░░░░░░░  8%
+```
+
+### Error Heatmap
+
+Show error frequency by time of day and error type.
+
+## Key Takeaways
+
+- 🎯 **Use error.toJSON()** - Complete structured error data
+- 🎯 **Add business context** - Enrich with IDs, metadata
+- 🎯 **Track metrics** - Count errors, calculate rates
+- 🎯 **Set up alerts** - Threshold and rate-based alerting
+- 🎯 **Integrate monitoring** - Datadog, Sentry, CloudWatch
+- 🎯 **Sanitize logs** - Remove sensitive data before logging
+
+## Next Steps
+
+Continue to [Module 8: API Reference →](./error-handling-08-api-reference.md) for complete error class documentation and best practices checklist.
+
+---
+
+**Previous:** [← Module 6: Retry Strategies](./error-handling-06-retry-strategies.md)
+**Next:** [Module 8: API Reference →](./error-handling-08-api-reference.md)