feat: Telemetry header

api/sdk.api.md

@@ -22,7 +22,7 @@ export class Confidence implements EventSender, Trackable, FlagResolver {
     //
     // @internal
     readonly contextChanges: Subscribe<string[]>;
-    static create({ clientSecret, region, timeout, environment, fetchImplementation, logger, resolveBaseUrl, }: ConfidenceOptions): Confidence;
+    static create({ clientSecret, region, timeout, environment, fetchImplementation, logger, resolveBaseUrl, disableTelemetry, }: ConfidenceOptions): Confidence;
     get environment(): string;
     evaluateFlag(path: string, defaultValue: string): FlagEvaluation<string>;
     // (undocumented)
@@ -52,6 +52,7 @@ export class Confidence implements EventSender, Trackable, FlagResolver {
 // @public
 export interface ConfidenceOptions {
     clientSecret: string;
+    disableTelemetry?: boolean;
     environment: 'client' | 'backend';
     // Warning: (ae-forgotten-export) The symbol "SimpleFetch" needs to be exported by the entry point index.d.ts
     fetchImplementation?: SimpleFetch;

packages/sdk/package.json

@@ -8,7 +8,7 @@
     "node": ">=18.17.0"
   },
   "scripts": {
-    "gen:proto": "protoc --plugin=$(yarn bin protoc-gen-ts_proto) --ts_proto_out=src/generated -I proto proto/confidence/flags/resolver/v1/api.proto --ts_proto_opt=outputEncodeMethods=false --ts_proto_opt=outputPartialMethods=false && prettier --config ../../prettier.config.js -w src/generated",
+    "gen:proto": "protoc --plugin=$(yarn bin protoc-gen-ts_proto) --ts_proto_out=src/generated -I proto proto/confidence/flags/resolver/v1/api.proto proto/confidence/telemetry/v1/telemetry.proto --ts_proto_opt=outputEncodeMethods=true --ts_proto_opt=outputPartialMethods=false && prettier --config ../../prettier.config.js -w src/generated",
     "build": "tsc -b",
     "bundle": "rollup -c && api-extractor run",
     "prepack": "yarn build && yarn bundle"
@@ -21,6 +21,7 @@
     "module": "dist/index.esm.js"
   },
   "dependencies": {
+    "@bufbuild/protobuf": "^2.0.0",
     "web-vitals": "^3.5.2"
   },
   "files": [
@@ -30,7 +31,7 @@
     "@microsoft/api-extractor": "7.43.1",
     "prettier": "*",
     "rollup": "4.24.0",
-    "ts-proto": "^1.171.0"
+    "ts-proto": "^2.3.0"
   },
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js"

packages/sdk/proto/confidence/telemetry/v1/telemetry.proto

@@ -0,0 +1,41 @@
+syntax = "proto3";
+
+package confidence.telemetry.v1;
+
+enum Platform {
+  PLATFORM_UNSPECIFIED = 0;
+  PLATFORM_JS_WEB = 4;
+  PLATFORM_JS_SERVER = 5;
+}
+
+message Monitoring {
+  repeated LibraryTraces library_traces = 1;
+  Platform platform = 2;
+}
+
+message LibraryTraces {
+  Library library = 1;
+  string library_version = 2;
+  repeated Trace traces = 3;
+
+  message Trace {
+    TraceId id = 1;
+    // only used for timed events.
+    optional uint64 millisecond_duration = 2;
+  }
+
+  enum Library {
+    LIBRARY_UNSPECIFIED = 0;
+    LIBRARY_CONFIDENCE = 1;
+    LIBRARY_OPEN_FEATURE = 2;
+    LIBRARY_REACT = 3;
+  }
+
+  enum TraceId {
+    TRACE_ID_UNSPECIFIED = 0;
+    TRACE_ID_RESOLVE_LATENCY = 1;
+    TRACE_ID_STALE_FLAG = 2;
+    TRACE_ID_FLAG_TYPE_MISMATCH = 3;
+    TRACE_ID_WITH_CONTEXT = 4;
+  }
+}

packages/sdk/src/Confidence.ts

@@ -17,6 +17,7 @@ import { Subscribe, Observer, subject, changeObserver } from './observing';
 import { SimpleFetch } from './types';
 import { FlagResolution } from './FlagResolution';
 import { AccessiblePromise } from './AccessiblePromise';
+import { Telemetry } from './Telemetry';
 
 /**
  * Confidence options, to be used for easier initialization of Confidence
@@ -37,6 +38,8 @@ export interface ConfidenceOptions {
   logger?: Logger;
   /** Sets an alternative resolve url */
   resolveBaseUrl?: string;
+  /** Disable telemetry */
+  disableTelemetry?: boolean;
 }
 
 /**
@@ -333,11 +336,17 @@ export class Confidence implements EventSender, Trackable, FlagResolver {
     fetchImplementation = defaultFetchImplementation(),
     logger = defaultLogger(),
     resolveBaseUrl,
+    disableTelemetry = false,
   }: ConfidenceOptions): Confidence {
     const sdk = {
       id: SdkId.SDK_ID_JS_CONFIDENCE,
       version: '0.2.1', // x-release-please-version
     } as const;
+    const telemetry = new Telemetry({
+      disabled: disableTelemetry,
+      logger,
+      environment,
+    });
     let flagResolverClient: FlagResolverClient = new FetchingFlagResolverClient({
       clientSecret,
       fetchImplementation,
@@ -346,6 +355,7 @@ export class Confidence implements EventSender, Trackable, FlagResolver {
       resolveTimeout: timeout,
       region,
       resolveBaseUrl,
+      telemetry,
     });
     if (environment === 'client') {
       flagResolverClient = new CachingFlagResolverClient(flagResolverClient, Number.POSITIVE_INFINITY);

packages/sdk/src/FlagResolverClient.test.ts

@@ -4,12 +4,15 @@ import {
   FlagResolverClient,
   PendingResolution,
   withRequestLogic,
+  withTelemetryData,
 } from './FlagResolverClient';
 import { setMaxListeners } from 'node:events';
 import { SdkId } from './generated/confidence/flags/resolver/v1/types';
-import { abortableSleep } from './fetch-util';
+import { abortableSleep, FetchBuilder } from './fetch-util';
 import { ApplyFlagsRequest, ResolveFlagsRequest } from './generated/confidence/flags/resolver/v1/api';
 import { FlagResolution } from './FlagResolution';
+import { Telemetry } from './Telemetry';
+import { LibraryTraces_Library, LibraryTraces_TraceId, Platform } from './generated/confidence/telemetry/v1/telemetry';
 const RESOLVE_ENDPOINT = 'https://resolver.confidence.dev/v1/flags:resolve';
 const APPLY_ENDPOINT = 'https://resolver.confidence.dev/v1/flags:apply';
 
@@ -56,6 +59,7 @@ describe('Client environment Evaluation', () => {
     },
     environment: 'client',
     resolveTimeout: 10,
+    telemetry: new Telemetry({ disabled: true, logger: { warn: jest.fn() }, environment: 'client' }),
   });
 
   describe('apply', () => {
@@ -108,6 +112,7 @@ describe('Backend environment Evaluation', () => {
     },
     environment: 'backend',
     resolveTimeout: 10,
+    telemetry: new Telemetry({ disabled: true, logger: { warn: jest.fn() }, environment: 'backend' }),
   });
 
   it('should resolve a full flag object', async () => {
@@ -267,9 +272,9 @@ describe('Backend environment Evaluation', () => {
   });
 });
 
-describe('withRequestLogic', () => {
+describe('intercept', () => {
   const fetchMock = jest.fn<Promise<Response>, [Request]>();
-
+  const fetchBuilder = new FetchBuilder();
   let underTest: typeof fetch;
 
   beforeEach(() => {
@@ -282,12 +287,43 @@ describe('withRequestLogic', () => {
     jest.useRealTimers();
   });
 
-  it('should throw on unknown urls', async () => {
-    fetchMock.mockResolvedValue(new Response());
-
-    await expect(underTest('https://resolver.confidence.dev/v1/flags:bad')).rejects.toThrow(
-      'Unexpected url: https://resolver.confidence.dev/v1/flags:bad',
+  describe('withTelemetryData', () => {
+    const telemetryMock = jest.mocked(
+      new Telemetry({ disabled: false, logger: { warn: jest.fn() }, environment: 'client' }),
     );
+
+    beforeEach(() => {
+      underTest = withTelemetryData(fetchBuilder, telemetryMock).build(fetchMock);
+      telemetryMock.getSnapshot = jest.fn().mockReturnValue({
+        libraryTraces: [
+          {
+            library: LibraryTraces_Library.LIBRARY_REACT,
+            libraryVersion: 'test',
+            traces: [{ id: LibraryTraces_TraceId.TRACE_ID_FLAG_TYPE_MISMATCH }],
+          },
+        ],
+        platform: Platform.PLATFORM_JS_WEB,
+      });
+    });
+
+    it('should add telemetry header', async () => {
+      fetchMock.mockResolvedValue(new Response());
+      await underTest('https://resolver.confidence.dev/v1/flags:resolve', { method: 'POST', body: '{}' });
+      expect(fetchMock).toBeCalledTimes(1);
+      const request = fetchMock.mock.calls[0][0];
+      expect(request.headers.has('X-Confidence-Telemetry')).toBeTruthy();
+      expect(request.headers.get('X-Confidence-Telemetry')).toEqual('CgwIAxIEdGVzdBoCCAMQBA==');
+    });
+  });
+
+  describe('withRequestLogic', () => {
+    it('should throw on unknown urls', async () => {
+      fetchMock.mockResolvedValue(new Response());
+
+      await expect(underTest('https://resolver.confidence.dev/v1/flags:bad')).rejects.toThrow(
+        'Unexpected url: https://resolver.confidence.dev/v1/flags:bad',
+      );
+    });
   });
 
   describe('resolve', () => {

packages/sdk/src/FlagResolverClient.ts

@@ -1,6 +1,7 @@
 import { FlagEvaluation } from '.';
 import { AccessiblePromise } from './AccessiblePromise';
 import { Applier, FlagResolution } from './FlagResolution';
+import { Telemetry, Meter } from './Telemetry';
 import { Value } from './Value';
 import { Context } from './context';
 import { FetchBuilder, TimeUnit } from './fetch-util';
@@ -11,6 +12,11 @@ import {
   AppliedFlag,
 } from './generated/confidence/flags/resolver/v1/api';
 import { Sdk } from './generated/confidence/flags/resolver/v1/types';
+import {
+  LibraryTraces_Library,
+  LibraryTraces_TraceId,
+  Monitoring,
+} from './generated/confidence/telemetry/v1/telemetry';
 import { SimpleFetch } from './types';
 
 const FLAG_PREFIX = 'flags/';
@@ -85,6 +91,7 @@ export type FlagResolverClientOptions = {
   environment: 'client' | 'backend';
   region?: 'eu' | 'us';
   resolveBaseUrl?: string;
+  telemetry: Telemetry;
 };
 
 export class FetchingFlagResolverClient implements FlagResolverClient {
@@ -94,6 +101,7 @@ export class FetchingFlagResolverClient implements FlagResolverClient {
   private readonly applyTimeout?: number;
   private readonly resolveTimeout: number;
   private readonly baseUrl: string;
+  private readonly markLatency: Meter;
 
   constructor({
     fetchImplementation,
@@ -105,9 +113,18 @@ export class FetchingFlagResolverClient implements FlagResolverClient {
     environment,
     region,
     resolveBaseUrl,
+    telemetry,
   }: FlagResolverClientOptions) {
+    this.markLatency = telemetry.registerMeter({
+      library: LibraryTraces_Library.LIBRARY_CONFIDENCE,
+      version: sdk.version,
+      id: LibraryTraces_TraceId.TRACE_ID_RESOLVE_LATENCY,
+    });
+    const fetchBuilderWithTelemetry = withTelemetryData(new FetchBuilder(), telemetry);
     // TODO think about both resolve and apply request logic for backends
-    this.fetchImplementation = environment === 'backend' ? fetchImplementation : withRequestLogic(fetchImplementation);
+    const fetchWithTelemetry = fetchBuilderWithTelemetry.build(fetchImplementation);
+    this.fetchImplementation = environment === 'backend' ? fetchWithTelemetry : withRequestLogic(fetchWithTelemetry);
+
     this.clientSecret = clientSecret;
     this.sdk = sdk;
     this.applyTimeout = applyTimeout;
@@ -134,13 +151,17 @@ export class FetchingFlagResolverClient implements FlagResolverClient {
         this.resolveTimeout,
         new ResolveError('TIMEOUT', 'Resolve timeout'),
       );
+      const start = Date.now();
       return this.resolveFlagsJson(request, signalWithTimeout)
         .then(response => FlagResolution.ready(context, response, this.createApplier(response.resolveToken)))
         .catch(error => {
           if (error instanceof ResolveError) {
             return FlagResolution.failed(context, error.code, error.message);
           }
           throw error;
+        })
+        .finally(() => {
+          this.markLatency(Date.now() - start);
         });
     });
   }
@@ -275,6 +296,20 @@ export class CachingFlagResolverClient implements FlagResolverClient {
   }
 }
 
+export function withTelemetryData(fetchBuilder: FetchBuilder, telemetry: Telemetry): FetchBuilder {
+  return fetchBuilder.modifyRequest(async request => {
+    const monitoring = telemetry.getSnapshot();
+    if (monitoring.libraryTraces.length > 0) {
+      const headers = new Headers(request.headers);
+      const base64Message = btoa(String.fromCharCode(...Monitoring.encode(monitoring).finish()));
+
+      headers.set('X-CONFIDENCE-TELEMETRY', base64Message);
+      return new Request(request, { headers });
+    }
+    return request;
+  });
+}
+
 export function withRequestLogic(fetchImplementation: (request: Request) => Promise<Response>): typeof fetch {
   const fetchResolve = new FetchBuilder()
     // infinite retries without delay until aborted by timeout

packages/sdk/src/Telemetry.test.ts

@@ -0,0 +1,79 @@
+import { LibraryTraces_Library, LibraryTraces_TraceId } from './generated/confidence/telemetry/v1/telemetry';
+import { Telemetry } from './Telemetry';
+
+describe('Telemetry', () => {
+  it('registerCounter and increment counter', () => {
+    const telemetry = new Telemetry({ disabled: false, logger: {}, environment: 'backend' });
+    const counter = telemetry.registerCounter({
+      library: LibraryTraces_Library.LIBRARY_CONFIDENCE,
+      version: '9.9.9',
+      id: LibraryTraces_TraceId.TRACE_ID_STALE_FLAG,
+    });
+    // increment the registered counter 3 times
+    counter();
+    counter();
+    counter();
+    const snapshot = telemetry.getSnapshot();
+    expect(snapshot).toBeTruthy();
+    expect(snapshot?.libraryTraces.length).toEqual(1);
+    expect(snapshot?.libraryTraces[0].library).toEqual(LibraryTraces_Library.LIBRARY_CONFIDENCE);
+    expect(snapshot?.libraryTraces[0].libraryVersion).toEqual('9.9.9');
+    expect(snapshot?.libraryTraces[0].traces).toEqual([
+      { id: LibraryTraces_TraceId.TRACE_ID_STALE_FLAG },
+      { id: LibraryTraces_TraceId.TRACE_ID_STALE_FLAG },
+      { id: LibraryTraces_TraceId.TRACE_ID_STALE_FLAG },
+    ]);
+  });
+
+  it('registerMeter and add measurement', () => {
+    const telemetry = new Telemetry({ disabled: false, logger: {}, environment: 'client' });
+    const meter = telemetry.registerMeter({
+      library: LibraryTraces_Library.LIBRARY_CONFIDENCE,
+      version: '9.9.9',
+      id: LibraryTraces_TraceId.TRACE_ID_RESOLVE_LATENCY,
+    });
+    // measure 3 times with different values
+    meter(10);
+    meter(20);
+    meter(30);
+    const snapshot = telemetry.getSnapshot();
+    expect(snapshot).toBeTruthy();
+    expect(snapshot?.libraryTraces.length).toEqual(1);
+    expect(snapshot?.libraryTraces[0].library).toEqual(LibraryTraces_Library.LIBRARY_CONFIDENCE);
+    expect(snapshot?.libraryTraces[0].libraryVersion).toEqual('9.9.9');
+    expect(snapshot?.libraryTraces[0].traces).toEqual([
+      { id: LibraryTraces_TraceId.TRACE_ID_RESOLVE_LATENCY, millisecondDuration: 10 },
+      { id: LibraryTraces_TraceId.TRACE_ID_RESOLVE_LATENCY, millisecondDuration: 20 },
+      { id: LibraryTraces_TraceId.TRACE_ID_RESOLVE_LATENCY, millisecondDuration: 30 },
+    ]);
+  });
+
+  it('snapshot is empty when telemetry is disabled', () => {
+    const telemetry = new Telemetry({ disabled: true, logger: {}, environment: 'client' });
+    const counter = telemetry.registerCounter({
+      library: LibraryTraces_Library.LIBRARY_CONFIDENCE,
+      version: '9.9.9',
+      id: LibraryTraces_TraceId.TRACE_ID_STALE_FLAG,
+    });
+    counter();
+    const snapshot = telemetry.getSnapshot();
+    expect(snapshot.libraryTraces.length).toBe(0);
+  });
+
+  it('monitoring gets cleared after snapshot is obtained', () => {
+    const telemetry = new Telemetry({ disabled: false, logger: {}, environment: 'client' });
+    const counter = telemetry.registerCounter({
+      library: LibraryTraces_Library.LIBRARY_CONFIDENCE,
+      version: '9.9.9',
+      id: LibraryTraces_TraceId.TRACE_ID_STALE_FLAG,
+    });
+    counter();
+    const snapshotFirst = telemetry.getSnapshot();
+    expect(snapshotFirst).toBeTruthy();
+    expect(snapshotFirst?.libraryTraces.length).toEqual(1);
+    expect(snapshotFirst?.libraryTraces[0].traces).toEqual([{ id: LibraryTraces_TraceId.TRACE_ID_STALE_FLAG }]);
+    const snapshotSecond = telemetry.getSnapshot();
+    // the counter is still registered but the traces are cleared
+    expect(snapshotSecond?.libraryTraces.length).toBe(0);
+  });
+});