unify capture log methods

Author: AbhiPrasad

packages/node/src/log.ts

@@ -3,266 +3,221 @@ import { format } from 'node:util';
 import type { LogSeverityLevel, Log } from '@sentry/core';
 import { _INTERNAL_captureLog } from '@sentry/core';
 
+type CaptureLogArgs =
+  | [message: string, attributes?: Log['attributes']]
+  | [messageTemplate: string, messageParams: Array<unknown>, attributes?: Log['attributes']];
+
 /**
  * Capture a log with the given level.
  *
  * @param level - The level of the log.
  * @param message - The message to log.
  * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
  */
-function captureLog(level: LogSeverityLevel, message: string, attributes?: Log['attributes']): void {
-  _INTERNAL_captureLog({ level, message, attributes });
+function captureLog(level: LogSeverityLevel, ...args: CaptureLogArgs): void {
+  const [messageOrMessageTemplate, paramsOrAttributes, maybeAttributes] = args;
+  if (Array.isArray(paramsOrAttributes)) {
+    const attributes = { ...maybeAttributes };
+    attributes['sentry.message.template'] = messageOrMessageTemplate;
+    paramsOrAttributes.forEach((param, index) => {
+      attributes[`sentry.message.param.${index}`] = param;
+    });
+    const message = format(messageOrMessageTemplate, ...paramsOrAttributes);
+    _INTERNAL_captureLog({ level, message, attributes });
+  } else {
+    _INTERNAL_captureLog({ level, message: messageOrMessageTemplate, attributes: paramsOrAttributes });
+  }
 }
 
 /**
  * @summary Capture a log with the `trace` level. Requires `_experiments.enableLogs` to be enabled.
  *
- * @param message - The message to log.
- * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
+ * You can either pass a message and attributes or a message template, params and attributes.
  *
  * @example
  *
  * ```
- * Sentry.logger.trace('Hello world', { userId: 100 });
+ * Sentry.logger.trace('Starting database connection', {
+ *   database: 'users',
+ *   connectionId: 'conn_123'
+ * });
  * ```
- */
-export function trace(message: string, attributes?: Log['attributes']): void {
-  captureLog('trace', message, attributes);
-}
-
-/**
- * @summary Capture a log with the `debug` level. Requires `_experiments.enableLogs` to be enabled.
- *
- * @param message - The message to log.
- * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
  *
- * @example
+ * @example With template strings
  *
  * ```
- * Sentry.logger.debug('Hello world', { userId: 100 });
+ * Sentry.logger.trace('Database connection %s established for %s',
+ *   ['successful', 'users'],
+ *   { connectionId: 'conn_123' }
+ * );
  * ```
  */
-export function debug(message: string, attributes?: Log['attributes']): void {
-  captureLog('debug', message, attributes);
+export function trace(...args: CaptureLogArgs): void {
+  captureLog('trace', ...args);
 }
 
 /**
- * @summary Capture a log with the `info` level. Requires `_experiments.enableLogs` to be enabled.
+ * @summary Capture a log with the `debug` level. Requires `_experiments.enableLogs` to be enabled.
  *
- * @param message - The message to log.
- * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
+ * You can either pass a message and attributes or a message template, params and attributes.
  *
  * @example
  *
  * ```
- * Sentry.logger.info('Hello world', { userId: 100 });
+ * Sentry.logger.debug('Cache miss for user profile', {
+ *   userId: 'user_123',
+ *   cacheKey: 'profile:user_123'
+ * });
  * ```
- */
-export function info(message: string, attributes?: Log['attributes']): void {
-  captureLog('info', message, attributes);
-}
-
-/**
- * @summary Capture a log with the `warn` level. Requires `_experiments.enableLogs` to be enabled.
  *
- * @param message - The message to log.
- * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
- *
- * @example
+ * @example With template strings
  *
  * ```
- * Sentry.logger.warn('Hello world', { userId: 100 });
+ * Sentry.logger.debug('Cache %s for %s: %s',
+ *   ['miss', 'user profile', 'key not found'],
+ *   { userId: 'user_123' }
+ * );
  * ```
  */
-export function warn(message: string, attributes?: Log['attributes']): void {
-  captureLog('warn', message, attributes);
+export function debug(...args: CaptureLogArgs): void {
+  captureLog('debug', ...args);
 }
 
 /**
- * @summary Capture a log with the `error` level. Requires `_experiments.enableLogs` to be enabled.
+ * @summary Capture a log with the `info` level. Requires `_experiments.enableLogs` to be enabled.
  *
- * @param message - The message to log.
- * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
+ * You can either pass a message and attributes or a message template, params and attributes.
  *
  * @example
  *
  * ```
- * Sentry.logger.error('Hello world', { userId: 100 });
+ * Sentry.logger.info('User profile updated', {
+ *   userId: 'user_123',
+ *   updatedFields: ['email', 'preferences']
+ * });
  * ```
- */
-export function error(message: string, attributes?: Log['attributes']): void {
-  captureLog('error', message, attributes);
-}
-
-/**
- * @summary Capture a log with the `fatal` level. Requires `_experiments.enableLogs` to be enabled.
  *
- * @param message - The message to log.
- * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
- *
- * @example
+ * @example With template strings
  *
  * ```
- * Sentry.logger.fatal('Hello world', { userId: 100 });
+ * Sentry.logger.info('User %s updated their %s',
+ *   ['John Doe', 'profile settings'],
+ *   { userId: 'user_123' }
+ * );
  * ```
  */
-export function fatal(message: string, attributes?: Log['attributes']): void {
-  captureLog('fatal', message, attributes);
+export function info(...args: CaptureLogArgs): void {
+  captureLog('info', ...args);
 }
 
 /**
- * @summary Capture a log with the `critical` level. Requires `_experiments.enableLogs` to be enabled.
+ * @summary Capture a log with the `warn` level. Requires `_experiments.enableLogs` to be enabled.
  *
- * @param message - The message to log.
- * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
+ * You can either pass a message and attributes or a message template, params and attributes.
  *
  * @example
  *
  * ```
- * Sentry.logger.critical('Hello world', { userId: 100 });
+ * Sentry.logger.warn('Rate limit approaching', {
+ *   endpoint: '/api/users',
+ *   currentRate: '95/100',
+ *   resetTime: '2024-03-20T10:00:00Z'
+ * });
  * ```
- */
-export function critical(message: string, attributes?: Log['attributes']): void {
-  captureLog('critical', message, attributes);
-}
-
-/**
- * Capture a formatted log with the given level.
- *
- * @param level - The level of the log.
- * @param message - The message template.
- * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
- */
-function captureLogFmt(
-  level: LogSeverityLevel,
-  messageTemplate: string,
-  params: Array<unknown>,
-  logAttributes: Log['attributes'] = {},
-): void {
-  const attributes = { ...logAttributes };
-  attributes['sentry.message.template'] = messageTemplate;
-  params.forEach((param, index) => {
-    attributes[`sentry.message.param.${index}`] = param;
-  });
-  const message = format(messageTemplate, ...params);
-  _INTERNAL_captureLog({ level, message, attributes });
-}
-
-/**
- * @summary Capture a formatted log with the `trace` level. Requires `_experiments.enableLogs` to be enabled.
- *
- * @param message - The message to log.
- * @param params - The parameters to interpolate into the message.
- * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
  *
- * @example
+ * @example With template strings
  *
  * ```
- * Sentry.logger.traceFmt('Hello world %s', ['foo'], { userId: 100 });
+ * Sentry.logger.warn('Rate limit %s for %s: %s',
+ *   ['approaching', '/api/users', '95/100 requests'],
+ *   { resetTime: '2024-03-20T10:00:00Z' }
+ * );
  * ```
  */
-export function traceFmt(message: string, params: Array<unknown>, attributes: Log['attributes'] = {}): void {
-  captureLogFmt('trace', message, params, attributes);
+export function warn(...args: CaptureLogArgs): void {
+  captureLog('warn', ...args);
 }
 
 /**
- * @summary Capture a formatted log with the `debug` level. Requires `_experiments.enableLogs` to be enabled.
+ * @summary Capture a log with the `error` level. Requires `_experiments.enableLogs` to be enabled.
  *
- * @param message - The message to log.
- * @param params - The parameters to interpolate into the message.
- * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
+ * You can either pass a message and attributes or a message template, params and attributes.
  *
  * @example
  *
  * ```
- * Sentry.logger.debugFmt('Hello world %s', ['foo'], { userId: 100 });
+ * Sentry.logger.error('Failed to process payment', {
+ *   orderId: 'order_123',
+ *   errorCode: 'PAYMENT_FAILED',
+ *   amount: 99.99
+ * });
  * ```
- */
-export function debugFmt(message: string, params: Array<unknown>, attributes: Log['attributes'] = {}): void {
-  captureLogFmt('debug', message, params, attributes);
-}
-
-/**
- * @summary Capture a formatted log with the `info` level. Requires `_experiments.enableLogs` to be enabled.
  *
- * @param message - The message to log.
- * @param params - The parameters to interpolate into the message.
- * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
- *
- * @example
+ * @example With template strings
  *
  * ```
- * Sentry.logger.infoFmt('Hello world %s', ['foo'], { userId: 100 });
+ * Sentry.logger.error('Payment processing failed for order %s: %s',
+ *   ['order_123', 'insufficient funds'],
+ *   { amount: 99.99 }
+ * );
  * ```
  */
-export function infoFmt(message: string, params: Array<unknown>, attributes?: Log['attributes']): void {
-  captureLogFmt('info', message, params, attributes);
+export function error(...args: CaptureLogArgs): void {
+  captureLog('error', ...args);
 }
 
 /**
- * @summary Capture a formatted log with the `warn` level. Requires `_experiments.enableLogs` to be enabled.
+ * @summary Capture a log with the `fatal` level. Requires `_experiments.enableLogs` to be enabled.
  *
- * @param message - The message to log.
- * @param params - The parameters to interpolate into the message.
- * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
+ * You can either pass a message and attributes or a message template, params and attributes.
  *
  * @example
  *
  * ```
- * Sentry.logger.warnFmt('Hello world %s', ['foo'], { userId: 100 });
+ * Sentry.logger.fatal('Database connection pool exhausted', {
+ *   database: 'users',
+ *   activeConnections: 100,
+ *   maxConnections: 100
+ * });
  * ```
- */
-export function warnFmt(message: string, params: Array<unknown>, attributes?: Log['attributes']): void {
-  captureLogFmt('warn', message, params, attributes);
-}
-
-/**
- * @summary Capture a formatted log with the `error` level. Requires `_experiments.enableLogs` to be enabled.
  *
- * @param message - The message to log.
- * @param params - The parameters to interpolate into the message.
- * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
- *
- * @example
+ * @example With template strings
  *
  * ```
- * Sentry.logger.errorFmt('Hello world %s', ['foo'], { userId: 100 });
+ * Sentry.logger.fatal('Database %s: %s connections active',
+ *   ['connection pool exhausted', '100/100'],
+ *   { database: 'users' }
+ * );
  * ```
  */
-export function errorFmt(message: string, params: Array<unknown>, attributes?: Log['attributes']): void {
-  captureLogFmt('error', message, params, attributes);
+export function fatal(...args: CaptureLogArgs): void {
+  captureLog('fatal', ...args);
 }
 
 /**
- * @summary Capture a formatted log with the `fatal` level. Requires `_experiments.enableLogs` to be enabled.
+ * @summary Capture a log with the `critical` level. Requires `_experiments.enableLogs` to be enabled.
  *
- * @param message - The message to log.
- * @param params - The parameters to interpolate into the message.
- * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
+ * You can either pass a message and attributes or a message template, params and attributes.
  *
  * @example
  *
  * ```
- * Sentry.logger.fatalFmt('Hello world %s', ['foo'], { userId: 100 });
+ * Sentry.logger.critical('Service health check failed', {
+ *   service: 'payment-gateway',
+ *   status: 'DOWN',
+ *   lastHealthy: '2024-03-20T09:55:00Z'
+ * });
  * ```
- */
-export function fatalFmt(message: string, params: Array<unknown>, attributes?: Log['attributes']): void {
-  captureLogFmt('fatal', message, params, attributes);
-}
-
-/**
- * @summary Capture a formatted log with the `critical` level. Requires `_experiments.enableLogs` to be enabled.
  *
- * @param message - The message to log.
- * @param params - The parameters to interpolate into the message.
- * @param attributes - Arbitrary structured data that stores information about the log - e.g., userId: 100.
- *
- * @example
+ * @example With template strings
  *
  * ```
- * Sentry.logger.criticalFmt('Hello world %s', ['foo'], { userId: 100 });
+ * Sentry.logger.critical('Service %s is %s',
+ *   ['payment-gateway', 'DOWN'],
+ *   { lastHealthy: '2024-03-20T09:55:00Z' }
+ * );
  * ```
  */
-export function criticalFmt(message: string, params: Array<unknown>, attributes?: Log['attributes']): void {
-  captureLogFmt('critical', message, params, attributes);
+export function critical(...args: CaptureLogArgs): void {
+  captureLog('critical', ...args);
 }