feat(utils): Add parameterize function

packages/browser-integration-tests/suites/public-api/captureMessage/parameterized_message/subject.js

@@ -0,0 +1,6 @@
+import { parameterize } from '@sentry/utils';
+
+const x = 'first';
+const y = 'second';
+
+Sentry.captureMessage(parameterize`This is a log statement with ${x} and ${y} params`);

packages/browser-integration-tests/suites/public-api/captureMessage/parameterized_message/test.ts

@@ -0,0 +1,16 @@
+import { expect } from '@playwright/test';
+import type { Event } from '@sentry/types';
+
+import { sentryTest } from '../../../../utils/fixtures';
+import { getFirstSentryEnvelopeRequest } from '../../../../utils/helpers';
+
+sentryTest('should capture a parameterized representation of the message', async ({ getLocalTestPath, page }) => {
+  const url = await getLocalTestPath({ testDir: __dirname });
+
+  const eventData = await getFirstSentryEnvelopeRequest<Event>(page, url);
+
+  expect(eventData.logentry).toStrictEqual({
+    message: 'This is a log statement with %s and %s params',
+    params: ['first', 'second'],
+  });
+});

packages/browser/src/client.ts

@@ -7,6 +7,7 @@ import type {
   Event,
   EventHint,
   Options,
+  ParameterizedString,
   Severity,
   SeverityLevel,
   UserFeedback,
@@ -84,7 +85,7 @@ export class BrowserClient extends BaseClient<BrowserClientOptions> {
    * @inheritDoc
    */
   public eventFromMessage(
-    message: string,
+    message: ParameterizedString,
     // eslint-disable-next-line deprecation/deprecation
     level: Severity | SeverityLevel = 'info',
     hint?: EventHint,

packages/browser/src/eventbuilder.ts

@@ -1,5 +1,14 @@
 import { getCurrentHub } from '@sentry/core';
-import type { Event, EventHint, Exception, Severity, SeverityLevel, StackFrame, StackParser } from '@sentry/types';
+import type {
+  Event,
+  EventHint,
+  Exception,
+  ParameterizedString,
+  Severity,
+  SeverityLevel,
+  StackFrame,
+  StackParser,
+} from '@sentry/types';
 import {
   addExceptionMechanism,
   addExceptionTypeValue,
@@ -9,6 +18,7 @@ import {
   isError,
   isErrorEvent,
   isEvent,
+  isParameterizedString,
   isPlainObject,
   normalizeToSize,
   resolvedSyncPromise,
@@ -168,7 +178,7 @@ export function eventFromException(
  */
 export function eventFromMessage(
   stackParser: StackParser,
-  message: string,
+  message: ParameterizedString,
   // eslint-disable-next-line deprecation/deprecation
   level: Severity | SeverityLevel = 'info',
   hint?: EventHint,
@@ -265,23 +275,32 @@ export function eventFromUnknownInput(
  */
 export function eventFromString(
   stackParser: StackParser,
-  input: string,
+  message: ParameterizedString,
   syntheticException?: Error,
   attachStacktrace?: boolean,
 ): Event {
-  const event: Event = {
-    message: input,
-  };
+  const event: Event = {};
 
   if (attachStacktrace && syntheticException) {
     const frames = parseStackFrames(stackParser, syntheticException);
     if (frames.length) {
       event.exception = {
-        values: [{ value: input, stacktrace: { frames } }],
+        values: [{ value: message, stacktrace: { frames } }],
       };
     }
   }
 
+  if (isParameterizedString(message)) {
+    const { __sentry_template_string__, __sentry_template_values__ } = message;
+
+    event.logentry = {
+      message: __sentry_template_string__,
+      params: __sentry_template_values__,
+    };
+    return event;
+  }
+
+  event.message = message;
   return event;
 }
 

packages/core/src/baseclient.ts

@@ -17,6 +17,7 @@ import type {
   Integration,
   IntegrationClass,
   Outcome,
+  ParameterizedString,
   PropagationContext,
   SdkMetadata,
   Session,
@@ -34,6 +35,7 @@ import {
   addItemToEnvelope,
   checkOrSetAlreadyCaught,
   createAttachmentEnvelopeItem,
+  isParameterizedString,
   isPlainObject,
   isPrimitive,
   isThenable,
@@ -170,16 +172,18 @@ export abstract class BaseClient<O extends ClientOptions> implements Client<O> {
    * @inheritDoc
    */
   public captureMessage(
-    message: string,
+    message: ParameterizedString,
     // eslint-disable-next-line deprecation/deprecation
     level?: Severity | SeverityLevel,
     hint?: EventHint,
     scope?: Scope,
   ): string | undefined {
     let eventId: string | undefined = hint && hint.event_id;
 
+    const eventMessage = isParameterizedString(message) ? message : String(message);
+
     const promisedEvent = isPrimitive(message)
-      ? this.eventFromMessage(String(message), level, hint)
+      ? this.eventFromMessage(eventMessage, level, hint)
       : this.eventFromException(message, hint);
 
     this._process(
@@ -773,7 +777,7 @@ export abstract class BaseClient<O extends ClientOptions> implements Client<O> {
    * @inheritDoc
    */
   public abstract eventFromMessage(
-    _message: string,
+    _message: ParameterizedString,
     // eslint-disable-next-line deprecation/deprecation
     _level?: Severity | SeverityLevel,
     _hint?: EventHint,

packages/core/src/server-runtime-client.ts

@@ -6,6 +6,7 @@ import type {
   Event,
   EventHint,
   MonitorConfig,
+  ParameterizedString,
   SerializedCheckIn,
   Severity,
   SeverityLevel,
@@ -57,7 +58,7 @@ export class ServerRuntimeClient<
    * @inheritDoc
    */
   public eventFromMessage(
-    message: string,
+    message: ParameterizedString,
     // eslint-disable-next-line deprecation/deprecation
     level: Severity | SeverityLevel = 'info',
     hint?: EventHint,

packages/core/test/mocks/client.ts

@@ -5,6 +5,7 @@ import type {
   EventHint,
   Integration,
   Outcome,
+  ParameterizedString,
   Session,
   Severity,
   SeverityLevel,
@@ -76,7 +77,7 @@ export class TestClient extends BaseClient<TestClientOptions> {
   }
 
   public eventFromMessage(
-    message: string,
+    message: ParameterizedString,
     // eslint-disable-next-line deprecation/deprecation
     level: Severity | SeverityLevel = 'info',
   ): PromiseLike<Event> {

packages/node-integration-tests/suites/public-api/captureMessage/parameterized_message/scenario.ts

@@ -0,0 +1,12 @@
+import * as Sentry from '@sentry/node';
+import { parameterize } from '@sentry/utils';
+
+Sentry.init({
+  dsn: 'https://[email protected]/1337',
+  release: '1.0',
+});
+
+const x = 'first';
+const y = 'second';
+
+Sentry.captureMessage(parameterize`This is a log statement with ${x} and ${y} params`);

packages/node-integration-tests/suites/public-api/captureMessage/parameterized_message/test.ts

@@ -0,0 +1,13 @@
+import { TestEnv, assertSentryEvent } from '../../../../utils';
+
+test('should capture a parameterized representation of the message', async () => {
+  const env = await TestEnv.init(__dirname);
+  const event = await env.getEnvelopeRequest();
+
+  assertSentryEvent(event[2], {
+    logentry: {
+      message: 'This is a log statement with %s and %s params',
+      params: ['first', 'second'],
+    },
+  });
+});

packages/replay/test/utils/TestClient.ts

@@ -1,5 +1,11 @@
 import { BaseClient, createTransport, initAndBind } from '@sentry/core';
-import type { BrowserClientReplayOptions, ClientOptions, Event, SeverityLevel } from '@sentry/types';
+import type {
+  BrowserClientReplayOptions,
+  ClientOptions,
+  Event,
+  ParameterizedString,
+  SeverityLevel,
+} from '@sentry/types';
 import { resolvedSyncPromise } from '@sentry/utils';
 
 export interface TestClientOptions extends ClientOptions, BrowserClientReplayOptions {}
@@ -24,7 +30,7 @@ export class TestClient extends BaseClient<TestClientOptions> {
     });
   }
 
-  public eventFromMessage(message: string, level: SeverityLevel = 'info'): PromiseLike<Event> {
+  public eventFromMessage(message: ParameterizedString, level: SeverityLevel = 'info'): PromiseLike<Event> {
     return resolvedSyncPromise({ message, level });
   }
 }

packages/tracing-internal/test/utils/TestClient.ts

@@ -1,5 +1,11 @@
 import { BaseClient, createTransport, initAndBind } from '@sentry/core';
-import type { BrowserClientReplayOptions, ClientOptions, Event, SeverityLevel } from '@sentry/types';
+import type {
+  BrowserClientReplayOptions,
+  ClientOptions,
+  Event,
+  ParameterizedString,
+  SeverityLevel,
+} from '@sentry/types';
 import { resolvedSyncPromise } from '@sentry/utils';
 
 export interface TestClientOptions extends ClientOptions, BrowserClientReplayOptions {}
@@ -24,7 +30,7 @@ export class TestClient extends BaseClient<TestClientOptions> {
     });
   }
 
-  public eventFromMessage(message: string, level: SeverityLevel = 'info'): PromiseLike<Event> {
+  public eventFromMessage(message: ParameterizedString, level: SeverityLevel = 'info'): PromiseLike<Event> {
     return resolvedSyncPromise({ message, level });
   }
 }

packages/types/src/client.ts

@@ -9,6 +9,7 @@ import type { EventProcessor } from './eventprocessor';
 import type { FeedbackEvent } from './feedback';
 import type { Integration, IntegrationClass } from './integration';
 import type { ClientOptions } from './options';
+import type { ParameterizedString } from './parameterize';
 import type { Scope } from './scope';
 import type { SdkMetadata } from './sdkmetadata';
 import type { Session, SessionAggregates } from './session';
@@ -158,7 +159,7 @@ export interface Client<O extends ClientOptions = ClientOptions> {
 
   /** Creates an {@link Event} from primitive inputs to `captureMessage`. */
   eventFromMessage(
-    message: string,
+    message: ParameterizedString,
     // eslint-disable-next-line deprecation/deprecation
     level?: Severity | SeverityLevel,
     hint?: EventHint,

packages/types/src/event.ts

@@ -20,6 +20,10 @@ import type { User } from './user';
 export interface Event {
   event_id?: string;
   message?: string;
+  logentry?: {
+    message?: string;
+    params?: string[];
+  };
   timestamp?: number;
   start_timestamp?: number;
   // eslint-disable-next-line deprecation/deprecation

packages/types/src/index.ts

@@ -139,3 +139,4 @@ export type {
 export type { BrowserClientReplayOptions, BrowserClientProfilingOptions } from './browseroptions';
 export type { CheckIn, MonitorConfig, FinishedCheckIn, InProgressCheckIn, SerializedCheckIn } from './checkin';
 export type { Metric, CounterMetric, GaugeMetric, DistributionMetric, SetMetric } from './metrics';
+export type { ParameterizedString } from './parameterize';

packages/types/src/parameterize.ts

@@ -0,0 +1,4 @@
+export type ParameterizedString = string & {
+  __sentry_template_string__?: string;
+  __sentry_template_values__?: string[];
+};

packages/utils/src/eventbuilder.ts

@@ -4,13 +4,14 @@ import type {
   Exception,
   Hub,
   Mechanism,
+  ParameterizedString,
   Severity,
   SeverityLevel,
   StackFrame,
   StackParser,
 } from '@sentry/types';
 
-import { isError, isPlainObject } from './is';
+import { isError, isParameterizedString, isPlainObject } from './is';
 import { addExceptionMechanism, addExceptionTypeValue } from './misc';
 import { normalizeToSize } from './normalize';
 import { extractExceptionKeysForMessage } from './object';
@@ -119,7 +120,7 @@ export function eventFromUnknownInput(
  */
 export function eventFromMessage(
   stackParser: StackParser,
-  message: string,
+  message: ParameterizedString,
   // eslint-disable-next-line deprecation/deprecation
   level: Severity | SeverityLevel = 'info',
   hint?: EventHint,
@@ -128,7 +129,6 @@ export function eventFromMessage(
   const event: Event = {
     event_id: hint && hint.event_id,
     level,
-    message,
   };
 
   if (attachStacktrace && hint && hint.syntheticException) {
@@ -145,5 +145,16 @@ export function eventFromMessage(
     }
   }
 
+  if (isParameterizedString(message)) {
+    const { __sentry_template_string__, __sentry_template_values__ } = message;
+
+    event.logentry = {
+      message: __sentry_template_string__,
+      params: __sentry_template_values__,
+    };
+    return event;
+  }
+
+  event.message = message;
   return event;
 }

packages/utils/src/index.ts

@@ -32,6 +32,7 @@ export * from './url';
 export * from './userIntegrations';
 export * from './cache';
 export * from './eventbuilder';
+export * from './parameterize';
 export * from './anr';
 export * from './lru';
 export * from './buildPolyfills';

packages/utils/src/is.ts

@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /* eslint-disable @typescript-eslint/explicit-module-boundary-types */
 
-import type { PolymorphicEvent, Primitive } from '@sentry/types';
+import type { ParameterizedString, PolymorphicEvent, Primitive } from '@sentry/types';
 
 // eslint-disable-next-line @typescript-eslint/unbound-method
 const objectToString = Object.prototype.toString;
@@ -78,6 +78,22 @@ export function isString(wat: unknown): wat is string {
   return isBuiltin(wat, 'String');
 }
 
+/**
+ * Checks whether given string is parameterized
+ * {@link isParameterizedString}.
+ *
+ * @param wat A value to be checked.
+ * @returns A boolean representing the result.
+ */
+export function isParameterizedString(wat: unknown): wat is ParameterizedString {
+  return (
+    typeof wat === 'object' &&
+    wat !== null &&
+    '__sentry_template_string__' in wat &&
+    '__sentry_template_values__' in wat
+  );
+}
+
 /**
  * Checks whether given value is a primitive (undefined, null, number, boolean, string, bigint, symbol)
  * {@link isPrimitive}.
@@ -86,7 +102,7 @@ export function isString(wat: unknown): wat is string {
  * @returns A boolean representing the result.
  */
 export function isPrimitive(wat: unknown): wat is Primitive {
-  return wat === null || (typeof wat !== 'object' && typeof wat !== 'function');
+  return wat === null || isParameterizedString(wat) || (typeof wat !== 'object' && typeof wat !== 'function');
 }
 
 /**