@kubesense/kubesense-browser-rum-core 1.0.0

package/src/domain/tracing/getDocumentTraceId.ts

@@ -0,0 +1,90 @@
+import type { TimeStamp } from '@kubesense/kubesense-browser-core'
+import { dateNow, findCommaSeparatedValue, ONE_MINUTE } from '@kubesense/kubesense-browser-core'
+import { isCommentNode, isTextNode } from '../../browser/htmlDomUtils'
+
+interface DocumentTraceData {
+  traceId: string
+  traceTime: TimeStamp
+}
+
+export const INITIAL_DOCUMENT_OUTDATED_TRACE_ID_THRESHOLD = 2 * ONE_MINUTE
+
+export function getDocumentTraceId(document: Document): string | undefined {
+  const data = getDocumentTraceDataFromMeta(document) || getDocumentTraceDataFromComment(document)
+
+  if (!data || data.traceTime <= dateNow() - INITIAL_DOCUMENT_OUTDATED_TRACE_ID_THRESHOLD) {
+    return undefined
+  }
+
+  return data.traceId
+}
+
+export function getDocumentTraceDataFromMeta(document: Document): DocumentTraceData | undefined {
+  const traceIdMeta = document.querySelector<HTMLMetaElement>('meta[name=kubesense-trace-id]')
+  const traceTimeMeta = document.querySelector<HTMLMetaElement>('meta[name=kubesense-trace-time]')
+  return createDocumentTraceData(traceIdMeta && traceIdMeta.content, traceTimeMeta && traceTimeMeta.content)
+}
+
+export function getDocumentTraceDataFromComment(document: Document): DocumentTraceData | undefined {
+  const comment = findTraceComment(document)
+  if (!comment) {
+    return undefined
+  }
+  return createDocumentTraceData(
+    findCommaSeparatedValue(comment, 'trace-id'),
+    findCommaSeparatedValue(comment, 'trace-time')
+  )
+}
+
+export function createDocumentTraceData(
+  traceId: string | undefined | null,
+  rawTraceTime: string | undefined | null
+): DocumentTraceData | undefined {
+  const traceTime = rawTraceTime && (Number(rawTraceTime) as TimeStamp)
+  if (!traceId || !traceTime) {
+    return undefined
+  }
+
+  return {
+    traceId,
+    traceTime,
+  }
+}
+
+export function findTraceComment(document: Document): string | undefined {
+  // 1. Try to find the comment as a direct child of the document
+  // Note: TSLint advises to use a 'for of', but TS doesn't allow to use 'for of' if the iterated
+  // value is not an array or string (here, a NodeList).
+  for (let i = 0; i < document.childNodes.length; i += 1) {
+    const comment = getTraceCommentFromNode(document.childNodes[i])
+    if (comment) {
+      return comment
+    }
+  }
+
+  // 2. If the comment is placed after the </html> tag, but have some space or new lines before or
+  // after, the DOM parser will lift it (and the surrounding text) at the end of the <body> tag.
+  // Try to look for the comment at the end of the <body> by by iterating over its child nodes in
+  // reverse order, stopping if we come across a non-text node.
+  if (document.body) {
+    for (let i = document.body.childNodes.length - 1; i >= 0; i -= 1) {
+      const node = document.body.childNodes[i]
+      const comment = getTraceCommentFromNode(node)
+      if (comment) {
+        return comment
+      }
+      if (!isTextNode(node)) {
+        break
+      }
+    }
+  }
+}
+
+function getTraceCommentFromNode(node: Node | null) {
+  if (node && isCommentNode(node)) {
+    const match = /^\s*KUBESENSE;(.*?)\s*$/.exec(node.data)
+    if (match) {
+      return match[1]
+    }
+  }
+}

package/src/domain/tracing/identifier.ts

@@ -0,0 +1,69 @@
+interface BaseIdentifier {
+  toString(radix?: number): string
+}
+
+export interface TraceIdentifier extends BaseIdentifier {
+  // We use a brand to distinguish between TraceIdentifier and SpanIdentifier, else TypeScript
+  // considers them as the same type
+  __brand: 'traceIdentifier'
+}
+
+export interface SpanIdentifier extends BaseIdentifier {
+  __brand: 'spanIdentifier'
+}
+
+export function createTraceIdentifier() {
+  return createIdentifier(64) as TraceIdentifier
+}
+
+export function createSpanIdentifier() {
+  return createIdentifier(63) as SpanIdentifier
+}
+
+function createIdentifier(bits: 63 | 64): BaseIdentifier {
+  const buffer = crypto.getRandomValues(new Uint32Array(2))
+  if (bits === 63) {
+    // eslint-disable-next-line no-bitwise
+    buffer[buffer.length - 1] >>>= 1 // force 63-bit
+  }
+
+  // The `.toString` function is intentionally similar to Number and BigInt `.toString` method.
+  //
+  // JavaScript numbers can represent integers up to 48 bits, this is why we need two of them to
+  // represent a 64 bits identifier. But BigInts don't have this limitation and can represent larger
+  // integer values.
+  //
+  // In the future, when we drop browsers without BigInts support, we could use BigInts directly
+  // represent identifiers by simply returning a BigInt from this function (as all we need is a
+  // value with a `.toString` method).
+  //
+  // Examples:
+  //   const buffer = getCrypto().getRandomValues(new Uint32Array(2))
+  //   return BigInt(buffer[0]) + BigInt(buffer[1]) << 32n
+  //
+  //   // Alternative with BigUint64Array (different Browser support than plain bigints!):
+  //   return crypto.getRandomValues(new BigUint64Array(1))[0]
+  //
+  // For now, let's keep using two plain numbers as having two different implementations (one for
+  // browsers with BigInt support and one for older browsers) don't bring much value.
+  return {
+    toString(radix = 10) {
+      let high = buffer[1]
+      let low = buffer[0]
+      let str = ''
+
+      do {
+        const mod = (high % radix) * 4294967296 + low
+        high = Math.floor(high / radix)
+        low = Math.floor(mod / radix)
+        str = (mod % radix).toString(radix) + str
+      } while (high || low)
+
+      return str
+    },
+  }
+}
+
+export function toPaddedHexadecimalString(id: BaseIdentifier) {
+  return id.toString(16).padStart(16, '0')
+}

package/src/domain/tracing/sampler.ts

@@ -0,0 +1,69 @@
+import { performDraw } from '@kubesense/kubesense-browser-core'
+
+let sampleDecisionCache: { sessionId: string; decision: boolean } | undefined
+
+export function isTraceSampled(sessionId: string, sampleRate: number) {
+  // Shortcuts for common cases. This is not strictly necessary, but it makes the code faster for
+  // customers willing to ingest all traces.
+  if (sampleRate === 100) {
+    return true
+  }
+
+  if (sampleRate === 0) {
+    return false
+  }
+
+  if (sampleDecisionCache && sessionId === sampleDecisionCache.sessionId) {
+    return sampleDecisionCache.decision
+  }
+
+  let decision: boolean
+  // @ts-expect-error BigInt might not be defined in every browser we support
+  if (window.BigInt) {
+    decision = sampleUsingKnuthFactor(BigInt(`0x${sessionId.split('-')[4]}`), sampleRate)
+  } else {
+    // For simplicity, we don't use consistent sampling for browser without BigInt support
+    // TODO: remove this when all browser we support have BigInt support
+    decision = performDraw(sampleRate)
+  }
+  sampleDecisionCache = { sessionId, decision }
+  return decision
+}
+
+// Exported for tests
+export function resetSampleDecisionCache() {
+  sampleDecisionCache = undefined
+}
+
+/**
+ * Perform sampling using the Knuth factor method. This method offer consistent sampling result
+ * based on the provided identifier.
+ *
+ * @param identifier The identifier to use for sampling.
+ * @param sampleRate The sample rate in percentage between 0 and 100.
+ */
+export function sampleUsingKnuthFactor(identifier: bigint, sampleRate: number) {
+  // The formula is:
+  //
+  //   (identifier * knuthFactor) % 2^64 < sampleRate * 2^64
+  //
+  // Because JavaScript numbers are 64-bit floats, we can't represent 64-bit integers, and the
+  // modulo would be incorrect. Thus, we are using BigInts here.
+  //
+  // Implementation in other languages:
+  // * Go     https://github.com/DataDog/kubesense-trace-go/blob/ec6fbb1f2d517b7b8e69961052adf7136f3af773/ddtrace/tracer/sampler.go#L86-L91
+  // * Python https://github.com/DataDog/kubesense-trace-py/blob/0cee2f066fb6e79aa15947c1514c0f406dea47c5/ddtrace/sampling_rule.py#L197
+  // * Ruby   https://github.com/DataDog/kubesense-trace-rb/blob/1a6e255cdcb7e7e22235ea5955f90f6dfa91045d/lib/kubesense/tracing/sampling/rate_sampler.rb#L42
+  // * C++    https://github.com/DataDog/kubesense-trace-cpp/blob/159629edc438ae45f2bb318eb7bd51abd05e94b5/src/kubesense/trace_sampler.cpp#L58
+  // * Java   https://github.com/DataDog/kubesense-trace-java/blob/896dd6b380533216e0bdee59614606c8272d313e/kubesense-trace-core/src/main/java/kubesense/trace/common/sampling/DeterministicSampler.java#L48
+  //
+  // Note: All implementations have slight variations. Some of them use '<=' instead of '<', and
+  // use `sampleRate * 2^64 - 1` instead of `sampleRate * 2^64`. The following implementation
+  // should adhere to the spec and is a bit simpler than using a 2^64-1 limit as there are less
+  // BigInt arithmetic to write. In practice this does not matter, as we are using floating point
+  // numbers in the end, and Number(2n**64n-1n) === Number(2n**64n).
+  const knuthFactor = BigInt('1111111111111111111')
+  const twoPow64 = BigInt('0x10000000000000000') // 2n ** 64n
+  const hash = (identifier * knuthFactor) % twoPow64
+  return Number(hash) <= (sampleRate / 100) * Number(twoPow64)
+}

package/src/domain/tracing/tracer.ts

@@ -0,0 +1,248 @@
+import type { ContextManager } from '@kubesense/kubesense-browser-core'
+import {
+  objectEntries,
+  shallowClone,
+  getType,
+  isMatchOption,
+  matchList,
+  TraceContextInjection,
+} from '@kubesense/kubesense-browser-core'
+import type { RumConfiguration } from '../configuration'
+import type {
+  RumFetchResolveContext,
+  RumFetchStartContext,
+  RumXhrCompleteContext,
+  RumXhrStartContext,
+} from '../requestCollection'
+import type { RumSessionManager } from '../rumSessionManager'
+import { isSampled } from '../sampler/sampler'
+import type { PropagatorType, TracingOption } from './tracer.types'
+import type { SpanIdentifier, TraceIdentifier } from './identifier'
+import { createSpanIdentifier, createTraceIdentifier, toPaddedHexadecimalString } from './identifier'
+
+export interface Tracer {
+  traceFetch: (context: Partial<RumFetchStartContext>) => void
+  traceXhr: (context: Partial<RumXhrStartContext>, xhr: XMLHttpRequest) => void
+  clearTracingIfNeeded: (context: RumFetchResolveContext | RumXhrCompleteContext) => void
+}
+
+interface TracingHeaders {
+  [key: string]: string
+}
+
+export function isTracingOption(item: unknown): item is TracingOption {
+  const expectedItem = item as TracingOption
+  return (
+    getType(expectedItem) === 'object' &&
+    isMatchOption(expectedItem.match) &&
+    Array.isArray(expectedItem.propagatorTypes)
+  )
+}
+
+/**
+ * Clear tracing information to avoid incomplete traces. Ideally, we should do it when the
+ * request did not reach the server, but the browser does not expose this. So, we clear tracing
+ * information if the request ended with status 0 without being aborted by the application.
+ *
+ * Reasoning:
+ *
+ * * Applications are usually aborting requests after a bit of time, for example when the user is
+ * typing (autocompletion) or navigating away (in a SPA). With a performant device and good
+ * network conditions, the request is likely to reach the server before being canceled.
+ *
+ * * Requests aborted otherwise (ex: lack of internet, CORS issue, blocked by a privacy extension)
+ * are likely to finish quickly and without reaching the server.
+ *
+ * Of course, it might not be the case every time, but it should limit having incomplete traces a
+ * bit.
+ * */
+export function clearTracingIfNeeded(context: RumFetchResolveContext | RumXhrCompleteContext) {
+  if (context.status === 0 && !context.isAborted) {
+    context.traceId = undefined
+    context.spanId = undefined
+    context.traceSampled = undefined
+  }
+}
+
+export function startTracer(
+  configuration: RumConfiguration,
+  sessionManager: RumSessionManager,
+  userContext: ContextManager,
+  accountContext: ContextManager
+): Tracer {
+  return {
+    clearTracingIfNeeded,
+    traceFetch: (context) =>
+      injectHeadersIfTracingAllowed(
+        configuration,
+        context,
+        sessionManager,
+        userContext,
+        accountContext,
+        (tracingHeaders: TracingHeaders) => {
+          if (context.input instanceof Request && !context.init?.headers) {
+            context.input = new Request(context.input)
+            Object.keys(tracingHeaders).forEach((key) => {
+              ;(context.input as Request).headers.append(key, tracingHeaders[key])
+            })
+          } else {
+            context.init = shallowClone(context.init)
+            const headers: Array<[string, string]> = []
+            if (context.init.headers instanceof Headers) {
+              context.init.headers.forEach((value, key) => {
+                headers.push([key, value])
+              })
+            } else if (Array.isArray(context.init.headers)) {
+              context.init.headers.forEach((header) => {
+                headers.push(header)
+              })
+            } else if (context.init.headers) {
+              Object.keys(context.init.headers).forEach((key) => {
+                headers.push([key, (context.init!.headers as Record<string, string>)[key]])
+              })
+            }
+            context.init.headers = headers.concat(objectEntries(tracingHeaders))
+          }
+        }
+      ),
+    traceXhr: (context, xhr) =>
+      injectHeadersIfTracingAllowed(
+        configuration,
+        context,
+        sessionManager,
+        userContext,
+        accountContext,
+        (tracingHeaders: TracingHeaders) => {
+          Object.keys(tracingHeaders).forEach((name) => {
+            xhr.setRequestHeader(name, tracingHeaders[name])
+          })
+        }
+      ),
+  }
+}
+
+function injectHeadersIfTracingAllowed(
+  configuration: RumConfiguration,
+  context: Partial<RumFetchStartContext | RumXhrStartContext>,
+  sessionManager: RumSessionManager,
+  userContext: ContextManager,
+  accountContext: ContextManager,
+  inject: (tracingHeaders: TracingHeaders) => void
+) {
+  const session = sessionManager.findTrackedSession()
+  if (!session) {
+    return
+  }
+
+  const tracingOption = configuration.allowedTracingUrls.find((tracingOption) =>
+    matchList([tracingOption.match], context.url!, true)
+  )
+  if (!tracingOption) {
+    return
+  }
+
+  const traceSampled = isSampled(session.id, configuration.traceSampleRate)
+
+  const shouldInjectHeaders = traceSampled || configuration.traceContextInjection === TraceContextInjection.ALL
+  if (!shouldInjectHeaders) {
+    return
+  }
+
+  context.traceSampled = traceSampled
+  context.traceId = createTraceIdentifier()
+  context.spanId = createSpanIdentifier()
+
+  inject(
+    makeTracingHeaders(
+      context.traceId,
+      context.spanId,
+      context.traceSampled,
+      session.id,
+      tracingOption.propagatorTypes,
+      userContext,
+      accountContext,
+      configuration
+    )
+  )
+}
+
+/**
+ * When trace is not sampled, set priority to '0' instead of not adding the tracing headers
+ * to prepare the implementation for sampling delegation.
+ */
+function makeTracingHeaders(
+  traceId: TraceIdentifier,
+  spanId: SpanIdentifier,
+  traceSampled: boolean,
+  sessionId: string,
+  propagatorTypes: PropagatorType[],
+  userContext: ContextManager,
+  accountContext: ContextManager,
+  configuration: RumConfiguration
+): TracingHeaders {
+  const tracingHeaders: TracingHeaders = {}
+
+  propagatorTypes.forEach((propagatorType) => {
+    switch (propagatorType) {
+      case 'kubesense': {
+        Object.assign(tracingHeaders, {
+          'x-kubesense-origin': 'rum',
+          'x-kubesense-parent-id': spanId.toString(),
+          'x-kubesense-sampling-priority': traceSampled ? '1' : '0',
+          'x-kubesense-trace-id': traceId.toString(),
+        })
+        break
+      }
+      // https://www.w3.org/TR/trace-context/
+      case 'tracecontext': {
+        Object.assign(tracingHeaders, {
+          traceparent: `00-0000000000000000${toPaddedHexadecimalString(traceId)}-${toPaddedHexadecimalString(spanId)}-0${
+            traceSampled ? '1' : '0'
+          }`,
+          tracestate: `dd=s:${traceSampled ? '1' : '0'};o:rum`,
+        })
+        break
+      }
+      // https://github.com/openzipkin/b3-propagation
+      case 'b3': {
+        Object.assign(tracingHeaders, {
+          b3: `${toPaddedHexadecimalString(traceId)}-${toPaddedHexadecimalString(spanId)}-${traceSampled ? '1' : '0'}`,
+        })
+        break
+      }
+      case 'b3multi': {
+        Object.assign(tracingHeaders, {
+          'X-B3-TraceId': toPaddedHexadecimalString(traceId),
+          'X-B3-SpanId': toPaddedHexadecimalString(spanId),
+          'X-B3-Sampled': traceSampled ? '1' : '0',
+        })
+        break
+      }
+    }
+  })
+
+  if (configuration.propagateTraceBaggage) {
+    const baggageItems: Record<string, string> = {
+      'session.id': sessionId,
+    }
+
+    const userId = userContext.getContext().id
+    if (typeof userId === 'string') {
+      baggageItems['user.id'] = userId
+    }
+
+    const accountId = accountContext.getContext().id
+    if (typeof accountId === 'string') {
+      baggageItems['account.id'] = accountId
+    }
+
+    const baggageHeader = Object.entries(baggageItems)
+      .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
+      .join(',')
+    if (baggageHeader) {
+      tracingHeaders['baggage'] = baggageHeader
+    }
+  }
+
+  return tracingHeaders
+}

package/src/domain/tracing/tracer.types.ts

@@ -0,0 +1,13 @@
+import type { MatchOption } from '@kubesense/kubesense-browser-core'
+
+/**
+ * kubesense: Kubsesense (x-kubesense-*)
+ * tracecontext: W3C Trace Context (traceparent, tracestate)
+ * b3: B3 Single Header (b3)
+ * b3multi: B3 Multiple Headers (X-B3-*)
+ */
+export type PropagatorType = 'kubesense' | 'b3' | 'b3multi' | 'tracecontext'
+export interface TracingOption {
+    match: MatchOption
+    propagatorTypes: PropagatorType[]
+  }

package/src/domain/trackEventCounts.ts

@@ -0,0 +1,67 @@
+import { noop } from '@kubesense/kubesense-browser-core'
+import { RumEventType } from '../rawRumEvent.types'
+import type { RumActionEvent, RumErrorEvent, RumLongTaskEvent, RumResourceEvent } from '../rumEvent.types'
+import type { LifeCycle } from './lifeCycle'
+import { LifeCycleEventType } from './lifeCycle'
+
+export interface EventCounts {
+  errorCount: number
+  actionCount: number
+  longTaskCount: number
+  resourceCount: number
+  frustrationCount: number
+}
+
+export function trackEventCounts({
+  lifeCycle,
+  isChildEvent,
+  onChange: callback = noop,
+}: {
+  lifeCycle: LifeCycle
+  isChildEvent: (event: RumActionEvent | RumErrorEvent | RumLongTaskEvent | RumResourceEvent) => boolean
+  onChange?: () => void
+}) {
+  const eventCounts: EventCounts = {
+    errorCount: 0,
+    longTaskCount: 0,
+    resourceCount: 0,
+    actionCount: 0,
+    frustrationCount: 0,
+  }
+
+  const subscription = lifeCycle.subscribe(LifeCycleEventType.RUM_EVENT_COLLECTED, (event): void => {
+    if (event.type === 'view' || event.type === 'vital' || !isChildEvent(event)) {
+      return
+    }
+    switch (event.type) {
+      case RumEventType.ERROR:
+        eventCounts.errorCount += 1
+        callback()
+        break
+      case RumEventType.ACTION:
+        eventCounts.actionCount += 1
+        if (event.action.frustration) {
+          eventCounts.frustrationCount += event.action.frustration.type.length
+        }
+        callback()
+        break
+      case RumEventType.LONG_TASK:
+        eventCounts.longTaskCount += 1
+        callback()
+        break
+      case RumEventType.RESOURCE:
+        if (!event._kubesense?.discarded) {
+          eventCounts.resourceCount += 1
+          callback()
+        }
+        break
+    }
+  })
+
+  return {
+    stop: () => {
+      subscription.unsubscribe()
+    },
+    eventCounts,
+  }
+}

package/src/domain/view/bfCacheSupport.ts

@@ -0,0 +1,20 @@
+import type { Configuration } from '@kubesense/kubesense-browser-core'
+import { addEventListener, DOM_EVENT } from '@kubesense/kubesense-browser-core'
+
+export function onBFCacheRestore(
+  configuration: Configuration,
+  callback: (event: PageTransitionEvent) => void
+): () => void {
+  const { stop } = addEventListener(
+    configuration,
+    window,
+    DOM_EVENT.PAGE_SHOW,
+    (event: PageTransitionEvent) => {
+      if (event.persisted) {
+        callback(event)
+      }
+    },
+    { capture: true }
+  )
+  return stop
+}

package/src/domain/view/trackViewEventCounts.ts

@@ -0,0 +1,15 @@
+import type { LifeCycle } from '../lifeCycle'
+import { trackEventCounts } from '../trackEventCounts'
+
+export function trackViewEventCounts(lifeCycle: LifeCycle, viewId: string, onChange: () => void) {
+  const { stop, eventCounts } = trackEventCounts({
+    lifeCycle,
+    isChildEvent: (event) => event.view.id === viewId,
+    onChange,
+  })
+
+  return {
+    stop,
+    eventCounts,
+  }
+}