Add sample rate option and update README for it (#58)

Author: draffensperger

README.md

@@ -55,22 +55,26 @@ it from the `/static` folder of your site.
 Once the OpenCensus Web packages are released to NPM, you will also be able to
 include them in your JavaScript build pipeline as an imported dependency.
 
-In order to indicate the endpoint of the OpenCensus Agent so that traces can be
-written, you will need to include a snippet of JavaScript that sets the
-`ocAgent` global variable, for instance:
+In order to indicate the trace sampling rate and endpoint of the OpenCensus 
+Agent so that traces can be written, you will need to include a snippet of 
+JavaScript that sets the `ocAgent` and `ocSampleRate` global variables, 
+for instance:
 
 ```html
-<script>ocAgent = 'https://example.com/my-opencensus-agent-endpoint'</script>
+<script>
+  ocAgent = 'https://example.com/my-opencensus-agent-endpoint';
+  // Sample all requests for trace, which is useful when testing.
+  // By default this is set to sample 1/10000 requests.
+  ocSampleRate = 1.0; 
+</script>
 ```
 
 ### 3. Optional: Send a trace parent and sampling decision from your server
 
-Currently, the OpenCensus Web will sample all requests by default. This is
-useful for experimentation with the library but is not appropriate for a real
-application.
-
 OpenCensus Web also supports connecting the server side spans for the initial
 HTML load with the client side span for the load from the browser's timing API.
+This works by having the server send its parent trace context (trace ID, span ID
+and trace sampling decision) to the client.
 
 Because the browser does not send a trace context header for the initial page
 navigation, the server needs to fake a trace context header in a middleware and

packages/opencensus-web-all/src/initial-load-context.ts

@@ -21,27 +21,37 @@ import {WindowWithOcwGlobals} from './types';
 
 const windowWithOcwGlobals = window as WindowWithOcwGlobals;
 
+/**
+ * The default trace sampling rate if no `traceparent` and no `ocSampleRate`
+ * are specified on the `window`.
+ */
+const DEFAULT_SAMPLE_RATE = 0.0001;
+
 /**
  * Gets a span context for the initial page load from the `window.traceparent`,
  * or generates a new random span context if it is missing. For now the new
  * random span context generated if `window.traceparent` is missing is always
  * marked sampled.
  */
 export function getInitialLoadSpanContext(): SpanContext {
-  if (!windowWithOcwGlobals.traceparent) return alwaysSampledSpanContext();
+  if (!windowWithOcwGlobals.traceparent) return randomSampledSpanContext();
   const spanContext =
       traceParentToSpanContext(windowWithOcwGlobals.traceparent);
   if (!spanContext) {
     console.log(`Invalid traceparent: ${windowWithOcwGlobals.traceparent}`);
-    return alwaysSampledSpanContext();
+    return randomSampledSpanContext();
   }
   return spanContext;
 }
 
-function alwaysSampledSpanContext() {
+function randomSampledSpanContext() {
+  const sampleRate = windowWithOcwGlobals.ocSampleRate || DEFAULT_SAMPLE_RATE;
   return {
     traceId: randomTraceId(),
     spanId: randomSpanId(),
-    options: 0x1,  // Sampled
+    // Math.random returns a number in the 0-1 range (inclusive of 0 but not 1).
+    // That means we should use the strict `<` operator to compare it to the
+    // sample rate. A value of 1 for `options` indicates trace sampling.
+    options: Math.random() < sampleRate ? 1 : 0,
   };
 }

packages/opencensus-web-all/src/types.ts

@@ -40,6 +40,12 @@ export declare interface WindowWithOcwGlobals extends WindowWithLongTasks {
    * See https://www.w3.org/TR/trace-context/ for details.
    */
   traceparent?: string;
+  /**
+   * If the `traceparent` global variable described above is not present on the
+   * `window`, then a trace sampling decision will be made randomly with the
+   * specified sample rate. If not specified, a default sampling rate is used.
+   */
+  ocSampleRate?: number;
   /**
    * List to collect long task timings as they are observed. This is on the
    * window so that the code to instrument the long tasks and the code that

packages/opencensus-web-all/test/test-export-initial-load.ts

@@ -38,35 +38,23 @@ function hexToBase64(hexString: string): string {
 }
 
 describe('exportRootSpanAfterLoadEvent', () => {
-  let realOcwAgent: string|undefined;
+  let realOcAgent: string|undefined;
   let realTraceparent: string|undefined;
   let sendSpy: jasmine.Spy;
   beforeEach(() => {
     jasmine.clock().install();
     spyOn(XMLHttpRequest.prototype, 'open');
     sendSpy = spyOn(XMLHttpRequest.prototype, 'send');
     spyOn(XMLHttpRequest.prototype, 'setRequestHeader');
-    realOcwAgent = windowWithOcwGlobals.ocAgent;
+    realOcAgent = windowWithOcwGlobals.ocAgent;
     realTraceparent = windowWithOcwGlobals.traceparent;
   });
   afterEach(() => {
     jasmine.clock().uninstall();
-    windowWithOcwGlobals.ocAgent = realOcwAgent;
+    windowWithOcwGlobals.ocAgent = realOcAgent;
     windowWithOcwGlobals.traceparent = realTraceparent;
   });
 
-  it('exports spans to agent if agent is configured', () => {
-    windowWithOcwGlobals.ocAgent = 'http://agent';
-    windowWithOcwGlobals.traceparent = undefined;
-
-    exportRootSpanAfterLoadEvent();
-
-    jasmine.clock().tick(300000);
-    expect(XMLHttpRequest.prototype.open)
-        .toHaveBeenCalledWith('POST', 'http://agent/v1/trace');
-    expect(XMLHttpRequest.prototype.send).toHaveBeenCalled();
-  });
-
   it('does not export if agent not configured', () => {
     windowWithOcwGlobals.ocAgent = undefined;
     windowWithOcwGlobals.traceparent = undefined;
@@ -96,7 +84,7 @@ describe('exportRootSpanAfterLoadEvent', () => {
     expect(sendBody).toContain(hexToBase64(traceId));
   });
 
-  it('does not export spans if traceparent sampling hint not set', () => {
+  it('does not export spans if traceparent sampling hint set to zero', () => {
     windowWithOcwGlobals.ocAgent = 'http://agent';
     windowWithOcwGlobals.traceparent =
         '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-00';
@@ -107,4 +95,29 @@ describe('exportRootSpanAfterLoadEvent', () => {
     expect(XMLHttpRequest.prototype.open).not.toHaveBeenCalled();
     expect(XMLHttpRequest.prototype.send).not.toHaveBeenCalled();
   });
+
+  it('does not export spans if traceparent unset and random is big', () => {
+    spyOn(Math, 'random').and.returnValue(0.99);
+    windowWithOcwGlobals.ocAgent = 'http://agent';
+    windowWithOcwGlobals.traceparent = '';
+
+    exportRootSpanAfterLoadEvent();
+
+    jasmine.clock().tick(300000);
+    expect(XMLHttpRequest.prototype.open).not.toHaveBeenCalled();
+    expect(XMLHttpRequest.prototype.send).not.toHaveBeenCalled();
+  });
+
+  it('exports spans if traceparent unset and random number is small', () => {
+    spyOn(Math, 'random').and.returnValue(0);
+    windowWithOcwGlobals.ocAgent = 'http://agent';
+    windowWithOcwGlobals.traceparent = undefined;
+
+    exportRootSpanAfterLoadEvent();
+
+    jasmine.clock().tick(300000);
+    expect(XMLHttpRequest.prototype.open)
+        .toHaveBeenCalledWith('POST', 'http://agent/v1/trace');
+    expect(XMLHttpRequest.prototype.send).toHaveBeenCalled();
+  });
 });

packages/opencensus-web-all/test/test-initial-load-context.ts

@@ -24,11 +24,14 @@ const TRACE_ID_REGEX = /[0-9a-f]{32}/;
 
 describe('getInitialLoadSpanContext', () => {
   let realTraceparent: string|undefined;
+  let realOcSampleRate: number|undefined;
   beforeEach(() => {
     realTraceparent = windowWithOcwGlobals.traceparent;
+    realOcSampleRate = windowWithOcwGlobals.ocSampleRate;
   });
   afterEach(() => {
     windowWithOcwGlobals.traceparent = realTraceparent;
+    windowWithOcwGlobals.ocSampleRate = realOcSampleRate;
   });
 
   it('sets trace and span ID from global `traceparent` when specified', () => {
@@ -43,17 +46,38 @@ describe('getInitialLoadSpanContext', () => {
 
   it('generates a new random span context if `traceparent` unspecified', () => {
     windowWithOcwGlobals.traceparent = undefined;
+    spyOn(Math, 'random').and.returnValue(0);
     const spanContext = getInitialLoadSpanContext();
     expect(spanContext.traceId).toMatch(TRACE_ID_REGEX);
     expect(spanContext.spanId).toMatch(SPAN_ID_REGEX);
     expect(spanContext.options).toBe(1);
+    expect(Math.random).toHaveBeenCalled();
   });
 
   it('generates a new random span context if `traceparent` is invalid', () => {
+    spyOn(Math, 'random').and.returnValue(0);
     windowWithOcwGlobals.traceparent = 'invalid trace parent header!';
     const spanContext = getInitialLoadSpanContext();
     expect(spanContext.traceId).toMatch(TRACE_ID_REGEX);
     expect(spanContext.spanId).toMatch(SPAN_ID_REGEX);
     expect(spanContext.options).toBe(1);
+    expect(Math.random).toHaveBeenCalled();
+  });
+
+  describe('specifying the sampling rate with window.ocSampleRate', () => {
+    beforeEach(() => {
+      spyOn(Math, 'random').and.returnValue(0.5);
+      windowWithOcwGlobals.traceparent = undefined;
+    });
+    it('sets trace options to unsampled if random above sample rate', () => {
+      windowWithOcwGlobals.ocSampleRate = 0.1;
+      const spanContext = getInitialLoadSpanContext();
+      expect(spanContext.options).toBe(0);
+    });
+    it('sets trace options to sampled if random below sample rate', () => {
+      windowWithOcwGlobals.ocSampleRate = 1.0;
+      const spanContext = getInitialLoadSpanContext();
+      expect(spanContext.options).toBe(1);
+    });
   });
 });