refactor: extract into files

Author: niieani

src/v3/ActiveTrace.ts

@@ -2,17 +2,18 @@
 /* eslint-disable max-classes-per-file */
 import { doesEntryMatchDefinition } from './doesEntryMatchDefinition'
 import { ensureTimestamp } from './ensureTimestamp'
+import type { ActiveTraceConfig, Span } from './spanTypes'
 import type {
-  ActiveTraceConfig,
   CompleteTraceDefinition,
+  TraceRecording,
+} from './traceRecordingTypes'
+import type {
   ScopeBase,
-  Span,
   SpanAndAnnotationEntry as SpanAndAnnotation,
   SpanAnnotation,
   SpanAnnotationRecord,
   Timestamp,
   TraceInterruptionReason,
-  TraceRecording,
 } from './types'
 import type {
   DistributiveOmit,

src/v3/convertToRum.ts

@@ -1,12 +1,7 @@
 /* eslint-disable @typescript-eslint/consistent-indexed-object-style */
-import {
-  ComponentRenderSpan,
-  ScopeBase,
-  Span,
-  SpanAndAnnotationEntry,
-  TraceRecording,
-  TraceRecordingBase,
-} from './types'
+import { ComponentRenderSpan, Span } from './spanTypes'
+import { TraceRecording, TraceRecordingBase } from './traceRecordingTypes'
+import { ScopeBase, SpanAndAnnotationEntry } from './types'
 
 export interface EmbeddedEntry {
   count: number

src/v3/docs/RFC.md

@@ -89,59 +89,7 @@ The model is heavily inspired by OpenTelemetry, adapting it to the frontend’s
 
 ### Model Overview
 
-The primary way to capture metrics would be to record a **Product Operation trace**. Such a **trace** would include the **spans** that occurred while the application was changing state, e.g. after a user performed a specific operation. The associated trace recording would then contain browser **spans**, like network requests, or other PerformanceEntries, as well as custom **spans**, like component renders.
-
-The Frontend Tracing model works as follows:
-
-1. The **Tracing Engine** is a singleton instantiated when the application boots. It provides the public API for initiating a new Trace using one of the **Trace Definitions**.
-2. **Trace Definition files** are created once a decision to instrument observability of a given **Product Operation** is made. The definitions include the `name` of the operation, along with the criteria by which **spans** required to consider the **Product Operation** `complete` are matched, as well as other optional details (such as: criteria by which an operation may be interrupted or how long it can be active before timing-out).
-3. A **Trace** is started imperatively, in response to a user’s action (such as _clicking_ or _pressing a key_), or a remote event (e.g. _receiving a message, or a new notification_).
-   Only a single **Product Operation Trace** can be active at a time.
-4. **Tracing Engine** listens for new **spans**, which are processed against the **active Trace’s Definition**, and stored in a list.
-5. The **Trace** is considered _complete_ once all of the _required_ **spans** have been seen, or
-6. The **Trace** is considered _interrupted,_ if any of the following occurs:
-   1. an _interrupting_ **spans** has been seen (as per trace definition)
-   2. the **Trace** is manually interrupted
-   3. the **Trace** times-out
-   4. another **Trace** starts
-7. The **Tracing Engine** generates a serializable **Trace Recording** containing all the seen **spans**. The resulting JSON output can be:
-   1. sent to an observability service for analysis (we plan on using Datadog RUM)
-   2. used to calculate individual metrics from the trace (e.g. for long-term analysis these might be stored in Datadog Metrics)
-   3. downloaded as a file and visualized (when debugging a problem locally)
-
-![tracing-engine](./tracing-engine.png)
-
-### Deriving SLIs and other metrics from a trace
-
-ℹ️ It is our recommendation that the primary way of creating duration metrics would be to derive them from data in the trace.
-
-Instead of the traditional approach of capturing isolated metrics imperatively in the code, the **trace** model allows us the flexibility to define and compute any number of metrics from the **trace recording**.
-
-We can distinguish the following types of metrics:
-
-1. **Duration of a Computed Span** — the time between any two **spans** that appeared in the **trace**. For example:
-   1. _time between the user’s click on a ticket_ and _everything in the ticket page has fully rendered with content_ (duration of the entire operation)
-   2. _time between the user’s click on a ticket_ and _the moment the first piece of the ticket UI was displayed_ (duration of a segment of the operation)
-
-![trace](./trace.png)
-
-2. **Computed Values** — any numerical value derived from the **spans** or their attributes. For example:
-   1. _The total number of times the OmniLog re-renders during a ticket load_
-   2. _The total number of requests to agent-graph made while loading the ticket_
-   3. _The total number of ZAF apps initialized while loading the ticket_
-
-### Measuring _Visually Complete_ in React
-
-Knowing whether a component is visually complete can be a challenge due to React’s renderer design, as it is impossible to deterministically tell how many times a given component will re-render in a given state. In order to ensure the Trace is as complete as possible, the **Trace Definition** may define a list of **spans** that will trigger a debouncing period, during which we may allow for these **spans** to “settle”.
-
-### _Visually Complete_ vs _Fully Interactive_
-
-Due to the single-threaded, event-loop-based nature of JavaScript, both asynchronous work, and DOM painting scheduled during a **Product Operation** may continue even after all the end criteria have been satisfied.
-While the end of a **Product Operation** gives us an indication of when the operation is _visually complete_, the user might still be blocked from interacting with the page. Thus, the duration of a **Trace** may not fully reflect the user’s _actual_ experience on the page.
-
-The **Trace Definition** may be configured to continue recording additional **spans**, until the page becomes fully interactive. The _fully-interactive_ time is determined by a configurable _quiet period_, in which no significant “[long-task](https://developer.mozilla.org/en-US/docs/Glossary/Long_task)” or “[long-animation-frame](https://developer.mozilla.org/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing)” **spans** have been seen.
-
-These additional **spans** won’t contribute to the reported duration of the Trace, but may be used to create computed **spans** (e.g. Time To Interactive — TTI).
+[model-overview.md](./model-overview.md)
 
 ### Not in Scope
 

src/v3/docs/model-overview.md

@@ -0,0 +1,55 @@
+### Model Overview
+
+The primary way to capture metrics would be to record a **Product Operation trace**. Such a **trace** would include the **spans** that occurred while the application was changing state, e.g. after a user performed a specific operation. The associated trace recording would then contain browser **spans**, like network requests, or other PerformanceEntries, as well as custom **spans**, like component renders.
+
+The Frontend Tracing model works as follows:
+
+1. The **Tracing Engine** is a singleton instantiated when the application boots. It provides the public API for initiating a new Trace using one of the **Trace Definitions**.
+2. **Trace Definition files** are created once a decision to instrument observability of a given **Product Operation** is made. The definitions include the `name` of the operation, along with the criteria by which **spans** required to consider the **Product Operation** `complete` are matched, as well as other optional details (such as: criteria by which an operation may be interrupted or how long it can be active before timing-out).
+3. A **Trace** is started imperatively, in response to a user’s action (such as _clicking_ or _pressing a key_), or a remote event (e.g. _receiving a message, or a new notification_).
+   Only a single **Product Operation Trace** can be active at a time.
+4. **Tracing Engine** listens for new **spans**, which are processed against the **active Trace’s Definition**, and stored in a list.
+5. The **Trace** is considered _complete_ once all of the _required_ **spans** have been seen, or
+6. The **Trace** is considered _interrupted,_ if any of the following occurs:
+   1. an _interrupting_ **spans** has been seen (as per trace definition)
+   2. the **Trace** is manually interrupted
+   3. the **Trace** times-out
+   4. another **Trace** starts
+7. The **Tracing Engine** generates a serializable **Trace Recording** containing all the seen **spans**. The resulting JSON output can be:
+   1. sent to an observability service for analysis (we plan on using Datadog RUM)
+   2. used to calculate individual metrics from the trace (e.g. for long-term analysis these might be stored in Datadog Metrics)
+   3. downloaded as a file and visualized (when debugging a problem locally)
+
+![tracing-engine](./tracing-engine.png)
+
+### Deriving SLIs and other metrics from a trace
+
+ℹ️ It is our recommendation that the primary way of creating duration metrics would be to derive them from data in the trace.
+
+Instead of the traditional approach of capturing isolated metrics imperatively in the code, the **trace** model allows us the flexibility to define and compute any number of metrics from the **trace recording**.
+
+We can distinguish the following types of metrics:
+
+1. **Duration of a Computed Span** — the time between any two **spans** that appeared in the **trace**. For example:
+   1. _time between the user’s click on a ticket_ and _everything in the ticket page has fully rendered with content_ (duration of the entire operation)
+   2. _time between the user’s click on a ticket_ and _the moment the first piece of the ticket UI was displayed_ (duration of a segment of the operation)
+
+![trace](./trace.png)
+
+2. **Computed Values** — any numerical value derived from the **spans** or their attributes. For example:
+   1. _The total number of times the OmniLog re-renders during a ticket load_
+   2. _The total number of requests to agent-graph made while loading the ticket_
+   3. _The total number of ZAF apps initialized while loading the ticket_
+
+### Measuring _Visually Complete_ in React
+
+Knowing whether a component is visually complete can be a challenge due to React’s renderer design, as it is impossible to deterministically tell how many times a given component will re-render in a given state. In order to ensure the Trace is as complete as possible, the **Trace Definition** may define a list of **spans** that will trigger a debouncing period, during which we may allow for these **spans** to “settle”.
+
+### _Visually Complete_ vs _Fully Interactive_
+
+Due to the single-threaded, event-loop-based nature of JavaScript, both asynchronous work, and DOM painting scheduled during a **Product Operation** may continue even after all the end criteria have been satisfied.
+While the end of a **Product Operation** gives us an indication of when the operation is _visually complete_, the user might still be blocked from interacting with the page. Thus, the duration of a **Trace** may not fully reflect the user’s _actual_ experience on the page.
+
+The **Trace Definition** may be configured to continue recording additional **spans**, until the page becomes fully interactive. The _fully-interactive_ time is determined by a configurable _quiet period_, in which no significant “[long-task](https://developer.mozilla.org/en-US/docs/Glossary/Long_task)” or “[long-animation-frame](https://developer.mozilla.org/en-US/docs/Web/API/Performance_API/Long_animation_frame_timing)” **spans** have been seen.
+
+These additional **spans** won’t contribute to the reported duration of the Trace, but may be used to create computed **spans** (e.g. Time To Interactive — TTI).

src/v3/doesEntryMatchDefinition.test.ts

@@ -1,12 +1,11 @@
 import { doesEntryMatchDefinition } from './doesEntryMatchDefinition'
+import type { ScopeBase, SpanAnnotation } from './types'
 import type {
   ComponentRenderSpan,
-  ScopeBase,
   Span,
-  SpanAnnotation,
   SpanBase,
   SpanMatcher,
-} from './types'
+} from './spanTypes'
 
 // Mock data for TraceEntryBase
 interface TestScopeT extends ScopeBase {

src/v3/doesEntryMatchDefinition.ts

@@ -1,4 +1,5 @@
-import { ScopeBase, SpanAndAnnotationEntry, SpanMatcher } from './types'
+import { ScopeBase, SpanAndAnnotationEntry } from './types'
+import { SpanMatcher } from './spanTypes'
 
 /**
  * Matches criteria against a performance entry event.
@@ -44,18 +45,18 @@ export function doesEntryMatchDefinition<ScopeT extends ScopeBase>(
     !attributes ||
     Boolean(
       span.attributes &&
-      Object.entries(attributes).every(
-        ([key, value]) => span.attributes?.[key] === value,
-      ),
+        Object.entries(attributes).every(
+          ([key, value]) => span.attributes?.[key] === value,
+        ),
     )
 
   const matchesScope =
     !scope ||
     Boolean(
       span.scope &&
-      Object.entries(scope).every(
-        ([key, value]) => span.scope?.[key] === value,
-      ),
+        Object.entries(scope).every(
+          ([key, value]) => span.scope?.[key] === value,
+        ),
     )
 
   const spanIsIdle = 'isIdle' in span ? span.isIdle : false

src/v3/getSpanFromPerformanceEntry.ts

@@ -1,13 +1,7 @@
 import { getCommonUrlForTracing } from '../main'
 import { ensureTimestamp } from './ensureTimestamp'
-import {
-  Attributes,
-  InitiatorType,
-  ScopeBase,
-  Span,
-  SpanType,
-  Timestamp,
-} from './types'
+import { ScopeBase, Timestamp } from './types'
+import { Attributes, InitiatorType, Span, SpanType } from './spanTypes'
 
 /**
  * Maps Performance Entry to Trace Entry

src/v3/hooks.ts

@@ -1,15 +1,14 @@
 import { useEffect, useRef } from 'react'
 import { useOnComponentUnmount } from '../ErrorBoundary'
 import { ensureTimestamp } from './ensureTimestamp'
-import type { TraceManager } from './traceManager'
 import type {
   BeaconConfig,
-  ComponentRenderSpan,
   GetScopeTFromTraceManager,
-  ScopeBase,
-  Timestamp,
   UseBeacon,
-} from './types'
+} from './hooksTypes'
+import type { ComponentRenderSpan } from './spanTypes'
+import type { TraceManager } from './traceManager'
+import type { ScopeBase, Timestamp } from './types'
 
 type MakeEntryInput<ScopeT extends ScopeBase> = Omit<
   ComponentRenderSpan<ScopeT>,
@@ -31,59 +30,59 @@ export const generateUseBeacon =
   <ScopeT extends ScopeBase>(
     traceManager: TraceManager<ScopeT>,
   ): UseBeacon<ScopeT> =>
-    (config: BeaconConfig<GetScopeTFromTraceManager<TraceManager<ScopeT>>>) => {
-      const renderCountRef = useRef(0)
-      renderCountRef.current += 1
-
-      // TODO: do we need to keep the render count in attributes or does this just become `occurrence` later? How did this work in the previous implementation
-      const attributes = {
-        ...config.attributes,
-        renderCount: renderCountRef.current,
-      }
+  (config: BeaconConfig<GetScopeTFromTraceManager<TraceManager<ScopeT>>>) => {
+    const renderCountRef = useRef(0)
+    renderCountRef.current += 1
 
-      const status = config.error ? 'error' : 'ok'
+    // TODO: do we need to keep the render count in attributes or does this just become `occurrence` later? How did this work in the previous implementation
+    const attributes = {
+      ...config.attributes,
+      renderCount: renderCountRef.current,
+    }
 
-      const renderStartTaskEntry: ComponentRenderSpan<ScopeT> = makeEntry({
-        ...config,
-        type: 'component-render-start',
-        duration: 0,
-        attributes,
-        status,
-      })
+    const status = config.error ? 'error' : 'ok'
 
-      traceManager.processSpan(renderStartTaskEntry)
+    const renderStartTaskEntry: ComponentRenderSpan<ScopeT> = makeEntry({
+      ...config,
+      type: 'component-render-start',
+      duration: 0,
+      attributes,
+      status,
+    })
 
-      // Beacon effect for tracking 'component-render'. This will fire after every render as it does not have any dependencies:
-      useEffect(() => {
-        traceManager.processSpan(
-          makeEntry({
-            ...config,
-            type: 'component-render',
-            // TODO: the previous implementation had `operationManager.performance.now()`. Was this different?
-            duration: performance.now() - renderStartTaskEntry.startTime.now,
-            status,
-            attributes,
-          }),
-        )
-      })
+    traceManager.processSpan(renderStartTaskEntry)
 
-      // Beacon effect for tracking 'component-unmount' entries
-      useOnComponentUnmount(
-        (errorBoundaryMetadata) => {
-          const unmountEntry = makeEntry({
-            ...config,
-            type: 'component-unmount',
-            attributes,
-            error: errorBoundaryMetadata?.error,
-            errorInfo: errorBoundaryMetadata?.errorInfo,
-            duration: 0, // TODO: is 0 duration correct?
-            status: errorBoundaryMetadata?.error ? 'error' : 'ok',
-          })
-          traceManager.processSpan(unmountEntry)
-        },
-        [config.name],
+    // Beacon effect for tracking 'component-render'. This will fire after every render as it does not have any dependencies:
+    useEffect(() => {
+      traceManager.processSpan(
+        makeEntry({
+          ...config,
+          type: 'component-render',
+          // TODO: the previous implementation had `operationManager.performance.now()`. Was this different?
+          duration: performance.now() - renderStartTaskEntry.startTime.now,
+          status,
+          attributes,
+        }),
       )
-    }
+    })
+
+    // Beacon effect for tracking 'component-unmount' entries
+    useOnComponentUnmount(
+      (errorBoundaryMetadata) => {
+        const unmountEntry = makeEntry({
+          ...config,
+          type: 'component-unmount',
+          attributes,
+          error: errorBoundaryMetadata?.error,
+          errorInfo: errorBoundaryMetadata?.errorInfo,
+          duration: 0, // TODO: is 0 duration correct?
+          status: errorBoundaryMetadata?.error ? 'error' : 'ok',
+        })
+        traceManager.processSpan(unmountEntry)
+      },
+      [config.name],
+    )
+  }
 
 // Just for example and type checking
 // const tracingManager = new TraceManager({

src/v3/hooksTypes.ts

@@ -0,0 +1,23 @@
+import type { Attributes } from './spanTypes'
+import type { TraceManager } from './traceManager'
+import type { ScopeBase } from './types'
+
+export type RenderedOutput = 'null' | 'loading' | 'content' | 'error'
+
+export interface BeaconConfig<ScopeT extends ScopeBase> {
+  name: string
+  scope: ScopeT
+  renderedOutput: RenderedOutput
+  isIdle: boolean
+  attributes: Attributes
+  error?: Error
+}
+
+export type UseBeacon<ScopeT extends ScopeBase> = (
+  beaconConfig: BeaconConfig<ScopeT>,
+) => void
+
+export type GetScopeTFromTraceManager<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TraceManagerT extends TraceManager<any>,
+> = TraceManagerT extends TraceManager<infer ScopeT> ? ScopeT : never