@newrelic/browser-agent 0.1.229 → 0.1.231

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

@@ -0,0 +1,143 @@
+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) {
+      if (typeof PerformanceNavigationTiming !== 'undefined') { // Navigation Timing level 2 API that replaced PerformanceTiming & PerformanceNavigation
+        const navTimingEntry = globalScope?.performance?.getEntriesByType('navigation')?.[0]
+        const perf = ({
+          timing: addPT(agentRuntime.offset, navTimingEntry, {}),
+          navigation: addPN(navTimingEntry, {})
+        })
+        chunksForQueryString.push(param('perf', stringify(perf)))
+      } else if (typeof PerformanceTiming !== 'undefined') { // Safari pre-15 did not support level 2 timing
+        const perf = ({
+          timing: addPT(agentRuntime.offset, globalScope.performance.timing, {}, true),
+          navigation: addPN(globalScope.performance.navigation, {})
+        })
+        chunksForQueryString.push(param('perf', stringify(perf)))
+      }
+    }
+
+    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,257 @@
+/*
+ * 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
+    this.cls = null // this should be null unless set to a numeric value by web-vitals so that we differentiate if CLS is supported
+
+    /*! 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) || entries.length === 0) 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)
+
+      const attributes = {}
+      if (entries.length > 0) {
+        // 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...
+        attributes.size = lcpEntry.size
+        attributes.eid = lcpEntry.id
+
+        if (lcpEntry.url) {
+          attributes['elUrl'] = cleanURL(lcpEntry.url)
+        }
+        if (lcpEntry.element?.tagName) {
+          attributes['elTag'] = lcpEntry.element.tagName
+        }
+      }
+
+      this.addConnectionAttributes(attributes)
+      this.addTiming(name.toLowerCase(), value, attributes)
+    })
+
+    /* 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.
+      reportAllChanges ensures our tracked cls has the most recent rolling value to attach to 'unload' and 'pagehide'. */
+    onCLS(({ value }) => this.cls = value, { reportAllChanges: true })
+
+    /* 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)
+    /*
+    Issue: Because window's pageHide commonly fires BEFORE vis change and "final" harvest would happen at the former in this case, we also have to add our vis-change event now or it may not be sent.
+    Affected: Safari < v14.1/.5 ; versions that don't support 'visiilitychange' event
+    Impact: For affected w/o this, NR 'pageHide' attribute may not be sent. For other browsers w/o this, NR 'pageHide' gets fragmented into its own harvest call on page unloading because of dual EoL logic.
+    Mitigation: NR 'unload' and 'pageHide' are both recorded when window pageHide fires, rather than only recording 'unload'.
+    Future: When EoL can become the singular subscribeToVisibilityChange, it's likely endCurrentSession isn't needed here as 'unload'-'pageHide' can be untangled.
+    */
+    this.endCurrentSession(timestamp)
+  }
+
+  addTiming (name, value, attrs) {
+    attrs = attrs || {}
+
+    // If cls was set to another value by `onCLS`, then it's supported and is attached onto any timing but is omitted until such time.
+    /*
+    *cli Apr'23 - Convert attach-to-all -> attach-if-not-null. See NEWRELIC-6143.
+    Issue: Because NR 'pageHide' was only sent once with what is considered the "final" CLS value, in the case that 'pageHide' fires before 'load' happens, we incorrectly a final CLS of 0 for that page.
+    Mitigation: We've set initial CLS to null so that it's omitted from timings like 'pageHide' in that edge case. It should only be included if onCLS callback was executed at least once.
+    Future: onCLS value changes should be reported directly & CLS separated into its own timing node so it's not beholden to 'pageHide' firing. It'd also be possible to report the real final CLS.
+    */
+    if (this.cls !== null) {
+      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. */
+  }
+}