Add function to adjust performance origin based on server time (#14)

Author: draffensperger

packages/opencensus-web-core/src/common/time-util.ts

@@ -14,10 +14,62 @@
  * limitations under the License.
  */
 
+/** Polyfill value of `performance.timeOrigin` for browser that lack support. */
 let perfOriginPolyfill = 0;
+/** If non-zero, the approximate peformance clock origin in server time. */
+let perfOriginInServerTime = 0;
 
-/** Returns the origin of the browser performance clock in epoch millis. */
+/**
+ * Returns the origin of the browser performance clock in epoch millis.
+ * This can be adjusted to align more closely with the server's clock using the
+ * `adjustPerfTimeOrigin` function.
+ */
 export function getPerfTimeOrigin(): number {
+  return perfOriginInServerTime ? perfOriginInServerTime :
+                                  getClientPerfTimeOrigin();
+}
+
+/**
+ * Adjusts the performance clock time origin based on server clock times for the
+ * start and duration of the navigation fetch (the initial HTML load request).
+ *
+ * This adjusts the client clock such that the network time is evenly spread on
+ * both sides of the request, so that the server's span will be positioned right
+ * in the middle of the client's span. This enables visualizing the server and
+ * client spans no the same timeline even if they have clock skew.
+ *
+ * @param serverNavFetchStartTime The server's measurement of the request start
+ *     in epoch milliseconds from the server clock. This would be sent back to
+ *     the client in a <script> in the rendered HTML.
+ * @param serverNavFetchDuration The server's measurement of the request
+ *     duration in milliseconds. This would also be sent to the client.
+ */
+export function adjustPerfTimeOrigin(
+    serverNavFetchStartTime: number, serverNavFetchDuration: number) {
+  // If there is no performance timing info, we don't have the client's
+  // start/end times for the navigation fetch, so we can't accurately use the
+  // server times to adjust the client time origin.
+  if (!performance.timing) return;
+  const clientStart = performance.timing.requestStart;
+  const clientEnd = performance.timing.responseStart;
+  const clientNavFetchDuration = clientEnd - clientStart;
+
+  // Server time is more than client time, which we don't expect, so don't try
+  // to adjust the time origin.
+  if (serverNavFetchDuration > clientNavFetchDuration) return;
+
+  const networkTime = clientNavFetchDuration - serverNavFetchDuration;
+  const halfNetworkTime = networkTime / 2;
+  const clientStartInServerTime = serverNavFetchStartTime - halfNetworkTime;
+  perfOriginInServerTime = clientStartInServerTime - clientStart;
+}
+
+/** Helper function used for testing. */
+function clearAdjustedPerfTime() {
+  perfOriginInServerTime = 0;
+}
+
+function getClientPerfTimeOrigin() {
   if (performance.timeOrigin) return performance.timeOrigin;
   if (!perfOriginPolyfill) {
     perfOriginPolyfill = Date.now() - performance.now();
@@ -59,3 +111,5 @@ function wholeAndFraction(num: number): [number, number] {
   const fraction = num - whole;
   return [whole, fraction];
 }
+
+export const TEST_ONLY = {clearAdjustedPerfTime};

packages/opencensus-web-core/test/test-time-util.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import {getDateForPerfTime, getIsoDateStrForPerfTime, getPerfTimeOrigin} from '../src/common/time-util';
+import {adjustPerfTimeOrigin, getDateForPerfTime, getIsoDateStrForPerfTime, getPerfTimeOrigin, TEST_ONLY} from '../src/common/time-util';
 
 describe('getPerfTimeOrigin', () => {
   it('returns `performance.timeOrigin` if set', () => {
@@ -32,6 +32,63 @@ describe('getPerfTimeOrigin', () => {
   });
 });
 
+describe('adjustPerfTimeOrigin', () => {
+  const CLIENT_TIME_ORIGIN = 1548000000000;
+  beforeEach(() => {
+    spyOnProperty(performance, 'timeOrigin')
+        .and.returnValue(CLIENT_TIME_ORIGIN);
+  });
+  afterEach(() => {
+    TEST_ONLY.clearAdjustedPerfTime();
+  });
+
+  it('keeps client time origin if no performance timing missing', () => {
+    spyOnProperty(performance, 'timing').and.returnValue(undefined);
+    adjustPerfTimeOrigin(1548000001000.2, 5.1);
+    expect(getPerfTimeOrigin()).toBe(CLIENT_TIME_ORIGIN);
+  });
+
+  it('keeps client time origin if server time longer than client', () => {
+    // Client nav fetch duration is 5ms
+    spyOnProperty(performance.timing, 'requestStart').and.returnValue(10.1);
+    spyOnProperty(performance.timing, 'responseStart').and.returnValue(15.1);
+
+    // Server nav fetch duration is 10ms
+    adjustPerfTimeOrigin(1548000001000.2, /* serverNavFetchDuration */ 10);
+
+    expect(getPerfTimeOrigin()).toBe(CLIENT_TIME_ORIGIN);
+  });
+
+  it('adjusts origin to center server span in client span', () => {
+    const clientNavFetchStartInPerfTime = 10;  // Performance clock millis.
+    spyOnProperty(performance.timing, 'requestStart')
+        .and.returnValue(clientNavFetchStartInPerfTime);
+    const clientNavFetchEndInPerfTime = 18;  // Performance clock millis.
+    spyOnProperty(performance.timing, 'responseStart')
+        .and.returnValue(clientNavFetchEndInPerfTime);
+
+    const serverNavFetchStartEpochMillis = 1500000001000;  // Epoch millis.
+    const serverNavFetchDuration = 6;                      // Duration millis
+    adjustPerfTimeOrigin(
+        serverNavFetchStartEpochMillis, serverNavFetchDuration);
+
+    // Calculations to make the expectation clearer:
+    const clientNavFetchDuration =
+        clientNavFetchEndInPerfTime - clientNavFetchStartInPerfTime;
+    expect(clientNavFetchDuration).toBe(8);  // Duration millis
+    const networkTime = clientNavFetchDuration - serverNavFetchDuration;
+    expect(networkTime).toBe(2);  // Duration millis
+    const clientNavStartInEpochMillis =
+        serverNavFetchStartEpochMillis - networkTime / 2;
+    expect(clientNavStartInEpochMillis).toBe(1500000000999);
+    const perfOriginInEpochMillis =
+        clientNavStartInEpochMillis - clientNavFetchStartInPerfTime;
+    expect(perfOriginInEpochMillis).toBe(1500000000989);
+
+    expect(getPerfTimeOrigin()).toBe(perfOriginInEpochMillis);
+  });
+});
+
 describe('getDateForPerfTime', () => {
   it('calculates date for perf time based on time origin', () => {
     spyOnProperty(performance, 'timeOrigin').and.returnValue(1548000000000);