@newrelic/browser-agent 0.1.229 → 0.1.230

package/src/features/page_view_event/aggregate/index.js

@@ -0,0 +1,134 @@
+import { handle } from '../../../common/event-emitter/handle'
+import { FEATURE_NAMES } from '../../../loaders/features/features'
+import { isiOS } from '../../../common/browser-version/ios-version'
+import { onTTFB } from 'web-vitals'
+import { mapOwn } from '../../../common/util/map-own'
+import { param, fromArray } from '../../../common/url/encode'
+import { addPT, addPN } from '../../../common/timing/nav-timing'
+import { stringify } from '../../../common/util/stringify'
+import { paintMetrics } from '../../../common/metrics/paint-metrics'
+import { submitData } from '../../../common/util/submit-data'
+import { getConfigurationValue, getInfo, getRuntime } from '../../../common/config/config'
+import { HarvestScheduler } from '../../../common/harvest/harvest-scheduler'
+import { AggregateBase } from '../../utils/aggregate-base'
+import * as CONSTANTS from '../constants'
+import { getActivatedFeaturesFlags } from './initialized-features'
+import { globalScope, isBrowserScope } from '../../../common/util/global-scope'
+import { drain } from '../../../common/drain/drain'
+
+const jsonp = 'NREUM.setToken'
+
+export class Aggregate extends AggregateBase {
+  static featureName = CONSTANTS.FEATURE_NAME
+  constructor (agentIdentifier, aggregator) {
+    super(agentIdentifier, aggregator, CONSTANTS.FEATURE_NAME)
+
+    if (typeof PerformanceNavigationTiming !== 'undefined' && !isiOS) {
+      this.alreadySent = false // we don't support timings on BFCache restores
+      const agentRuntime = getRuntime(agentIdentifier) // we'll store timing values on the runtime obj to be read by the aggregate module
+
+      /* Time To First Byte
+        This listener must record these values *before* PVE's aggregate sends RUM. */
+      onTTFB(({ value, entries }) => {
+        if (this.alreadySent) return
+        this.alreadySent = true
+
+        agentRuntime[CONSTANTS.TTFB] = Math.round(value) // this is our "backend" duration; web-vitals will ensure it's lower bounded at 0
+
+        // Similar to what vitals does for ttfb, we have to factor in activation-start when calculating relative timings:
+        const navEntry = entries[0]
+        const respOrActivStart = Math.max(navEntry.responseStart, navEntry.activationStart || 0)
+        agentRuntime[CONSTANTS.FBTWL] = Math.max(Math.round(navEntry.loadEventEnd - respOrActivStart), 0) // our "frontend" duration
+        handle('timing', ['load', Math.round(navEntry.loadEventEnd)], undefined, FEATURE_NAMES.pageViewTiming, this.ee)
+        agentRuntime[CONSTANTS.FBTDC] = Math.max(Math.round(navEntry.domContentLoadedEventEnd - respOrActivStart), 0) // our "dom processing" duration
+
+        this.sendRum()
+      })
+    } else {
+      this.sendRum() // timings either already in runtime from instrument or is meant to get 0'd.
+    }
+  }
+
+  getScheme () {
+    return getConfigurationValue(this.agentIdentifier, 'ssl') === false ? 'http' : 'https'
+  }
+
+  sendRum () {
+    const info = getInfo(this.agentIdentifier)
+    if (!info.beacon) return
+    if (info.queueTime) this.aggregator.store('measures', 'qt', { value: info.queueTime })
+    if (info.applicationTime) this.aggregator.store('measures', 'ap', { value: info.applicationTime })
+    const agentRuntime = getRuntime(this.agentIdentifier)
+
+    // These 3 values should've been recorded after load and before this func runs. They are part of the minimum required for PageView events to be created.
+    // Following PR #428, which demands that all agents send RUM call, these need to be sent even outside of the main window context where PerformanceTiming
+    // or PerformanceNavigationTiming do not exists. Hence, they'll be filled in by 0s instead in, for example, worker threads that still init the PVE module.
+    this.aggregator.store('measures', 'be', { value: isBrowserScope ? agentRuntime[CONSTANTS.TTFB] : 0 })
+    this.aggregator.store('measures', 'fe', { value: isBrowserScope ? agentRuntime[CONSTANTS.FBTWL] : 0 })
+    this.aggregator.store('measures', 'dc', { value: isBrowserScope ? agentRuntime[CONSTANTS.FBTDC] : 0 })
+
+    var measuresMetrics = this.aggregator.get('measures')
+
+    var measuresQueryString = mapOwn(measuresMetrics, function (metricName, measure) {
+      return '&' + metricName + '=' + measure.params.value
+    }).join('')
+
+    // currently we only have one version of our protocol
+    // in the future we may add more
+    var protocol = '1'
+
+    var scheduler = new HarvestScheduler('page_view_event', {}, this)
+
+    var chunksForQueryString = [scheduler.harvest.baseQueryString()]
+
+    chunksForQueryString.push(measuresQueryString)
+
+    chunksForQueryString.push(param('tt', info.ttGuid))
+    chunksForQueryString.push(param('us', info.user))
+    chunksForQueryString.push(param('ac', info.account))
+    chunksForQueryString.push(param('pr', info.product))
+    chunksForQueryString.push(param('af', getActivatedFeaturesFlags(this.agentIdentifier).join(',')))
+
+    if (globalScope.performance && typeof (globalScope.performance.timing) !== 'undefined') {
+      var navTimingApiData = ({
+        timing: addPT(agentRuntime.offset, globalScope.performance.timing, {}),
+        navigation: addPN(globalScope.performance.navigation, {})
+      })
+      chunksForQueryString.push(param('perf', stringify(navTimingApiData)))
+    }
+
+    try { // PVTiming sends these too, albeit using web-vitals and slightly different; it's unknown why they're duplicated, but PVT should be the truth
+      var entries = globalScope.performance.getEntriesByType('paint')
+      entries.forEach(function (entry) {
+        if (!entry.startTime || entry.startTime <= 0) return
+
+        if (entry.name === 'first-paint') {
+          chunksForQueryString.push(param('fp', String(Math.floor(entry.startTime))))
+        } else if (entry.name === 'first-contentful-paint') {
+          chunksForQueryString.push(param('fcp', String(Math.floor(entry.startTime))))
+        }
+        paintMetrics[entry.name] = Math.floor(entry.startTime) // this is consumed by Spa module
+      })
+    } catch (e) {}
+
+    chunksForQueryString.push(param('xx', info.extra))
+    chunksForQueryString.push(param('ua', info.userAttributes))
+    chunksForQueryString.push(param('at', info.atts))
+
+    var customJsAttributes = stringify(info.jsAttributes)
+    chunksForQueryString.push(param('ja', customJsAttributes === '{}' ? null : customJsAttributes))
+
+    var queryString = fromArray(chunksForQueryString, agentRuntime.maxBytes)
+
+    // Capture bytes sent to RUM call endpoint (currently `1`) as a supportability metric. See metrics aggregator (on unload).
+    agentRuntime.bytesSent[protocol] = (agentRuntime.bytesSent[protocol] || 0) + queryString?.length || 0
+
+    const isValidJsonp = submitData.jsonp(
+      this.getScheme() + '://' + info.beacon + '/' + protocol + '/' + info.licenseKey + queryString,
+      jsonp
+    )
+    // Usually `drain` is invoked automatically after processing feature flags contained in the JSONP callback from
+    // ingest (see `activateFeatures`), so when JSONP cannot execute (as with module workers), we drain manually.
+    if (!isValidJsonp) drain(this.agentIdentifier, CONSTANTS.FEATURE_NAME)
+  }
+}

package/src/features/page_view_event/aggregate/initialized-features.js

@@ -0,0 +1,31 @@
+import { FEATURE_NAMES } from '../../../loaders/features/features'
+
+/**
+ * Get an array of flags required by downstream (NR UI) based on the features initialized in this agent
+ * (aka what is running on the page).
+ * @param {String} agentId - the ID of the initialized agent on the page, mapping to the one under the global 'newrelic' object
+ * @returns {String[]} Up to 5 short strings corresponding to ingest mapping of features.
+ */
+export function getActivatedFeaturesFlags (agentId) {
+  const flagArr = []
+
+  Object.keys(newrelic.initializedAgents[agentId].features).forEach(featName => {
+    switch (featName) {
+      case FEATURE_NAMES.ajax:
+        flagArr.push('xhr'); break
+      case FEATURE_NAMES.jserrors:
+        flagArr.push('err'); break
+      case FEATURE_NAMES.pageAction:
+        flagArr.push('ins'); break
+      case FEATURE_NAMES.sessionTrace:
+        flagArr.push('stn'); break
+      case FEATURE_NAMES.spa:
+        flagArr.push('spa'); break
+    }
+  })
+
+  return flagArr
+}
+
+// Note: this module and the "af" param in src/features/page_view_event/aggregate/index.js can be removed in the future at such time
+// that it's no longer being used. For the browser agent, this is an unused flag system.

package/src/features/page_view_event/constants.js

@@ -0,0 +1,6 @@
+import { FEATURE_NAMES } from '../../loaders/features/features'
+
+export const FEATURE_NAME = FEATURE_NAMES.pageViewEvent
+export const TTFB = 'firstbyte'
+export const FBTDC = 'domcontent'
+export const FBTWL = 'windowload'

package/src/features/page_view_event/index.js

@@ -0,0 +1 @@
+export { Instrument as PageViewEvent } from './instrument/index'

package/src/features/page_view_event/instrument/index.js

@@ -0,0 +1,33 @@
+
+import { handle } from '../../../common/event-emitter/handle'
+import { isiOS } from '../../../common/browser-version/ios-version'
+import { InstrumentBase } from '../../utils/instrument-base'
+import * as CONSTANTS from '../constants'
+import { FEATURE_NAMES } from '../../../loaders/features/features'
+import { getRuntime } from '../../../common/config/config'
+import { onDOMContentLoaded, onWindowLoad } from '../../../common/window/load'
+import { now } from '../../../common/timing/now'
+
+export class Instrument extends InstrumentBase {
+  static featureName = CONSTANTS.FEATURE_NAME
+  constructor (agentIdentifier, aggregator, auto = true) {
+    super(agentIdentifier, aggregator, CONSTANTS.FEATURE_NAME, auto)
+
+    if ((typeof PerformanceNavigationTiming === 'undefined' || isiOS) && typeof PerformanceTiming !== 'undefined') {
+      // For majority browser versions in which PNT exists, we can get load timings later from the nav entry (in the aggregate portion). At minimum, PT should exist for main window.
+      // *cli Mar'23 - iOS 15.2 & 15.4 testing in Sauce still fails with onTTFB. Hence, all iOS will fallback to this for now. Unknown if this is similar in nature to iOS_below16 bug.
+      const agentRuntime = getRuntime(agentIdentifier)
+
+      agentRuntime[CONSTANTS.TTFB] = Math.max(Date.now() - agentRuntime.offset, 0)
+      onDOMContentLoaded(() => agentRuntime[CONSTANTS.FBTDC] = Math.max(now() - agentRuntime[CONSTANTS.TTFB], 0))
+      onWindowLoad(() => {
+        const timeNow = now()
+        agentRuntime[CONSTANTS.FBTWL] = Math.max(timeNow - agentRuntime[CONSTANTS.TTFB], 0)
+        handle('timing', ['load', timeNow], undefined, FEATURE_NAMES.pageViewTiming, this.ee)
+      })
+    }
+    // Else, inference: inside worker or some other env where these events are irrelevant. They'll get filled in with 0s in RUM call.
+
+    this.importAggregator()
+  }
+}

package/src/features/page_view_timing/aggregate/index.js

@@ -0,0 +1,246 @@
+/*
+ * Copyright 2020 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { onFCP, onFID, onLCP, onCLS, onINP } from 'web-vitals'
+import { onFirstPaint } from '../first-paint'
+import { onLongTask } from '../long-tasks'
+import { iOS_below16 } from '../../../common/browser-version/ios-version'
+import { nullable, numeric, getAddStringContext, addCustomAttributes } from '../../../common/serialize/bel-serializer'
+import { mapOwn } from '../../../common/util/map-own'
+import { HarvestScheduler } from '../../../common/harvest/harvest-scheduler'
+import { registerHandler } from '../../../common/event-emitter/register-handler'
+import { cleanURL } from '../../../common/url/clean-url'
+import { handle } from '../../../common/event-emitter/handle'
+import { getInfo, getConfigurationValue, getRuntime } from '../../../common/config/config'
+import { AggregateBase } from '../../utils/aggregate-base'
+import { FEATURE_NAME } from '../constants'
+import { drain } from '../../../common/drain/drain'
+import { FEATURE_NAMES } from '../../../loaders/features/features'
+
+export class Aggregate extends AggregateBase {
+  static featureName = FEATURE_NAME
+  constructor (agentIdentifier, aggregator) {
+    super(agentIdentifier, aggregator, FEATURE_NAME)
+
+    this.timings = []
+    this.timingsSent = []
+    this.curSessEndRecorded = false
+
+    try { // we (only) need to track cls state because it's attached to other timing events rather than reported on change...
+      this.clsSupported = PerformanceObserver.supportedEntryTypes.includes('layout-shift')
+      this.cls = 0
+    } catch (e) {}
+
+    /*! This is the section that used to be in the loader portion: !*/
+    /* ------------------------------------------------------------ */
+    const pageStartedHidden = getRuntime(agentIdentifier).initHidden // our attempt at recapturing initial vis state since this code runs post-load time
+    this.alreadySent = new Set() // since we don't support timings on BFCache restores, this tracks and helps cap metrics that web-vitals report more than once
+
+    /* PerformancePaintTiming API - BFC is not yet supported. */
+    onFirstPaint(({ name, value }) => {
+      if (pageStartedHidden) return
+      this.addTiming(name.toLowerCase(), Math.floor(value))
+    })
+
+    /* First Contentful Paint - As of WV v3, it still imperfectly tries to detect document vis state asap and isn't supposed to report if page starts hidden. */
+    if (iOS_below16) {
+      try {
+        if (!pageStartedHidden) { // see ios-version.js for detail on this following bug case; tldr: buffered flag doesn't work but getEntriesByType does
+          const paintEntries = performance.getEntriesByType('paint')
+          paintEntries.forEach(entry => {
+            if (entry.name === 'first-contentful-paint') {
+              this.addTiming('fcp', Math.floor(entry.startTime))
+            }
+          })
+        }
+      } catch (e) {}
+    } else {
+      onFCP(({ name, value }) => {
+        if (pageStartedHidden || this.alreadySent.has(name)) return
+        this.alreadySent.add(name)
+        this.addTiming(name.toLowerCase(), value)
+      })
+    }
+
+    /* First Input Delay (+"First Interaction") - As of WV v3, it still imperfectly tries to detect document vis state asap and isn't supposed to report if page starts hidden. */
+    onFID(({ name, value, entries }) => {
+      if (pageStartedHidden || this.alreadySent.has(name)) return
+      this.alreadySent.add(name)
+
+      // CWV will only report one (THE) first-input entry to us; fid isn't reported if there are no user interactions occurs before the *first* page hiding.
+      const fiEntry = entries[0]
+      const attributes = {
+        type: fiEntry.name,
+        fid: Math.round(value)
+      }
+      this.addConnectionAttributes(attributes)
+      this.addTiming('fi', Math.round(fiEntry.startTime), attributes)
+    })
+
+    /* Largest Contentful Paint - As of WV v3, it still imperfectly tries to detect document vis state asap and isn't supposed to report if page starts hidden. */
+    onLCP(({ name, value, entries }) => {
+      if (pageStartedHidden || this.alreadySent.has(name)) return
+      this.alreadySent.add(name)
+
+      // CWV will only ever report one (THE) lcp entry to us; lcp is also only reported *once* on earlier(user interaction, page hidden).
+      const lcpEntry = entries[entries.length - 1] // this looks weird if we only expect one, but this is how cwv-attribution gets it so to be sure...
+      const attrs = {
+        size: lcpEntry.size,
+        eid: lcpEntry.id
+      }
+      this.addConnectionAttributes(attrs)
+      if (lcpEntry.url) {
+        attrs['elUrl'] = cleanURL(lcpEntry.url)
+      }
+      if (lcpEntry.element && lcpEntry.element.tagName) {
+        attrs['elTag'] = lcpEntry.element.tagName
+      }
+      this.addTiming(name.toLowerCase(), value, attrs)
+    })
+
+    /* Cumulative Layout Shift - We don't have to limit this callback since cls is stored as a state and only sent as attribute on other timings. */
+    onCLS(({ value }) => this.cls = value)
+
+    /* Interaction-to-Next-Paint */
+    onINP(({ name, value, id }) => this.addTiming(name.toLowerCase(), value, { metricId: id }))
+
+    /* PerformanceLongTaskTiming API */
+    if (getConfigurationValue(this.agentIdentifier, 'page_view_timing.long_task') === true) {
+      onLongTask(({ name, value, info }) => this.addTiming(name.toLowerCase(), value, info)) // lt context is passed as 'info'=attrs in the timing node
+    }
+    /* ------------------------------------End of ex-loader section */
+
+    /* It's important that CWV api, like "onLCP", is called before this scheduler is initialized. The reason is because they listen to the same
+      on vis change or pagehide events, and we'd want ex. onLCP to record the timing (win the race) before we try to send "final harvest". */
+    this.scheduler = new HarvestScheduler('events', {
+      onFinished: (...args) => this.onHarvestFinished(...args),
+      getPayload: (...args) => this.prepareHarvest(...args)
+    }, this)
+
+    registerHandler('timing', (name, value, attrs) => this.addTiming(name, value, attrs), this.featureName, this.ee) // notice CLS is added to all timings via 4th param
+    registerHandler('docHidden', msTimestamp => this.endCurrentSession(msTimestamp), this.featureName, this.ee)
+    registerHandler('winPagehide', msTimestamp => this.recordPageUnload(msTimestamp), this.featureName, this.ee)
+
+    const initialHarvestSeconds = getConfigurationValue(this.agentIdentifier, 'page_view_timing.initialHarvestSeconds') || 10
+    const harvestTimeSeconds = getConfigurationValue(this.agentIdentifier, 'page_view_timing.harvestTimeSeconds') || 30
+    // send initial data sooner, then start regular
+    this.ee.on(`drain-${this.featureName}`, () => { this.scheduler.startTimer(harvestTimeSeconds, initialHarvestSeconds) })
+
+    drain(this.agentIdentifier, this.featureName)
+  }
+
+  // takes an attributes object and appends connection attributes if available
+  addConnectionAttributes (attributes) {
+    var connection = navigator.connection || navigator.mozConnection || navigator.webkitConnection // to date, both window & worker shares the same support for connection
+    if (!connection) return
+
+    if (connection.type) attributes['net-type'] = connection.type
+    if (connection.effectiveType) attributes['net-etype'] = connection.effectiveType
+    if (connection.rtt) attributes['net-rtt'] = connection.rtt
+    if (connection.downlink) attributes['net-dlink'] = connection.downlink
+
+    return attributes
+  }
+
+  /**
+   * Add the time of _document visibilitychange to hidden_ to the next PVT harvest == NRDB pageHide attr.
+   * @param {number} timestamp
+   */
+  endCurrentSession (timestamp) {
+    if (!this.curSessEndRecorded) { // TO DO: stage 2 - we don't want to capture this timing twice on page navigating away, but it should run again if we return to page and away *again*
+      this.addTiming('pageHide', timestamp, null)
+      this.curSessEndRecorded = true
+    }
+  }
+
+  /**
+   * Add the time of _window pagehide event_ firing to the next PVT harvest == NRDB windowUnload attr.
+   */
+  recordPageUnload (timestamp) {
+    this.addTiming('unload', timestamp, null)
+    // Because window's pageHide commonly fires before vis change and the final harvest occurs on the earlier of the two, we also have to add that now or it won't make it into the last payload out.
+    this.endCurrentSession(timestamp)
+  }
+
+  addTiming (name, value, attrs) {
+    attrs = attrs || {}
+
+    // If CLS is supported, a cls value should exist and be reported, even at 0.
+    // *cli Mar'23 - At this time, it remains attached to all timings. See NEWRELIC-6143.
+    if (this.clsSupported) {
+      attrs['cls'] = this.cls
+    }
+
+    this.timings.push({
+      name: name,
+      value: value,
+      attrs: attrs
+    })
+
+    handle('pvtAdded', [name, value, attrs], undefined, FEATURE_NAMES.sessionTrace, this.ee)
+  }
+
+  onHarvestFinished (result) {
+    if (result.retry && this.timingsSent.length > 0) {
+      for (var i = 0; i < this.timingsSent.length; i++) {
+        this.timings.push(this.timingsSent[i])
+      }
+      this.timingsSent = []
+    }
+  }
+
+  appendGlobalCustomAttributes (timing) {
+    var timingAttributes = timing.attrs || {}
+    var customAttributes = getInfo(this.agentIdentifier).jsAttributes || {}
+
+    var reservedAttributes = ['size', 'eid', 'cls', 'type', 'fid', 'elTag', 'elUrl', 'net-type',
+      'net-etype', 'net-rtt', 'net-dlink']
+    mapOwn(customAttributes, function (key, val) {
+      if (reservedAttributes.indexOf(key) < 0) {
+        timingAttributes[key] = val
+      }
+    })
+  }
+
+  // serialize and return current timing data, clear and save current data for retry
+  prepareHarvest (options) {
+    if (this.timings.length === 0) return
+
+    var payload = this.getPayload(this.timings)
+    if (options.retry) {
+      for (var i = 0; i < this.timings.length; i++) {
+        this.timingsSent.push(this.timings[i])
+      }
+    }
+    this.timings = []
+    return { body: { e: payload } }
+  }
+
+  // serialize array of timing data
+  getPayload (data) {
+    var addString = getAddStringContext(this.agentIdentifier)
+
+    var payload = 'bel.6;'
+
+    for (var i = 0; i < data.length; i++) {
+      var timing = data[i]
+
+      payload += 'e,'
+      payload += addString(timing.name) + ','
+      payload += nullable(timing.value, numeric, false) + ','
+
+      this.appendGlobalCustomAttributes(timing)
+
+      var attrParts = addCustomAttributes(timing.attrs, addString)
+      if (attrParts && attrParts.length > 0) {
+        payload += numeric(attrParts.length) + ';' + attrParts.join(';')
+      }
+
+      if ((i + 1) < data.length) payload += ';'
+    }
+
+    return payload
+  }
+}

package/src/features/page_view_timing/constants.js

@@ -0,0 +1,3 @@
+import { FEATURE_NAMES } from '../../loaders/features/features'
+
+export const FEATURE_NAME = FEATURE_NAMES.pageViewTiming

package/src/features/page_view_timing/first-paint.js

@@ -0,0 +1,41 @@
+/**
+ * Calls the `onReport` function when the 'first-paint' PerformancePaintTiming entry is observed.
+ * The argument supplied is an object similar to the Metric type used by web-vitals library.
+ *
+ * @param {Function} onReport - callback that accepts a `metric` object as the single parameter
+ */
+export const onFirstPaint = (onReport) => {
+  const handleEntries = (entries) => {
+    entries.forEach(entry => {
+      if (entry.name === 'first-paint') {
+        observer.disconnect()
+
+        /* Initial hidden state and pre-rendering not yet considered for first paint. See web-vitals onFCP for example. */
+        const metric = {
+          name: 'FP',
+          value: entry.startTime
+        }
+        onReport(metric)
+      }
+    })
+  }
+
+  let observer
+  try {
+    if (PerformanceObserver.supportedEntryTypes.includes('paint')) {
+      observer = new PerformanceObserver((list) => {
+        // Delay by a microtask to workaround a bug in Safari where the
+        // callback is invoked immediately, rather than in a separate task.
+        // See: https://github.com/GoogleChrome/web-vitals/issues/277
+        Promise.resolve().then(() => {
+          handleEntries(list.getEntries())
+        })
+      })
+      observer.observe({ type: 'paint', buffered: true })
+    }
+  } catch (e) {
+    // Do nothing.
+  }
+
+  /* BFCache restore not yet considered for first paint. See web-vitals onFCP for example. */
+}

package/src/features/page_view_timing/index.js

@@ -0,0 +1 @@
+export { Instrument as PageViewTiming } from './instrument/index'

package/src/features/page_view_timing/instrument/index.js

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2020 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { handle } from '../../../common/event-emitter/handle'
+import { getRuntime } from '../../../common/config/config'
+import { subscribeToVisibilityChange } from '../../../common/window/page-visibility'
+import { windowAddEventListener } from '../../../common/event-listener/event-listener-opts'
+import { now } from '../../../common/timing/now'
+import { InstrumentBase } from '../../utils/instrument-base'
+import { FEATURE_NAME } from '../constants'
+import { isBrowserScope } from '../../../common/util/global-scope'
+
+export class Instrument extends InstrumentBase {
+  static featureName = FEATURE_NAME
+  constructor (agentIdentifier, aggregator, auto = true) {
+    super(agentIdentifier, aggregator, FEATURE_NAME, auto)
+    if (!isBrowserScope) return // CWV is irrelevant outside web context
+
+    // Document visibility state becomes hidden; this should run as soon as possible in page life.
+    // While we try to replicate web-vital's visibilitywatcher logic in an effort to defer that library to post-pageload, this isn't perfect and doesn't consider prerendering.
+    getRuntime(agentIdentifier).initHidden = Boolean(document.visibilityState === 'hidden')
+    subscribeToVisibilityChange(() => handle('docHidden', [now()], undefined, FEATURE_NAME, this.ee), true)
+
+    // Window fires its pagehide event (typically on navigation--this occurrence is a *subset* of vis change); don't defer this unless it's guarantee it cannot happen before load(?)
+    windowAddEventListener('pagehide', () => handle('winPagehide', [now()], undefined, FEATURE_NAME, this.ee))
+
+    this.importAggregator()
+  }
+}

package/src/features/page_view_timing/long-tasks.js

@@ -0,0 +1,60 @@
+import { subscribeToEOL } from '../../common/unload/eol'
+
+/**
+ * Calls the `onReport` function for every entry reported by the PerformanceLongTaskTiming API.
+ * The reported value is a `DOMHighResTimeStamp`.
+ *
+ * The callback is always called when the page's visibility state changes to hidden.
+ * As a result, the `onReport` function might be called multiple times during the same page load.
+ *
+ * @param {Function} onReport - callback that accepts a `metric` object as the single parameter
+ */
+export const onLongTask = (onReport) => {
+  const handleEntries = (entries) => {
+    entries.forEach(entry => {
+      const metric = {
+        name: 'LT',
+        value: entry.duration,
+        info: {	// this property deviates from CWV std interface but will hold the custom context to send to NRDB
+          ltFrame: entry.name,				// MDN: the browsing context or frame that can be attributed to the long task
+          ltStart: entry.startTime,	// MDN: a double representing the time (millisec) when the task started
+          ltCtr: entry.attribution[0].containerType			// MDN: type of frame container: 'iframe', 'embed', or 'object' ... but this can also be 'window'
+        }
+      }
+      if (metric.info.ltCtr !== 'window') {	// the following properties are only of relevance & appended for html elements
+        Object.assign(metric.info, {
+          ltCtrSrc: entry.attribution[0].containerSrc,		// MDN: container's 'src' attribute
+          ltCtrId: entry.attribution[0].containerId,			// MDN: container's 'id' attribute
+          ltCtrName: entry.attribution[0].containerName		// MDN: container's 'name' attribute
+        })
+      }
+
+      onReport(metric)	// report every long task observed unconditionally
+    })
+  }
+
+  let observer
+  try {
+    if (PerformanceObserver.supportedEntryTypes.includes('longtask')) {
+      observer = new PerformanceObserver((list) => {
+        // Delay by a microtask to workaround a bug in Safari where the
+        // callback is invoked immediately, rather than in a separate task.
+        // See: https://github.com/GoogleChrome/web-vitals/issues/277
+        Promise.resolve().then(() => {
+          handleEntries(list.getEntries())
+        })
+      })
+      observer.observe({ type: 'longtask', buffered: true })
+    }
+  } catch (e) {
+    // Do nothing.
+  }
+
+  if (observer) {
+    subscribeToEOL(() => {
+      handleEntries(observer.takeRecords())
+    }, true)	// this bool is a temp arg under staged BFCache work that runs the func under the new page session logic -- tb removed w/ the feature flag later
+
+    /* No work needed on BFCache restore for long task. */
+  }
+}