web: add WindowLoad OpenTelemetry auto instrumentation (#40188)

Author: valerybugakov

client/web/src/monitoring/opentelemetry/initOpenTelemetry.ts

@@ -13,6 +13,7 @@ import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions'
 import isAbsoluteUrl from 'is-absolute-url'
 
 import { ConsoleBatchSpanExporter } from './exporters/consoleBatchSpanExporter'
+import { WindowLoadInstrumentation } from './instrumentations/window-load'
 
 export function initOpenTelemetry(): void {
     const { openTelemetry, externalURL } = window.context
@@ -45,7 +46,10 @@ export function initOpenTelemetry(): void {
 
         registerInstrumentations({
             // Type-casting is required since the `FetchInstrumentation` is wrongly typed internally as `node.js` instrumentation.
-            instrumentations: [(new FetchInstrumentation() as unknown) as InstrumentationOption],
+            instrumentations: [
+                (new FetchInstrumentation() as unknown) as InstrumentationOption,
+                new WindowLoadInstrumentation(),
+            ],
         })
     }
 }

client/web/src/monitoring/opentelemetry/instrumentations/constants.ts

@@ -0,0 +1,5 @@
+export enum WindowLoadSpanName {
+    WINDOW_LOAD = 'windowLoad',
+    DOCUMENT_FETCH = 'documentFetch',
+    RESOURCE_FETCH = 'resourceFetch',
+}

client/web/src/monitoring/opentelemetry/instrumentations/window-load.ts

@@ -0,0 +1,127 @@
+import { propagation, Span, ROOT_CONTEXT } from '@opentelemetry/api'
+import { otperformance } from '@opentelemetry/core'
+import { PerformanceTimingNames } from '@opentelemetry/sdk-trace-web'
+import { SemanticAttributes } from '@opentelemetry/semantic-conventions'
+
+import {
+    addTimeEventsToSpan,
+    addSpanPerformancePaintEvents,
+    performanceNavigationTimingToEntries,
+    getServerSideTraceParent,
+    ActiveSpanConfig,
+    InstrumentationBaseWeb,
+} from '../sdk'
+
+import { WindowLoadSpanName } from './constants'
+
+/**
+ * Auto instrumentation of the window load event based on Web Performance API `navigation` entries.
+ *
+ * 1. Listens to the first performance `navigation` entries update.
+ * 2. Creates the `WINDOW_LOAD` span capturing timings from `FETCH_START` till `LOAD_EVENT_END`.
+ * 3. Adds performance `navigation` events to the `WINDOW_LOAD` span.
+ * 4. Adds performance `paint` events to the `WINDOW_LOAD` span.
+ * 5. Creates nested spans for all resources loaded before the `LOAD_EVENT_END`.
+ *
+ * See Navigation Timing API documentation
+ * https://developer.mozilla.org/en-US/docs/Web/API/Navigation_timing_API
+ *
+ * See Navigation Timing spec processing model:
+ * https://www.w3.org/TR/navigation-timing-2/#processing-model
+ *
+ * See Resource Timing spec processing model:
+ * https://www.w3.org/TR/resource-timing-2/#attribute-descriptions
+ *
+ * Based on the OpenTelemetry Instrumentation Document Load
+ * https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/web/opentelemetry-instrumentation-document-load
+ *
+ * The implementation is forked because of various issues blocking
+ * the integration with other auto instrumentations.
+ *
+ * RUM integration: https://github.com/open-telemetry/opentelemetry-js-contrib/issues/732
+ * Fetch integration: https://github.com/open-telemetry/opentelemetry-js-contrib/issues/995
+ */
+export class WindowLoadInstrumentation extends InstrumentationBaseWeb {
+    public static instrumentationName = '@sourcegraph/instrumentation-window-load'
+    public static version = '0.1'
+
+    // The PerformanceObserver listener is executed once for the first `navigation` list update.
+    private observer = new PerformanceObserver((_list, observer) => {
+        this.collectPerformance()
+        observer.disconnect()
+    })
+
+    constructor() {
+        super(WindowLoadInstrumentation.instrumentationName, WindowLoadInstrumentation.version)
+    }
+
+    private addResourcesSpans(parentSpan: Span): void {
+        // Casting is required until this issue is resolved: https://github.com/microsoft/TypeScript/issues/33866
+        for (const resource of otperformance.getEntriesByType('resource') as PerformanceResourceTiming[]) {
+            this.createFinishedSpan({
+                name: WindowLoadSpanName.RESOURCE_FETCH,
+                startTime: resource[PerformanceTimingNames.FETCH_START],
+                endTime: resource[PerformanceTimingNames.RESPONSE_END],
+                parentSpan,
+                networkEvents: resource,
+                attributes: {
+                    [SemanticAttributes.HTTP_URL]: resource.name,
+                },
+            })
+        }
+    }
+
+    private collectPerformance(): void {
+        const entries = performanceNavigationTimingToEntries()
+        const rootContext = propagation.extract(ROOT_CONTEXT, { traceparent: getServerSideTraceParent() })
+
+        const rootSpanConfig: ActiveSpanConfig = {
+            name: WindowLoadSpanName.WINDOW_LOAD,
+            startTime: entries[PerformanceTimingNames.FETCH_START],
+            context: rootContext,
+            attributes: {
+                [SemanticAttributes.HTTP_URL]: location.href,
+                [SemanticAttributes.HTTP_USER_AGENT]: navigator.userAgent,
+            },
+        }
+
+        this.createActiveSpan(rootSpanConfig, rootSpan => {
+            addTimeEventsToSpan(rootSpan, entries, [
+                PerformanceTimingNames.FETCH_START,
+                PerformanceTimingNames.UNLOAD_EVENT_START,
+                PerformanceTimingNames.UNLOAD_EVENT_END,
+                PerformanceTimingNames.DOM_INTERACTIVE,
+                PerformanceTimingNames.DOM_CONTENT_LOADED_EVENT_START,
+                PerformanceTimingNames.DOM_CONTENT_LOADED_EVENT_END,
+                PerformanceTimingNames.DOM_COMPLETE,
+                PerformanceTimingNames.LOAD_EVENT_START,
+                PerformanceTimingNames.LOAD_EVENT_END,
+            ])
+
+            addSpanPerformancePaintEvents(rootSpan)
+
+            this.addResourcesSpans(rootSpan)
+            this.createFinishedSpan({
+                name: WindowLoadSpanName.DOCUMENT_FETCH,
+                startTime: entries[PerformanceTimingNames.FETCH_START],
+                endTime: entries[PerformanceTimingNames.RESPONSE_END],
+                networkEvents: entries,
+                parentSpan: rootSpan,
+            })
+
+            rootSpan.end(entries[PerformanceTimingNames.LOAD_EVENT_END])
+        })
+    }
+
+    public enable(): void {
+        if (window.document.readyState === 'complete') {
+            return this.collectPerformance()
+        }
+
+        this.observer.observe({ type: 'navigation' })
+    }
+
+    public disable(): void {
+        this.observer.disconnect()
+    }
+}

client/web/src/monitoring/opentelemetry/sdk/createActiveSpan.ts

@@ -0,0 +1,39 @@
+import { context, trace, Tracer, ROOT_CONTEXT, SpanOptions, Context, Span } from '@opentelemetry/api'
+
+export interface ActiveSpanConfig extends SpanOptions {
+    name: string
+    startTime?: number
+    endTime?: number
+    parentSpan?: Span
+    context?: Context
+}
+
+/**
+ * Creates span, links to a parent span, calls callback in the new span context.
+ * A helper to use with the Web Performance API where the `endTime` is often available right away.
+ *
+ * See https://opentelemetry.io/docs/instrumentation/js/instrumentation/#create-nested-spans
+ */
+export function createActiveSpan<F extends (span: Span) => unknown>(
+    tracer: Tracer,
+    config: ActiveSpanConfig,
+    callback: F
+): ReturnType<F> | null {
+    const { name, startTime, parentSpan, context: spanContext = ROOT_CONTEXT, ...restSpanOptions } = config
+
+    if (typeof startTime === 'undefined') {
+        return null
+    }
+
+    const resultContext = parentSpan ? trace.setSpan(context.active(), parentSpan) : spanContext
+
+    return tracer.startActiveSpan<F>(
+        name,
+        {
+            startTime,
+            ...restSpanOptions,
+        },
+        resultContext,
+        callback
+    )
+}

client/web/src/monitoring/opentelemetry/sdk/createFinishedSpan.ts

@@ -0,0 +1,52 @@
+import { context, trace, Tracer, ROOT_CONTEXT, SpanOptions, Context, Span } from '@opentelemetry/api'
+import { addSpanNetworkEvents, PerformanceEntries } from '@opentelemetry/sdk-trace-web'
+
+export interface FinishedSpanConfig extends SpanOptions {
+    name: string
+    startTime?: number
+    endTime?: number
+    parentSpan?: Span
+    context?: Context
+    networkEvents?: PerformanceEntries
+}
+
+/**
+ * Creates span, links to a parent span, adds network events, ends the span.
+ * A helper to use with the Web Performance API where the `endTime` is often available right away.
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/API/Performance
+ */
+export function createFinishedSpan(tracer: Tracer, config: FinishedSpanConfig): Span | null {
+    const {
+        name,
+        startTime,
+        endTime,
+        parentSpan,
+        context: spanContext = ROOT_CONTEXT,
+        networkEvents,
+        ...restSpanOptions
+    } = config
+
+    if (typeof startTime === 'undefined' || typeof endTime === 'undefined') {
+        return null
+    }
+
+    const resultContext = parentSpan ? trace.setSpan(context.active(), parentSpan) : spanContext
+
+    const span = tracer.startSpan(
+        name,
+        {
+            startTime,
+            ...restSpanOptions,
+        },
+        resultContext
+    )
+
+    if (networkEvents) {
+        addSpanNetworkEvents(span, networkEvents)
+    }
+
+    span.end(endTime)
+
+    return span
+}

client/web/src/monitoring/opentelemetry/sdk/index.ts

@@ -0,0 +1,5 @@
+export * from './performance'
+export * from './trace'
+export * from './createActiveSpan'
+export * from './createFinishedSpan'
+export * from './instrumentation-base-web'

client/web/src/monitoring/opentelemetry/sdk/instrumentation-base-web.ts

@@ -0,0 +1,28 @@
+import { Instrumentation, InstrumentationConfig, InstrumentationBase } from '@opentelemetry/instrumentation'
+
+import { createActiveSpan } from './createActiveSpan'
+import { createFinishedSpan } from './createFinishedSpan'
+
+/**
+ * Base abstract class for instrumenting Sourcegraph OpenTelemetry web plugins.
+ *
+ * The implementation is based on
+ * https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation
+ */
+export abstract class InstrumentationBaseWeb extends InstrumentationBase implements Instrumentation {
+    protected createActiveSpan = createActiveSpan.bind(this, this.tracer)
+    protected createFinishedSpan = createFinishedSpan.bind(this, this.tracer)
+
+    constructor(
+        instrumentationName: string,
+        instrumentationVersion: string,
+        // Do not enable instrumentation by default until `registerInstrumentations` call.
+        config: InstrumentationConfig = { enabled: false }
+    ) {
+        super(instrumentationName, instrumentationVersion, config)
+    }
+
+    public init(): void {
+        /** noop, the abstract method is defined for overriding modules in node.js */
+    }
+}

client/web/src/monitoring/opentelemetry/sdk/performance.ts

@@ -0,0 +1,37 @@
+import { Span } from '@opentelemetry/api'
+import { otperformance } from '@opentelemetry/core'
+import { hasKey, PerformanceEntries, PerformanceTimingNames } from '@opentelemetry/sdk-trace-web'
+import { camelCase } from 'lodash'
+
+/**
+ * Picks `navigation` performance entries matching keys specified in `PerformanceTimingNames`.
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/API/PerformanceNavigationTiming
+ */
+export function performanceNavigationTimingToEntries(): PerformanceEntries {
+    const [timing] = otperformance.getEntriesByType('navigation') as PerformanceNavigationTiming[]
+
+    return Object.values(PerformanceTimingNames).reduce<PerformanceEntries>((result, key) => {
+        if (timing && hasKey(timing, key)) {
+            const value = timing[key]
+
+            if (typeof value === 'number') {
+                result[key] = value
+            }
+        }
+
+        return result
+    }, {})
+}
+
+/**
+ * If `paint` performance entries are available adds `first-paint`
+ * and `first-contentful-paint` events if to the span.
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/API/PerformancePaintTiming
+ */
+export const addSpanPerformancePaintEvents = (span: Span): void => {
+    for (const { name, startTime } of otperformance.getEntriesByType('paint')) {
+        span.addEvent(camelCase(name), startTime)
+    }
+}

client/web/src/monitoring/opentelemetry/sdk/trace.ts

@@ -0,0 +1,43 @@
+import { context, trace, Span, TimeInput } from '@opentelemetry/api'
+import { TRACE_PARENT_HEADER } from '@opentelemetry/core'
+
+/**
+ * Parses `traceParent` - a meta property that comes from server.
+ * It should be dynamically generated server side to have the server's request trace Id,
+ * a parent span Id that was set on the server's request span.
+ *
+ * See https://opentelemetry.io/docs/instrumentation/js/getting-started/browser/
+ */
+export function getServerSideTraceParent(): string {
+    const metaElement = Array.from(document.querySelectorAll('meta')).find(
+        element => element.getAttribute('name') === TRACE_PARENT_HEADER
+    )
+
+    return metaElement?.content || ''
+}
+
+/**
+ * Sets span as active and executes the callback in span's context.
+ *
+ * See https://github.com/open-telemetry/opentelemetry-js-api/blob/main/docs/tracing.md#describing-a-span
+ */
+export function runInSpanContext(span: Span, callback: () => void): void {
+    context.with(trace.setSpan(context.active(), span), callback)
+}
+
+/**
+ * Adds defined time events to span.
+ *
+ * See https://opentelemetry.io/docs/concepts/signals/traces/#span-events
+ */
+export function addTimeEventsToSpan<T extends Record<string, TimeInput | undefined>>(
+    span: Span,
+    timeEvents: T,
+    names: Extract<keyof T, string>[]
+): void {
+    for (const name of names) {
+        if (typeof timeEvents[name] !== 'undefined') {
+            span.addEvent(name, timeEvents[name])
+        }
+    }
+}