feat: Telemetry header

api/sdk.api.md

@@ -4,6 +4,9 @@
 
 ```ts
 
+import { BinaryReader } from '@bufbuild/protobuf/wire';
+import { BinaryWriter } from '@bufbuild/protobuf/wire';
+
 // @public
 export namespace Closer {
     export function combine(...closers: Closer[]): Closer;
@@ -22,7 +25,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 +55,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,34 @@
+syntax = "proto3";
+
+package confidence.telemetry.v1;
+
+message Monitoring {
+  repeated LibraryTraces library_traces = 1;
+}
+
+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,15 @@ 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,
+    });
     let flagResolverClient: FlagResolverClient = new FetchingFlagResolverClient({
       clientSecret,
       fetchImplementation,
@@ -346,6 +353,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

@@ -10,6 +10,7 @@ import { SdkId } from './generated/confidence/flags/resolver/v1/types';
 import { abortableSleep } from './fetch-util';
 import { ApplyFlagsRequest, ResolveFlagsRequest } from './generated/confidence/flags/resolver/v1/api';
 import { FlagResolution } from './FlagResolution';
+import { Telemetry } from './Telemetry';
 const RESOLVE_ENDPOINT = 'https://resolver.confidence.dev/v1/flags:resolve';
 const APPLY_ENDPOINT = 'https://resolver.confidence.dev/v1/flags:apply';
 
@@ -56,6 +57,7 @@ describe('Client environment Evaluation', () => {
     },
     environment: 'client',
     resolveTimeout: 10,
+    telemetry: new Telemetry({ disabled: true }),
   });
 
   describe('apply', () => {
@@ -108,6 +110,7 @@ describe('Backend environment Evaluation', () => {
     },
     environment: 'backend',
     resolveTimeout: 10,
+    telemetry: new Telemetry({ disabled: true }),
   });
 
   it('should resolve a full flag object', async () => {

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,20 @@ export class FetchingFlagResolverClient implements FlagResolverClient {
     environment,
     region,
     resolveBaseUrl,
+    telemetry,
   }: FlagResolverClientOptions) {
+    this.markLatency = telemetry.registerMeter({
+      // TODO how to get library name?
+      library: LibraryTraces_Library.LIBRARY_CONFIDENCE,
+      version: sdk.version,
+      id: LibraryTraces_TraceId.TRACE_ID_RESOLVE_LATENCY,
+    });
     // TODO think about both resolve and apply request logic for backends
-    this.fetchImplementation = environment === 'backend' ? fetchImplementation : withRequestLogic(fetchImplementation);
+    this.fetchImplementation =
+      environment === 'backend'
+        ? withTelemetryData(fetchImplementation, telemetry)
+        : withRequestLogic(withTelemetryData(fetchImplementation, telemetry));
+
     this.clientSecret = clientSecret;
     this.sdk = sdk;
     this.applyTimeout = applyTimeout;
@@ -134,13 +153,17 @@ export class FetchingFlagResolverClient implements FlagResolverClient {
         this.resolveTimeout,
         new ResolveError('TIMEOUT', 'Resolve timeout'),
       );
+      const start = new Date().getTime();
       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(new Date().getTime() - start);
         });
     });
   }
@@ -275,6 +298,25 @@ export class CachingFlagResolverClient implements FlagResolverClient {
   }
 }
 
+export function withTelemetryData(
+  fetchImplementation: (request: Request) => Promise<Response>,
+  telemetry: Telemetry,
+): typeof fetch {
+  return new FetchBuilder()
+    .modifyRequest(async request => {
+      const monitoring = telemetry.getSnapshot();
+      if (monitoring) {
+        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;
+    })
+    .build(fetchImplementation);
+}
+
 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.ts

@@ -0,0 +1,87 @@
+import {
+  LibraryTraces_Library,
+  LibraryTraces_TraceId,
+  Monitoring,
+} from './generated/confidence/telemetry/v1/telemetry';
+
+export type TelemetryOptions = { disabled: boolean };
+
+export type Tag = {
+  library: LibraryTraces_Library;
+  version: string;
+  id: LibraryTraces_TraceId;
+};
+
+export type Counter = () => void;
+export type Meter = (value: number) => void;
+
+export class Telemetry {
+  private disabled: boolean;
+  constructor(opts: TelemetryOptions) {
+    this.disabled = opts.disabled;
+  }
+
+  private monitoring: Monitoring = {
+    libraryTraces: [],
+  };
+
+  private pushTrace(tags: Tag, value: number | undefined = undefined): void {
+    const library = tags.library;
+    const version = tags.version;
+    const existing = this.monitoring.libraryTraces.find(trace => {
+      return trace.library === library && trace.libraryVersion === version;
+    });
+    if (existing) {
+      existing.traces.push({
+        id: tags.id,
+        millisecondDuration: value,
+      });
+    } else {
+      // should never happen. remove?
+      this.monitoring.libraryTraces.push({
+        library,
+        libraryVersion: version,
+        traces: [
+          {
+            id: tags.id,
+            millisecondDuration: value,
+          },
+        ],
+      });
+    }
+  }
+
+  registerCounter(tag: Tag): Counter {
+    this.monitoring.libraryTraces.push({
+      library: tag.library,
+      libraryVersion: tag.version,
+      traces: [],
+    });
+    return () => {
+      this.pushTrace(tag);
+    };
+  }
+
+  registerMeter(tag: Tag): Meter {
+    this.monitoring.libraryTraces.push({
+      library: tag.library,
+      libraryVersion: tag.version,
+      traces: [],
+    });
+    return (value: number) => {
+      this.pushTrace(tag, value);
+    };
+  }
+
+  getSnapshot(): Monitoring | undefined {
+    if (this.disabled) {
+      return undefined;
+    }
+    const snapshot = { ...this.monitoring };
+    this.monitoring.libraryTraces.forEach(trace => {
+      // only clear traces. keep library and version since they are registered.
+      trace.traces = [];
+    });
+    return snapshot;
+  }
+}