@xenterprises/fastify-xlogger 1.0.0

package/.gitlab-ci.yml

@@ -0,0 +1,45 @@
+# ============================================================================
+# GitLab CI/CD Pipeline - xLogger
+# ============================================================================
+# Runs tests on merge requests and commits to main/master
+
+stages:
+  - test
+
+variables:
+  NODE_ENV: test
+
+# ============================================================================
+# Shared Configuration
+# ============================================================================
+.shared_rules: &shared_rules
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == "main"'
+    - if: '$CI_COMMIT_BRANCH == "master"'
+    - if: '$CI_COMMIT_TAG'
+
+# ============================================================================
+# STAGE: TEST
+# ============================================================================
+test:
+  stage: test
+  image: node:20-alpine
+  <<: *shared_rules
+
+  cache:
+    key: ${CI_COMMIT_REF_SLUG}
+    paths:
+      - node_modules/
+
+  before_script:
+    - npm ci
+
+  script:
+    - echo "Running xLogger tests..."
+    - npm test
+    - npm audit --audit-level=high || true
+
+  retry:
+    max: 2
+    when: runner_system_failure

package/README.md

@@ -0,0 +1,396 @@
+# xLogger
+
+A Fastify plugin for standardized logging with Pino. Provides automatic request context, secret redaction, canonical log schema, boundary logging for external APIs, and background job correlation.
+
+## Philosophy
+
+**Logging is infrastructure. Centralize it and keep it boring.**
+
+- Use Fastify's built-in Pino logger as the single logging engine
+- Never create a second logger
+- Log structured objects, not concatenated strings
+- Automatically redact secrets at the logger level
+- Standardize context across all log entries
+
+## Installation
+
+```bash
+npm install xlogger
+```
+
+## Quick Start
+
+```javascript
+import Fastify from "fastify";
+import xLogger, { getLoggerOptions } from "xlogger";
+
+// Create Fastify with xLogger-configured Pino options
+const fastify = Fastify({
+  logger: getLoggerOptions({
+    serviceName: "my-api",
+  }),
+});
+
+// Register the plugin
+await fastify.register(xLogger, {
+  serviceName: "my-api",
+});
+
+// Use structured logging everywhere
+fastify.get("/users/:id", async (request, reply) => {
+  const { id } = request.params;
+
+  // Use the context-aware logger
+  request.contextLog.info({ userId: id }, "Fetching user");
+
+  // Or use the standard logger with context extraction
+  fastify.xlogger.logEvent({
+    event: "user.fetched",
+    data: { userId: id },
+    request,
+  });
+
+  return { id };
+});
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `active` | boolean | `true` | Enable/disable the plugin |
+| `serviceName` | string | `process.env.SERVICE_NAME` | Service name for logs |
+| `environment` | string | `process.env.NODE_ENV` | Environment name |
+| `redactPaths` | string[] | `[]` | Additional paths to redact |
+| `redactClobber` | boolean | `false` | Replace default redact paths |
+| `contextExtractor` | function | `null` | Custom context extraction function |
+| `enableBoundaryLogging` | boolean | `true` | Enable boundary logging helpers |
+
+## Features
+
+### 1. Automatic Request Context
+
+Every log entry automatically includes:
+- `requestId` - Unique request identifier
+- `orgId` - Tenant/organization ID (from headers or user object)
+- `userId` - User ID (from headers or user object)
+- `route` - Route pattern
+- `method` - HTTP method
+- `traceId` / `spanId` - OpenTelemetry context (if present)
+
+```javascript
+// Context is automatically added to request.contextLog
+request.contextLog.info({ action: "invite_sent" }, "Invite sent");
+
+// Output includes requestId, orgId, userId, route, method automatically
+```
+
+### 2. Secret Redaction
+
+Secrets are automatically redacted at the logger level:
+
+```javascript
+// These fields are automatically redacted:
+// - authorization, cookie, set-cookie headers
+// - password, token, secret, apiKey fields
+// - cardNumber, cvv, ssn, creditCard
+// - Nested paths like *.password, *.token
+
+fastify.log.info({
+  user: {
+    email: "john@example.com",
+    password: "secret123"  // Will be logged as [REDACTED]
+  }
+}, "User data");
+```
+
+**Default Redact Paths:**
+- `req.headers.authorization`
+- `req.headers.cookie`
+- `req.headers['set-cookie']`
+- `req.headers['x-api-key']`
+- `password`, `token`, `secret`, `apiKey`, `api_key`
+- `accessToken`, `refreshToken`, `privateKey`
+- `cardNumber`, `cvv`, `ssn`, `creditCard`
+- `*.password`, `*.token`, `*.secret`, `*.apiKey`
+
+### 3. Canonical Log Schema
+
+Recommended fields for consistent log structure:
+
+| Field | Description |
+|-------|-------------|
+| `event` | Event name (e.g., "user.created", "payment.completed") |
+| `msg` | Human-readable message |
+| `requestId` | Request identifier |
+| `orgId` | Organization/tenant ID |
+| `userId` | User ID |
+| `route` | Route pattern |
+| `method` | HTTP method |
+| `statusCode` | Response status code |
+| `durationMs` | Duration in milliseconds |
+| `err` | Error object |
+| `vendor` | External service name |
+| `externalId` | External resource ID |
+
+### 4. Boundary Logging (External API Calls)
+
+Log external API calls with timing, vendor IDs, and retry info:
+
+```javascript
+// Simple boundary logging
+fastify.xlogger.logBoundary({
+  vendor: "stripe",
+  operation: "createCustomer",
+  externalId: "cus_123",
+  durationMs: 150,
+  success: true,
+  request,
+});
+
+// Or use the boundary logger helper with automatic timing
+const boundary = fastify.xlogger.createBoundaryLogger("stripe", "createCustomer", request);
+
+try {
+  const customer = await stripe.customers.create({ email });
+  boundary.success({ externalId: customer.id, statusCode: 200 });
+} catch (err) {
+  boundary.fail(err, { statusCode: err.statusCode });
+}
+
+// With retries
+const boundary = fastify.xlogger.createBoundaryLogger("twilio", "sendSMS", request);
+for (let i = 0; i < 3; i++) {
+  try {
+    const result = await twilio.messages.create({ to, body });
+    boundary.success({ externalId: result.sid });
+    break;
+  } catch (err) {
+    boundary.retry();
+    if (i === 2) boundary.fail(err);
+  }
+}
+```
+
+### 5. Background Job Correlation
+
+Pass context to background jobs for tracing:
+
+```javascript
+// In your route handler
+fastify.post("/process", async (request, reply) => {
+  const context = fastify.xlogger.extractContext(request);
+
+  // Queue the job with context
+  await queue.add("processData", {
+    data: request.body,
+    ...context,
+  });
+
+  return { queued: true };
+});
+
+// In your job processor
+async function processJob(job) {
+  const { requestId, orgId, userId, data } = job.data;
+
+  const jobContext = fastify.xlogger.createJobContext({
+    jobName: "processData",
+    requestId,
+    orgId,
+    userId,
+  });
+
+  jobContext.start({ itemCount: data.length });
+
+  try {
+    await processData(data);
+    jobContext.complete({ processed: data.length });
+  } catch (err) {
+    jobContext.fail(err);
+    throw err;
+  }
+}
+```
+
+### 6. Environment-Aware Output
+
+- **Production**: JSON logs for aggregation systems
+- **Development**: Pretty-printed logs with colors
+
+```javascript
+// Automatically detected from NODE_ENV
+const options = getLoggerOptions();
+
+// Or force pretty printing
+const options = getLoggerOptions({ pretty: true });
+```
+
+## API Reference
+
+### Decorators
+
+| Decorator | Description |
+|-----------|-------------|
+| `fastify.xlogger.config` | Plugin configuration |
+| `fastify.xlogger.extractContext(request)` | Extract context from request |
+| `fastify.xlogger.logEvent(params)` | Log a business event |
+| `fastify.xlogger.logBoundary(params)` | Log an external API call |
+| `fastify.xlogger.createBoundaryLogger(vendor, op, req)` | Create timed boundary logger |
+| `fastify.xlogger.createJobContext(params)` | Create background job context |
+| `fastify.xlogger.levels` | Log level constants |
+| `fastify.xlogger.redactPaths` | Configured redact paths |
+| `request.contextLog` | Child logger with request context |
+
+### `logEvent(params)`
+
+Log a business event with canonical schema.
+
+```javascript
+fastify.xlogger.logEvent({
+  event: "user.created",           // Required: event name
+  msg: "User was created",         // Optional: message
+  level: "info",                   // Optional: log level (default: "info")
+  data: { email: "john@example.com" },  // Optional: additional data
+  request,                         // Optional: request for context
+});
+```
+
+### `logBoundary(params)`
+
+Log an external API call.
+
+```javascript
+fastify.xlogger.logBoundary({
+  vendor: "stripe",        // Required: service name
+  operation: "createCustomer",  // Required: operation name
+  externalId: "cus_123",   // Optional: external resource ID
+  durationMs: 150,         // Optional: call duration
+  statusCode: 200,         // Optional: response status
+  success: true,           // Optional: success flag (default: true)
+  retryCount: 0,           // Optional: number of retries
+  metadata: {},            // Optional: additional metadata
+  err: null,               // Optional: error if failed
+  request,                 // Optional: request for context
+});
+```
+
+### `createBoundaryLogger(vendor, operation, request)`
+
+Create a boundary logger with automatic timing.
+
+```javascript
+const boundary = fastify.xlogger.createBoundaryLogger("stripe", "createCustomer", request);
+
+boundary.retry();          // Increment retry counter
+boundary.success(params);  // Log success with timing
+boundary.fail(err, params); // Log failure with timing
+```
+
+### `createJobContext(params)`
+
+Create a correlation context for background jobs.
+
+```javascript
+const job = fastify.xlogger.createJobContext({
+  jobName: "processPayments",  // Required: job name
+  requestId: "req_123",        // Optional: original request ID
+  orgId: "org_456",            // Optional: organization ID
+  userId: "user_789",          // Optional: user ID
+  correlationId: "corr_abc",   // Optional: correlation ID (auto-generated if not provided)
+});
+
+job.context;       // { correlationId, jobName, orgId, userId, originalRequestId }
+job.log;           // Child logger with context
+job.start(data);   // Log job started
+job.complete(data); // Log job completed
+job.fail(err, data); // Log job failed
+```
+
+### `getLoggerOptions(options)`
+
+Get Pino logger options for Fastify initialization.
+
+```javascript
+import { getLoggerOptions } from "xlogger";
+
+const fastify = Fastify({
+  logger: getLoggerOptions({
+    level: "debug",           // Optional: log level
+    serviceName: "my-api",    // Optional: service name
+    redactPaths: ["custom"],  // Optional: additional redact paths
+    pretty: false,            // Optional: force pretty printing
+  }),
+});
+```
+
+## Log Levels
+
+| Level | Value | Use For |
+|-------|-------|---------|
+| `fatal` | 60 | Process cannot continue |
+| `error` | 50 | Failures requiring attention |
+| `warn` | 40 | Recoverable issues |
+| `info` | 30 | Business events, normal operations |
+| `debug` | 20 | Detailed debugging information |
+| `trace` | 10 | Very detailed tracing |
+
+## Best Practices
+
+### Do
+
+```javascript
+// Log structured objects
+fastify.log.info({ userId, action: "login" }, "User logged in");
+
+// Use the canonical schema
+fastify.xlogger.logEvent({
+  event: "payment.completed",
+  data: { amount: 100, currency: "USD" },
+  request,
+});
+
+// Use boundary logging for external calls
+const boundary = fastify.xlogger.createBoundaryLogger("stripe", "charge", request);
+```
+
+### Don't
+
+```javascript
+// Don't concatenate strings
+fastify.log.info("User " + userId + " logged in"); // Bad!
+
+// Don't log sensitive data (it will be redacted, but still)
+fastify.log.info({ password: userPassword }); // Bad!
+
+// Don't log full request/response payloads
+fastify.log.info({ body: request.body }); // Usually bad!
+```
+
+## Integration with Error Tracking
+
+Use logs for aggregation/search and Sentry for error tracking:
+
+```javascript
+fastify.setErrorHandler((error, request, reply) => {
+  // Log the error
+  request.contextLog.error({ err: error }, "Request failed");
+
+  // Send to Sentry with context
+  Sentry.captureException(error, {
+    extra: fastify.xlogger.extractContext(request),
+  });
+
+  reply.status(500).send({ error: "Internal Server Error" });
+});
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@xenterprises/fastify-xlogger",
+  "version": "1.0.0",
+  "description": "Fastify plugin for standardized logging with Pino - context, redaction, and canonical schema",
+  "type": "module",
+  "main": "src/xLogger.js",
+  "exports": {
+    ".": "./src/xLogger.js"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "npm": ">=10.0.0"
+  },
+  "scripts": {
+    "test": "node --test test/xLogger.test.js",
+    "lint": "eslint src/ test/"
+  },
+  "keywords": [
+    "fastify",
+    "logging",
+    "pino",
+    "structured-logging",
+    "redaction",
+    "observability",
+    "saas"
+  ],
+  "author": "X Enterprises",
+  "license": "MIT",
+  "dependencies": {
+    "fastify-plugin": "^5.0.1"
+  },
+  "peerDependencies": {
+    "fastify": "^5.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.0.0",
+    "fastify": "^5.0.0",
+    "pino-pretty": "^11.0.0"
+  }
+}

package/src/xLogger.js

@@ -0,0 +1,462 @@
+/**
+ * xLogger - Standardized Logging for Fastify SaaS Plugins
+ *
+ * Wraps Fastify's built-in Pino logger with:
+ * - Standardized request context (requestId, orgId, userId, route, method)
+ * - Automatic secret redaction
+ * - Canonical log schema
+ * - Environment-aware formatting (JSON in prod, pretty in dev)
+ * - Boundary logging helpers for external API calls
+ * - Background job correlation support
+ *
+ * @see https://getpino.io/
+ */
+
+import fp from "fastify-plugin";
+
+/**
+ * Default paths to redact from logs
+ */
+const DEFAULT_REDACT_PATHS = [
+  // Auth headers
+  "req.headers.authorization",
+  "req.headers.cookie",
+  "req.headers['set-cookie']",
+  "req.headers['x-api-key']",
+  // Common secret fields
+  "password",
+  "token",
+  "secret",
+  "apiKey",
+  "api_key",
+  "accessToken",
+  "access_token",
+  "refreshToken",
+  "refresh_token",
+  "privateKey",
+  "private_key",
+  // Payment/PII
+  "cardNumber",
+  "card_number",
+  "cvv",
+  "ssn",
+  "creditCard",
+  // Nested paths
+  "*.password",
+  "*.token",
+  "*.secret",
+  "*.apiKey",
+  "*.api_key",
+];
+
+/**
+ * Log levels and their numeric values
+ */
+const LOG_LEVELS = {
+  fatal: 60,
+  error: 50,
+  warn: 40,
+  info: 30,
+  debug: 20,
+  trace: 10,
+};
+
+/**
+ * xLogger Plugin
+ *
+ * @param {import('fastify').FastifyInstance} fastify - Fastify instance
+ * @param {Object} options - Plugin options
+ * @param {boolean} [options.active] - Enable/disable the plugin (default: true)
+ * @param {string[]} [options.redactPaths] - Additional paths to redact
+ * @param {boolean} [options.redactClobber] - Replace default redact paths instead of extending
+ * @param {boolean} [options.includeRequestBody] - Include request body in logs (default: false)
+ * @param {boolean} [options.includeResponseBody] - Include response body in logs (default: false)
+ * @param {string} [options.serviceName] - Service name for logs
+ * @param {string} [options.environment] - Environment name (default: process.env.NODE_ENV)
+ * @param {Function} [options.contextExtractor] - Custom function to extract context from request
+ * @param {boolean} [options.enableBoundaryLogging] - Enable external API call logging helpers (default: true)
+ */
+async function xLogger(fastify, options) {
+  // Check if plugin is disabled
+  if (options.active === false) {
+    console.info("   ⏸️  xLogger Disabled");
+    return;
+  }
+
+  const config = {
+    redactPaths: options.redactClobber
+      ? options.redactPaths || []
+      : [...DEFAULT_REDACT_PATHS, ...(options.redactPaths || [])],
+    includeRequestBody: options.includeRequestBody || false,
+    includeResponseBody: options.includeResponseBody || false,
+    serviceName: options.serviceName || process.env.SERVICE_NAME || "fastify-app",
+    environment: options.environment || process.env.NODE_ENV || "development",
+    contextExtractor: options.contextExtractor || null,
+    enableBoundaryLogging: options.enableBoundaryLogging !== false,
+  };
+
+  // Store configuration
+  fastify.decorate("xlogger", {
+    config,
+  });
+
+  /**
+   * Extract standard context from request
+   * @param {import('fastify').FastifyRequest} request
+   * @returns {Object} Context object
+   */
+  function extractContext(request) {
+    const context = {
+      requestId: request.id,
+      route: request.routeOptions?.url || request.url,
+      method: request.method,
+    };
+
+    // Extract orgId and userId from various sources
+    // Check request user object (set by auth plugins)
+    if (request.user) {
+      if (request.user.orgId) context.orgId = request.user.orgId;
+      if (request.user.organizationId) context.orgId = request.user.organizationId;
+      if (request.user.tenantId) context.orgId = request.user.tenantId;
+      if (request.user.id) context.userId = request.user.id;
+      if (request.user.userId) context.userId = request.user.userId;
+      if (request.user.sub) context.userId = request.user.sub;
+    }
+
+    // Check headers for tenant context
+    if (request.headers["x-org-id"]) context.orgId = request.headers["x-org-id"];
+    if (request.headers["x-tenant-id"]) context.orgId = request.headers["x-tenant-id"];
+    if (request.headers["x-user-id"]) context.userId = request.headers["x-user-id"];
+
+    // OpenTelemetry trace context
+    if (request.headers.traceparent) {
+      const parts = request.headers.traceparent.split("-");
+      if (parts.length >= 3) {
+        context.traceId = parts[1];
+        context.spanId = parts[2];
+      }
+    }
+
+    // Custom context extractor
+    if (config.contextExtractor) {
+      const customContext = config.contextExtractor(request);
+      Object.assign(context, customContext);
+    }
+
+    return context;
+  }
+
+  /**
+   * Create a child logger with request context
+   * @param {import('fastify').FastifyRequest} request
+   * @returns {import('pino').Logger} Child logger with context
+   */
+  function createRequestLogger(request) {
+    const context = extractContext(request);
+    return request.log.child(context);
+  }
+
+  // Add context logger to request
+  fastify.decorateRequest("contextLog", null);
+
+  fastify.addHook("onRequest", async (request) => {
+    request.contextLog = createRequestLogger(request);
+  });
+
+  /**
+   * Log a business event with canonical schema
+   * @param {Object} params - Event parameters
+   * @param {string} params.event - Event name (e.g., "user.created", "payment.completed")
+   * @param {string} [params.msg] - Human-readable message
+   * @param {string} [params.level] - Log level (default: "info")
+   * @param {Object} [params.data] - Additional event data
+   * @param {import('fastify').FastifyRequest} [params.request] - Request for context
+   */
+  function logEvent({ event, msg, level = "info", data = {}, request = null }) {
+    const logData = {
+      event,
+      ...data,
+    };
+
+    // Add request context if available
+    if (request) {
+      Object.assign(logData, extractContext(request));
+    }
+
+    const logger = request?.log || fastify.log;
+    const message = msg || event;
+
+    if (logger[level]) {
+      logger[level](logData, message);
+    } else {
+      logger.info(logData, message);
+    }
+  }
+
+  /**
+   * Log an external API call (boundary logging)
+   * @param {Object} params - Call parameters
+   * @param {string} params.vendor - External service name (e.g., "stripe", "twilio")
+   * @param {string} params.operation - Operation name (e.g., "createCustomer", "sendSMS")
+   * @param {string} [params.externalId] - External resource ID
+   * @param {number} [params.durationMs] - Call duration in milliseconds
+   * @param {number} [params.statusCode] - Response status code
+   * @param {boolean} [params.success] - Whether the call succeeded
+   * @param {number} [params.retryCount] - Number of retries
+   * @param {Object} [params.metadata] - Additional metadata (no sensitive data!)
+   * @param {Error} [params.err] - Error if failed
+   * @param {import('fastify').FastifyRequest} [params.request] - Request for context
+   */
+  function logBoundary({
+    vendor,
+    operation,
+    externalId,
+    durationMs,
+    statusCode,
+    success = true,
+    retryCount,
+    metadata = {},
+    err,
+    request = null,
+  }) {
+    const logData = {
+      event: "boundary.call",
+      vendor,
+      operation,
+      success,
+      ...metadata,
+    };
+
+    if (externalId) logData.externalId = externalId;
+    if (durationMs !== undefined) logData.durationMs = durationMs;
+    if (statusCode !== undefined) logData.statusCode = statusCode;
+    if (retryCount !== undefined) logData.retryCount = retryCount;
+    if (err) logData.err = err;
+
+    // Add request context if available
+    if (request) {
+      Object.assign(logData, extractContext(request));
+    }
+
+    const logger = request?.log || fastify.log;
+    const level = success ? "info" : "error";
+    const message = `${vendor}.${operation} ${success ? "completed" : "failed"}`;
+
+    logger[level](logData, message);
+  }
+
+  /**
+   * Create a boundary logger helper that times the operation
+   * @param {string} vendor - External service name
+   * @param {string} operation - Operation name
+   * @param {import('fastify').FastifyRequest} [request] - Request for context
+   * @returns {Object} Boundary logger with start/success/fail methods
+   */
+  function createBoundaryLogger(vendor, operation, request = null) {
+    const startTime = Date.now();
+    let retryCount = 0;
+
+    return {
+      /**
+       * Increment retry counter
+       */
+      retry() {
+        retryCount++;
+      },
+
+      /**
+       * Log successful completion
+       * @param {Object} [params] - Additional parameters
+       */
+      success(params = {}) {
+        logBoundary({
+          vendor,
+          operation,
+          durationMs: Date.now() - startTime,
+          success: true,
+          retryCount: retryCount > 0 ? retryCount : undefined,
+          request,
+          ...params,
+        });
+      },
+
+      /**
+       * Log failure
+       * @param {Error} err - The error
+       * @param {Object} [params] - Additional parameters
+       */
+      fail(err, params = {}) {
+        logBoundary({
+          vendor,
+          operation,
+          durationMs: Date.now() - startTime,
+          success: false,
+          retryCount: retryCount > 0 ? retryCount : undefined,
+          err,
+          request,
+          ...params,
+        });
+      },
+    };
+  }
+
+  /**
+   * Create a correlation context for background jobs
+   * @param {Object} params - Correlation parameters
+   * @param {string} [params.requestId] - Original request ID
+   * @param {string} [params.orgId] - Organization ID
+   * @param {string} [params.userId] - User ID
+   * @param {string} [params.correlationId] - Correlation ID (generated if not provided)
+   * @param {string} [params.jobName] - Job name
+   * @returns {Object} Correlation context and child logger
+   */
+  function createJobContext({ requestId, orgId, userId, correlationId, jobName }) {
+    const context = {
+      correlationId: correlationId || `job_${Date.now()}_${Math.random().toString(36).slice(2)}`,
+      jobName,
+    };
+
+    if (requestId) context.originalRequestId = requestId;
+    if (orgId) context.orgId = orgId;
+    if (userId) context.userId = userId;
+
+    const logger = fastify.log.child(context);
+
+    return {
+      context,
+      log: logger,
+      /**
+       * Log job start
+       * @param {Object} [data] - Additional data
+       */
+      start(data = {}) {
+        logger.info({ event: "job.started", ...data }, `Job ${jobName} started`);
+      },
+      /**
+       * Log job completion
+       * @param {Object} [data] - Additional data
+       */
+      complete(data = {}) {
+        logger.info({ event: "job.completed", ...data }, `Job ${jobName} completed`);
+      },
+      /**
+       * Log job failure
+       * @param {Error} err - The error
+       * @param {Object} [data] - Additional data
+       */
+      fail(err, data = {}) {
+        logger.error({ event: "job.failed", err, ...data }, `Job ${jobName} failed`);
+      },
+    };
+  }
+
+  // Add logging utilities to xlogger namespace
+  fastify.xlogger.extractContext = extractContext;
+  fastify.xlogger.logEvent = logEvent;
+  fastify.xlogger.logBoundary = logBoundary;
+  fastify.xlogger.createBoundaryLogger = createBoundaryLogger;
+  fastify.xlogger.createJobContext = createJobContext;
+  fastify.xlogger.levels = LOG_LEVELS;
+  fastify.xlogger.redactPaths = config.redactPaths;
+
+  // Log response with canonical fields
+  fastify.addHook("onResponse", async (request, reply) => {
+    const context = extractContext(request);
+    const logData = {
+      event: "http.response",
+      ...context,
+      statusCode: reply.statusCode,
+      durationMs: Math.round(reply.elapsedTime),
+    };
+
+    // Determine log level based on status code
+    let level = "info";
+    if (reply.statusCode >= 500) {
+      level = "error";
+    } else if (reply.statusCode >= 400) {
+      level = "warn";
+    }
+
+    request.log[level](logData, `${request.method} ${request.url} ${reply.statusCode}`);
+  });
+
+  console.info("   ✅ xLogger Standardized Logging Enabled");
+  console.info(`      • Service: ${config.serviceName}`);
+  console.info(`      • Environment: ${config.environment}`);
+  console.info(`      • Redact paths: ${config.redactPaths.length} configured`);
+}
+
+export default fp(xLogger, {
+  name: "xLogger",
+});
+
+/**
+ * Get Pino logger options with xLogger defaults
+ * Use this when creating the Fastify instance
+ *
+ * @param {Object} [options] - Options
+ * @param {string} [options.level] - Log level (default: based on NODE_ENV)
+ * @param {string[]} [options.redactPaths] - Additional paths to redact
+ * @param {boolean} [options.pretty] - Force pretty printing
+ * @param {string} [options.serviceName] - Service name
+ * @returns {Object} Pino logger options
+ */
+export function getLoggerOptions(options = {}) {
+  const isProd = process.env.NODE_ENV === "production";
+  const level = options.level || (isProd ? "info" : "debug");
+
+  const redactPaths = [...DEFAULT_REDACT_PATHS, ...(options.redactPaths || [])];
+
+  const loggerOptions = {
+    level,
+    redact: {
+      paths: redactPaths,
+      censor: "[REDACTED]",
+    },
+    serializers: {
+      req(request) {
+        return {
+          method: request.method,
+          url: request.url,
+          hostname: request.hostname,
+          remoteAddress: request.ip,
+          remotePort: request.socket?.remotePort,
+        };
+      },
+      res(reply) {
+        return {
+          statusCode: reply.statusCode,
+        };
+      },
+      err(err) {
+        return {
+          type: err.constructor.name,
+          message: err.message,
+          stack: err.stack,
+          code: err.code,
+          statusCode: err.statusCode,
+        };
+      },
+    },
+    base: {
+      service: options.serviceName || process.env.SERVICE_NAME || "fastify-app",
+      env: process.env.NODE_ENV || "development",
+    },
+  };
+
+  // Pretty print in development
+  if (!isProd || options.pretty) {
+    loggerOptions.transport = {
+      target: "pino-pretty",
+      options: {
+        colorize: true,
+        translateTime: "HH:MM:ss",
+        ignore: "pid,hostname",
+      },
+    };
+  }
+
+  return loggerOptions;
+}
+
+export { DEFAULT_REDACT_PATHS, LOG_LEVELS };

package/test/xLogger.test.js

@@ -0,0 +1,402 @@
+/**
+ * xLogger Tests
+ *
+ * Tests for the xLogger Fastify plugin
+ */
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert";
+import Fastify from "fastify";
+import xLogger, { getLoggerOptions, DEFAULT_REDACT_PATHS, LOG_LEVELS } from "../src/xLogger.js";
+
+describe("xLogger Plugin", () => {
+  let fastify;
+
+  beforeEach(() => {
+    fastify = Fastify({
+      logger: {
+        level: "silent", // Suppress logs during tests
+      },
+    });
+  });
+
+  afterEach(async () => {
+    await fastify.close();
+  });
+
+  describe("Plugin Registration", () => {
+    test("should register successfully", async () => {
+      await fastify.register(xLogger, {});
+      await fastify.ready();
+
+      assert.ok(fastify.xlogger, "xlogger should exist");
+      assert.ok(fastify.xlogger.config, "xlogger.config should exist");
+      assert.ok(fastify.xlogger.logEvent, "xlogger.logEvent should exist");
+      assert.ok(fastify.xlogger.logBoundary, "xlogger.logBoundary should exist");
+      assert.ok(fastify.xlogger.createBoundaryLogger, "xlogger.createBoundaryLogger should exist");
+      assert.ok(fastify.xlogger.createJobContext, "xlogger.createJobContext should exist");
+      assert.ok(fastify.xlogger.extractContext, "xlogger.extractContext should exist");
+    });
+
+    test("should skip registration when active is false", async () => {
+      await fastify.register(xLogger, { active: false });
+      await fastify.ready();
+
+      assert.ok(!fastify.xlogger, "xlogger should not exist");
+    });
+
+    test("should use default redact paths", async () => {
+      await fastify.register(xLogger, {});
+      await fastify.ready();
+
+      assert.ok(fastify.xlogger.redactPaths.includes("password"));
+      assert.ok(fastify.xlogger.redactPaths.includes("token"));
+      assert.ok(fastify.xlogger.redactPaths.includes("req.headers.authorization"));
+    });
+
+    test("should extend redact paths with custom paths", async () => {
+      await fastify.register(xLogger, {
+        redactPaths: ["customSecret", "myApiKey"],
+      });
+      await fastify.ready();
+
+      assert.ok(fastify.xlogger.redactPaths.includes("password"));
+      assert.ok(fastify.xlogger.redactPaths.includes("customSecret"));
+      assert.ok(fastify.xlogger.redactPaths.includes("myApiKey"));
+    });
+
+    test("should replace redact paths when redactClobber is true", async () => {
+      await fastify.register(xLogger, {
+        redactPaths: ["onlyThis"],
+        redactClobber: true,
+      });
+      await fastify.ready();
+
+      assert.ok(!fastify.xlogger.redactPaths.includes("password"));
+      assert.ok(fastify.xlogger.redactPaths.includes("onlyThis"));
+    });
+
+    test("should store service name in config", async () => {
+      await fastify.register(xLogger, {
+        serviceName: "my-test-service",
+      });
+      await fastify.ready();
+
+      assert.strictEqual(fastify.xlogger.config.serviceName, "my-test-service");
+    });
+  });
+
+  describe("Request Context", () => {
+    test("should decorate request with contextLog", async () => {
+      await fastify.register(xLogger, {});
+
+      fastify.get("/test", async (request) => {
+        assert.ok(request.contextLog, "contextLog should exist on request");
+        return { ok: true };
+      });
+
+      await fastify.ready();
+
+      const response = await fastify.inject({
+        method: "GET",
+        url: "/test",
+      });
+
+      assert.strictEqual(response.statusCode, 200);
+    });
+
+    test("should extract context from request", async () => {
+      await fastify.register(xLogger, {});
+      let extractedContext;
+
+      fastify.get("/test", async (request) => {
+        extractedContext = fastify.xlogger.extractContext(request);
+        return { ok: true };
+      });
+
+      await fastify.ready();
+
+      await fastify.inject({
+        method: "GET",
+        url: "/test",
+      });
+
+      assert.ok(extractedContext.requestId, "requestId should exist");
+      assert.strictEqual(extractedContext.method, "GET");
+      assert.strictEqual(extractedContext.route, "/test");
+    });
+
+    test("should extract orgId from x-org-id header", async () => {
+      await fastify.register(xLogger, {});
+      let extractedContext;
+
+      fastify.get("/test", async (request) => {
+        extractedContext = fastify.xlogger.extractContext(request);
+        return { ok: true };
+      });
+
+      await fastify.ready();
+
+      await fastify.inject({
+        method: "GET",
+        url: "/test",
+        headers: {
+          "x-org-id": "org_123",
+        },
+      });
+
+      assert.strictEqual(extractedContext.orgId, "org_123");
+    });
+
+    test("should extract userId from x-user-id header", async () => {
+      await fastify.register(xLogger, {});
+      let extractedContext;
+
+      fastify.get("/test", async (request) => {
+        extractedContext = fastify.xlogger.extractContext(request);
+        return { ok: true };
+      });
+
+      await fastify.ready();
+
+      await fastify.inject({
+        method: "GET",
+        url: "/test",
+        headers: {
+          "x-user-id": "user_456",
+        },
+      });
+
+      assert.strictEqual(extractedContext.userId, "user_456");
+    });
+
+    test("should extract OpenTelemetry trace context", async () => {
+      await fastify.register(xLogger, {});
+      let extractedContext;
+
+      fastify.get("/test", async (request) => {
+        extractedContext = fastify.xlogger.extractContext(request);
+        return { ok: true };
+      });
+
+      await fastify.ready();
+
+      await fastify.inject({
+        method: "GET",
+        url: "/test",
+        headers: {
+          traceparent: "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
+        },
+      });
+
+      assert.strictEqual(extractedContext.traceId, "0af7651916cd43dd8448eb211c80319c");
+      assert.strictEqual(extractedContext.spanId, "b7ad6b7169203331");
+    });
+
+    test("should use custom context extractor", async () => {
+      await fastify.register(xLogger, {
+        contextExtractor: (request) => ({
+          customField: "custom_value",
+          fromQuery: request.query.foo,
+        }),
+      });
+      let extractedContext;
+
+      fastify.get("/test", async (request) => {
+        extractedContext = fastify.xlogger.extractContext(request);
+        return { ok: true };
+      });
+
+      await fastify.ready();
+
+      await fastify.inject({
+        method: "GET",
+        url: "/test?foo=bar",
+      });
+
+      assert.strictEqual(extractedContext.customField, "custom_value");
+      assert.strictEqual(extractedContext.fromQuery, "bar");
+    });
+  });
+
+  describe("Boundary Logging", () => {
+    test("should create boundary logger with timing", async () => {
+      await fastify.register(xLogger, {});
+      await fastify.ready();
+
+      const boundary = fastify.xlogger.createBoundaryLogger("stripe", "createCustomer");
+
+      assert.ok(boundary.success, "success method should exist");
+      assert.ok(boundary.fail, "fail method should exist");
+      assert.ok(boundary.retry, "retry method should exist");
+    });
+
+    test("should track retry count", async () => {
+      await fastify.register(xLogger, {});
+      await fastify.ready();
+
+      const boundary = fastify.xlogger.createBoundaryLogger("stripe", "createCustomer");
+
+      boundary.retry();
+      boundary.retry();
+
+      // The retry count is internal, but we can verify it doesn't throw
+      assert.doesNotThrow(() => boundary.success());
+    });
+  });
+
+  describe("Job Context", () => {
+    test("should create job context with correlation ID", async () => {
+      await fastify.register(xLogger, {});
+      await fastify.ready();
+
+      const job = fastify.xlogger.createJobContext({
+        jobName: "processPayments",
+        orgId: "org_123",
+        userId: "user_456",
+      });
+
+      assert.ok(job.context, "context should exist");
+      assert.ok(job.log, "log should exist");
+      assert.ok(job.start, "start method should exist");
+      assert.ok(job.complete, "complete method should exist");
+      assert.ok(job.fail, "fail method should exist");
+      assert.ok(job.context.correlationId, "correlationId should be generated");
+      assert.strictEqual(job.context.jobName, "processPayments");
+      assert.strictEqual(job.context.orgId, "org_123");
+      assert.strictEqual(job.context.userId, "user_456");
+    });
+
+    test("should use provided correlation ID", async () => {
+      await fastify.register(xLogger, {});
+      await fastify.ready();
+
+      const job = fastify.xlogger.createJobContext({
+        jobName: "syncData",
+        correlationId: "custom_corr_123",
+      });
+
+      assert.strictEqual(job.context.correlationId, "custom_corr_123");
+    });
+
+    test("should include original request ID", async () => {
+      await fastify.register(xLogger, {});
+      await fastify.ready();
+
+      const job = fastify.xlogger.createJobContext({
+        jobName: "asyncTask",
+        requestId: "req_789",
+      });
+
+      assert.strictEqual(job.context.originalRequestId, "req_789");
+    });
+  });
+
+  describe("Log Event", () => {
+    test("should log event without request", async () => {
+      await fastify.register(xLogger, {});
+      await fastify.ready();
+
+      // Should not throw
+      assert.doesNotThrow(() => {
+        fastify.xlogger.logEvent({
+          event: "user.created",
+          msg: "User was created",
+          data: { email: "test@example.com" },
+        });
+      });
+    });
+
+    test("should log event with different levels", async () => {
+      await fastify.register(xLogger, {});
+      await fastify.ready();
+
+      // Should not throw for different levels
+      assert.doesNotThrow(() => {
+        fastify.xlogger.logEvent({
+          event: "debug.event",
+          level: "debug",
+        });
+      });
+
+      assert.doesNotThrow(() => {
+        fastify.xlogger.logEvent({
+          event: "warn.event",
+          level: "warn",
+        });
+      });
+
+      assert.doesNotThrow(() => {
+        fastify.xlogger.logEvent({
+          event: "error.event",
+          level: "error",
+        });
+      });
+    });
+  });
+});
+
+describe("getLoggerOptions", () => {
+  test("should return valid Pino options", () => {
+    const options = getLoggerOptions();
+
+    assert.ok(options.level, "level should exist");
+    assert.ok(options.redact, "redact should exist");
+    assert.ok(options.serializers, "serializers should exist");
+    assert.ok(options.base, "base should exist");
+  });
+
+  test("should use debug level in non-production", () => {
+    const originalEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = "development";
+
+    const options = getLoggerOptions();
+
+    assert.strictEqual(options.level, "debug");
+
+    process.env.NODE_ENV = originalEnv;
+  });
+
+  test("should include pretty transport in non-production", () => {
+    const originalEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = "development";
+
+    const options = getLoggerOptions();
+
+    assert.ok(options.transport, "transport should exist");
+    assert.strictEqual(options.transport.target, "pino-pretty");
+
+    process.env.NODE_ENV = originalEnv;
+  });
+
+  test("should allow custom service name", () => {
+    const options = getLoggerOptions({ serviceName: "my-service" });
+
+    assert.strictEqual(options.base.service, "my-service");
+  });
+
+  test("should extend redact paths", () => {
+    const options = getLoggerOptions({ redactPaths: ["customPath"] });
+
+    assert.ok(options.redact.paths.includes("customPath"));
+    assert.ok(options.redact.paths.includes("password"));
+  });
+});
+
+describe("Exports", () => {
+  test("should export DEFAULT_REDACT_PATHS", () => {
+    assert.ok(Array.isArray(DEFAULT_REDACT_PATHS));
+    assert.ok(DEFAULT_REDACT_PATHS.length > 0);
+    assert.ok(DEFAULT_REDACT_PATHS.includes("password"));
+  });
+
+  test("should export LOG_LEVELS", () => {
+    assert.ok(LOG_LEVELS);
+    assert.strictEqual(LOG_LEVELS.fatal, 60);
+    assert.strictEqual(LOG_LEVELS.error, 50);
+    assert.strictEqual(LOG_LEVELS.warn, 40);
+    assert.strictEqual(LOG_LEVELS.info, 30);
+    assert.strictEqual(LOG_LEVELS.debug, 20);
+    assert.strictEqual(LOG_LEVELS.trace, 10);
+  });
+});