feat(core): Add client.captureLog method

Author: AbhiPrasad

packages/browser/src/client.ts

@@ -89,6 +89,12 @@ export class BrowserClient extends Client<BrowserClientOptions> {
       });
     }
 
+    if (opts._experiments?.enableLogs) {
+      setInterval(() => {
+        this._flushLogsBuffer();
+      }, 5000);
+    }
+
     if (this._options.sendDefaultPii) {
       this.on('postprocessEvent', addAutoIpAddressToUser);
       this.on('beforeSendSession', addAutoIpAddressToSession);

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,11 +61,15 @@ 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 type { Log, SerializedOtelLog } from './types-hoist/log';
+import { SEVERITY_TEXT_TO_SEVERITY_NUMBER, createOtelLogEnvelope, logAttributeToSerializedLogAttribute } from './log';
+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';
+const MAX_LOG_BUFFER_SIZE = 100;
 
 /**
  * Base implementation for all JavaScript SDK clients.
@@ -117,6 +125,8 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
   // eslint-disable-next-line @typescript-eslint/ban-types
   private _hooks: Record<string, Function[]>;
 
+  private _logsBuffer: Array<SerializedOtelLog>;
+
   /**
    * Initializes this client instance.
    *
@@ -129,6 +139,7 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
     this._outcomes = {};
     this._hooks = {};
     this._eventProcessors = [];
+    this._logsBuffer = [];
 
     if (options.dsn) {
       this._dsn = makeDsn(options.dsn);
@@ -256,6 +267,58 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
    */
   public captureCheckIn?(checkIn: CheckIn, monitorConfig?: MonitorConfig, scope?: Scope): string;
 
+  /**
+   * Captures a log event and sends it to Sentry.
+   *
+   * @param log The log event to capture.
+   *
+   * @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.
+   */
+  public captureLog({ level, message, attributes, severityNumber }: Log, currentScope = getCurrentScope()): void {
+    const { _experiments, release, environment } = this.getOptions();
+    if (!_experiments?.enableLogs) {
+      DEBUG_BUILD && logger.warn('logging option not enabled, log will not be captured.');
+      return;
+    }
+
+    const [, traceContext] = _getTraceInfoFromScope(this, currentScope);
+
+    const logAttributes = {
+      ...attributes,
+    };
+
+    if (release) {
+      logAttributes.release = release;
+    }
+
+    if (environment) {
+      logAttributes.environment = environment;
+    }
+
+    const span = _getSpanForScope(currentScope);
+    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],
+    };
+
+    this._logsBuffer.push(serializedLog);
+    if (this._logsBuffer.length > MAX_LOG_BUFFER_SIZE) {
+      this._flushLogsBuffer();
+    }
+  }
+
   /**
    * Get the current Dsn.
    */
@@ -295,6 +358,7 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
    * still events in the queue when the timeout is reached.
    */
   public flush(timeout?: number): PromiseLike<boolean> {
+    this._flushLogsBuffer();
     const transport = this._transport;
     if (transport) {
       this.emit('flush');
@@ -1136,6 +1200,21 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
     this.sendEnvelope(envelope);
   }
 
+  /**
+   * Flushes the logs buffer to Sentry.
+   */
+  protected _flushLogsBuffer(): void {
+    if (this._logsBuffer.length === 0) {
+      return;
+    }
+
+    const envelope = createOtelLogEnvelope(this._logsBuffer, this._options._metadata, this._options.tunnel, this._dsn);
+    this._logsBuffer = [];
+    // sendEnvelope should not throw
+    // eslint-disable-next-line @typescript-eslint/no-floating-promises
+    this.sendEnvelope(envelope);
+  }
+
   /**
    * Creates an {@link Event} from all inputs to `captureException` and non-primitive inputs to `captureMessage`.
    */
@@ -1256,3 +1335,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/log.ts

@@ -0,0 +1,91 @@
+import type {
+  DsnComponents,
+  LogSeverityLevel,
+  SdkMetadata,
+  SerializedLogAttribute,
+  SerializedOtelLog,
+} from './types-hoist';
+import type { OtelLogItem, OtelLogEnvelope } from './types-hoist/envelope';
+import { createEnvelope, dsnToString } from './utils-hoist';
+
+export const SEVERITY_TEXT_TO_SEVERITY_NUMBER: Partial<Record<LogSeverityLevel, number>> = {
+  trace: 1,
+  debug: 5,
+  info: 9,
+  warn: 13,
+  error: 17,
+  fatal: 21,
+};
+
+/**
+ * Convert 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:
+      return {
+        key,
+        value: { stringValue: JSON.stringify(value) ?? '' },
+      };
+  }
+}
+
+/**
+ * Creates envelope item for a single log
+ */
+export function createOtelLogEnvelopeItem(log: SerializedOtelLog): OtelLogItem {
+  const headers: OtelLogItem[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
+ */
+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/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 {

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

@@ -110,7 +110,12 @@ export type {
   TraceFlag,
 } from './span';
 export type { SpanStatus } from './spanStatus';
-export type { SerializedOtelLog, LogAttribute, LogSeverityLevel, LogAttributeValueType } from './log';
+export type {
+  LogSeverityLevel,
+  SerializedOtelLog,
+  SerializedLogAttribute,
+  SerializedLogAttributeValueType,
+} from './log';
 export type { TimedEvent } from './timedEvent';
 export type { StackFrame } from './stackframe';
 export type { Stacktrace, StackParser, StackLineParser, StackLineParserFn } from './stacktrace';