feat(node): Add logging public APIs to Node SDKs (#15764)

ref #15526

Continuing off the work from
#15763, this PR adds
the logging public API to the Node SDK. It also adds a basic
weight-based flushing strategy to the SDK that is in the server-runtime
client.

The main file added was `log.ts`. In that file I've added logger methods
for `trace`, `debug`, `info`, `warn`, `error`, `fatal` (the log severity
levels) as well as an internal capture log helper all these methods
call.

Usage:

```js
import * as Sentry from "@sentry/node";

Sentry.init({
  dsn: "your-dsn-here",
  _experiments: {
    enableLogs: true  // This is required to use the logging features
  }
});

// Trace level (lowest severity)
Sentry.logger.trace("This is a trace message", { userId: 123 });

// Debug level
Sentry.logger.debug("This is a debug message", { component: "UserProfile" });

// Info level
Sentry.logger.info("User %s logged in successfully", [123]);

// Warning level
Sentry.logger.warn("API response was slow", { responseTime: 2500 });

// Error level
Sentry.logger.error("Failed to load user %s data", [123], { errorCode: 404 });

// Critical level
Sentry.logger.critical("Database connection failed", { dbHost: "primary-db" });

// Fatal level (highest severity)
Sentry.logger.fatal("Application is shutting down unexpectedly", { memory: "exhausted" });
```

Author: AbhiPrasad

Diff for: packages/astro/src/index.server.ts

@@ -127,6 +127,7 @@ export {
   withScope,
   zodErrorsIntegration,
   profiler,
+  logger,
 } from '@sentry/node';
 
 export { init } from './server/sdk';

Diff for: packages/astro/src/index.types.ts

@@ -10,6 +10,7 @@ import type { NodeOptions } from '@sentry/node';
 import type { Client, Integration, Options, StackParser } from '@sentry/core';
 
 import type * as clientSdk from './index.client';
+import type * as serverSdk from './index.server';
 import sentryAstro from './index.server';
 
 /** Initializes Sentry Astro SDK */
@@ -26,4 +27,6 @@ export declare function flush(timeout?: number | undefined): PromiseLike<boolean
 
 export declare const Span: clientSdk.Span;
 
+export declare const logger: typeof clientSdk.logger | typeof serverSdk.logger;
+
 export default sentryAstro;

Diff for: packages/aws-serverless/src/index.ts

@@ -113,6 +113,7 @@ export {
   profiler,
   amqplibIntegration,
   vercelAIIntegration,
+  logger,
 } from '@sentry/node';
 
 export {

Diff for: packages/bun/src/index.ts

@@ -132,6 +132,7 @@ export {
   profiler,
   amqplibIntegration,
   vercelAIIntegration,
+  logger,
 } from '@sentry/node';
 
 export {

Diff for: packages/core/src/client.ts

@@ -16,6 +16,7 @@ import type {
   FeedbackEvent,
   FetchBreadcrumbHint,
   Integration,
+  Log,
   MonitorConfig,
   Outcome,
   ParameterizedString,
@@ -621,6 +622,13 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
    */
   public on(hook: 'close', callback: () => void): () => void;
 
+  /**
+   * A hook that is called before a log is captured
+   *
+   * @returns {() => void} A function that, when executed, removes the registered callback.
+   */
+  public on(hook: 'beforeCaptureLog', callback: (log: Log) => void): () => void;
+
   /**
    * Register a hook on this client.
    */
@@ -768,6 +776,11 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
    */
   public emit(hook: 'close'): void;
 
+  /**
+   * Emit a hook event for client before capturing a log
+   */
+  public emit(hook: 'beforeCaptureLog', log: Log): void;
+
   /**
    * Emit a hook that was previously registered via `on()`.
    */

Diff for: packages/core/src/logs/index.ts

@@ -110,14 +110,14 @@ export function _INTERNAL_captureLog(log: Log, client = getClient(), scope = get
   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;
+  } else {
+    logBuffer.push(serializedLog);
+    if (logBuffer.length > MAX_LOG_BUFFER_SIZE) {
+      _INTERNAL_flushLogsBuffer(client, logBuffer);
+    }
   }
 
-  logBuffer.push(serializedLog);
-  if (logBuffer.length > MAX_LOG_BUFFER_SIZE) {
-    _INTERNAL_flushLogsBuffer(client, logBuffer);
-  }
+  client.emit('beforeCaptureLog', log);
 }
 
 /**

Diff for: packages/core/src/server-runtime-client.ts

@@ -4,8 +4,10 @@ import type {
   ClientOptions,
   Event,
   EventHint,
+  Log,
   MonitorConfig,
   ParameterizedString,
+  Primitive,
   SerializedCheckIn,
   SeverityLevel,
 } from './types-hoist';
@@ -20,6 +22,8 @@ import { eventFromMessage, eventFromUnknownInput } from './utils-hoist/eventbuil
 import { logger } from './utils-hoist/logger';
 import { uuid4 } from './utils-hoist/misc';
 import { resolvedSyncPromise } from './utils-hoist/syncpromise';
+import { _INTERNAL_flushLogsBuffer } from './logs';
+import { isPrimitive } from './utils-hoist';
 
 export interface ServerRuntimeClientOptions extends ClientOptions<BaseTransportOptions> {
   platform?: string;
@@ -33,6 +37,8 @@ export interface ServerRuntimeClientOptions extends ClientOptions<BaseTransportO
 export class ServerRuntimeClient<
   O extends ClientOptions & ServerRuntimeClientOptions = ServerRuntimeClientOptions,
 > extends Client<O> {
+  private _logWeight: number;
+
   /**
    * Creates a new Edge SDK instance.
    * @param options Configuration options for this SDK.
@@ -42,6 +48,26 @@ export class ServerRuntimeClient<
     registerSpanErrorInstrumentation();
 
     super(options);
+
+    this._logWeight = 0;
+
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const client = this;
+    this.on('flush', () => {
+      _INTERNAL_flushLogsBuffer(client);
+    });
+
+    this.on('beforeCaptureLog', log => {
+      client._logWeight += estimateLogSizeInBytes(log);
+
+      // We flush the logs buffer if it exceeds 0.8 MB
+      // The log weight is a rough estimate, so we flush way before
+      // the payload gets too big.
+      if (client._logWeight > 800_000) {
+        _INTERNAL_flushLogsBuffer(client);
+        client._logWeight = 0;
+      }
+    });
   }
 
   /**
@@ -196,3 +222,45 @@ function setCurrentRequestSessionErroredOrCrashed(eventHint?: EventHint): void {
     }
   }
 }
+
+/**
+ * Estimate the size of a log in bytes.
+ *
+ * @param log - The log to estimate the size of.
+ * @returns The estimated size of the log in bytes.
+ */
+function estimateLogSizeInBytes(log: Log): number {
+  let weight = 0;
+
+  // Estimate byte size of 2 bytes per character. This is a rough estimate JS strings are stored as UTF-16.
+  if (log.message) {
+    weight += log.message.length * 2;
+  }
+
+  if (log.attributes) {
+    Object.values(log.attributes).forEach(value => {
+      if (Array.isArray(value)) {
+        weight += value.length * estimatePrimitiveSizeInBytes(value[0]);
+      } else if (isPrimitive(value)) {
+        weight += estimatePrimitiveSizeInBytes(value);
+      } else {
+        // For objects values, we estimate the size of the object as 100 bytes
+        weight += 100;
+      }
+    });
+  }
+
+  return weight;
+}
+
+function estimatePrimitiveSizeInBytes(value: Primitive): number {
+  if (typeof value === 'string') {
+    return value.length * 2;
+  } else if (typeof value === 'number') {
+    return 8;
+  } else if (typeof value === 'boolean') {
+    return 4;
+  }
+
+  return 0;
+}

Diff for: packages/core/src/types-hoist/log.ts

@@ -41,7 +41,7 @@ export interface Log {
   /**
    * Arbitrary structured data that stores information about the log - e.g., userId: 100.
    */
-  attributes?: Record<string, string | number | boolean | Array<string | number | boolean>>;
+  attributes?: Record<string, unknown>;
 
   /**
    * The severity number - generally higher severity are levels like 'error' and lower are levels like 'debug'

Diff for: packages/google-cloud-serverless/src/index.ts

@@ -113,6 +113,7 @@ export {
   amqplibIntegration,
   childProcessIntegration,
   vercelAIIntegration,
+  logger,
 } from '@sentry/node';
 
 export {

Diff for: packages/nextjs/src/index.types.ts

@@ -32,6 +32,8 @@ export declare const createReduxEnhancer: typeof clientSdk.createReduxEnhancer;
 export declare const showReportDialog: typeof clientSdk.showReportDialog;
 export declare const withErrorBoundary: typeof clientSdk.withErrorBoundary;
 
+export declare const logger: typeof clientSdk.logger | typeof serverSdk.logger;
+
 export { withSentryConfig } from './config';
 
 /**

Diff for: packages/node/src/index.ts

@@ -150,3 +150,7 @@ export type {
   User,
   Span,
 } from '@sentry/core';
+
+import * as logger from './log';
+
+export { logger };