Branch for 9.4.0-alpha

.size-limit.js

@@ -8,7 +8,7 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init'),
  gzip: true,
- limit: '24 KB',
+ limit: '25 KB',
  },
  {
  name: '@sentry/browser - with treeshaking flags',
@@ -40,14 +40,14 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration'),
  gzip: true,
- limit: '37.5 KB',
+ limit: '38 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay)',
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration', 'replayIntegration'),
  gzip: true,
- limit: '75.2 KB',
+ limit: '77 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay) - with treeshaking flags',
@@ -79,7 +79,7 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration', 'replayIntegration', 'replayCanvasIntegration'),
  gzip: true,
- limit: '80 KB',
+ limit: '82 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay, Feedback)',
@@ -210,7 +210,7 @@ module.exports = [
  import: createImport('init'),
  ignore: ['next/router', 'next/constants'],
  gzip: true,
- limit: '41 KB',
+ limit: '43 KB',
  },
  // SvelteKit SDK (ESM)
  {

CHANGELOG.md

@@ -10,6 +10,36 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+## 9.4.0-alpha.0
+
+This is an alpha release that includes experimental functionality for the new logs API in Sentry. Support for these methods are only avaliable in the browser and core SDKs.
+
+- feat(logs): Add experimental user-callable logging methods (#15442)
+
+Logging is gated by an experimental option, `_experiments.enableLogs`.
+
+```js
+Sentry.init({
+ _experiments: {
+ enableLogs: true,
+ },
+});
+```
+
+These API are exposed in the `Sentry._experiment_log` namespace.
+
+On the high level, there are functions for each of the logging severity levels `critical`, `fatal`, `error`, `warn`, `info`, `debug`, `trace`. These functions are tagged template functions, so they use a special string template syntax that we use to parameterize functions accordingly.
+
+```js
+Sentry._experiment_log.info`user ${username} just bought ${item}!`;
+```
+
+If you want more custom usage, we also expose a `captureLog` method that allows you to pass custom attributes, but it's less easy to use than the tagged template functions.
+
+```js
+Sentry._experiment_log.captureLog('error', 'Hello world!', { 'user.id': 123 });
+```
+
 ## 9.3.0
 
 ### Important Changes

packages/browser/src/index.ts

@@ -10,6 +10,7 @@ export {
  extraErrorDataIntegration,
  rewriteFramesIntegration,
  captureFeedback,
+ _experiment_log,
 } from '@sentry/core';
 
 export { replayIntegration, getReplay } from '@sentry-internal/replay';

packages/core/src/exports.ts

@@ -1,5 +1,6 @@
 import { getClient, getCurrentScope, getIsolationScope, withIsolationScope } from './currentScopes';
 import { DEBUG_BUILD } from './debug-build';
+import { captureLog, sendLog } from './log';
 import type { CaptureContext } from './scope';
 import { closeSession, makeSession, updateSession } from './session';
 import type {
@@ -10,6 +11,7 @@ import type {
  Extra,
  Extras,
  FinishedCheckIn,
+ LogSeverityLevel,
  MonitorConfig,
  Primitive,
  Session,
@@ -334,3 +336,68 @@ export function captureSession(end: boolean = false): void {
  // only send the update
  _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: sendLog.bind(null, 'info') 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.log`user ${username} just bought ${item}!`
+ */
+ log: sendLog.bind(null, 'log') 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: 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: 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/index.ts

@@ -29,6 +29,7 @@ export {
  endSession,
  captureSession,
  addEventProcessor,
+ _experiment_log,
 } from './exports';
 export {
  getCurrentScope,

packages/core/src/log.ts

@@ -0,0 +1,188 @@
+import type { Client } from './client';
+import { getClient, getCurrentScope } from './currentScopes';
+import { DEBUG_BUILD } from './debug-build';
+import type { Scope } from './scope';
+import { getDynamicSamplingContextFromScope } from './tracing';
+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';
+
+const LOG_BUFFER_MAX_LENGTH = 25;
+
+let GLOBAL_LOG_BUFFER: Log[] = [];
+
+let isFlushingLogs = false;
+
+const SEVERITY_TEXT_TO_SEVERITY_NUMBER: Partial<Record<LogSeverityLevel | 'log', number>> = {
+ trace: 1,
+ debug: 5,
+ info: 9,
+ log: 10,
+ warn: 13,
+ error: 17,
+ fatal: 21,
+};
+
+/**
+ * Creates envelope item for a single log
+ */
+export function createLogEnvelopeItem(log: Log): LogItem {
+ const headers: LogItem[0] = {
+ type: 'otel_log',
+ };
+
+ return [headers, log];
+}
+
+/**
+ * Records a log and sends it to sentry.
+ *
+ * Logs represent a message (and optionally some structured data) which provide context for a trace or error.
+ * Ex: sentry.addLog({level: 'warning', message: `user ${user} just bought ${item}`, attributes: {user, item}}
+ *
+ * @params log - the log object which will be sent
+ */
+function createLogEnvelope(logs: Log[], client: Client, scope: Scope): LogEnvelope {
+ const dsc = getDynamicSamplingContextFromScope(client, scope);
+
+ const dsn = client.getDsn();
+
+ const headers: LogEnvelope[0] = {
+ trace: dropUndefinedKeys(dsc) as DynamicSamplingContext,
+ ...(dsn ? { dsn: dsnToString(dsn) } : {}),
+ };
+
+ return createEnvelope<LogEnvelope>(headers, logs.map(createLogEnvelopeItem));
+}
+
+function valueToAttribute(key: string, value: unknown): LogAttribute {
+ switch (typeof value) {
+ case 'number':
+ return {
+ key,
+ value: { doubleValue: value },
+ };
+ case 'boolean':
+ return {
+ key,
+ value: { boolValue: value },
+ };
+ case 'string':
+ return {
+ key,
+ value: { stringValue: value },
+ };
+ default:
+ return {
+ key,
+ value: { stringValue: JSON.stringify(value) ?? '' },
+ };
+ }
+}
+
+function addToLogBuffer(client: Client, log: Log, scope: Scope): void {
+ function sendLogs(flushedLogs: Log[]): void {
+ const envelope = createLogEnvelope(flushedLogs, client, scope);
+ // eslint-disable-next-line @typescript-eslint/no-floating-promises
+ void client.sendEnvelope(envelope);
+ }
+
+ if (GLOBAL_LOG_BUFFER.length >= LOG_BUFFER_MAX_LENGTH) {
+ sendLogs(GLOBAL_LOG_BUFFER);
+ GLOBAL_LOG_BUFFER = [];
+ } else {
+ GLOBAL_LOG_BUFFER.push(log);
+ }
+
+ // this is the first time logs have been enabled, let's kick off an interval to flush them
+ // we should only do this once.
+ if (!isFlushingLogs) {
+ setInterval(() => {
+ if (GLOBAL_LOG_BUFFER.length > 0) {
+ sendLogs(GLOBAL_LOG_BUFFER);
+ GLOBAL_LOG_BUFFER = [];
+ }
+ }, 5000);
+ }
+ isFlushingLogs = true;
+}
+
+/**
+ * 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 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);
+}
+
+/**
+ * Sends a log to Sentry.
+ */
+export function captureLog(
+ level: LogSeverityLevel,
+ message: string,
+ customAttributes: Record<string, unknown> = {},
+ severityNumber?: number,
+): void {
+ const client = getClient();
+
+ if (!client) {
+ DEBUG_BUILD && logger.warn('No client available, log will not be captured.');
+ return;
+ }
+
+ if (!client.getOptions()._experiments?.enableLogs) {
+ DEBUG_BUILD && logger.warn('logging option not enabled, log will not be captured.');
+ return;
+ }
+
+ const { release, environment } = client.getOptions();
+
+ const logAttributes = {
+ ...customAttributes,
+ };
+
+ if (release) {
+ logAttributes['sentry.release'] = release;
+ }
+
+ if (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,
+ timeUnixNano: `${new Date().getTime().toString()}000000`,
+ traceId: scope.getPropagationContext().traceId,
+ severityNumber,
+ };
+
+ const maybeSeverityNumber = SEVERITY_TEXT_TO_SEVERITY_NUMBER[level];
+ if (maybeSeverityNumber !== undefined && log.severityNumber === undefined) {
+ log.severityNumber = maybeSeverityNumber;
+ }
+
+ addToLogBuffer(client, log, scope);
+}

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

@@ -182,7 +182,12 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
  * Options which are in beta, or otherwise not guaranteed to be stable.
  */
  _experiments?: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
  [key: string]: any;
+ /**
+ * If logs support should be enabled. Defaults to false.
+ */
+ enableLogs?: boolean;
  };
 
  /**

packages/eslint-config-sdk/src/base.js

@@ -84,7 +84,7 @@ module.exports = {
  // Make sure all expressions are used. Turned off in tests
  // Must disable base rule to prevent false positives
  'no-unused-expressions': 'off',
- '@typescript-eslint/no-unused-expressions': ['error', { allowShortCircuit: true }],
+ '@typescript-eslint/no-unused-expressions': ['error', { allowShortCircuit: true, allowTaggedTemplates: true }],
 
  // Make sure Promises are handled appropriately
  '@typescript-eslint/no-floating-promises': ['error', { ignoreVoid: false }],

.size-limit.js

@@ -8,7 +8,7 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init'),
  gzip: true,
- limit: '24 KB',
+ limit: '25 KB',
  },
  {
  name: '@sentry/browser - with treeshaking flags',
@@ -40,14 +40,14 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration'),
  gzip: true,
- limit: '37.5 KB',
+ limit: '38 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay)',
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration', 'replayIntegration'),
  gzip: true,
- limit: '75.2 KB',
+ limit: '77 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay) - with treeshaking flags',
@@ -79,7 +79,7 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration', 'replayIntegration', 'replayCanvasIntegration'),
  gzip: true,
- limit: '80 KB',
+ limit: '82 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay, Feedback)',
@@ -210,7 +210,7 @@ module.exports = [
  import: createImport('init'),
  ignore: ['next/router', 'next/constants'],
  gzip: true,
- limit: '41 KB',
+ limit: '43 KB',
  },
  // SvelteKit SDK (ESM)
  {

CHANGELOG.md

@@ -10,6 +10,36 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+## 9.4.0-alpha.0
+
+This is an alpha release that includes experimental functionality for the new logs API in Sentry. Support for these methods are only avaliable in the browser and core SDKs.
+
+- feat(logs): Add experimental user-callable logging methods (#15442)
+
+Logging is gated by an experimental option, `_experiments.enableLogs`.
+
+```js
+Sentry.init({
+ _experiments: {
+ enableLogs: true,
+ },
+});
+```
+
+These API are exposed in the `Sentry._experiment_log` namespace.
+
+On the high level, there are functions for each of the logging severity levels `critical`, `fatal`, `error`, `warn`, `info`, `debug`, `trace`. These functions are tagged template functions, so they use a special string template syntax that we use to parameterize functions accordingly.
+
+```js
+Sentry._experiment_log.info`user ${username} just bought ${item}!`;
+```
+
+If you want more custom usage, we also expose a `captureLog` method that allows you to pass custom attributes, but it's less easy to use than the tagged template functions.
+
+```js
+Sentry._experiment_log.captureLog('error', 'Hello world!', { 'user.id': 123 });
+```
+
 ## 9.3.0
 
 ### Important Changes

packages/browser/src/index.ts

@@ -10,6 +10,7 @@ export {
  extraErrorDataIntegration,
  rewriteFramesIntegration,
  captureFeedback,
+ _experiment_log,
 } from '@sentry/core';
 
 export { replayIntegration, getReplay } from '@sentry-internal/replay';

packages/core/src/exports.ts

@@ -1,5 +1,6 @@
 import { getClient, getCurrentScope, getIsolationScope, withIsolationScope } from './currentScopes';
 import { DEBUG_BUILD } from './debug-build';
+import { captureLog, sendLog } from './log';
 import type { CaptureContext } from './scope';
 import { closeSession, makeSession, updateSession } from './session';
 import type {
@@ -10,6 +11,7 @@ import type {
  Extra,
  Extras,
  FinishedCheckIn,
+ LogSeverityLevel,
  MonitorConfig,
  Primitive,
  Session,
@@ -334,3 +336,68 @@ export function captureSession(end: boolean = false): void {
  // only send the update
  _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: sendLog.bind(null, 'info') 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.log`user ${username} just bought ${item}!`
+ */
+ log: sendLog.bind(null, 'log') 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: 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: 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/index.ts

@@ -29,6 +29,7 @@ export {
  endSession,
  captureSession,
  addEventProcessor,
+ _experiment_log,
 } from './exports';
 export {
  getCurrentScope,

packages/core/src/log.ts

@@ -0,0 +1,188 @@
+import type { Client } from './client';
+import { getClient, getCurrentScope } from './currentScopes';
+import { DEBUG_BUILD } from './debug-build';
+import type { Scope } from './scope';
+import { getDynamicSamplingContextFromScope } from './tracing';
+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';
+
+const LOG_BUFFER_MAX_LENGTH = 25;
+
+let GLOBAL_LOG_BUFFER: Log[] = [];
+
+let isFlushingLogs = false;
+
+const SEVERITY_TEXT_TO_SEVERITY_NUMBER: Partial<Record<LogSeverityLevel | 'log', number>> = {
+ trace: 1,
+ debug: 5,
+ info: 9,
+ log: 10,
+ warn: 13,
+ error: 17,
+ fatal: 21,
+};
+
+/**
+ * Creates envelope item for a single log
+ */
+export function createLogEnvelopeItem(log: Log): LogItem {
+ const headers: LogItem[0] = {
+ type: 'otel_log',
+ };
+
+ return [headers, log];
+}
+
+/**
+ * Records a log and sends it to sentry.
+ *
+ * Logs represent a message (and optionally some structured data) which provide context for a trace or error.
+ * Ex: sentry.addLog({level: 'warning', message: `user ${user} just bought ${item}`, attributes: {user, item}}
+ *
+ * @params log - the log object which will be sent
+ */
+function createLogEnvelope(logs: Log[], client: Client, scope: Scope): LogEnvelope {
+ const dsc = getDynamicSamplingContextFromScope(client, scope);
+
+ const dsn = client.getDsn();
+
+ const headers: LogEnvelope[0] = {
+ trace: dropUndefinedKeys(dsc) as DynamicSamplingContext,
+ ...(dsn ? { dsn: dsnToString(dsn) } : {}),
+ };
+
+ return createEnvelope<LogEnvelope>(headers, logs.map(createLogEnvelopeItem));
+}
+
+function valueToAttribute(key: string, value: unknown): LogAttribute {
+ switch (typeof value) {
+ case 'number':
+ return {
+ key,
+ value: { doubleValue: value },
+ };
+ case 'boolean':
+ return {
+ key,
+ value: { boolValue: value },
+ };
+ case 'string':
+ return {
+ key,
+ value: { stringValue: value },
+ };
+ default:
+ return {
+ key,
+ value: { stringValue: JSON.stringify(value) ?? '' },
+ };
+ }
+}
+
+function addToLogBuffer(client: Client, log: Log, scope: Scope): void {
+ function sendLogs(flushedLogs: Log[]): void {
+ const envelope = createLogEnvelope(flushedLogs, client, scope);
+ // eslint-disable-next-line @typescript-eslint/no-floating-promises
+ void client.sendEnvelope(envelope);
+ }
+
+ if (GLOBAL_LOG_BUFFER.length >= LOG_BUFFER_MAX_LENGTH) {
+ sendLogs(GLOBAL_LOG_BUFFER);
+ GLOBAL_LOG_BUFFER = [];
+ } else {
+ GLOBAL_LOG_BUFFER.push(log);
+ }
+
+ // this is the first time logs have been enabled, let's kick off an interval to flush them
+ // we should only do this once.
+ if (!isFlushingLogs) {
+ setInterval(() => {
+ if (GLOBAL_LOG_BUFFER.length > 0) {
+ sendLogs(GLOBAL_LOG_BUFFER);
+ GLOBAL_LOG_BUFFER = [];
+ }
+ }, 5000);
+ }
+ isFlushingLogs = true;
+}
+
+/**
+ * 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 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);
+}
+
+/**
+ * Sends a log to Sentry.
+ */
+export function captureLog(
+ level: LogSeverityLevel,
+ message: string,
+ customAttributes: Record<string, unknown> = {},
+ severityNumber?: number,
+): void {
+ const client = getClient();
+
+ if (!client) {
+ DEBUG_BUILD && logger.warn('No client available, log will not be captured.');
+ return;
+ }
+
+ if (!client.getOptions()._experiments?.enableLogs) {
+ DEBUG_BUILD && logger.warn('logging option not enabled, log will not be captured.');
+ return;
+ }
+
+ const { release, environment } = client.getOptions();
+
+ const logAttributes = {
+ ...customAttributes,
+ };
+
+ if (release) {
+ logAttributes['sentry.release'] = release;
+ }
+
+ if (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,
+ timeUnixNano: `${new Date().getTime().toString()}000000`,
+ traceId: scope.getPropagationContext().traceId,
+ severityNumber,
+ };
+
+ const maybeSeverityNumber = SEVERITY_TEXT_TO_SEVERITY_NUMBER[level];
+ if (maybeSeverityNumber !== undefined && log.severityNumber === undefined) {
+ log.severityNumber = maybeSeverityNumber;
+ }
+
+ addToLogBuffer(client, log, scope);
+}

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

@@ -182,7 +182,12 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
  * Options which are in beta, or otherwise not guaranteed to be stable.
  */
  _experiments?: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
  [key: string]: any;
+ /**
+ * If logs support should be enabled. Defaults to false.
+ */
+ enableLogs?: boolean;
  };
 
  /**

packages/eslint-config-sdk/src/base.js

@@ -84,7 +84,7 @@ module.exports = {
  // Make sure all expressions are used. Turned off in tests
  // Must disable base rule to prevent false positives
  'no-unused-expressions': 'off',
- '@typescript-eslint/no-unused-expressions': ['error', { allowShortCircuit: true }],
+ '@typescript-eslint/no-unused-expressions': ['error', { allowShortCircuit: true, allowTaggedTemplates: true }],
 
  // Make sure Promises are handled appropriately
  '@typescript-eslint/no-floating-promises': ['error', { ignoreVoid: false }],

.size-limit.js

@@ -8,7 +8,7 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init'),
  gzip: true,
- limit: '24 KB',
+ limit: '25 KB',
  },
  {
  name: '@sentry/browser - with treeshaking flags',
@@ -40,14 +40,14 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration'),
  gzip: true,
- limit: '37.5 KB',
+ limit: '38 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay)',
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration', 'replayIntegration'),
  gzip: true,
- limit: '75.2 KB',
+ limit: '77 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay) - with treeshaking flags',
@@ -79,7 +79,7 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration', 'replayIntegration', 'replayCanvasIntegration'),
  gzip: true,
- limit: '80 KB',
+ limit: '82 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay, Feedback)',
@@ -210,7 +210,7 @@ module.exports = [
  import: createImport('init'),
  ignore: ['next/router', 'next/constants'],
  gzip: true,
- limit: '41 KB',
+ limit: '43 KB',
  },
  // SvelteKit SDK (ESM)
  {

CHANGELOG.md

@@ -10,6 +10,36 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+## 9.4.0-alpha.0
+
+This is an alpha release that includes experimental functionality for the new logs API in Sentry. Support for these methods are only avaliable in the browser and core SDKs.
+
+- feat(logs): Add experimental user-callable logging methods (#15442)
+
+Logging is gated by an experimental option, `_experiments.enableLogs`.
+
+```js
+Sentry.init({
+ _experiments: {
+ enableLogs: true,
+ },
+});
+```
+
+These API are exposed in the `Sentry._experiment_log` namespace.
+
+On the high level, there are functions for each of the logging severity levels `critical`, `fatal`, `error`, `warn`, `info`, `debug`, `trace`. These functions are tagged template functions, so they use a special string template syntax that we use to parameterize functions accordingly.
+
+```js
+Sentry._experiment_log.info`user ${username} just bought ${item}!`;
+```
+
+If you want more custom usage, we also expose a `captureLog` method that allows you to pass custom attributes, but it's less easy to use than the tagged template functions.
+
+```js
+Sentry._experiment_log.captureLog('error', 'Hello world!', { 'user.id': 123 });
+```
+
 ## 9.3.0
 
 ### Important Changes

packages/browser/src/index.ts

@@ -10,6 +10,7 @@ export {
  extraErrorDataIntegration,
  rewriteFramesIntegration,
  captureFeedback,
+ _experiment_log,
 } from '@sentry/core';
 
 export { replayIntegration, getReplay } from '@sentry-internal/replay';

packages/core/src/exports.ts

@@ -1,5 +1,6 @@
 import { getClient, getCurrentScope, getIsolationScope, withIsolationScope } from './currentScopes';
 import { DEBUG_BUILD } from './debug-build';
+import { captureLog, sendLog } from './log';
 import type { CaptureContext } from './scope';
 import { closeSession, makeSession, updateSession } from './session';
 import type {
@@ -10,6 +11,7 @@ import type {
  Extra,
  Extras,
  FinishedCheckIn,
+ LogSeverityLevel,
  MonitorConfig,
  Primitive,
  Session,
@@ -334,3 +336,68 @@ export function captureSession(end: boolean = false): void {
  // only send the update
  _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: sendLog.bind(null, 'info') 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.log`user ${username} just bought ${item}!`
+ */
+ log: sendLog.bind(null, 'log') 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: 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: 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/index.ts

@@ -29,6 +29,7 @@ export {
  endSession,
  captureSession,
  addEventProcessor,
+ _experiment_log,
 } from './exports';
 export {
  getCurrentScope,

packages/core/src/log.ts

@@ -0,0 +1,188 @@
+import type { Client } from './client';
+import { getClient, getCurrentScope } from './currentScopes';
+import { DEBUG_BUILD } from './debug-build';
+import type { Scope } from './scope';
+import { getDynamicSamplingContextFromScope } from './tracing';
+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';
+
+const LOG_BUFFER_MAX_LENGTH = 25;
+
+let GLOBAL_LOG_BUFFER: Log[] = [];
+
+let isFlushingLogs = false;
+
+const SEVERITY_TEXT_TO_SEVERITY_NUMBER: Partial<Record<LogSeverityLevel | 'log', number>> = {
+ trace: 1,
+ debug: 5,
+ info: 9,
+ log: 10,
+ warn: 13,
+ error: 17,
+ fatal: 21,
+};
+
+/**
+ * Creates envelope item for a single log
+ */
+export function createLogEnvelopeItem(log: Log): LogItem {
+ const headers: LogItem[0] = {
+ type: 'otel_log',
+ };
+
+ return [headers, log];
+}
+
+/**
+ * Records a log and sends it to sentry.
+ *
+ * Logs represent a message (and optionally some structured data) which provide context for a trace or error.
+ * Ex: sentry.addLog({level: 'warning', message: `user ${user} just bought ${item}`, attributes: {user, item}}
+ *
+ * @params log - the log object which will be sent
+ */
+function createLogEnvelope(logs: Log[], client: Client, scope: Scope): LogEnvelope {
+ const dsc = getDynamicSamplingContextFromScope(client, scope);
+
+ const dsn = client.getDsn();
+
+ const headers: LogEnvelope[0] = {
+ trace: dropUndefinedKeys(dsc) as DynamicSamplingContext,
+ ...(dsn ? { dsn: dsnToString(dsn) } : {}),
+ };
+
+ return createEnvelope<LogEnvelope>(headers, logs.map(createLogEnvelopeItem));
+}
+
+function valueToAttribute(key: string, value: unknown): LogAttribute {
+ switch (typeof value) {
+ case 'number':
+ return {
+ key,
+ value: { doubleValue: value },
+ };
+ case 'boolean':
+ return {
+ key,
+ value: { boolValue: value },
+ };
+ case 'string':
+ return {
+ key,
+ value: { stringValue: value },
+ };
+ default:
+ return {
+ key,
+ value: { stringValue: JSON.stringify(value) ?? '' },
+ };
+ }
+}
+
+function addToLogBuffer(client: Client, log: Log, scope: Scope): void {
+ function sendLogs(flushedLogs: Log[]): void {
+ const envelope = createLogEnvelope(flushedLogs, client, scope);
+ // eslint-disable-next-line @typescript-eslint/no-floating-promises
+ void client.sendEnvelope(envelope);
+ }
+
+ if (GLOBAL_LOG_BUFFER.length >= LOG_BUFFER_MAX_LENGTH) {
+ sendLogs(GLOBAL_LOG_BUFFER);
+ GLOBAL_LOG_BUFFER = [];
+ } else {
+ GLOBAL_LOG_BUFFER.push(log);
+ }
+
+ // this is the first time logs have been enabled, let's kick off an interval to flush them
+ // we should only do this once.
+ if (!isFlushingLogs) {
+ setInterval(() => {
+ if (GLOBAL_LOG_BUFFER.length > 0) {
+ sendLogs(GLOBAL_LOG_BUFFER);
+ GLOBAL_LOG_BUFFER = [];
+ }
+ }, 5000);
+ }
+ isFlushingLogs = true;
+}
+
+/**
+ * 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 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);
+}
+
+/**
+ * Sends a log to Sentry.
+ */
+export function captureLog(
+ level: LogSeverityLevel,
+ message: string,
+ customAttributes: Record<string, unknown> = {},
+ severityNumber?: number,
+): void {
+ const client = getClient();
+
+ if (!client) {
+ DEBUG_BUILD && logger.warn('No client available, log will not be captured.');
+ return;
+ }
+
+ if (!client.getOptions()._experiments?.enableLogs) {
+ DEBUG_BUILD && logger.warn('logging option not enabled, log will not be captured.');
+ return;
+ }
+
+ const { release, environment } = client.getOptions();
+
+ const logAttributes = {
+ ...customAttributes,
+ };
+
+ if (release) {
+ logAttributes['sentry.release'] = release;
+ }
+
+ if (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,
+ timeUnixNano: `${new Date().getTime().toString()}000000`,
+ traceId: scope.getPropagationContext().traceId,
+ severityNumber,
+ };
+
+ const maybeSeverityNumber = SEVERITY_TEXT_TO_SEVERITY_NUMBER[level];
+ if (maybeSeverityNumber !== undefined && log.severityNumber === undefined) {
+ log.severityNumber = maybeSeverityNumber;
+ }
+
+ addToLogBuffer(client, log, scope);
+}

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

@@ -182,7 +182,12 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
  * Options which are in beta, or otherwise not guaranteed to be stable.
  */
  _experiments?: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
  [key: string]: any;
+ /**
+ * If logs support should be enabled. Defaults to false.
+ */
+ enableLogs?: boolean;
  };
 
  /**

packages/eslint-config-sdk/src/base.js

@@ -84,7 +84,7 @@ module.exports = {
  // Make sure all expressions are used. Turned off in tests
  // Must disable base rule to prevent false positives
  'no-unused-expressions': 'off',
- '@typescript-eslint/no-unused-expressions': ['error', { allowShortCircuit: true }],
+ '@typescript-eslint/no-unused-expressions': ['error', { allowShortCircuit: true, allowTaggedTemplates: true }],
 
  // Make sure Promises are handled appropriately
  '@typescript-eslint/no-floating-promises': ['error', { ignoreVoid: false }],

.size-limit.js

@@ -8,7 +8,7 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init'),
  gzip: true,
- limit: '24 KB',
+ limit: '25 KB',
  },
  {
  name: '@sentry/browser - with treeshaking flags',
@@ -40,14 +40,14 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration'),
  gzip: true,
- limit: '37.5 KB',
+ limit: '38 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay)',
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration', 'replayIntegration'),
  gzip: true,
- limit: '75.2 KB',
+ limit: '77 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay) - with treeshaking flags',
@@ -79,7 +79,7 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration', 'replayIntegration', 'replayCanvasIntegration'),
  gzip: true,
- limit: '80 KB',
+ limit: '82 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay, Feedback)',
@@ -210,7 +210,7 @@ module.exports = [
  import: createImport('init'),
  ignore: ['next/router', 'next/constants'],
  gzip: true,
- limit: '41 KB',
+ limit: '43 KB',
  },
  // SvelteKit SDK (ESM)
  {

CHANGELOG.md

@@ -10,6 +10,36 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+## 9.4.0-alpha.0
+
+This is an alpha release that includes experimental functionality for the new logs API in Sentry. Support for these methods are only avaliable in the browser and core SDKs.
+
+- feat(logs): Add experimental user-callable logging methods (#15442)
+
+Logging is gated by an experimental option, `_experiments.enableLogs`.
+
+```js
+Sentry.init({
+ _experiments: {
+ enableLogs: true,
+ },
+});
+```
+
+These API are exposed in the `Sentry._experiment_log` namespace.
+
+On the high level, there are functions for each of the logging severity levels `critical`, `fatal`, `error`, `warn`, `info`, `debug`, `trace`. These functions are tagged template functions, so they use a special string template syntax that we use to parameterize functions accordingly.
+
+```js
+Sentry._experiment_log.info`user ${username} just bought ${item}!`;
+```
+
+If you want more custom usage, we also expose a `captureLog` method that allows you to pass custom attributes, but it's less easy to use than the tagged template functions.
+
+```js
+Sentry._experiment_log.captureLog('error', 'Hello world!', { 'user.id': 123 });
+```
+
 ## 9.3.0
 
 ### Important Changes

packages/browser/src/index.ts

@@ -10,6 +10,7 @@ export {
  extraErrorDataIntegration,
  rewriteFramesIntegration,
  captureFeedback,
+ _experiment_log,
 } from '@sentry/core';
 
 export { replayIntegration, getReplay } from '@sentry-internal/replay';

packages/core/src/exports.ts

@@ -1,5 +1,6 @@
 import { getClient, getCurrentScope, getIsolationScope, withIsolationScope } from './currentScopes';
 import { DEBUG_BUILD } from './debug-build';
+import { captureLog, sendLog } from './log';
 import type { CaptureContext } from './scope';
 import { closeSession, makeSession, updateSession } from './session';
 import type {
@@ -10,6 +11,7 @@ import type {
  Extra,
  Extras,
  FinishedCheckIn,
+ LogSeverityLevel,
  MonitorConfig,
  Primitive,
  Session,
@@ -334,3 +336,68 @@ export function captureSession(end: boolean = false): void {
  // only send the update
  _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: sendLog.bind(null, 'info') 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.log`user ${username} just bought ${item}!`
+ */
+ log: sendLog.bind(null, 'log') 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: 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: 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/index.ts

@@ -29,6 +29,7 @@ export {
  endSession,
  captureSession,
  addEventProcessor,
+ _experiment_log,
 } from './exports';
 export {
  getCurrentScope,

packages/core/src/log.ts

@@ -0,0 +1,188 @@
+import type { Client } from './client';
+import { getClient, getCurrentScope } from './currentScopes';
+import { DEBUG_BUILD } from './debug-build';
+import type { Scope } from './scope';
+import { getDynamicSamplingContextFromScope } from './tracing';
+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';
+
+const LOG_BUFFER_MAX_LENGTH = 25;
+
+let GLOBAL_LOG_BUFFER: Log[] = [];
+
+let isFlushingLogs = false;
+
+const SEVERITY_TEXT_TO_SEVERITY_NUMBER: Partial<Record<LogSeverityLevel | 'log', number>> = {
+ trace: 1,
+ debug: 5,
+ info: 9,
+ log: 10,
+ warn: 13,
+ error: 17,
+ fatal: 21,
+};
+
+/**
+ * Creates envelope item for a single log
+ */
+export function createLogEnvelopeItem(log: Log): LogItem {
+ const headers: LogItem[0] = {
+ type: 'otel_log',
+ };
+
+ return [headers, log];
+}
+
+/**
+ * Records a log and sends it to sentry.
+ *
+ * Logs represent a message (and optionally some structured data) which provide context for a trace or error.
+ * Ex: sentry.addLog({level: 'warning', message: `user ${user} just bought ${item}`, attributes: {user, item}}
+ *
+ * @params log - the log object which will be sent
+ */
+function createLogEnvelope(logs: Log[], client: Client, scope: Scope): LogEnvelope {
+ const dsc = getDynamicSamplingContextFromScope(client, scope);
+
+ const dsn = client.getDsn();
+
+ const headers: LogEnvelope[0] = {
+ trace: dropUndefinedKeys(dsc) as DynamicSamplingContext,
+ ...(dsn ? { dsn: dsnToString(dsn) } : {}),
+ };
+
+ return createEnvelope<LogEnvelope>(headers, logs.map(createLogEnvelopeItem));
+}
+
+function valueToAttribute(key: string, value: unknown): LogAttribute {
+ switch (typeof value) {
+ case 'number':
+ return {
+ key,
+ value: { doubleValue: value },
+ };
+ case 'boolean':
+ return {
+ key,
+ value: { boolValue: value },
+ };
+ case 'string':
+ return {
+ key,
+ value: { stringValue: value },
+ };
+ default:
+ return {
+ key,
+ value: { stringValue: JSON.stringify(value) ?? '' },
+ };
+ }
+}
+
+function addToLogBuffer(client: Client, log: Log, scope: Scope): void {
+ function sendLogs(flushedLogs: Log[]): void {
+ const envelope = createLogEnvelope(flushedLogs, client, scope);
+ // eslint-disable-next-line @typescript-eslint/no-floating-promises
+ void client.sendEnvelope(envelope);
+ }
+
+ if (GLOBAL_LOG_BUFFER.length >= LOG_BUFFER_MAX_LENGTH) {
+ sendLogs(GLOBAL_LOG_BUFFER);
+ GLOBAL_LOG_BUFFER = [];
+ } else {
+ GLOBAL_LOG_BUFFER.push(log);
+ }
+
+ // this is the first time logs have been enabled, let's kick off an interval to flush them
+ // we should only do this once.
+ if (!isFlushingLogs) {
+ setInterval(() => {
+ if (GLOBAL_LOG_BUFFER.length > 0) {
+ sendLogs(GLOBAL_LOG_BUFFER);
+ GLOBAL_LOG_BUFFER = [];
+ }
+ }, 5000);
+ }
+ isFlushingLogs = true;
+}
+
+/**
+ * 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 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);
+}
+
+/**
+ * Sends a log to Sentry.
+ */
+export function captureLog(
+ level: LogSeverityLevel,
+ message: string,
+ customAttributes: Record<string, unknown> = {},
+ severityNumber?: number,
+): void {
+ const client = getClient();
+
+ if (!client) {
+ DEBUG_BUILD && logger.warn('No client available, log will not be captured.');
+ return;
+ }
+
+ if (!client.getOptions()._experiments?.enableLogs) {
+ DEBUG_BUILD && logger.warn('logging option not enabled, log will not be captured.');
+ return;
+ }
+
+ const { release, environment } = client.getOptions();
+
+ const logAttributes = {
+ ...customAttributes,
+ };
+
+ if (release) {
+ logAttributes['sentry.release'] = release;
+ }
+
+ if (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,
+ timeUnixNano: `${new Date().getTime().toString()}000000`,
+ traceId: scope.getPropagationContext().traceId,
+ severityNumber,
+ };
+
+ const maybeSeverityNumber = SEVERITY_TEXT_TO_SEVERITY_NUMBER[level];
+ if (maybeSeverityNumber !== undefined && log.severityNumber === undefined) {
+ log.severityNumber = maybeSeverityNumber;
+ }
+
+ addToLogBuffer(client, log, scope);
+}

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

@@ -182,7 +182,12 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
  * Options which are in beta, or otherwise not guaranteed to be stable.
  */
  _experiments?: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
  [key: string]: any;
+ /**
+ * If logs support should be enabled. Defaults to false.
+ */
+ enableLogs?: boolean;
  };
 
  /**

packages/eslint-config-sdk/src/base.js

@@ -84,7 +84,7 @@ module.exports = {
  // Make sure all expressions are used. Turned off in tests
  // Must disable base rule to prevent false positives
  'no-unused-expressions': 'off',
- '@typescript-eslint/no-unused-expressions': ['error', { allowShortCircuit: true }],
+ '@typescript-eslint/no-unused-expressions': ['error', { allowShortCircuit: true, allowTaggedTemplates: true }],
 
  // Make sure Promises are handled appropriately
  '@typescript-eslint/no-floating-promises': ['error', { ignoreVoid: false }],

.size-limit.js

@@ -8,7 +8,7 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init'),
  gzip: true,
- limit: '24 KB',
+ limit: '25 KB',
  },
  {
  name: '@sentry/browser - with treeshaking flags',
@@ -40,14 +40,14 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration'),
  gzip: true,
- limit: '37.5 KB',
+ limit: '38 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay)',
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration', 'replayIntegration'),
  gzip: true,
- limit: '75.2 KB',
+ limit: '77 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay) - with treeshaking flags',
@@ -79,7 +79,7 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration', 'replayIntegration', 'replayCanvasIntegration'),
  gzip: true,
- limit: '80 KB',
+ limit: '82 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay, Feedback)',
@@ -210,7 +210,7 @@ module.exports = [
  import: createImport('init'),
  ignore: ['next/router', 'next/constants'],
  gzip: true,
- limit: '41 KB',
+ limit: '43 KB',
  },
  // SvelteKit SDK (ESM)
  {

CHANGELOG.md

@@ -10,6 +10,36 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+## 9.4.0-alpha.0
+
+This is an alpha release that includes experimental functionality for the new logs API in Sentry. Support for these methods are only avaliable in the browser and core SDKs.
+
+- feat(logs): Add experimental user-callable logging methods (#15442)
+
+Logging is gated by an experimental option, `_experiments.enableLogs`.
+
+```js
+Sentry.init({
+ _experiments: {
+ enableLogs: true,
+ },
+});
+```
+
+These API are exposed in the `Sentry._experiment_log` namespace.
+
+On the high level, there are functions for each of the logging severity levels `critical`, `fatal`, `error`, `warn`, `info`, `debug`, `trace`. These functions are tagged template functions, so they use a special string template syntax that we use to parameterize functions accordingly.
+
+```js
+Sentry._experiment_log.info`user ${username} just bought ${item}!`;
+```
+
+If you want more custom usage, we also expose a `captureLog` method that allows you to pass custom attributes, but it's less easy to use than the tagged template functions.
+
+```js
+Sentry._experiment_log.captureLog('error', 'Hello world!', { 'user.id': 123 });
+```
+
 ## 9.3.0
 
 ### Important Changes

packages/browser/src/index.ts

@@ -10,6 +10,7 @@ export {
  extraErrorDataIntegration,
  rewriteFramesIntegration,
  captureFeedback,
+ _experiment_log,
 } from '@sentry/core';
 
 export { replayIntegration, getReplay } from '@sentry-internal/replay';

packages/core/src/exports.ts

@@ -1,5 +1,6 @@
 import { getClient, getCurrentScope, getIsolationScope, withIsolationScope } from './currentScopes';
 import { DEBUG_BUILD } from './debug-build';
+import { captureLog, sendLog } from './log';
 import type { CaptureContext } from './scope';
 import { closeSession, makeSession, updateSession } from './session';
 import type {
@@ -10,6 +11,7 @@ import type {
  Extra,
  Extras,
  FinishedCheckIn,
+ LogSeverityLevel,
  MonitorConfig,
  Primitive,
  Session,
@@ -334,3 +336,68 @@ export function captureSession(end: boolean = false): void {
  // only send the update
  _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: sendLog.bind(null, 'info') 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.log`user ${username} just bought ${item}!`
+ */
+ log: sendLog.bind(null, 'log') 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: 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: 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/index.ts

@@ -29,6 +29,7 @@ export {
  endSession,
  captureSession,
  addEventProcessor,
+ _experiment_log,
 } from './exports';
 export {
  getCurrentScope,

packages/core/src/log.ts

@@ -0,0 +1,188 @@
+import type { Client } from './client';
+import { getClient, getCurrentScope } from './currentScopes';
+import { DEBUG_BUILD } from './debug-build';
+import type { Scope } from './scope';
+import { getDynamicSamplingContextFromScope } from './tracing';
+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';
+
+const LOG_BUFFER_MAX_LENGTH = 25;
+
+let GLOBAL_LOG_BUFFER: Log[] = [];
+
+let isFlushingLogs = false;
+
+const SEVERITY_TEXT_TO_SEVERITY_NUMBER: Partial<Record<LogSeverityLevel | 'log', number>> = {
+ trace: 1,
+ debug: 5,
+ info: 9,
+ log: 10,
+ warn: 13,
+ error: 17,
+ fatal: 21,
+};
+
+/**
+ * Creates envelope item for a single log
+ */
+export function createLogEnvelopeItem(log: Log): LogItem {
+ const headers: LogItem[0] = {
+ type: 'otel_log',
+ };
+
+ return [headers, log];
+}
+
+/**
+ * Records a log and sends it to sentry.
+ *
+ * Logs represent a message (and optionally some structured data) which provide context for a trace or error.
+ * Ex: sentry.addLog({level: 'warning', message: `user ${user} just bought ${item}`, attributes: {user, item}}
+ *
+ * @params log - the log object which will be sent
+ */
+function createLogEnvelope(logs: Log[], client: Client, scope: Scope): LogEnvelope {
+ const dsc = getDynamicSamplingContextFromScope(client, scope);
+
+ const dsn = client.getDsn();
+
+ const headers: LogEnvelope[0] = {
+ trace: dropUndefinedKeys(dsc) as DynamicSamplingContext,
+ ...(dsn ? { dsn: dsnToString(dsn) } : {}),
+ };
+
+ return createEnvelope<LogEnvelope>(headers, logs.map(createLogEnvelopeItem));
+}
+
+function valueToAttribute(key: string, value: unknown): LogAttribute {
+ switch (typeof value) {
+ case 'number':
+ return {
+ key,
+ value: { doubleValue: value },
+ };
+ case 'boolean':
+ return {
+ key,
+ value: { boolValue: value },
+ };
+ case 'string':
+ return {
+ key,
+ value: { stringValue: value },
+ };
+ default:
+ return {
+ key,
+ value: { stringValue: JSON.stringify(value) ?? '' },
+ };
+ }
+}
+
+function addToLogBuffer(client: Client, log: Log, scope: Scope): void {
+ function sendLogs(flushedLogs: Log[]): void {
+ const envelope = createLogEnvelope(flushedLogs, client, scope);
+ // eslint-disable-next-line @typescript-eslint/no-floating-promises
+ void client.sendEnvelope(envelope);
+ }
+
+ if (GLOBAL_LOG_BUFFER.length >= LOG_BUFFER_MAX_LENGTH) {
+ sendLogs(GLOBAL_LOG_BUFFER);
+ GLOBAL_LOG_BUFFER = [];
+ } else {
+ GLOBAL_LOG_BUFFER.push(log);
+ }
+
+ // this is the first time logs have been enabled, let's kick off an interval to flush them
+ // we should only do this once.
+ if (!isFlushingLogs) {
+ setInterval(() => {
+ if (GLOBAL_LOG_BUFFER.length > 0) {
+ sendLogs(GLOBAL_LOG_BUFFER);
+ GLOBAL_LOG_BUFFER = [];
+ }
+ }, 5000);
+ }
+ isFlushingLogs = true;
+}
+
+/**
+ * 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 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);
+}
+
+/**
+ * Sends a log to Sentry.
+ */
+export function captureLog(
+ level: LogSeverityLevel,
+ message: string,
+ customAttributes: Record<string, unknown> = {},
+ severityNumber?: number,
+): void {
+ const client = getClient();
+
+ if (!client) {
+ DEBUG_BUILD && logger.warn('No client available, log will not be captured.');
+ return;
+ }
+
+ if (!client.getOptions()._experiments?.enableLogs) {
+ DEBUG_BUILD && logger.warn('logging option not enabled, log will not be captured.');
+ return;
+ }
+
+ const { release, environment } = client.getOptions();
+
+ const logAttributes = {
+ ...customAttributes,
+ };
+
+ if (release) {
+ logAttributes['sentry.release'] = release;
+ }
+
+ if (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,
+ timeUnixNano: `${new Date().getTime().toString()}000000`,
+ traceId: scope.getPropagationContext().traceId,
+ severityNumber,
+ };
+
+ const maybeSeverityNumber = SEVERITY_TEXT_TO_SEVERITY_NUMBER[level];
+ if (maybeSeverityNumber !== undefined && log.severityNumber === undefined) {
+ log.severityNumber = maybeSeverityNumber;
+ }
+
+ addToLogBuffer(client, log, scope);
+}

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

@@ -182,7 +182,12 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
  * Options which are in beta, or otherwise not guaranteed to be stable.
  */
  _experiments?: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
  [key: string]: any;
+ /**
+ * If logs support should be enabled. Defaults to false.
+ */
+ enableLogs?: boolean;
  };
 
  /**

packages/eslint-config-sdk/src/base.js

@@ -84,7 +84,7 @@ module.exports = {
  // Make sure all expressions are used. Turned off in tests
  // Must disable base rule to prevent false positives
  'no-unused-expressions': 'off',
- '@typescript-eslint/no-unused-expressions': ['error', { allowShortCircuit: true }],
+ '@typescript-eslint/no-unused-expressions': ['error', { allowShortCircuit: true, allowTaggedTemplates: true }],
 
  // Make sure Promises are handled appropriately
  '@typescript-eslint/no-floating-promises': ['error', { ignoreVoid: false }],

.size-limit.js

@@ -8,7 +8,7 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init'),
  gzip: true,
- limit: '24 KB',
+ limit: '25 KB',
  },
  {
  name: '@sentry/browser - with treeshaking flags',
@@ -40,14 +40,14 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration'),
  gzip: true,
- limit: '37.5 KB',
+ limit: '38 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay)',
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration', 'replayIntegration'),
  gzip: true,
- limit: '75.2 KB',
+ limit: '77 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay) - with treeshaking flags',
@@ -79,7 +79,7 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration', 'replayIntegration', 'replayCanvasIntegration'),
  gzip: true,
- limit: '80 KB',
+ limit: '82 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay, Feedback)',
@@ -210,7 +210,7 @@ module.exports = [
  import: createImport('init'),
  ignore: ['next/router', 'next/constants'],
  gzip: true,
- limit: '41 KB',
+ limit: '43 KB',
  },
  // SvelteKit SDK (ESM)
  {

CHANGELOG.md

@@ -10,6 +10,36 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+## 9.4.0-alpha.0
+
+This is an alpha release that includes experimental functionality for the new logs API in Sentry. Support for these methods are only avaliable in the browser and core SDKs.
+
+- feat(logs): Add experimental user-callable logging methods (#15442)
+
+Logging is gated by an experimental option, `_experiments.enableLogs`.
+
+```js
+Sentry.init({
+ _experiments: {
+ enableLogs: true,
+ },
+});
+```
+
+These API are exposed in the `Sentry._experiment_log` namespace.
+
+On the high level, there are functions for each of the logging severity levels `critical`, `fatal`, `error`, `warn`, `info`, `debug`, `trace`. These functions are tagged template functions, so they use a special string template syntax that we use to parameterize functions accordingly.
+
+```js
+Sentry._experiment_log.info`user ${username} just bought ${item}!`;
+```
+
+If you want more custom usage, we also expose a `captureLog` method that allows you to pass custom attributes, but it's less easy to use than the tagged template functions.
+
+```js
+Sentry._experiment_log.captureLog('error', 'Hello world!', { 'user.id': 123 });
+```
+
 ## 9.3.0
 
 ### Important Changes

packages/browser/src/index.ts

@@ -10,6 +10,7 @@ export {
  extraErrorDataIntegration,
  rewriteFramesIntegration,
  captureFeedback,
+ _experiment_log,
 } from '@sentry/core';
 
 export { replayIntegration, getReplay } from '@sentry-internal/replay';

packages/core/src/exports.ts

@@ -1,5 +1,6 @@
 import { getClient, getCurrentScope, getIsolationScope, withIsolationScope } from './currentScopes';
 import { DEBUG_BUILD } from './debug-build';
+import { captureLog, sendLog } from './log';
 import type { CaptureContext } from './scope';
 import { closeSession, makeSession, updateSession } from './session';
 import type {
@@ -10,6 +11,7 @@ import type {
  Extra,
  Extras,
  FinishedCheckIn,
+ LogSeverityLevel,
  MonitorConfig,
  Primitive,
  Session,
@@ -334,3 +336,68 @@ export function captureSession(end: boolean = false): void {
  // only send the update
  _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: sendLog.bind(null, 'info') 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.log`user ${username} just bought ${item}!`
+ */
+ log: sendLog.bind(null, 'log') 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: 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: 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/index.ts

@@ -29,6 +29,7 @@ export {
  endSession,
  captureSession,
  addEventProcessor,
+ _experiment_log,
 } from './exports';
 export {
  getCurrentScope,

packages/core/src/log.ts

@@ -0,0 +1,188 @@
+import type { Client } from './client';
+import { getClient, getCurrentScope } from './currentScopes';
+import { DEBUG_BUILD } from './debug-build';
+import type { Scope } from './scope';
+import { getDynamicSamplingContextFromScope } from './tracing';
+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';
+
+const LOG_BUFFER_MAX_LENGTH = 25;
+
+let GLOBAL_LOG_BUFFER: Log[] = [];
+
+let isFlushingLogs = false;
+
+const SEVERITY_TEXT_TO_SEVERITY_NUMBER: Partial<Record<LogSeverityLevel | 'log', number>> = {
+ trace: 1,
+ debug: 5,
+ info: 9,
+ log: 10,
+ warn: 13,
+ error: 17,
+ fatal: 21,
+};
+
+/**
+ * Creates envelope item for a single log
+ */
+export function createLogEnvelopeItem(log: Log): LogItem {
+ const headers: LogItem[0] = {
+ type: 'otel_log',
+ };
+
+ return [headers, log];
+}
+
+/**
+ * Records a log and sends it to sentry.
+ *
+ * Logs represent a message (and optionally some structured data) which provide context for a trace or error.
+ * Ex: sentry.addLog({level: 'warning', message: `user ${user} just bought ${item}`, attributes: {user, item}}
+ *
+ * @params log - the log object which will be sent
+ */
+function createLogEnvelope(logs: Log[], client: Client, scope: Scope): LogEnvelope {
+ const dsc = getDynamicSamplingContextFromScope(client, scope);
+
+ const dsn = client.getDsn();
+
+ const headers: LogEnvelope[0] = {
+ trace: dropUndefinedKeys(dsc) as DynamicSamplingContext,
+ ...(dsn ? { dsn: dsnToString(dsn) } : {}),
+ };
+
+ return createEnvelope<LogEnvelope>(headers, logs.map(createLogEnvelopeItem));
+}
+
+function valueToAttribute(key: string, value: unknown): LogAttribute {
+ switch (typeof value) {
+ case 'number':
+ return {
+ key,
+ value: { doubleValue: value },
+ };
+ case 'boolean':
+ return {
+ key,
+ value: { boolValue: value },
+ };
+ case 'string':
+ return {
+ key,
+ value: { stringValue: value },
+ };
+ default:
+ return {
+ key,
+ value: { stringValue: JSON.stringify(value) ?? '' },
+ };
+ }
+}
+
+function addToLogBuffer(client: Client, log: Log, scope: Scope): void {
+ function sendLogs(flushedLogs: Log[]): void {
+ const envelope = createLogEnvelope(flushedLogs, client, scope);
+ // eslint-disable-next-line @typescript-eslint/no-floating-promises
+ void client.sendEnvelope(envelope);
+ }
+
+ if (GLOBAL_LOG_BUFFER.length >= LOG_BUFFER_MAX_LENGTH) {
+ sendLogs(GLOBAL_LOG_BUFFER);
+ GLOBAL_LOG_BUFFER = [];
+ } else {
+ GLOBAL_LOG_BUFFER.push(log);
+ }
+
+ // this is the first time logs have been enabled, let's kick off an interval to flush them
+ // we should only do this once.
+ if (!isFlushingLogs) {
+ setInterval(() => {
+ if (GLOBAL_LOG_BUFFER.length > 0) {
+ sendLogs(GLOBAL_LOG_BUFFER);
+ GLOBAL_LOG_BUFFER = [];
+ }
+ }, 5000);
+ }
+ isFlushingLogs = true;
+}
+
+/**
+ * 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 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);
+}
+
+/**
+ * Sends a log to Sentry.
+ */
+export function captureLog(
+ level: LogSeverityLevel,
+ message: string,
+ customAttributes: Record<string, unknown> = {},
+ severityNumber?: number,
+): void {
+ const client = getClient();
+
+ if (!client) {
+ DEBUG_BUILD && logger.warn('No client available, log will not be captured.');
+ return;
+ }
+
+ if (!client.getOptions()._experiments?.enableLogs) {
+ DEBUG_BUILD && logger.warn('logging option not enabled, log will not be captured.');
+ return;
+ }
+
+ const { release, environment } = client.getOptions();
+
+ const logAttributes = {
+ ...customAttributes,
+ };
+
+ if (release) {
+ logAttributes['sentry.release'] = release;
+ }
+
+ if (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,
+ timeUnixNano: `${new Date().getTime().toString()}000000`,
+ traceId: scope.getPropagationContext().traceId,
+ severityNumber,
+ };
+
+ const maybeSeverityNumber = SEVERITY_TEXT_TO_SEVERITY_NUMBER[level];
+ if (maybeSeverityNumber !== undefined && log.severityNumber === undefined) {
+ log.severityNumber = maybeSeverityNumber;
+ }
+
+ addToLogBuffer(client, log, scope);
+}

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

@@ -182,7 +182,12 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
  * Options which are in beta, or otherwise not guaranteed to be stable.
  */
  _experiments?: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
  [key: string]: any;
+ /**
+ * If logs support should be enabled. Defaults to false.
+ */
+ enableLogs?: boolean;
  };
 
  /**

packages/eslint-config-sdk/src/base.js

@@ -84,7 +84,7 @@ module.exports = {
  // Make sure all expressions are used. Turned off in tests
  // Must disable base rule to prevent false positives
  'no-unused-expressions': 'off',
- '@typescript-eslint/no-unused-expressions': ['error', { allowShortCircuit: true }],
+ '@typescript-eslint/no-unused-expressions': ['error', { allowShortCircuit: true, allowTaggedTemplates: true }],
 
  // Make sure Promises are handled appropriately
  '@typescript-eslint/no-floating-promises': ['error', { ignoreVoid: false }],

.size-limit.js

@@ -8,7 +8,7 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init'),
  gzip: true,
- limit: '24 KB',
+ limit: '25 KB',
  },
  {
  name: '@sentry/browser - with treeshaking flags',
@@ -40,14 +40,14 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration'),
  gzip: true,
- limit: '37.5 KB',
+ limit: '38 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay)',
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration', 'replayIntegration'),
  gzip: true,
- limit: '75.2 KB',
+ limit: '77 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay) - with treeshaking flags',
@@ -79,7 +79,7 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration', 'replayIntegration', 'replayCanvasIntegration'),
  gzip: true,
- limit: '80 KB',
+ limit: '82 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay, Feedback)',
@@ -210,7 +210,7 @@ module.exports = [
  import: createImport('init'),
  ignore: ['next/router', 'next/constants'],
  gzip: true,
- limit: '41 KB',
+ limit: '43 KB',
  },
  // SvelteKit SDK (ESM)
  {

CHANGELOG.md

@@ -10,6 +10,36 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+## 9.4.0-alpha.0
+
+This is an alpha release that includes experimental functionality for the new logs API in Sentry. Support for these methods are only avaliable in the browser and core SDKs.
+
+- feat(logs): Add experimental user-callable logging methods (#15442)
+
+Logging is gated by an experimental option, `_experiments.enableLogs`.
+
+```js
+Sentry.init({
+ _experiments: {
+ enableLogs: true,
+ },
+});
+```
+
+These API are exposed in the `Sentry._experiment_log` namespace.
+
+On the high level, there are functions for each of the logging severity levels `critical`, `fatal`, `error`, `warn`, `info`, `debug`, `trace`. These functions are tagged template functions, so they use a special string template syntax that we use to parameterize functions accordingly.
+
+```js
+Sentry._experiment_log.info`user ${username} just bought ${item}!`;
+```
+
+If you want more custom usage, we also expose a `captureLog` method that allows you to pass custom attributes, but it's less easy to use than the tagged template functions.
+
+```js
+Sentry._experiment_log.captureLog('error', 'Hello world!', { 'user.id': 123 });
+```
+
 ## 9.3.0
 
 ### Important Changes

packages/browser/src/index.ts

@@ -10,6 +10,7 @@ export {
  extraErrorDataIntegration,
  rewriteFramesIntegration,
  captureFeedback,
+ _experiment_log,
 } from '@sentry/core';
 
 export { replayIntegration, getReplay } from '@sentry-internal/replay';

packages/core/src/exports.ts

@@ -1,5 +1,6 @@
 import { getClient, getCurrentScope, getIsolationScope, withIsolationScope } from './currentScopes';
 import { DEBUG_BUILD } from './debug-build';
+import { captureLog, sendLog } from './log';
 import type { CaptureContext } from './scope';
 import { closeSession, makeSession, updateSession } from './session';
 import type {
@@ -10,6 +11,7 @@ import type {
  Extra,
  Extras,
  FinishedCheckIn,
+ LogSeverityLevel,
  MonitorConfig,
  Primitive,
  Session,
@@ -334,3 +336,68 @@ export function captureSession(end: boolean = false): void {
  // only send the update
  _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: sendLog.bind(null, 'info') 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.log`user ${username} just bought ${item}!`
+ */
+ log: sendLog.bind(null, 'log') 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: 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: 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/index.ts

@@ -29,6 +29,7 @@ export {
  endSession,
  captureSession,
  addEventProcessor,
+ _experiment_log,
 } from './exports';
 export {
  getCurrentScope,

packages/core/src/log.ts

@@ -0,0 +1,188 @@
+import type { Client } from './client';
+import { getClient, getCurrentScope } from './currentScopes';
+import { DEBUG_BUILD } from './debug-build';
+import type { Scope } from './scope';
+import { getDynamicSamplingContextFromScope } from './tracing';
+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';
+
+const LOG_BUFFER_MAX_LENGTH = 25;
+
+let GLOBAL_LOG_BUFFER: Log[] = [];
+
+let isFlushingLogs = false;
+
+const SEVERITY_TEXT_TO_SEVERITY_NUMBER: Partial<Record<LogSeverityLevel | 'log', number>> = {
+ trace: 1,
+ debug: 5,
+ info: 9,
+ log: 10,
+ warn: 13,
+ error: 17,
+ fatal: 21,
+};
+
+/**
+ * Creates envelope item for a single log
+ */
+export function createLogEnvelopeItem(log: Log): LogItem {
+ const headers: LogItem[0] = {
+ type: 'otel_log',
+ };
+
+ return [headers, log];
+}
+
+/**
+ * Records a log and sends it to sentry.
+ *
+ * Logs represent a message (and optionally some structured data) which provide context for a trace or error.
+ * Ex: sentry.addLog({level: 'warning', message: `user ${user} just bought ${item}`, attributes: {user, item}}
+ *
+ * @params log - the log object which will be sent
+ */
+function createLogEnvelope(logs: Log[], client: Client, scope: Scope): LogEnvelope {
+ const dsc = getDynamicSamplingContextFromScope(client, scope);
+
+ const dsn = client.getDsn();
+
+ const headers: LogEnvelope[0] = {
+ trace: dropUndefinedKeys(dsc) as DynamicSamplingContext,
+ ...(dsn ? { dsn: dsnToString(dsn) } : {}),
+ };
+
+ return createEnvelope<LogEnvelope>(headers, logs.map(createLogEnvelopeItem));
+}
+
+function valueToAttribute(key: string, value: unknown): LogAttribute {
+ switch (typeof value) {
+ case 'number':
+ return {
+ key,
+ value: { doubleValue: value },
+ };
+ case 'boolean':
+ return {
+ key,
+ value: { boolValue: value },
+ };
+ case 'string':
+ return {
+ key,
+ value: { stringValue: value },
+ };
+ default:
+ return {
+ key,
+ value: { stringValue: JSON.stringify(value) ?? '' },
+ };
+ }
+}
+
+function addToLogBuffer(client: Client, log: Log, scope: Scope): void {
+ function sendLogs(flushedLogs: Log[]): void {
+ const envelope = createLogEnvelope(flushedLogs, client, scope);
+ // eslint-disable-next-line @typescript-eslint/no-floating-promises
+ void client.sendEnvelope(envelope);
+ }
+
+ if (GLOBAL_LOG_BUFFER.length >= LOG_BUFFER_MAX_LENGTH) {
+ sendLogs(GLOBAL_LOG_BUFFER);
+ GLOBAL_LOG_BUFFER = [];
+ } else {
+ GLOBAL_LOG_BUFFER.push(log);
+ }
+
+ // this is the first time logs have been enabled, let's kick off an interval to flush them
+ // we should only do this once.
+ if (!isFlushingLogs) {
+ setInterval(() => {
+ if (GLOBAL_LOG_BUFFER.length > 0) {
+ sendLogs(GLOBAL_LOG_BUFFER);
+ GLOBAL_LOG_BUFFER = [];
+ }
+ }, 5000);
+ }
+ isFlushingLogs = true;
+}
+
+/**
+ * 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 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);
+}
+
+/**
+ * Sends a log to Sentry.
+ */
+export function captureLog(
+ level: LogSeverityLevel,
+ message: string,
+ customAttributes: Record<string, unknown> = {},
+ severityNumber?: number,
+): void {
+ const client = getClient();
+
+ if (!client) {
+ DEBUG_BUILD && logger.warn('No client available, log will not be captured.');
+ return;
+ }
+
+ if (!client.getOptions()._experiments?.enableLogs) {
+ DEBUG_BUILD && logger.warn('logging option not enabled, log will not be captured.');
+ return;
+ }
+
+ const { release, environment } = client.getOptions();
+
+ const logAttributes = {
+ ...customAttributes,
+ };
+
+ if (release) {
+ logAttributes['sentry.release'] = release;
+ }
+
+ if (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,
+ timeUnixNano: `${new Date().getTime().toString()}000000`,
+ traceId: scope.getPropagationContext().traceId,
+ severityNumber,
+ };
+
+ const maybeSeverityNumber = SEVERITY_TEXT_TO_SEVERITY_NUMBER[level];
+ if (maybeSeverityNumber !== undefined && log.severityNumber === undefined) {
+ log.severityNumber = maybeSeverityNumber;
+ }
+
+ addToLogBuffer(client, log, scope);
+}

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

@@ -182,7 +182,12 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
  * Options which are in beta, or otherwise not guaranteed to be stable.
  */
  _experiments?: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
  [key: string]: any;
+ /**
+ * If logs support should be enabled. Defaults to false.
+ */
+ enableLogs?: boolean;
  };
 
  /**

packages/eslint-config-sdk/src/base.js

@@ -84,7 +84,7 @@ module.exports = {
  // Make sure all expressions are used. Turned off in tests
  // Must disable base rule to prevent false positives
  'no-unused-expressions': 'off',
- '@typescript-eslint/no-unused-expressions': ['error', { allowShortCircuit: true }],
+ '@typescript-eslint/no-unused-expressions': ['error', { allowShortCircuit: true, allowTaggedTemplates: true }],
 
  // Make sure Promises are handled appropriately
  '@typescript-eslint/no-floating-promises': ['error', { ignoreVoid: false }],

.size-limit.js

@@ -8,7 +8,7 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init'),
  gzip: true,
- limit: '24 KB',
+ limit: '25 KB',
  },
  {
  name: '@sentry/browser - with treeshaking flags',
@@ -40,14 +40,14 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration'),
  gzip: true,
- limit: '37.5 KB',
+ limit: '38 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay)',
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration', 'replayIntegration'),
  gzip: true,
- limit: '75.2 KB',
+ limit: '77 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay) - with treeshaking flags',
@@ -79,7 +79,7 @@ module.exports = [
  path: 'packages/browser/build/npm/esm/index.js',
  import: createImport('init', 'browserTracingIntegration', 'replayIntegration', 'replayCanvasIntegration'),
  gzip: true,
- limit: '80 KB',
+ limit: '82 KB',
  },
  {
  name: '@sentry/browser (incl. Tracing, Replay, Feedback)',
@@ -210,7 +210,7 @@ module.exports = [
  import: createImport('init'),
  ignore: ['next/router', 'next/constants'],
  gzip: true,
- limit: '41 KB',
+ limit: '43 KB',
  },
  // SvelteKit SDK (ESM)
  {

CHANGELOG.md

@@ -10,6 +10,36 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+## 9.4.0-alpha.0
+
+This is an alpha release that includes experimental functionality for the new logs API in Sentry. Support for these methods are only avaliable in the browser and core SDKs.
+
+- feat(logs): Add experimental user-callable logging methods (#15442)
+
+Logging is gated by an experimental option, `_experiments.enableLogs`.
+
+```js
+Sentry.init({
+ _experiments: {
+ enableLogs: true,
+ },
+});
+```
+
+These API are exposed in the `Sentry._experiment_log` namespace.
+
+On the high level, there are functions for each of the logging severity levels `critical`, `fatal`, `error`, `warn`, `info`, `debug`, `trace`. These functions are tagged template functions, so they use a special string template syntax that we use to parameterize functions accordingly.
+
+```js
+Sentry._experiment_log.info`user ${username} just bought ${item}!`;
+```
+
+If you want more custom usage, we also expose a `captureLog` method that allows you to pass custom attributes, but it's less easy to use than the tagged template functions.
+
+```js
+Sentry._experiment_log.captureLog('error', 'Hello world!', { 'user.id': 123 });
+```
+
 ## 9.3.0
 
 ### Important Changes

packages/browser/src/index.ts

@@ -10,6 +10,7 @@ export {
  extraErrorDataIntegration,
  rewriteFramesIntegration,
  captureFeedback,
+ _experiment_log,
 } from '@sentry/core';
 
 export { replayIntegration, getReplay } from '@sentry-internal/replay';

packages/core/src/exports.ts

@@ -1,5 +1,6 @@
 import { getClient, getCurrentScope, getIsolationScope, withIsolationScope } from './currentScopes';
 import { DEBUG_BUILD } from './debug-build';
+import { captureLog, sendLog } from './log';
 import type { CaptureContext } from './scope';
 import { closeSession, makeSession, updateSession } from './session';
 import type {
@@ -10,6 +11,7 @@ import type {
  Extra,
  Extras,
  FinishedCheckIn,
+ LogSeverityLevel,
  MonitorConfig,
  Primitive,
  Session,
@@ -334,3 +336,68 @@ export function captureSession(end: boolean = false): void {
  // only send the update
  _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: sendLog.bind(null, 'info') 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.log`user ${username} just bought ${item}!`
+ */
+ log: sendLog.bind(null, 'log') 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: 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: 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/index.ts

@@ -29,6 +29,7 @@ export {
  endSession,
  captureSession,
  addEventProcessor,
+ _experiment_log,
 } from './exports';
 export {
  getCurrentScope,

packages/core/src/log.ts

@@ -0,0 +1,188 @@
+import type { Client } from './client';
+import { getClient, getCurrentScope } from './currentScopes';
+import { DEBUG_BUILD } from './debug-build';
+import type { Scope } from './scope';
+import { getDynamicSamplingContextFromScope } from './tracing';
+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';
+
+const LOG_BUFFER_MAX_LENGTH = 25;
+
+let GLOBAL_LOG_BUFFER: Log[] = [];
+
+let isFlushingLogs = false;
+
+const SEVERITY_TEXT_TO_SEVERITY_NUMBER: Partial<Record<LogSeverityLevel | 'log', number>> = {
+ trace: 1,
+ debug: 5,
+ info: 9,
+ log: 10,
+ warn: 13,
+ error: 17,
+ fatal: 21,
+};
+
+/**
+ * Creates envelope item for a single log
+ */
+export function createLogEnvelopeItem(log: Log): LogItem {
+ const headers: LogItem[0] = {
+ type: 'otel_log',
+ };
+
+ return [headers, log];
+}
+
+/**
+ * Records a log and sends it to sentry.
+ *
+ * Logs represent a message (and optionally some structured data) which provide context for a trace or error.
+ * Ex: sentry.addLog({level: 'warning', message: `user ${user} just bought ${item}`, attributes: {user, item}}
+ *
+ * @params log - the log object which will be sent
+ */
+function createLogEnvelope(logs: Log[], client: Client, scope: Scope): LogEnvelope {
+ const dsc = getDynamicSamplingContextFromScope(client, scope);
+
+ const dsn = client.getDsn();
+
+ const headers: LogEnvelope[0] = {
+ trace: dropUndefinedKeys(dsc) as DynamicSamplingContext,
+ ...(dsn ? { dsn: dsnToString(dsn) } : {}),
+ };
+
+ return createEnvelope<LogEnvelope>(headers, logs.map(createLogEnvelopeItem));
+}
+
+function valueToAttribute(key: string, value: unknown): LogAttribute {
+ switch (typeof value) {
+ case 'number':
+ return {
+ key,
+ value: { doubleValue: value },
+ };
+ case 'boolean':
+ return {
+ key,
+ value: { boolValue: value },
+ };
+ case 'string':
+ return {
+ key,
+ value: { stringValue: value },
+ };
+ default:
+ return {
+ key,
+ value: { stringValue: JSON.stringify(value) ?? '' },
+ };
+ }
+}
+
+function addToLogBuffer(client: Client, log: Log, scope: Scope): void {
+ function sendLogs(flushedLogs: Log[]): void {
+ const envelope = createLogEnvelope(flushedLogs, client, scope);
+ // eslint-disable-next-line @typescript-eslint/no-floating-promises
+ void client.sendEnvelope(envelope);
+ }
+
+ if (GLOBAL_LOG_BUFFER.length >= LOG_BUFFER_MAX_LENGTH) {
+ sendLogs(GLOBAL_LOG_BUFFER);
+ GLOBAL_LOG_BUFFER = [];
+ } else {
+ GLOBAL_LOG_BUFFER.push(log);
+ }
+
+ // this is the first time logs have been enabled, let's kick off an interval to flush them
+ // we should only do this once.
+ if (!isFlushingLogs) {
+ setInterval(() => {
+ if (GLOBAL_LOG_BUFFER.length > 0) {
+ sendLogs(GLOBAL_LOG_BUFFER);
+ GLOBAL_LOG_BUFFER = [];
+ }
+ }, 5000);
+ }
+ isFlushingLogs = true;
+}
+
+/**
+ * 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 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);
+}
+
+/**
+ * Sends a log to Sentry.
+ */
+export function captureLog(
+ level: LogSeverityLevel,
+ message: string,
+ customAttributes: Record<string, unknown> = {},
+ severityNumber?: number,
+): void {
+ const client = getClient();
+
+ if (!client) {
+ DEBUG_BUILD && logger.warn('No client available, log will not be captured.');
+ return;
+ }
+
+ if (!client.getOptions()._experiments?.enableLogs) {
+ DEBUG_BUILD && logger.warn('logging option not enabled, log will not be captured.');
+ return;
+ }
+
+ const { release, environment } = client.getOptions();
+
+ const logAttributes = {
+ ...customAttributes,
+ };
+
+ if (release) {
+ logAttributes['sentry.release'] = release;
+ }
+
+ if (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,
+ timeUnixNano: `${new Date().getTime().toString()}000000`,
+ traceId: scope.getPropagationContext().traceId,
+ severityNumber,
+ };
+
+ const maybeSeverityNumber = SEVERITY_TEXT_TO_SEVERITY_NUMBER[level];
+ if (maybeSeverityNumber !== undefined && log.severityNumber === undefined) {
+ log.severityNumber = maybeSeverityNumber;
+ }
+
+ addToLogBuffer(client, log, scope);
+}

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

@@ -182,7 +182,12 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
  * Options which are in beta, or otherwise not guaranteed to be stable.
  */
  _experiments?: {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
  [key: string]: any;
+ /**
+ * If logs support should be enabled. Defaults to false.
+ */
+ enableLogs?: boolean;
  };
 
  /**

packages/eslint-config-sdk/src/base.js

@@ -84,7 +84,7 @@ module.exports = {
  // Make sure all expressions are used. Turned off in tests
  // Must disable base rule to prevent false positives
  'no-unused-expressions': 'off',
- '@typescript-eslint/no-unused-expressions': ['error', { allowShortCircuit: true }],
+ '@typescript-eslint/no-unused-expressions': ['error', { allowShortCircuit: true, allowTaggedTemplates: true }],
 
  // Make sure Promises are handled appropriately
  '@typescript-eslint/no-floating-promises': ['error', { ignoreVoid: false }],