feat(log): add transports support from private impl

Author: shellscape

.eslintignore

@@ -1,2 +1,4 @@
 **/dist
 **/bin
+
+packages/log/recipes

packages/log/recipes/README.md

@@ -0,0 +1,22 @@
+# @dot/log Recipes
+
+This directory contains recipes for extending @dot/log with additional transports and functionality.
+
+## Available Recipes
+
+- [Better Stack Transport](./better-stack.ts) - Integration with Better Stack logging service
+- [Sentry Transport](./sentry.ts) - Integration with Sentry error tracking and performance monitoring
+
+Each recipe provides a custom Transport implementation that can be used with @dot/log to send logs to additional services beyond the default console output.
+
+To use a recipe, import the transport class and add it to the transports array when creating a logger:
+
+```ts
+import { getLog } from '@dot/log';
+import { SentryTransport } from '@dot/log/recipes/sentry';
+
+const log = getLog({
+  name: 'my-app',
+  transports: [new SentryTransport()]
+});
+```

packages/log/recipes/better-stack.ts

@@ -0,0 +1,51 @@
+import { Logtail } from '@logtail/node';
+import type { StackContextHint } from '@logtail/types';
+import type { MethodFactoryLevels } from 'loglevelnext';
+
+import { Transport, type LogMethodOptions, type SendLogOptions } from '@dot/log';
+
+const stackContextHint = {
+  fileName: '@rally/log/transports/server/better-stack',
+  methodNames: ['log', 'error', 'warn', 'info', 'http', 'verbose', 'debug', 'silly']
+} satisfies StackContextHint;
+const { warn } = console;
+
+export class BetterStackTransport extends Transport {
+  private logtail: Logtail | undefined = void 0;
+
+  constructor() {
+    super();
+
+    const { BETTERSTACK_TOKEN, DISABLE_BETTERSTACK, RALLY_LOG_LEVEL } = process.env as Record<
+      string,
+      string
+    >;
+    const logLevel = RALLY_LOG_LEVEL as MethodFactoryLevels;
+
+    if (!BETTERSTACK_TOKEN || !!DISABLE_BETTERSTACK) {
+      if (logLevel === 'debug' || logLevel === 'trace') {
+        if (DISABLE_BETTERSTACK)
+          warn(`@rally/log → betterstack: disabled by way of the DISABLE_BETTERSTACK envar`);
+      }
+      return;
+    }
+
+    this.logtail = new Logtail(BETTERSTACK_TOKEN);
+  }
+
+  send({ args, methodName }: SendLogOptions) {
+    if (!this.logtail) return;
+
+    let data = { rallyEnv: process.env.DEPLOY_ENV };
+    const [message, ...rest] = args;
+    const [maybeOptions] = rest.slice(-1) as LogMethodOptions[];
+
+    if (maybeOptions?.data) {
+      data = { ...data, ...maybeOptions.data };
+      rest.pop();
+    }
+
+    this.logtail.log(message, methodName, data, stackContextHint);
+    this.logtail.flush();
+  }
+}

packages/log/recipes/sentry.ts

@@ -0,0 +1,110 @@
+import type { default as SentryType, Event, Scope } from '@sentry/node';
+import type { MethodFactoryLevels } from 'loglevelnext';
+
+import { Transport, type LogMethodOptions, type SendLogOptions } from '@dot/log';
+
+interface ReportOptions {
+  args: any[];
+  methodName: string;
+  sentryInstance: Promise<typeof SentryType | undefined>;
+}
+
+const { warn } = console;
+const appEnv: Record<string, string> = {
+  default: 'unknown',
+  development: 'dev',
+  production: 'prod',
+  test: 'test'
+};
+const isLambda = Boolean(process.env.AWS_LAMBDA_FUNCTION_NAME);
+
+const initSentry = async () => {
+  if (typeof process === 'undefined') return void 0;
+
+  const {
+    DISABLE_SENTRY,
+    NODE_ENV,
+    RALLY_LOG_LEVEL,
+    SENTRY_DSN,
+    SENTRY_MODULE,
+    SENTRY_SAMPLE_RATE
+  } = process.env as Record<string, string>;
+  const logLevel = RALLY_LOG_LEVEL as MethodFactoryLevels;
+
+  if (!SENTRY_DSN || !!DISABLE_SENTRY) {
+    if (logLevel === 'debug' || logLevel === 'trace') {
+      if (DISABLE_SENTRY) warn(`@rally/log → sentry: disabled by way of the DISABLE_SENTRY envar`);
+    }
+    return void 0;
+  }
+
+  const dsn = SENTRY_DSN;
+  const enabled = ['prod', 'production'].includes(NODE_ENV);
+  const environment = appEnv[NODE_ENV || 'default'];
+  const moduleName = SENTRY_MODULE;
+  const sampleRate = parseFloat(SENTRY_SAMPLE_RATE || '1');
+
+  const { default: Sentry } = await import('@sentry/node');
+  const beforeSend = ((event: Event) => {
+    return { ...event, tags: { module: moduleName, ...event.tags } };
+  }) as any;
+  const initMethod = isLambda ? Sentry.initWithoutDefaultIntegrations : Sentry.init;
+
+  initMethod({
+    attachStacktrace: true,
+    beforeSend,
+    dsn,
+    enabled,
+    environment,
+    sampleRate
+  });
+
+  return Sentry;
+};
+
+const report = async (options: ReportOptions) => {
+  const { args, methodName, sentryInstance } = options;
+
+  const tags = { rallyEnv: process.env.DEPLOY_ENV };
+  const [message, ...rest] = args;
+  const [maybeOptions] = rest.slice(-1) as LogMethodOptions[];
+  const event: Event = { extra: { args: rest }, message, tags };
+  const sentry = await sentryInstance;
+
+  if (!sentry) return;
+
+  if (maybeOptions && maybeOptions.data) {
+    event.tags = { ...maybeOptions.data };
+    rest.pop();
+  }
+
+  if (methodName === 'warn') {
+    sentry.captureEvent({ level: 'warning', ...event });
+  } else if (methodName === 'error') {
+    sentry.withScope((scope: Scope) => {
+      scope.setExtras(event as any);
+      scope.setLevel('error');
+      scope.setTags({ message, ...event.tags });
+
+      // Note: The typing in @sentry/types is incorrect: https://github.com/getsentry/sentry-javascript/issues/5764
+      // We need to assert that this is a truthy value
+      if (message) sentry.captureException(message);
+      else warn('@sa/log → sentry: message was falsy:', event);
+    });
+  }
+};
+
+export class SentryTransport extends Transport {
+  private sentryInstance: Promise<typeof SentryType | undefined> | undefined = void 0;
+
+  constructor() {
+    super();
+
+    this.sentryInstance = initSentry();
+  }
+
+  send({ args, methodName }: SendLogOptions) {
+    if (!this.sentryInstance) return;
+    report({ args, methodName, sentryInstance: this.sentryInstance });
+  }
+}

packages/log/src/LogFactory.ts

@@ -1,20 +1,43 @@
-import { PrefixFactory, PrefixFactoryOptions } from 'loglevelnext';
-import { DeferredPromise } from 'p-defer';
+import type { PrefixFactoryOptions } from 'loglevelnext';
+import { PrefixFactory } from 'loglevelnext';
+import type { DeferredPromise } from 'p-defer';
+
+import type { Transport } from './Transport';
 
 interface FactoryOptions {
   ready: DeferredPromise<unknown>;
+  transports?: Transport[];
 }
 
+export type LogMethodArgs = [string, ...unknown[]];
+
+const NOOP = '() => { }';
+
 export class LogFactory extends PrefixFactory {
   private readonly ready: DeferredPromise<unknown>;
+  private readonly transports: Transport[];
 
   constructor(options: PrefixFactoryOptions & FactoryOptions) {
     super(void 0, options);
 
     this.ready = options.ready;
+    this.transports = options.transports || [];
+  }
+
+  override make(methodName: any) {
+    const og = super.make(methodName);
+    return (...args: LogMethodArgs) => {
+      // is the method a noop?
+      if (og.toString() !== NOOP) {
+        this.transports.forEach((transport) => transport.send({ args, methodName }));
+      }
+
+      // call the original method and output to console
+      og(...args);
+    };
   }
 
-  replaceMethods(level: number | string) {
+  override replaceMethods(level: number | string) {
     super.replaceMethods(level);
     this.ready?.resolve();
   }

packages/log/src/Transport.ts

@@ -0,0 +1,14 @@
+import type { MethodFactoryLevels } from 'loglevelnext';
+
+export interface LogMethodOptions {
+  data: Record<string, string | number>;
+}
+
+export interface SendLogOptions {
+  args: [string, ...unknown[]];
+  methodName: MethodFactoryLevels;
+}
+
+export abstract class Transport {
+  abstract send(options: SendLogOptions): void;
+}

packages/log/src/index.ts

@@ -3,14 +3,16 @@ import loglevel, { MethodFactoryLevels } from 'loglevelnext';
 import defer from 'p-defer';
 
 import { LogFactory } from './LogFactory';
+import { type Transport } from './Transport';
 
 export type { MethodFactoryLevels };
-
+export * from './Transport';
 export { LogFactory };
 
 export interface LogOptions {
   brand?: string;
   name: string;
+  transports?: Transport[];
 }
 
 type LogIndex = {
@@ -52,12 +54,13 @@ export const getLog = (opts?: LogOptions) => {
     level: ({ level }: { level: string }) => colors[level],
     ready,
     template,
-    time: () => new Date().toTimeString().split(' ')[0]
+    time: () => new Date().toTimeString().split(' ')[0],
+    transports: options.transports
   } as any);
   const { DOT_LOG_LEVEL = 'info' } = typeof process === 'undefined' ? defaultEnv : process.env;
   const logOptions = {
     factory,
-    level: DOT_LOG_LEVEL,
+    level: DOT_LOG_LEVEL || 'info',
     name: `dot-log:${options.name}`
   };
 

shared/tsconfig.base.json

@@ -22,5 +22,5 @@
     "target": "es2020",
     "useUnknownInCatchVariables": false
   },
-  "exclude": ["dist", "node_modules"]
+  "exclude": ["dist", "node_modules", "**/recipes"]
 }