@kubesense/kubesense-browser-logs 0.0.0-stage → 2.0.0-beta.1

package/src/entries/main.ts

@@ -0,0 +1,65 @@
+/**
+ *
+ * KubeSense Browser Logs SDK for collecting and forwarding browser logs to KubeSense.
+ * Provides comprehensive logging capabilities with automatic error tracking and custom log collection.
+ *
+ * @packageDocumentation
+ * @see [Browser Log Collection](https://docs.kubesense.ai/logs/log_collection/javascript/)
+ */
+
+import { globalObject } from '@kubesense/kubesense-js-core/util'
+import { defineGlobal } from '@kubesense/kubesense-browser-core'
+import type { LogsPublicApi } from '../boot/logsPublicApi'
+import { makeLogsPublicApi } from '../boot/logsPublicApi'
+
+export type { InternalContext } from '../domain/contexts/internalContext'
+export type { LogsMessage } from '../domain/logger'
+export { Logger, HandlerType } from '../domain/logger'
+export { StatusType } from '../domain/logger/isAuthorized'
+export type { LoggerConfiguration, LogsPublicApi as KubesenseLogs } from '../boot/logsPublicApi'
+export type { LogsInitConfiguration, LogsBeforeSend } from '../domain/configuration'
+export type { LogsEvent } from '../logsEvent.types'
+export type { LogsPlugin, OnLogsStartOptions, OnInitOptions } from '../domain/plugins'
+export type {
+  LogsEventDomainContext,
+  NetworkLogsEventDomainContext,
+  ConsoleLogsEventDomainContext,
+  LoggerLogsEventDomainContext,
+} from '../domainContext.types'
+
+/**
+ * @deprecated Use {@link KubesenseLogs} instead
+ */
+export type LogsGlobal = LogsPublicApi
+
+export type {
+  InitConfiguration,
+  PublicApi,
+  Context,
+  ContextValue,
+  ContextArray,
+  User,
+  Account,
+  TraceContextInjection,
+  SessionPersistence,
+  TrackingConsent,
+  MatchOption,
+  RawReportType,
+  ErrorSource,
+} from '@kubesense/kubesense-browser-core'
+export type { ProxyFn, Site } from '@kubesense/kubesense-js-core/transport'
+export type { ConsoleApiName } from '@kubesense/kubesense-js-core/util'
+
+/**
+ * The global Logs instance. Use this to call Logs methods.
+ *
+ * @category Main
+ * @see {@link KubesenseLogs}
+ * @see [Browser Log Collection](https://docs.kubesense.ai/logs/log_collection/javascript/)
+ */
+export const kubesenseLogs = makeLogsPublicApi({ sdkName: 'logs' })
+
+interface BrowserWindow {
+  KUBESENSE_LOGS?: LogsPublicApi
+}
+defineGlobal(globalObject as BrowserWindow, 'KUBESENSE_LOGS', kubesenseLogs)

package/src/logsEvent.types.ts

@@ -0,0 +1,198 @@
+export interface LogsEvent {
+  /**
+   * Start of the log in ms from epoch
+   */
+  date: number
+  /**
+   * The log message
+   */
+  message: string
+  /**
+   * The log status
+   */
+  status: 'ok' | 'debug' | 'info' | 'notice' | 'warn' | 'error' | 'critical' | 'alert' | 'emerg'
+  /**
+   * Origin of the log
+   */
+  origin: 'network' | 'source' | 'console' | 'logger' | 'agent' | 'report'
+  /**
+   * UUID of the application
+   */
+  application_id?: string
+  /**
+   * The service name
+   */
+  service?: string
+  /**
+   * Tags of the log
+   */
+  ktags?: string
+  /**
+   * UUID of the session (deprecated in favor of session.id)
+   */
+  session_id?: string
+  /**
+   * Session properties
+   */
+  session?: {
+    /**
+     * UUID of the session
+     */
+    id?: string
+
+    [k: string]: unknown
+  }
+  /**
+   * View properties
+   */
+  view: {
+    /**
+     * URL that linked to the initial view of the page
+     */
+    referrer?: string
+    /**
+     * URL of the view
+     */
+    url: string
+    /**
+     * UUID of the view
+     */
+    id?: string
+    /**
+     * User defined name of the view
+     */
+    name?: string
+
+    [k: string]: unknown
+  }
+  /**
+   * Logger properties
+   */
+  logger?: {
+    /**
+     * Name of the logger
+     */
+    name: string
+
+    [k: string]: unknown
+  }
+  /**
+   * Error properties
+   */
+  error?: {
+    /**
+     * Kind of the error
+     */
+    kind?: string
+    /**
+     * Stacktrace of the error
+     */
+    stack?: string
+    /**
+     * Fingerprint of the error
+     */
+    fingerprint?: string
+    /**
+     * Message of the error
+     */
+    message?: string
+    /**
+     * Flattened causes of the error
+     */
+    causes?: Array<{
+      message: string
+      source: string
+      type?: string
+      stack?: string
+    }>
+    /**
+     * The language or platform impacting the error stack trace format
+     */
+    source_type?: 'browser' | 'browser+wasm'
+    /**
+     * WebAssembly modules available for stack trace symbolication
+     */
+    wasm_modules?: Array<{
+      url: string
+      build_id: string
+    }>
+
+    [k: string]: unknown
+  }
+  /**
+   * Resource properties of the error
+   */
+  http?: {
+    /**
+     * HTTP method of the resource
+     */
+    method: 'POST' | 'GET' | 'HEAD' | 'PUT' | 'DELETE' | 'PATCH'
+    /**
+     * HTTP Status code of the resource
+     */
+    status_code: number
+    /**
+     * URL of the resource
+     */
+    url: string
+
+    [k: string]: unknown
+  }
+  user_action?: {
+    id: string | string[]
+  }
+  usr?: {
+    /**
+     * Identifier of the user
+     */
+    id?: string
+    /**
+     * Name of the user
+     */
+    name?: string
+    /**
+     * Email of the user
+     */
+    email?: string
+    /**
+     * Mobile phone number of the user
+     */
+    mobile?: string
+    /**
+     * Identifier of the user across sessions
+     */
+    anonymous_id?: string
+    [k: string]: unknown
+  }
+  account?: {
+    /**
+     * Identifier of the account
+     */
+    id: string
+    /**
+     * Name of the account
+     */
+    name?: string
+    [k: string]: unknown
+  }
+  /**
+   * Internal properties
+   */
+  _kubesense?: {
+    /**
+     * Mapping of source file URLs to their debug IDs for source map deobfuscation
+     */
+    debug_ids?: Array<{
+      /**
+       * URL of the source file
+       */
+      url: string
+      /**
+       * Debug ID (UUID) for the source file
+       */
+      id: string
+    }>
+  }
+
+  [k: string]: unknown
+}

package/src/rawLogsEvent.types.ts

@@ -0,0 +1,74 @@
+import type { ErrorSource, RawErrorCause, ErrorHandling, DebugIdEntry } from '@kubesense/kubesense-browser-core'
+import type { TimeStamp } from '@kubesense/kubesense-js-core/time'
+import type { StatusType } from './domain/logger/isAuthorized'
+
+export type RawLogsEvent =
+  | RawConsoleLogsEvent
+  | RawNetworkLogsEvent
+  | RawLoggerLogsEvent
+  | RawAgentLogsEvent
+  | RawReportLogsEvent
+  | RawRuntimeLogsEvent
+
+interface Error {
+  message?: string
+  kind?: string
+  stack?: string
+  fingerprint?: string
+  causes?: RawErrorCause[]
+  handling: ErrorHandling | undefined
+}
+
+export interface CommonRawLogsEvent {
+  date: TimeStamp
+  message: string
+  status: StatusType
+  error?: Error
+  origin: ErrorSource
+  _kubesense?: {
+    debug_ids?: DebugIdEntry[]
+  }
+  [key: string]: unknown
+}
+
+export interface RawConsoleLogsEvent extends CommonRawLogsEvent {
+  origin: typeof ErrorSource.CONSOLE
+}
+
+export interface RawLoggerLogsEvent extends CommonRawLogsEvent {
+  origin: typeof ErrorSource.LOGGER
+}
+
+export interface RawNetworkLogsEvent extends CommonRawLogsEvent {
+  origin: typeof ErrorSource.NETWORK
+  status: typeof StatusType.error
+  error: Error
+  http: {
+    method: 'POST' | 'GET' | 'HEAD' | 'PUT' | 'DELETE' | 'PATCH'
+    status_code: number
+    url: string
+    [k: string]: unknown
+  }
+}
+
+export interface RawReportLogsEvent extends CommonRawLogsEvent {
+  origin: typeof ErrorSource.REPORT
+}
+
+export interface RawRuntimeLogsEvent extends CommonRawLogsEvent {
+  origin: typeof ErrorSource.SOURCE
+  status: typeof StatusType.error
+  error: Error
+}
+
+export interface RawAgentLogsEvent extends CommonRawLogsEvent {
+  origin: typeof ErrorSource.AGENT
+  status: typeof StatusType.error
+}
+
+export interface CommonContext {
+  view?: {
+    referrer: string
+    url: string
+  }
+}

package/src/transport/startLogsBatch.ts

@@ -0,0 +1,29 @@
+import type { Context, SessionManager } from '@kubesense/kubesense-browser-core'
+import { createBatch } from '@kubesense/kubesense-browser-core'
+import { createEndpointBuilder, createReplicaEndpointBuilder } from '@kubesense/kubesense-js-core/transport'
+import type { LogsConfiguration } from '../domain/configuration'
+import type { LifeCycle } from '../domain/lifeCycle'
+import { LifeCycleEventType } from '../domain/lifeCycle'
+import type { LogsEvent } from '../logsEvent.types'
+
+export function startLogsBatch(
+  configuration: LogsConfiguration,
+  lifeCycle: LifeCycle,
+  reportError: (message: string) => void,
+  sessionManager: SessionManager
+) {
+  const endpoints = [createEndpointBuilder(configuration, 'logs')]
+  const replicaEndpoint = createReplicaEndpointBuilder(configuration, 'logs')
+  if (replicaEndpoint) {
+    endpoints.push(replicaEndpoint)
+  }
+
+  const batch = createBatch({ endpoints, reportError })
+  sessionManager.expireObservable.subscribe(() => batch.forceFlush('session_expire'))
+
+  lifeCycle.subscribe(LifeCycleEventType.LOG_COLLECTED, (serverLogsEvent: LogsEvent & Context) => {
+    batch.add(serverLogsEvent)
+  })
+
+  return batch
+}

package/src/transport/startLogsBridge.ts

@@ -0,0 +1,13 @@
+import type { Context } from '@kubesense/kubesense-browser-core'
+import { getEventBridge } from '@kubesense/kubesense-browser-core'
+import type { LifeCycle } from '../domain/lifeCycle'
+import { LifeCycleEventType } from '../domain/lifeCycle'
+import type { LogsEvent } from '../logsEvent.types'
+
+export function startLogsBridge(lifeCycle: LifeCycle) {
+  const bridge = getEventBridge<'log', LogsEvent>()!
+
+  lifeCycle.subscribe(LifeCycleEventType.LOG_COLLECTED, (serverLogsEvent: LogsEvent & Context) => {
+    bridge.send('log', serverLogsEvent)
+  })
+}