feat(core): Add captureLog method (#15717)

## Description

`captureLog` takes in a `log` interface as well as a scope, and
constructs a serialized log to send to Sentry. Instead of directly
sending the serialized log, it adds it to a log buffer that is flushed
based on some strategy. As a fallback, the buffer flushes itself when it
gets over 100 items, which ensures we never get a payload thats too
large.

The browser and server runtime client are expected to add more advanced
flushing strategies on top of the simple implementation exposed in
`captureLog`. This will be done in future PRs.

The serialized log that is constructed by `captureLog` send logs via the
opentelemetry format. This is temporary, in the future we'll switch to
the sentry logs protocol, but while that gets ready we are using the
OTEL one.

## Next steps

1. Add flushing strategy for server-runtime-client
2. Implement top-level API methods as per develop spec
3. Add support for paramaterized strings
4. Add integration tests to validate envelope gets sent correctly

Author: AbhiPrasad

.size-limit.js

@@ -47,7 +47,7 @@ module.exports = [
     path: 'packages/browser/build/npm/esm/index.js',
     import: createImport('init', 'browserTracingIntegration', 'replayIntegration'),
     gzip: true,
-    limit: '75.2 KB',
+    limit: '75.5 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: '80.5 KB',
   },
   {
     name: '@sentry/browser (incl. Tracing, Replay, Feedback)',

packages/browser/src/client.ts

@@ -15,6 +15,7 @@ import {
   addAutoIpAddressToUser,
   applySdkMetadata,
   getSDKSource,
+  _INTERNAL_flushLogsBuffer,
 } from '@sentry/core';
 import { eventFromException, eventFromMessage } from './eventbuilder';
 import { WINDOW } from './helpers';
@@ -85,6 +86,9 @@ export class BrowserClient extends Client<BrowserClientOptions> {
       WINDOW.document.addEventListener('visibilitychange', () => {
         if (WINDOW.document.visibilityState === 'hidden') {
           this._flushOutcomes();
+          if (this._options._experiments?.enableLogs) {
+            _INTERNAL_flushLogsBuffer(this);
+          }
         }
       });
     }

packages/core/src/client.ts

@@ -28,6 +28,7 @@ import type {
   SpanContextData,
   SpanJSON,
   StartSpanOptions,
+  TraceContext,
   TransactionEvent,
   Transport,
   TransportMakeRequestResponse,
@@ -44,7 +45,10 @@ import { afterSetupIntegrations } from './integration';
 import { setupIntegration, setupIntegrations } from './integration';
 import type { Scope } from './scope';
 import { updateSession } from './session';
-import { getDynamicSamplingContextFromScope } from './tracing/dynamicSamplingContext';
+import {
+  getDynamicSamplingContextFromScope,
+  getDynamicSamplingContextFromSpan,
+} from './tracing/dynamicSamplingContext';
 import { createClientReportEnvelope } from './utils-hoist/clientreport';
 import { dsnToString, makeDsn } from './utils-hoist/dsn';
 import { addItemToEnvelope, createAttachmentEnvelopeItem } from './utils-hoist/envelope';
@@ -57,8 +61,9 @@ import { getPossibleEventMessages } from './utils/eventUtils';
 import { merge } from './utils/merge';
 import { parseSampleRate } from './utils/parseSampleRate';
 import { prepareEvent } from './utils/prepareEvent';
-import { showSpanDropWarning } from './utils/spanUtils';
+import { showSpanDropWarning, spanToTraceContext } from './utils/spanUtils';
 import { convertSpanJsonToTransactionEvent, convertTransactionEventToSpanJson } from './utils/transactionEvent';
+import { _getSpanForScope } from './utils/spanOnScope';
 
 const ALREADY_SEEN_ERROR = "Not capturing exception because it's already been captured.";
 const MISSING_RELEASE_FOR_SESSION_ERROR = 'Discarded session because of missing or non-string release';
@@ -617,7 +622,7 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
   public on(hook: 'close', callback: () => void): () => void;
 
   /**
-   * Register a hook oin this client.
+   * Register a hook on this client.
    */
   public on(hook: string, callback: unknown): () => void {
     const hooks = (this._hooks[hook] = this._hooks[hook] || []);
@@ -1256,3 +1261,20 @@ function isErrorEvent(event: Event): event is ErrorEvent {
 function isTransactionEvent(event: Event): event is TransactionEvent {
   return event.type === 'transaction';
 }
+
+/** Extract trace information from scope */
+export function _getTraceInfoFromScope(
+  client: Client,
+  scope: Scope | undefined,
+): [dynamicSamplingContext: Partial<DynamicSamplingContext> | undefined, traceContext: TraceContext | undefined] {
+  if (!scope) {
+    return [undefined, undefined];
+  }
+
+  const span = _getSpanForScope(scope);
+  const traceContext = span ? spanToTraceContext(span) : getTraceContextFromScope(scope);
+  const dynamicSamplingContext = span
+    ? getDynamicSamplingContextFromSpan(span)
+    : getDynamicSamplingContextFromScope(client, scope);
+  return [dynamicSamplingContext, traceContext];
+}

packages/core/src/index.ts

@@ -113,6 +113,7 @@ export { instrumentFetchRequest } from './fetch';
 export { trpcMiddleware } from './trpc';
 export { captureFeedback } from './feedback';
 export type { ReportDialogOptions } from './report-dialog';
+export { _INTERNAL_flushLogsBuffer } from './logs';
 
 // TODO: Make this structure pretty again and don't do "export *"
 export * from './utils-hoist/index';

packages/core/src/logs/constants.ts

@@ -0,0 +1,15 @@
+import type { LogSeverityLevel } from '../types-hoist';
+
+/**
+ * Maps a log severity level to a log severity number.
+ *
+ * @see LogSeverityLevel
+ */
+export const SEVERITY_TEXT_TO_SEVERITY_NUMBER: Partial<Record<LogSeverityLevel, number>> = {
+  trace: 1,
+  debug: 5,
+  info: 9,
+  warn: 13,
+  error: 17,
+  fatal: 21,
+};

packages/core/src/logs/envelope.ts

@@ -0,0 +1,51 @@
+import { createEnvelope } from '../utils-hoist';
+
+import type { DsnComponents, SdkMetadata, SerializedOtelLog } from '../types-hoist';
+import type { OtelLogEnvelope, OtelLogItem } from '../types-hoist/envelope';
+import { dsnToString } from '../utils-hoist';
+
+/**
+ * Creates OTEL log envelope item for a serialized OTEL log.
+ *
+ * @param log - The serialized OTEL log to include in the envelope.
+ * @returns The created OTEL log envelope item.
+ */
+export function createOtelLogEnvelopeItem(log: SerializedOtelLog): OtelLogItem {
+  return [
+    {
+      type: 'otel_log',
+    },
+    log,
+  ];
+}
+
+/**
+ * Creates an envelope for a list of logs.
+ *
+ * @param logs - The logs to include in the envelope.
+ * @param metadata - The metadata to include in the envelope.
+ * @param tunnel - The tunnel to include in the envelope.
+ * @param dsn - The DSN to include in the envelope.
+ * @returns The created envelope.
+ */
+export function createOtelLogEnvelope(
+  logs: Array<SerializedOtelLog>,
+  metadata?: SdkMetadata,
+  tunnel?: string,
+  dsn?: DsnComponents,
+): OtelLogEnvelope {
+  const headers: OtelLogEnvelope[0] = {};
+
+  if (metadata?.sdk) {
+    headers.sdk = {
+      name: metadata.sdk.name,
+      version: metadata.sdk.version,
+    };
+  }
+
+  if (!!tunnel && !!dsn) {
+    headers.dsn = dsnToString(dsn);
+  }
+
+  return createEnvelope<OtelLogEnvelope>(headers, logs.map(createOtelLogEnvelopeItem));
+}

packages/core/src/logs/index.ts

@@ -0,0 +1,156 @@
+import type { Client } from '../client';
+import { _getTraceInfoFromScope } from '../client';
+import { getClient, getCurrentScope } from '../currentScopes';
+import { DEBUG_BUILD } from '../debug-build';
+import { SEVERITY_TEXT_TO_SEVERITY_NUMBER } from './constants';
+import type { SerializedLogAttribute, SerializedOtelLog } from '../types-hoist';
+import type { Log } from '../types-hoist/log';
+import { logger } from '../utils-hoist';
+import { _getSpanForScope } from '../utils/spanOnScope';
+import { createOtelLogEnvelope } from './envelope';
+
+const MAX_LOG_BUFFER_SIZE = 100;
+
+const CLIENT_TO_LOG_BUFFER_MAP = new WeakMap<Client, Array<SerializedOtelLog>>();
+
+/**
+ * Converts a log attribute to a serialized log attribute.
+ *
+ * @param key - The key of the log attribute.
+ * @param value - The value of the log attribute.
+ * @returns The serialized log attribute.
+ */
+export function logAttributeToSerializedLogAttribute(key: string, value: unknown): SerializedLogAttribute {
+  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: {
+      let stringValue = '';
+      try {
+        stringValue = JSON.stringify(value) ?? '';
+      } catch (_) {
+        // Do nothing
+      }
+      return {
+        key,
+        value: { stringValue },
+      };
+    }
+  }
+}
+
+/**
+ * Captures a log event and sends it to Sentry.
+ *
+ * @param log - The log event to capture.
+ * @param scope - A scope. Uses the current scope if not provided.
+ * @param client - A client. Uses the current client if not provided.
+ *
+ * @experimental This method will experience breaking changes. This is not yet part of
+ * the stable Sentry SDK API and can be changed or removed without warning.
+ */
+export function captureLog(log: Log, scope = getCurrentScope(), client = getClient()): void {
+  if (!client) {
+    DEBUG_BUILD && logger.warn('No client available to capture log.');
+    return;
+  }
+
+  const { _experiments, release, environment } = client.getOptions();
+  if (!_experiments?.enableLogs) {
+    DEBUG_BUILD && logger.warn('logging option not enabled, log will not be captured.');
+    return;
+  }
+
+  const [, traceContext] = _getTraceInfoFromScope(client, scope);
+
+  const { level, message, attributes, severityNumber } = log;
+
+  const logAttributes = {
+    ...attributes,
+  };
+
+  if (release) {
+    logAttributes.release = release;
+  }
+
+  if (environment) {
+    logAttributes.environment = environment;
+  }
+
+  const span = _getSpanForScope(scope);
+  if (span) {
+    // Add the parent span ID to the log attributes for trace context
+    logAttributes['sentry.trace.parent_span_id'] = span.spanContext().spanId;
+  }
+
+  const serializedLog: SerializedOtelLog = {
+    severityText: level,
+    body: {
+      stringValue: message,
+    },
+    attributes: Object.entries(logAttributes).map(([key, value]) => logAttributeToSerializedLogAttribute(key, value)),
+    timeUnixNano: `${new Date().getTime().toString()}000000`,
+    traceId: traceContext?.trace_id,
+    severityNumber: severityNumber ?? SEVERITY_TEXT_TO_SEVERITY_NUMBER[level],
+  };
+
+  const logBuffer = CLIENT_TO_LOG_BUFFER_MAP.get(client);
+  if (logBuffer === undefined) {
+    CLIENT_TO_LOG_BUFFER_MAP.set(client, [serializedLog]);
+    // Every time we initialize a new log buffer, we start a new interval to flush the buffer
+    return;
+  }
+
+  logBuffer.push(serializedLog);
+  if (logBuffer.length > MAX_LOG_BUFFER_SIZE) {
+    _INTERNAL_flushLogsBuffer(client, logBuffer);
+  }
+}
+
+/**
+ * Flushes the logs buffer to Sentry.
+ *
+ * @param client - A client.
+ * @param maybeLogBuffer - A log buffer. Uses the log buffer for the given client if not provided.
+ */
+export function _INTERNAL_flushLogsBuffer(client: Client, maybeLogBuffer?: Array<SerializedOtelLog>): void {
+  const logBuffer = maybeLogBuffer ?? CLIENT_TO_LOG_BUFFER_MAP.get(client) ?? [];
+  if (logBuffer.length === 0) {
+    return;
+  }
+
+  const clientOptions = client.getOptions();
+  const envelope = createOtelLogEnvelope(logBuffer, clientOptions._metadata, clientOptions.tunnel, client.getDsn());
+
+  // Clear the log buffer after envelopes have been constructed.
+  logBuffer.length = 0;
+
+  // sendEnvelope should not throw
+  // eslint-disable-next-line @typescript-eslint/no-floating-promises
+  client.sendEnvelope(envelope);
+}
+
+/**
+ * Returns the log buffer for a given client.
+ *
+ * Exported for testing purposes.
+ *
+ * @param client - The client to get the log buffer for.
+ * @returns The log buffer for the given client.
+ */
+export function _INTERNAL_getLogBuffer(client: Client): Array<SerializedOtelLog> | undefined {
+  return CLIENT_TO_LOG_BUFFER_MAP.get(client);
+}

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

@@ -2,32 +2,24 @@ import type {
   BaseTransportOptions,
   CheckIn,
   ClientOptions,
-  DynamicSamplingContext,
   Event,
   EventHint,
   MonitorConfig,
   ParameterizedString,
   SerializedCheckIn,
   SeverityLevel,
-  TraceContext,
 } from './types-hoist';
 
 import { createCheckInEnvelope } from './checkin';
-import { Client } from './client';
-import { getIsolationScope, getTraceContextFromScope } from './currentScopes';
+import { Client, _getTraceInfoFromScope } from './client';
+import { getIsolationScope } from './currentScopes';
 import { DEBUG_BUILD } from './debug-build';
 import type { Scope } from './scope';
-import {
-  getDynamicSamplingContextFromScope,
-  getDynamicSamplingContextFromSpan,
-  registerSpanErrorInstrumentation,
-} from './tracing';
+import { registerSpanErrorInstrumentation } from './tracing';
 import { eventFromMessage, eventFromUnknownInput } from './utils-hoist/eventbuilder';
 import { logger } from './utils-hoist/logger';
 import { uuid4 } from './utils-hoist/misc';
 import { resolvedSyncPromise } from './utils-hoist/syncpromise';
-import { _getSpanForScope } from './utils/spanOnScope';
-import { spanToTraceContext } from './utils/spanUtils';
 
 export interface ServerRuntimeClientOptions extends ClientOptions<BaseTransportOptions> {
   platform?: string;
@@ -136,7 +128,7 @@ export class ServerRuntimeClient<
       };
     }
 
-    const [dynamicSamplingContext, traceContext] = this._getTraceInfoFromScope(scope);
+    const [dynamicSamplingContext, traceContext] = _getTraceInfoFromScope(this, scope);
     if (traceContext) {
       serializedCheckIn.contexts = {
         trace: traceContext,
@@ -186,23 +178,6 @@ export class ServerRuntimeClient<
 
     return super._prepareEvent(event, hint, currentScope, isolationScope);
   }
-
-  /** Extract trace information from scope */
-  protected _getTraceInfoFromScope(
-    scope: Scope | undefined,
-  ): [dynamicSamplingContext: Partial<DynamicSamplingContext> | undefined, traceContext: TraceContext | undefined] {
-    if (!scope) {
-      return [undefined, undefined];
-    }
-
-    const span = _getSpanForScope(scope);
-
-    const traceContext = span ? spanToTraceContext(span) : getTraceContextFromScope(scope);
-    const dynamicSamplingContext = span
-      ? getDynamicSamplingContextFromSpan(span)
-      : getDynamicSamplingContextFromScope(this, scope);
-    return [dynamicSamplingContext, traceContext];
-  }
 }
 
 function setCurrentRequestSessionErroredOrCrashed(eventHint?: EventHint): void {