feat: sample sessions sent to telemetry MONGOSH-1651

packages/cli-repl/src/cli-repl.ts

@@ -43,6 +43,7 @@ import { promisify } from 'util';
 import { getOsInfo } from './get-os-info';
 import { UpdateNotificationManager } from './update-notification-manager';
 import { markTime } from './startup-timing';
+import { SampledAnalytics } from '@mongosh/logging/lib/analytics-helpers';
 
 /**
  * Connecting text key.
@@ -500,13 +501,15 @@ export class CliRepl implements MongoshIOProvider {
       } as any /* axiosConfig and axiosRetryConfig are existing options, but don't have type definitions */
     );
     this.toggleableAnalytics = new ToggleableAnalytics(
-      new ThrottledAnalytics({
-        target: this.segmentAnalytics,
-        throttle: {
-          rate: 30,
-          metadataPath: this.shellHomeDirectory.paths.shellLocalDataPath,
-        },
-      })
+      SampledAnalytics.default(
+        new ThrottledAnalytics({
+          target: this.segmentAnalytics,
+          throttle: {
+            rate: 30,
+            metadataPath: this.shellHomeDirectory.paths.shellLocalDataPath,
+          },
+        })
+      )
     );
   }
 

packages/logging/src/analytics-helpers.spec.ts

@@ -4,7 +4,11 @@ import fs from 'fs';
 import { promisify } from 'util';
 import { expect } from 'chai';
 import type { MongoshAnalytics } from './analytics-helpers';
-import { ToggleableAnalytics, ThrottledAnalytics } from './analytics-helpers';
+import {
+  ToggleableAnalytics,
+  ThrottledAnalytics,
+  SampledAnalytics,
+} from './analytics-helpers';
 
 const wait = promisify(setTimeout);
 
@@ -245,4 +249,51 @@ describe('analytics helpers', function () {
       ).to.match(/^(hi,hi,hi|bye,bye,bye)$/);
     });
   });
+
+  describe('SampledAnalytics', function () {
+    const userId = `u-${Date.now()}`;
+    const iEvt = { userId, traits: { platform: 'what', session_id: 'abc' } };
+    const tEvt = {
+      userId,
+      event: 'hi',
+      properties: { mongosh_version: '1.2.3', session_id: 'abc' },
+    };
+
+    afterEach(function () {
+      delete process.env.MONGOSH_ANALYTICS_SAMPLE;
+    });
+
+    it('should override sampling with the MONGOSH_ANALYTICS_SAMPLE environment variable', function () {
+      process.env.MONGOSH_ANALYTICS_SAMPLE = 'true';
+      const analytics = SampledAnalytics.disabledForAll(
+        target
+      ) as SampledAnalytics;
+
+      expect(analytics.enabled).to.be.true;
+    });
+
+    it('should send the event forward when sampled', function () {
+      const analytics = SampledAnalytics.enabledForAll(
+        target
+      ) as SampledAnalytics;
+      expect(analytics.enabled).to.be.true;
+
+      analytics.identify(iEvt);
+      analytics.track(tEvt);
+
+      expect(events.length).to.equal(2);
+    });
+
+    it('should not send the event forward when not sampled', function () {
+      const analytics = SampledAnalytics.disabledForAll(
+        target
+      ) as SampledAnalytics;
+      expect(analytics.enabled).to.be.false;
+
+      analytics.identify(iEvt);
+      analytics.track(tEvt);
+
+      expect(events.length).to.equal(0);
+    });
+  });
 });

packages/logging/src/analytics-helpers.ts

@@ -378,3 +378,72 @@ export class ThrottledAnalytics implements MongoshAnalytics {
     });
   }
 }
+
+type SampledAnalyticsOptions = {
+  target?: MongoshAnalytics;
+  /**
+   * Sampling options. If not provided, sampling will be defaulted to 30% of sessions.
+   * Also, from an exposed environment standpoint, providing a MONGOSH_ANALYTICS_SAMPLE
+   * environment variable with a truthy value will force the sampling to 100%.
+   *
+   * The sampling configuration can be changed, however, by default it will be a Math.random
+   * bounded from 0 to 100. If you are going to configure it use a evenly distributed random function.
+   */
+  sampling: {
+    percentage: number;
+    samplingFunction: (percentage: number) => boolean;
+  } | null;
+};
+
+export class SampledAnalytics implements MongoshAnalytics {
+  private isEnabled: boolean;
+  private target: MongoshAnalytics;
+
+  private constructor(configuration: SampledAnalyticsOptions) {
+    configuration.sampling ??= {
+      percentage: 30,
+      samplingFunction: (percentage) => Math.random() * 100 < percentage,
+    };
+
+    const shouldBeSampled = configuration.sampling.samplingFunction(
+      configuration.sampling.percentage
+    );
+
+    this.isEnabled = !!process.env.MONGOSH_ANALYTICS_SAMPLE || shouldBeSampled;
+    this.target = configuration.target || new NoopAnalytics();
+  }
+
+  static default(target?: MongoshAnalytics): MongoshAnalytics {
+    return new SampledAnalytics({ target, sampling: null });
+  }
+
+  static enabledForAll(target?: MongoshAnalytics): MongoshAnalytics {
+    return new SampledAnalytics({
+      target,
+      sampling: { percentage: 100, samplingFunction: () => true },
+    });
+  }
+
+  static disabledForAll(target?: MongoshAnalytics): MongoshAnalytics {
+    return new SampledAnalytics({
+      target,
+      sampling: { percentage: 0, samplingFunction: () => false },
+    });
+  }
+
+  get enabled(): boolean {
+    return this.isEnabled;
+  }
+
+  identify(message: AnalyticsIdentifyMessage): void {
+    this.isEnabled && this.target.identify(message);
+  }
+
+  track(message: AnalyticsTrackMessage): void {
+    this.isEnabled && this.target.track(message);
+  }
+
+  flush(callback: (err?: Error | undefined) => void): void {
+    this.isEnabled && this.target.flush(callback);
+  }
+}