initial work on .log

Author: colin-sentry

packages/browser/src/index.ts

@@ -10,6 +10,9 @@ export {
   extraErrorDataIntegration,
   rewriteFramesIntegration,
   captureFeedback,
+  _experimentalLogError,
+  _experimentalLogInfo,
+  _experimentalLogWarning,
 } from '@sentry/core';
 
 export { replayIntegration, getReplay } from '@sentry-internal/replay';

packages/core/src/exports.ts

@@ -24,6 +24,7 @@ import { timestampInSeconds } from './utils-hoist/time';
 import { GLOBAL_OBJ } from './utils-hoist/worldwide';
 import type { ExclusiveEventHintOrCaptureContext } from './utils/prepareEvent';
 import { parseEventHintOrCaptureContext } from './utils/prepareEvent';
+import { captureLog } from './ourlogs';
 
 /**
  * Captures an exception event and sends it to Sentry.
@@ -334,3 +335,28 @@ export function captureSession(end: boolean = false): void {
   // only send the update
   _sendSessionUpdate();
 }
+
+
+/**
+ * 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.logInfo`user ${username} just bought ${item}!`
+ */
+export const _experimentalLogInfo = captureLog.bind(null, 'info');
+
+/**
+ * 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.logError`user ${username} just bought ${item}!`
+ */
+export const _experimentalLogError = captureLog.bind(null, 'error');
+
+/**
+ * A utility to record a log with level 'WARNING' and send it to sentry.
+ *
+ * Logs represent a message and some parameters which provide context for a trace or error.
+ * Ex: sentry.logWarning`user ${username} just bought ${item}!`
+ */
+export const _experimentalLogWarning = captureLog.bind(null, 'warning');

packages/core/src/index.ts

@@ -29,6 +29,9 @@ export {
   endSession,
   captureSession,
   addEventProcessor,
+  _experimentalLogError,
+  _experimentalLogInfo,
+  _experimentalLogWarning
 } from './exports';
 export {
   getCurrentScope,

packages/core/src/ourlogs.ts

@@ -0,0 +1,111 @@
+import { getClient, getGlobalScope } from './currentScopes';
+import type { LogEnvelope, LogItem } from './types-hoist/envelope';
+import type { Log, LogAttribute, LogSeverityLevel } from './types-hoist/ourlogs';
+import { createEnvelope, dsnToString } from './utils-hoist';
+
+/**
+ * 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 addLog(log: Log): void {
+  const client = getClient();
+
+  if (!client) {
+    return;
+  }
+
+  // if (!client.getOptions()._experiments?.logSupport) {
+  //   return;
+  // }
+
+  const globalScope = getGlobalScope();
+  const dsn = client.getDsn();
+
+  const headers: LogEnvelope[0] = {
+    trace: {
+      trace_id: globalScope.getPropagationContext().traceId,
+      public_key: dsn?.publicKey,
+    },
+    ...(dsn ? {dsn: dsnToString(dsn)} : {}),
+  }
+  if(!log.traceId) {
+    log.traceId = globalScope.getPropagationContext().traceId || '00000000-0000-0000-0000-000000000000';
+  }
+  if(!log.timeUnixNano) {
+    log.timeUnixNano = `${(new Date()).getTime().toString()}000000`;
+  }
+
+  const envelope = createEnvelope<LogEnvelope>(headers, [createLogEnvelopeItem(log)]);
+
+  client.sendEnvelope(envelope).then(null, ex => console.error(ex));
+}
+
+/**
+ * A utility function to be able to create methods like Sentry.info(...)
+ *
+ * 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 template, Sentry.info`hello ${world}`
+ */
+export function captureLog(level: LogSeverityLevel, strings: string[], ...values: unknown[]): void {
+  addLog({
+    severityText: level,
+    body: {
+      stringValue: strings.reduce((acc, str, i) => acc + str + (values[i] ?? ''), '' ),
+    },
+    attributes: values.map<LogAttribute>((value, index) => {
+      const key = `param${index}`;
+      if (typeof value === 'number') {
+        if(Number.isInteger(value)) {
+          return {
+            key,
+            value: {
+              intValue: value
+            }
+          }
+        }
+        return {
+          key,
+          value: {
+            doubleValue: value
+          }
+        }
+      } else if (typeof value === 'boolean') {
+        return {
+          key,
+          value: {
+            boolValue: value
+          }
+        }
+      } else if (typeof value === 'string') {
+        return {
+          key,
+          value: {
+            stringValue: value
+          }
+        }
+      } else {
+        return {
+          key,
+          value: {
+            stringValue: JSON.stringify(value)
+          }
+        }
+      }
+    }, {})
+  })
+}

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

@@ -10,6 +10,7 @@ import type { ReplayEvent, ReplayRecordingData } from './replay';
 import type { SdkInfo } from './sdkinfo';
 import type { SerializedSession, SessionAggregates } from './session';
 import type { SpanJSON } from './span';
+import { Log } from './ourlogs';
 
 // Based on: https://develop.sentry.dev/sdk/envelopes/
 
@@ -43,6 +44,7 @@ export type EnvelopeItemType =
   | 'replay_recording'
   | 'check_in'
   | 'span'
+  | 'otel_log'
   | 'raw_security';
 
 export type BaseEnvelopeHeaders = {
@@ -85,6 +87,7 @@ type CheckInItemHeaders = { type: 'check_in' };
 type ProfileItemHeaders = { type: 'profile' };
 type ProfileChunkItemHeaders = { type: 'profile_chunk' };
 type SpanItemHeaders = { type: 'span' };
+type LogItemHeaders = { type: 'otel_log' };
 type RawSecurityHeaders = { type: 'raw_security'; sentry_release?: string; sentry_environment?: string };
 
 export type EventItem = BaseEnvelopeItem<EventItemHeaders, Event>;
@@ -101,6 +104,7 @@ export type FeedbackItem = BaseEnvelopeItem<FeedbackItemHeaders, FeedbackEvent>;
 export type ProfileItem = BaseEnvelopeItem<ProfileItemHeaders, Profile>;
 export type ProfileChunkItem = BaseEnvelopeItem<ProfileChunkItemHeaders, ProfileChunk>;
 export type SpanItem = BaseEnvelopeItem<SpanItemHeaders, Partial<SpanJSON>>;
+export type LogItem = BaseEnvelopeItem<LogItemHeaders, Log>;
 export type RawSecurityItem = BaseEnvelopeItem<RawSecurityHeaders, LegacyCSPReport>;
 
 export type EventEnvelopeHeaders = { event_id: string; sent_at: string; trace?: Partial<DynamicSamplingContext> };
@@ -109,6 +113,7 @@ type CheckInEnvelopeHeaders = { trace?: DynamicSamplingContext };
 type ClientReportEnvelopeHeaders = BaseEnvelopeHeaders;
 type ReplayEnvelopeHeaders = BaseEnvelopeHeaders;
 type SpanEnvelopeHeaders = BaseEnvelopeHeaders & { trace?: DynamicSamplingContext };
+type LogEnvelopeHeaders = BaseEnvelopeHeaders & { trace?: DynamicSamplingContext };
 
 export type EventEnvelope = BaseEnvelope<
   EventEnvelopeHeaders,
@@ -121,6 +126,7 @@ export type CheckInEnvelope = BaseEnvelope<CheckInEnvelopeHeaders, CheckInItem>;
 export type SpanEnvelope = BaseEnvelope<SpanEnvelopeHeaders, SpanItem>;
 export type ProfileChunkEnvelope = BaseEnvelope<BaseEnvelopeHeaders, ProfileChunkItem>;
 export type RawSecurityEnvelope = BaseEnvelope<BaseEnvelopeHeaders, RawSecurityItem>;
+export type LogEnvelope = BaseEnvelope<LogEnvelopeHeaders, LogItem>;
 
 export type Envelope =
   | EventEnvelope
@@ -130,6 +136,7 @@ export type Envelope =
   | ReplayEnvelope
   | CheckInEnvelope
   | SpanEnvelope
-  | RawSecurityEnvelope;
+  | RawSecurityEnvelope
+  | LogEnvelope;
 
 export type EnvelopeItem = Envelope[1][number];

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

@@ -113,6 +113,12 @@ export type {
   SpanContextData,
   TraceFlag,
 } from './span';
+export type {
+  Log,
+  LogAttribute,
+  LogSeverityLevel,
+  LogAttributeValueType
+} from './ourlogs';
 export type { SpanStatus } from './spanStatus';
 export type { TimedEvent } from './timedEvent';
 export type { StackFrame } from './stackframe';

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

@@ -0,0 +1,67 @@
+import type { SeverityLevel } from './severity';
+
+export type LogSeverityLevel = SeverityLevel | 'critical' | 'trace';
+
+export type LogAttributeValueType = {
+  stringValue: string
+} | {
+  intValue: number
+} | {
+  boolValue: boolean
+} | {
+  doubleValue: number
+}
+
+export type LogAttribute = {
+  key: string,
+  value: LogAttributeValueType
+};
+
+export interface Log {
+  /**
+   * Allowed values are, from highest to lowest:
+   * `critical`, `fatal`, `error`, `warning`, `info`, `debug`, `trace`.
+   *
+   * The log level changes how logs are filtered and displayed.
+   * Critical level logs are emphasized more than trace level logs.
+   *
+   * @summary The severity level of the log.
+   */
+  severityText?: LogSeverityLevel;
+
+  /**
+   * The severity number - generally higher severity are levels like 'error' and lower are levels like 'debug'
+   */
+  severityNumber?: number;
+
+  /**
+   * OTEL trace flags (bitmap) - currently 1 means sampled, 0 means unsampled - for sentry always set to 0
+   */
+  traceFlags?: number;
+
+  /**
+   * The trace ID for this log
+   */
+  traceId?: string;
+
+  /**
+   * The message to be logged - for example, 'hello world' would become a log like '[INFO] hello world'
+   */
+  body: {
+    stringValue: string,
+  };
+
+  /**
+   * Arbitrary structured data that stores information about the log - e.g., userId: 100.
+   */
+  attributes?: LogAttribute[];
+
+  /**
+   * This doesn't have to be explicitly specified most of the time. If you need to set it, the value
+   * is the number of seconds since midnight on January 1, 1970 ("unix epoch time")
+   *
+   * @summary A timestamp representing when the log occurred.
+   * @link https://develop.sentry.dev/sdk/event-payloads/breadcrumbs/#:~:text=is%20info.-,timestamp,-(recommended)
+   */
+  timeUnixNano?: string;
+}

packages/core/src/utils-hoist/envelope.ts

@@ -223,6 +223,7 @@ const ITEM_TYPE_TO_DATA_CATEGORY_MAP: Record<EnvelopeItemType, DataCategory> = {
   feedback: 'feedback',
   span: 'span',
   raw_security: 'security',
+  otel_log: 'log_item',
 };
 
 /**