ref: re-org functions and exports

Author: AbhiPrasad

packages/core/src/exports.ts

@@ -1,6 +1,6 @@
 import { getClient, getCurrentScope, getIsolationScope, withIsolationScope } from './currentScopes';
 import { DEBUG_BUILD } from './debug-build';
-import { captureLog } from './log';
+import { captureLog, sendLog } from './log';
 import type { CaptureContext } from './scope';
 import { closeSession, makeSession, updateSession } from './session';
 import type {
@@ -11,6 +11,7 @@ import type {
   Extra,
   Extras,
   FinishedCheckIn,
+  LogSeverityLevel,
   MonitorConfig,
   Primitive,
   Session,
@@ -336,29 +337,60 @@ 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.
+ *
+ * @experimental Will be removed in future versions. Do not use.
  */
 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}!`
+   */
+  trace: sendLog.bind(null, 'trace') as OmitFirstArg<typeof sendLog>,
+  /**
+   * 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}!`
+   */
+  debug: sendLog.bind(null, 'debug') as OmitFirstArg<typeof sendLog>,
   /**
    * 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}!`
    */
-  info: captureLog.bind(null, 'info'),
+  info: sendLog.bind(null, 'info') as OmitFirstArg<typeof sendLog>,
   /**
    * 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}!`
    */
-  error: captureLog.bind(null, 'error'),
+  error: sendLog.bind(null, 'error') as OmitFirstArg<typeof sendLog>,
   /**
    * 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}!`
    */
-  warn: captureLog.bind(null, 'warn'),
+  warn: sendLog.bind(null, 'warn') as OmitFirstArg<typeof sendLog>,
+  /**
+   * 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}!`
+   */
+  fatal: sendLog.bind(null, 'fatal') as OmitFirstArg<typeof sendLog>,
+  /**
+   * 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.
+   */
+  captureLog,
 };

packages/core/src/log.ts

@@ -14,11 +14,12 @@ let GLOBAL_LOG_BUFFER: Log[] = [];
 let isFlushingLogs = false;
 
 const SEVERITY_TEXT_TO_SEVERITY_NUMBER: Partial<Record<LogSeverityLevel, number>> = {
-  debug: 10,
-  info: 20,
-  warning: 30,
-  error: 40,
-  critical: 50,
+  trace: 1,
+  debug: 5,
+  info: 9,
+  warn: 13,
+  error: 17,
+  fatal: 21,
 };
 
 /**
@@ -106,12 +107,36 @@ function addToLogBuffer(client: Client, log: Log, scope: Scope): void {
 }
 
 /**
- * A utility function to be able to create methods like Sentry.info`...`
+ * 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}`
  */
-export function captureLog(level: LogSeverityLevel, messages: string[] | string, ...values: unknown[]): void {
+export function sendLog(level: LogSeverityLevel, messageArr: TemplateStringsArray, ...values: unknown[]): void {
+  const message = messageArr.reduce((acc, str, i) => acc + str + (values[i] ?? ''), '');
+
+  const attributes = values.reduce<Record<string, unknown>>(
+    (acc, value, index) => {
+      acc[`param${index}`] = value;
+      return acc;
+    },
+    {
+      'sentry.template': messageArr.map((s, i) => s + (i < messageArr.length - 1 ? `$param${i}` : '')).join(''),
+    },
+  );
+
+  captureLog(level, message, attributes);
+}
+
+/**
+ * Sends a log to Sentry.
+ */
+export function captureLog(
+  level: LogSeverityLevel,
+  message: string,
+  customAttributes: Record<string, unknown> = {},
+  severityNumber?: number,
+): void {
   const client = getClient();
 
   if (!client) {
@@ -124,53 +149,37 @@ export function captureLog(level: LogSeverityLevel, messages: string[] | string,
     return;
   }
 
-  const message = Array.isArray(messages)
-    ? messages.reduce((acc, str, i) => acc + str + (values[i] ?? ''), '')
-    : messages;
-  const attributes = values.map<LogAttribute>((value, index) => valueToAttribute(`param${index}`, value));
-  if (Array.isArray(messages)) {
-    attributes.push({
-      key: 'sentry.template',
-      value: {
-        stringValue: messages.map((s, i) => s + (i < messages.length - 1 ? `$param${i}` : '')).join(''),
-      },
-    });
-  }
-
   const { release, environment } = client.getOptions();
 
+  const logAttributes = {
+    ...customAttributes,
+  };
+
   if (release) {
-    attributes.push({
-      key: 'sentry.release',
-      value: {
-        stringValue: release,
-      },
-    });
+    logAttributes['sentry.release'] = release;
   }
 
   if (environment) {
-    attributes.push({
-      key: 'sentry.environment',
-      value: {
-        stringValue: environment,
-      },
-    });
+    logAttributes['sentry.environment'] = environment;
   }
 
   const scope = getCurrentScope();
 
+  const attributes = Object.entries(logAttributes).map<LogAttribute>(([key, value]) => valueToAttribute(key, value));
+
   const log: Log = {
     severityText: level,
     body: {
       stringValue: message,
     },
-    attributes: attributes,
+    attributes,
     timeUnixNano: `${new Date().getTime().toString()}000000`,
     traceId: scope.getPropagationContext().traceId,
+    severityNumber,
   };
 
   const maybeSeverityNumber = SEVERITY_TEXT_TO_SEVERITY_NUMBER[level];
-  if (maybeSeverityNumber !== undefined) {
+  if (maybeSeverityNumber !== undefined && log.severityNumber === undefined) {
     log.severityNumber = maybeSeverityNumber;
   }
 

packages/core/src/types-hoist/log.ts

@@ -1,4 +1,4 @@
-export type LogSeverityLevel = 'trace' | 'debug' | 'info' | 'warning' | 'error' | 'fatal' | 'critical';
+export type LogSeverityLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'critical';
 
 export type LogAttributeValueType =
   | {
@@ -22,7 +22,7 @@ export type LogAttribute = {
 export interface Log {
   /**
    * Allowed values are, from highest to lowest:
-   * `critical`, `fatal`, `error`, `warning`, `info`, `debug`, `trace`.
+   * `critical`, `fatal`, `error`, `warn`, `info`, `debug`, `trace`.
    *
    * The log level changes how logs are filtered and displayed.
    * Critical level logs are emphasized more than trace level logs.