ref: introduce format function and restructure exports

Author: AbhiPrasad

packages/core/src/exports.ts

@@ -11,7 +11,6 @@ import type {
   Extra,
   Extras,
   FinishedCheckIn,
-  LogSeverityLevel,
   MonitorConfig,
   Primitive,
   Session,
@@ -24,6 +23,7 @@ import { logger } from './utils-hoist/logger';
 import { uuid4 } from './utils-hoist/misc';
 import { timestampInSeconds } from './utils-hoist/time';
 import { GLOBAL_OBJ } from './utils-hoist/worldwide';
+import { parameterize } from './utils/parameterize';
 import type { ExclusiveEventHintOrCaptureContext } from './utils/prepareEvent';
 import { parseEventHintOrCaptureContext } from './utils/prepareEvent';
 
@@ -337,8 +337,6 @@ export function captureSession(end: boolean = false): void {
   _sendSessionUpdate();
 }
 
-type OmitFirstArg<F> = F extends (x: LogSeverityLevel, ...args: infer P) => infer R ? (...args: P) => R : never;
-
 /**
  * A namespace for experimental logging functions.
  *
@@ -349,55 +347,106 @@ export const _experiment_log = {
    * A utility to record a log with level 'TRACE' and send it to sentry.
    *
    * Logs represent a message and some parameters which provide context for a trace or error.
-   * Ex: Sentry._experiment_log.trace`user ${username} just bought ${item}!`
+   *
+   * @example
+   * ```js
+   * const { trace, fmt } = Sentry._experiment_log;
+   * trace(fmt`user ${username} just bought ${item}!`);
+   * ```
    */
-  trace: sendLog.bind(null, 'trace') as OmitFirstArg<typeof sendLog>,
+  trace: sendLog('trace'),
   /**
    * A utility to record a log with level 'DEBUG' and send it to sentry.
    *
    * Logs represent a message and some parameters which provide context for a trace or error.
-   * Ex: Sentry._experiment_log.debug`user ${username} just bought ${item}!`
+   *
+   * @example
+   * ```js
+   * const { debug, fmt } = Sentry._experiment_log;
+   * debug(fmt`user ${username} just bought ${item}!`);
+   * ```
    */
-  debug: sendLog.bind(null, 'debug') as OmitFirstArg<typeof sendLog>,
+  debug: sendLog('debug'),
   /**
    * A utility to record a log with level 'INFO' and send it to sentry.
    *
    * Logs represent a message and some parameters which provide context for a trace or error.
-   * Ex: Sentry._experiment_log.info`user ${username} just bought ${item}!`
+   *
+   * @example
+   * ```js
+   * const { info, fmt } = Sentry._experiment_log;
+   * info(fmt`user ${username} just bought ${item}!`);
+   * ```
    */
-  info: sendLog.bind(null, 'info') as OmitFirstArg<typeof sendLog>,
+  info: sendLog('info'),
   /**
    * A utility to record a log with level 'INFO' and send it to sentry.
    *
    * Logs represent a message and some parameters which provide context for a trace or error.
-   * Ex: Sentry._experiment_log.log`user ${username} just bought ${item}!`
+   *
+   * @example
+   * ```js
+   * const { log, fmt } = Sentry._experiment_log;
+   * log(fmt`user ${username} just bought ${item}!`);
+   * ```
    */
-  log: sendLog.bind(null, 'log') as OmitFirstArg<typeof sendLog>,
+  log: sendLog('info', 10),
   /**
    * A utility to record a log with level 'ERROR' and send it to sentry.
    *
    * Logs represent a message and some parameters which provide context for a trace or error.
-   * Ex: Sentry._experiment_log.error`user ${username} just bought ${item}!`
+   *
+   * @example
+   * ```js
+   * const { error, fmt } = Sentry._experiment_log;
+   * error(fmt`user ${username} just bought ${item}!`);
+   * ```
    */
-  error: sendLog.bind(null, 'error') as OmitFirstArg<typeof sendLog>,
+  error: sendLog('error'),
   /**
    * A utility to record a log with level 'WARN' and send it to sentry.
    *
    * Logs represent a message and some parameters which provide context for a trace or error.
-   * Ex: Sentry._experiment_log.warn`user ${username} just bought ${item}!`
+   *
+   * @example
+   * ```js
+   * const { warn, fmt } = Sentry._experiment_log;
+   * warn(fmt`user ${username} just bought ${item}!`);
+   * ```
    */
-  warn: sendLog.bind(null, 'warn') as OmitFirstArg<typeof sendLog>,
+  warn: sendLog('warn'),
   /**
    * A utility to record a log with level 'FATAL' and send it to sentry.
    *
    * Logs represent a message and some parameters which provide context for a trace or error.
-   * Ex: Sentry._experiment_log.warn`user ${username} just bought ${item}!`
+   *
+   * @example
+   * ```js
+   * const { fatal, fmt } = Sentry._experiment_log;
+   * fatal(fmt`user ${username} just bought ${item}!`);
+   * ```
    */
-  fatal: sendLog.bind(null, 'fatal') as OmitFirstArg<typeof sendLog>,
+  fatal: sendLog('fatal'),
+
+  /**
+   * Tagged template function which returns parameterized representation of the message
+   *
+   * @example
+   * ```js
+   * Sentry._experiment_log.fmt`This is a log statement with ${x} and ${y} params`
+   * ```
+   */
+  fmt: parameterize,
+
   /**
    * A flexible utility to record a log with a custom level and send it to sentry.
    *
    * You can optionally pass in custom attributes and a custom severity number to be attached to the log.
+   *
+   * @example
+   * ```js
+   * Sentry._experiment_log.emit({ level: 'info', message: Sentry._experiment_log.fmt`user ${username }just bought ${item}`, attributes: { extra: 123 } })
+   * ```
    */
-  captureLog,
+  emit: captureLog,
 };

packages/core/src/log.ts

@@ -3,9 +3,10 @@ import { getClient, getCurrentScope } from './currentScopes';
 import { DEBUG_BUILD } from './debug-build';
 import type { Scope } from './scope';
 import { getDynamicSamplingContextFromScope } from './tracing';
+import type { ParameterizedString } from './types-hoist';
 import type { DynamicSamplingContext, LogEnvelope, LogItem } from './types-hoist/envelope';
 import type { Log, LogAttribute, LogSeverityLevel } from './types-hoist/log';
-import { createEnvelope, dropUndefinedKeys, dsnToString, logger } from './utils-hoist';
+import { createEnvelope, dropUndefinedKeys, dsnToString, isParameterizedString, logger } from './utils-hoist';
 
 const LOG_BUFFER_MAX_LENGTH = 25;
 
@@ -108,36 +109,30 @@ function addToLogBuffer(client: Client, log: Log, scope: Scope): void {
 }
 
 /**
- * A utility function to be able to create methods like Sentry.info`...` that use tagged template functions.
- *
- * The first parameter is bound with, e.g., const info = captureLog.bind(null, 'info')
- * The other parameters are in the format to be passed a tagged template, Sentry.info`hello ${world}`
+ * A utility function to be able to create methods like Sentry.info(...).
  */
-export function sendLog(level: LogSeverityLevel, messageArr: TemplateStringsArray, ...values: unknown[]): void {
-  const message = messageArr.reduce((acc, str, i) => acc + str + (JSON.stringify(values[i]) ?? ''), '');
-
-  const attributes = values.reduce<Record<string, unknown>>(
-    (acc, value, index) => {
-      acc[`sentry.message.parameters.${index}`] = value;
-      return acc;
-    },
-    {
-      'sentry.message.template': messageArr.map((s, i) => s + (i < messageArr.length - 1 ? `$param.${i}` : '')).join(''),
-    },
-  );
-
-  captureLog(level, message, attributes);
+export function sendLog(
+  level: LogSeverityLevel,
+  severityNumber?: number,
+): (message: ParameterizedString | string, customAttributes?: Record<string, unknown>) => void {
+  return (message: ParameterizedString | string, attributes: Record<string, unknown> = {}): void =>
+    captureLog({ level, message, attributes, severityNumber });
 }
 
 /**
  * Sends a log to Sentry.
  */
-export function captureLog(
-  level: LogSeverityLevel,
-  message: string,
-  customAttributes: Record<string, unknown> = {},
-  severityNumber?: number,
-): void {
+export function captureLog({
+  level,
+  message,
+  attributes,
+  severityNumber,
+}: {
+  level: LogSeverityLevel;
+  message: ParameterizedString | string;
+  attributes?: Record<string, unknown>;
+  severityNumber?: number;
+}): void {
   const client = getClient();
 
   if (!client) {
@@ -153,9 +148,19 @@ export function captureLog(
   const { release, environment } = client.getOptions();
 
   const logAttributes = {
-    ...customAttributes,
+    ...attributes,
   };
 
+  if (isParameterizedString(message)) {
+    const { __sentry_template_string__ = '', __sentry_template_values__ = [] } = message;
+    if (__sentry_template_string__) {
+      logAttributes['sentry.message.template'] = __sentry_template_string__;
+      __sentry_template_values__.forEach((value, index) => {
+        logAttributes[`sentry.message.parameters.${index}`] = value;
+      });
+    }
+  }
+
   if (release) {
     logAttributes['sentry.release'] = release;
   }
@@ -166,14 +171,16 @@ export function captureLog(
 
   const scope = getCurrentScope();
 
-  const attributes = Object.entries(logAttributes).map<LogAttribute>(([key, value]) => valueToAttribute(key, value));
+  const finalAttributes = Object.entries(logAttributes).map<LogAttribute>(([key, value]) =>
+    valueToAttribute(key, value),
+  );
 
   const log: Log = {
     severityText: level,
     body: {
       stringValue: message,
     },
-    attributes,
+    attributes: finalAttributes,
     timeUnixNano: `${new Date().getTime().toString()}000000`,
     traceId: scope.getPropagationContext().traceId,
     severityNumber,