|
1 | 1 | import { getGlobalObject } from './misc'; |
2 | 2 | import { dynamicRequire, isNodeEnv } from './node'; |
3 | 3 |
|
4 | | -const INITIAL_TIME = Date.now(); |
| 4 | +/** |
| 5 | + * An object that can return the current timestamp in seconds since the UNIX epoch. |
| 6 | + */ |
| 7 | +interface TimestampSource { |
| 8 | + nowSeconds(): number; |
| 9 | +} |
| 10 | + |
| 11 | +/** |
| 12 | + * A TimestampSource implementation for environments that do not support the Performance Web API natively. |
| 13 | + * |
| 14 | + * Note that this TimestampSource does not use a monotonic clock. A call to `nowSeconds` may return a timestamp earlier |
| 15 | + * than a previously returned value. We do not try to emulate a monotonic behavior in order to facilitate debugging. It |
| 16 | + * is more obvious to explain "why does my span have negative duration" than "why my spans have zero duration". |
| 17 | + */ |
| 18 | +const dateTimestampSource: TimestampSource = { |
| 19 | + nowSeconds: () => Date.now() / 1000, |
| 20 | +}; |
5 | 21 |
|
6 | 22 | /** |
7 | | - * Cross platform compatible partial performance implementation |
| 23 | + * A partial definition of the [Performance Web API]{@link https://developer.mozilla.org/en-US/docs/Web/API/Performance} |
| 24 | + * for accessing a high resolution monotonic clock. |
8 | 25 | */ |
9 | | -interface CrossPlatformPerformance { |
| 26 | +interface Performance { |
| 27 | + /** |
| 28 | + * The millisecond timestamp at which measurement began, measured in Unix time. |
| 29 | + */ |
10 | 30 | timeOrigin: number; |
11 | 31 | /** |
12 | | - * Returns the current timestamp in ms |
| 32 | + * Returns the current millisecond timestamp, where 0 represents the start of measurement. |
13 | 33 | */ |
14 | 34 | now(): number; |
15 | 35 | } |
16 | 36 |
|
17 | | -let prevNow = 0; |
18 | | - |
19 | | -const performanceFallback: CrossPlatformPerformance = { |
20 | | - now(): number { |
21 | | - let now = Date.now() - INITIAL_TIME; |
22 | | - if (now < prevNow) { |
23 | | - now = prevNow; |
24 | | - } |
25 | | - prevNow = now; |
26 | | - return now; |
27 | | - }, |
28 | | - timeOrigin: INITIAL_TIME, |
29 | | -}; |
30 | | - |
31 | | -const crossPlatformPerformance: CrossPlatformPerformance = ((): CrossPlatformPerformance => { |
32 | | - // React Native's performance.now() starts with a gigantic offset, so we need to wrap it. |
33 | | - if (isReactNative()) { |
34 | | - return getReactNativePerformanceWrapper(); |
35 | | - } |
36 | | - |
37 | | - if (isNodeEnv()) { |
38 | | - try { |
39 | | - const perfHooks = dynamicRequire(module, 'perf_hooks') as { performance: CrossPlatformPerformance }; |
40 | | - return perfHooks.performance; |
41 | | - } catch (_) { |
42 | | - return performanceFallback; |
43 | | - } |
44 | | - } |
45 | | - |
| 37 | +/** |
| 38 | + * Returns a wrapper around the native Performance API browser implementation, or undefined for browsers that do not |
| 39 | + * support the API. |
| 40 | + * |
| 41 | + * Wrapping the native API works around differences in behavior from different browsers. |
| 42 | + */ |
| 43 | +function getBrowserPerformance(): Performance | undefined { |
46 | 44 | const { performance } = getGlobalObject<Window>(); |
47 | | - |
48 | 45 | if (!performance || !performance.now) { |
49 | | - return performanceFallback; |
| 46 | + return undefined; |
50 | 47 | } |
51 | 48 |
|
52 | | - // Polyfill for performance.timeOrigin. |
| 49 | + // Replace performance.timeOrigin with our own timeOrigin based on Date.now(). |
53 | 50 | // |
54 | | - // While performance.timing.navigationStart is deprecated in favor of performance.timeOrigin, performance.timeOrigin |
55 | | - // is not as widely supported. Namely, performance.timeOrigin is undefined in Safari as of writing. |
56 | | - if (performance.timeOrigin === undefined) { |
57 | | - // As of writing, performance.timing is not available in Web Workers in mainstream browsers, so it is not always a |
58 | | - // valid fallback. In the absence of a initial time provided by the browser, fallback to INITIAL_TIME. |
59 | | - // @ts-ignore ignored because timeOrigin is a readonly property but we want to override |
60 | | - // eslint-disable-next-line deprecation/deprecation |
61 | | - performance.timeOrigin = (performance.timing && performance.timing.navigationStart) || INITIAL_TIME; |
62 | | - } |
| 51 | + // This is a partial workaround for browsers reporting performance.timeOrigin such that performance.timeOrigin + |
| 52 | + // performance.now() gives a date arbitrarily in the past. |
| 53 | + // |
| 54 | + // Additionally, computing timeOrigin in this way fills the gap for browsers where performance.timeOrigin is |
| 55 | + // undefined. |
| 56 | + // |
| 57 | + // The assumption that performance.timeOrigin + performance.now() ~= Date.now() is flawed, but we depend on it to |
| 58 | + // interact with data coming out of performance entries. |
| 59 | + // |
| 60 | + // Note that despite recommendations against it in the spec, browsers implement the Performance API with a clock that |
| 61 | + // might stop when the computer is asleep (and perhaps under other circumstances). Such behavior causes |
| 62 | + // performance.timeOrigin + performance.now() to have an arbitrary skew over Date.now(). In laptop computers, we have |
| 63 | + // observed skews that can be as long as days, weeks or months. |
| 64 | + // |
| 65 | + // See https://github.com/getsentry/sentry-javascript/issues/2590. |
| 66 | + // |
| 67 | + // BUG: despite our best intentions, this workaround has its limitations. It mostly addresses timings of pageload |
| 68 | + // transactions, but ignores the skew built up over time that can aversely affect timestamps of navigation |
| 69 | + // transactions of long-lived web pages. |
| 70 | + const timeOrigin = Date.now() - performance.now(); |
63 | 71 |
|
64 | | - return performance; |
65 | | -})(); |
| 72 | + return { |
| 73 | + now: () => performance.now(), |
| 74 | + timeOrigin, |
| 75 | + }; |
| 76 | +} |
66 | 77 |
|
67 | 78 | /** |
68 | | - * Returns a timestamp in seconds with milliseconds precision since the UNIX epoch calculated with the monotonic clock. |
| 79 | + * Returns the native Performance API implementation from Node.js. Returns undefined in old Node.js versions that don't |
| 80 | + * implement the API. |
69 | 81 | */ |
70 | | -export function timestampWithMs(): number { |
71 | | - return (crossPlatformPerformance.timeOrigin + crossPlatformPerformance.now()) / 1000; |
| 82 | +function getNodePerformance(): Performance | undefined { |
| 83 | + try { |
| 84 | + const perfHooks = dynamicRequire(module, 'perf_hooks') as { performance: Performance }; |
| 85 | + return perfHooks.performance; |
| 86 | + } catch (_) { |
| 87 | + return undefined; |
| 88 | + } |
72 | 89 | } |
73 | 90 |
|
74 | 91 | /** |
75 | | - * Determines if running in react native |
| 92 | + * The Performance API implementation for the current platform, if available. |
76 | 93 | */ |
77 | | -function isReactNative(): boolean { |
78 | | - return getGlobalObject<Window>().navigator?.product === 'ReactNative'; |
79 | | -} |
| 94 | +const platformPerformance: Performance | undefined = isNodeEnv() ? getNodePerformance() : getBrowserPerformance(); |
| 95 | + |
| 96 | +const timestampSource: TimestampSource = |
| 97 | + platformPerformance === undefined |
| 98 | + ? dateTimestampSource |
| 99 | + : { |
| 100 | + nowSeconds: () => (platformPerformance.timeOrigin + platformPerformance.now()) / 1000, |
| 101 | + }; |
80 | 102 |
|
81 | 103 | /** |
82 | | - * Performance wrapper for react native as performance.now() has been found to start off with an unusual offset. |
| 104 | + * Returns a timestamp in seconds since the UNIX epoch using the Date API. |
83 | 105 | */ |
84 | | -function getReactNativePerformanceWrapper(): CrossPlatformPerformance { |
85 | | - // Performance only available >= RN 0.63 |
86 | | - const { performance } = getGlobalObject<Window>(); |
87 | | - if (performance && typeof performance.now === 'function') { |
88 | | - const INITIAL_OFFSET = performance.now(); |
| 106 | +export const dateTimestampInSeconds = dateTimestampSource.nowSeconds.bind(dateTimestampSource); |
| 107 | + |
| 108 | +/** |
| 109 | + * Returns a timestamp in seconds since the UNIX epoch using either the Performance or Date APIs, depending on the |
| 110 | + * availability of the Performance API. |
| 111 | + * |
| 112 | + * See `usingPerformanceAPI` to test whether the Performance API is used. |
| 113 | + * |
| 114 | + * BUG: Note that because of how browsers implement the Performance API, the clock might stop when the computer is |
| 115 | + * asleep. This creates a skew between `dateTimestampInSeconds` and `timestampInSeconds`. The |
| 116 | + * skew can grow to arbitrary amounts like days, weeks or months. |
| 117 | + * See https://github.com/getsentry/sentry-javascript/issues/2590. |
| 118 | + */ |
| 119 | +export const timestampInSeconds = timestampSource.nowSeconds.bind(timestampSource); |
89 | 120 |
|
90 | | - return { |
91 | | - now(): number { |
92 | | - return performance.now() - INITIAL_OFFSET; |
93 | | - }, |
94 | | - timeOrigin: INITIAL_TIME, |
95 | | - }; |
| 121 | +// Re-exported with an old name for backwards-compatibility. |
| 122 | +export const timestampWithMs = timestampInSeconds; |
| 123 | + |
| 124 | +/** |
| 125 | + * A boolean that is true when timestampInSeconds uses the Performance API to produce monotonic timestamps. |
| 126 | + */ |
| 127 | +export const usingPerformanceAPI = platformPerformance !== undefined; |
| 128 | + |
| 129 | +/** |
| 130 | + * The number of milliseconds since the UNIX epoch. This value is only usable in a browser, and only when the |
| 131 | + * performance API is available. |
| 132 | + */ |
| 133 | +export const browserPerformanceTimeOrigin = ((): number | undefined => { |
| 134 | + const { performance } = getGlobalObject<Window>(); |
| 135 | + if (!performance) { |
| 136 | + return undefined; |
96 | 137 | } |
97 | | - return performanceFallback; |
98 | | -} |
| 138 | + if (performance.timeOrigin) { |
| 139 | + return performance.timeOrigin; |
| 140 | + } |
| 141 | + // While performance.timing.navigationStart is deprecated in favor of performance.timeOrigin, performance.timeOrigin |
| 142 | + // is not as widely supported. Namely, performance.timeOrigin is undefined in Safari as of writing. |
| 143 | + // Also as of writing, performance.timing is not available in Web Workers in mainstream browsers, so it is not always |
| 144 | + // a valid fallback. In the absence of an initial time provided by the browser, fallback to the current time from the |
| 145 | + // Date API. |
| 146 | + // eslint-disable-next-line deprecation/deprecation |
| 147 | + return (performance.timing && performance.timing.navigationStart) || Date.now(); |
| 148 | +})(); |
0 commit comments