feat(utils): Add parameterize function (#9145)

Add `parameterize` fuction to utils package that takes params from a format string and attaches them as extra properties to a string. These are picked up during event processing and a `LogEntry` item is added to the event.

Author: AleshaOleg

dev-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`);

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

@@ -0,0 +1,22 @@
+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 bundle = process.env.PW_BUNDLE;
+
+  if (bundle && bundle.startsWith('bundle_')) {
+    sentryTest.skip();
+  }
+
+  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'],
+  });
+});

dev-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`);

dev-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/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 { getClient } 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,
@@ -167,7 +177,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,
@@ -264,23 +274,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

@@ -19,6 +19,7 @@ import type {
   MetricBucketItem,
   MetricsAggregator,
   Outcome,
+  ParameterizedString,
   PropagationContext,
   SdkMetadata,
   Session,
@@ -36,6 +37,7 @@ import {
   addItemToEnvelope,
   checkOrSetAlreadyCaught,
   createAttachmentEnvelopeItem,
+  isParameterizedString,
   isPlainObject,
   isPrimitive,
   isThenable,
@@ -182,16 +184,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(
@@ -816,7 +820,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,
@@ -63,7 +64,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/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

@@ -10,6 +10,7 @@ import type { FeedbackEvent } from './feedback';
 import type { Integration, IntegrationClass } from './integration';
 import type { MetricBucketItem } from './metrics';
 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';
@@ -159,7 +160,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

@@ -140,3 +140,4 @@ export type {
 export type { BrowserClientReplayOptions, BrowserClientProfilingOptions } from './browseroptions';
 export type { CheckIn, MonitorConfig, FinishedCheckIn, InProgressCheckIn, SerializedCheckIn } from './checkin';
 export type { MetricsAggregator, MetricBucketItem, MetricInstance } 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

@@ -6,13 +6,14 @@ import type {
   Extras,
   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';
@@ -127,7 +128,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,
@@ -136,7 +137,6 @@ export function eventFromMessage(
   const event: Event = {
     event_id: hint && hint.event_id,
     level,
-    message,
   };
 
   if (attachStacktrace && hint && hint.syntheticException) {
@@ -153,5 +153,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';