@xenterprises/fastify-xlogger 1.0.0 → 1.1.1

package/README.md

@@ -226,6 +226,91 @@ const options = getLoggerOptions();
 const options = getLoggerOptions({ pretty: true });
 ```
 
+### 7. Custom Transports (Betterstack, Logtail, etc.)
+
+Send logs to centralized logging services like Betterstack/Logtail using custom transports:
+
+#### Install Transport (Optional Peer Dependency)
+
+```bash
+npm install @logtail/pino
+```
+
+#### Single Transport (Betterstack)
+
+```javascript
+import Fastify from "fastify";
+import xLogger, { getLoggerOptions } from "xlogger";
+
+const fastify = Fastify({
+  logger: getLoggerOptions({
+    serviceName: "my-api",
+    transport: {
+      target: "@logtail/pino",
+      options: {
+        sourceToken: process.env.BETTERSTACK_SOURCE_TOKEN,
+      },
+    },
+  }),
+});
+
+await fastify.register(xLogger, {
+  serviceName: "my-api",
+});
+```
+
+#### Multiple Transports
+
+Send logs to both Betterstack and a local file:
+
+```javascript
+const fastify = Fastify({
+  logger: getLoggerOptions({
+    serviceName: "my-api",
+    transport: {
+      targets: [
+        {
+          target: "@logtail/pino",
+          options: {
+            sourceToken: process.env.BETTERSTACK_SOURCE_TOKEN,
+          },
+        },
+        {
+          target: "pino/file",
+          options: {
+            destination: "/var/log/app.log",
+          },
+        },
+      ],
+    },
+  }),
+});
+```
+
+#### Environment-Based Configuration
+
+```javascript
+// In development: use pino-pretty (default)
+// In production: use Betterstack if token is set, otherwise JSON stdout
+const transport = process.env.BETTERSTACK_SOURCE_TOKEN
+  ? {
+      target: "@logtail/pino",
+      options: {
+        sourceToken: process.env.BETTERSTACK_SOURCE_TOKEN,
+      },
+    }
+  : undefined;
+
+const fastify = Fastify({
+  logger: getLoggerOptions({
+    serviceName: "my-api",
+    transport,
+  }),
+});
+```
+
+**Note**: When a custom transport is provided, it overrides the default environment-based transport configuration (pino-pretty in development, JSON in production).
+
 ## API Reference
 
 ### Decorators
@@ -320,6 +405,12 @@ const fastify = Fastify({
     serviceName: "my-api",    // Optional: service name
     redactPaths: ["custom"],  // Optional: additional redact paths
     pretty: false,            // Optional: force pretty printing
+    transport: {              // Optional: custom transport configuration
+      target: "@logtail/pino",
+      options: {
+        sourceToken: process.env.BETTERSTACK_SOURCE_TOKEN,
+      },
+    },
   }),
 });
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenterprises/fastify-xlogger",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Fastify plugin for standardized logging with Pino - context, redaction, and canonical schema",
   "type": "module",
   "main": "src/xLogger.js",
@@ -30,7 +30,13 @@
     "fastify-plugin": "^5.0.1"
   },
   "peerDependencies": {
-    "fastify": "^5.0.0"
+    "fastify": "^5.0.0",
+    "@logtail/pino": "^0.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@logtail/pino": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "eslint": "^9.0.0",

package/src/xLogger.js

@@ -399,6 +399,10 @@ export default fp(xLogger, {
  * @param {string[]} [options.redactPaths] - Additional paths to redact
  * @param {boolean} [options.pretty] - Force pretty printing
  * @param {string} [options.serviceName] - Service name
+ * @param {Object} [options.transport] - Custom Pino transport configuration
+ * @param {string} [options.transport.target] - Transport target module (e.g., '@logtail/pino')
+ * @param {Object} [options.transport.options] - Transport options
+ * @param {Array} [options.transport.targets] - Multiple transport targets
  * @returns {Object} Pino logger options
  */
 export function getLoggerOptions(options = {}) {
@@ -444,8 +448,12 @@ export function getLoggerOptions(options = {}) {
     },
   };
 
-  // Pretty print in development
-  if (!isProd || options.pretty) {
+  // If custom transport is provided, use it
+  if (options.transport) {
+    loggerOptions.transport = options.transport;
+  }
+  // Otherwise, use pretty print in development
+  else if (!isProd || options.pretty) {
     loggerOptions.transport = {
       target: "pino-pretty",
       options: {

package/test/xLogger.test.js

@@ -1,402 +0,0 @@
-/**
- * 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);
-  });
-});