@webex/internal-plugin-metrics 3.12.0-next.34 → 3.12.0-next.35

package/dist/types/call-diagnostic/call-diagnostic-metrics-latencies.d.ts

@@ -1,5 +1,35 @@
 import { WebexPlugin } from '@webex/webex-core';
 import { MetricEventNames, PreComputedLatencies } from '../metrics.types';
+type SaveTimestampOptions = {
+    meetingId?: string;
+    dataSetName?: string;
+    trackingId?: string;
+};
+type SaveLatencyOptions = {
+    accumulate?: boolean;
+    meetingId?: string;
+    dataSetName?: string;
+};
+type LocusSyncLatencyRecord = {
+    meetingId: string;
+    dataSetName: string;
+    randomBackoffTime: number;
+    trackingId?: string;
+    syncStart?: number;
+    hashTreeRequest?: number;
+    hashTreeResponse?: number;
+    syncRequest?: number;
+    syncResponse?: number;
+    messageReceived?: number;
+};
+/**
+ * Container for the latencies tracked for a single meeting. Locus sync is currently the only
+ * meeting-specific latency we track, but this wrapper lets us add other latency records in the
+ * future without changing the shape of `meetingLatencies`.
+ */
+type MeetingLatencyRecord = {
+    locusSync: LocusSyncLatencyRecord;
+};
 /**
  * @description Helper class to store latencies timestamp and to calculate various latencies for CA.
  * @exports
@@ -8,8 +38,12 @@ import { MetricEventNames, PreComputedLatencies } from '../metrics.types';
 export default class CallDiagnosticLatencies extends WebexPlugin {
     latencyTimestamps: Map<MetricEventNames, number>;
     precomputedLatencies: Map<PreComputedLatencies, number>;
+    meetingLatencies: Map<string, MeetingLatencyRecord[]>;
     private meetingId?;
     private MAX_INTEGER;
+    private LOCUS_SYNC_SKEW_THRESHOLD_MS;
+    private LOCUS_SYNC_PENDING_RECORD_TTL_MS;
+    private LOCUS_SYNC_MAX_RECORDS_PER_DATASET;
     /**
      * @constructor
      */
@@ -18,6 +52,164 @@ export default class CallDiagnosticLatencies extends WebexPlugin {
      * Clear timestamps
      */
     clearTimestamps(): void;
+    /**
+     * Clear tracked Locus sync latency state for a dataset.
+     *
+     * When a `trackingId` is supplied only the single record matching it is dropped, mirroring the
+     * native client which discards the individual in-progress record on a sync error (by syncId).
+     * When no `trackingId` is supplied every record for the dataset is dropped (legacy behavior).
+     *
+     * @param dataSetName dataset name
+     * @param meetingId meeting id
+     * @param trackingId optional sync tracking id to drop a single record instead of the whole dataset
+     */
+    clearLocusSyncLatency(dataSetName: string, meetingId: string, trackingId?: string): void;
+    /**
+     * Calculates Locus sync latency values from stored milestone timestamps.
+     * @param meetingId meeting id
+     * @param trackingId sync tracking id used to match the record
+     * @returns sync latency metrics
+     */
+    getLocusSyncLatency(meetingId: string, trackingId: string): {
+        totalTime: number;
+        syncMessageReceiveTime?: number;
+        syncResponseTime?: number;
+        randomBackoffTime: number;
+        hashtreePrepTime: number;
+        hashtreeResponseTime: number;
+        syncPrepTime: number;
+    };
+    /**
+     * Records the time the LLM state-update message for a Locus sync arrived. This is the milestone
+     * that gates the client.locus.sync.complete metric: the metric is emitted only for flows where
+     * the update came over LLM (aligned with the agreed requirement that body/http-only syncs do not
+     * emit). The record is matched by meeting id + tracking id, regardless of which other milestones
+     * are present yet, so the real arrival time is captured even if the /sync response has not landed.
+     * @param meetingId meeting id
+     * @param trackingId sync tracking id used to match the pending record
+     * @returns void
+     */
+    recordLocusSyncMessageReceived(meetingId: string, trackingId: string): void;
+    /**
+     * Complete and remove the Locus sync latency record for a meeting + tracking id.
+     *
+     * Both milestones are required, in any arrival order: the metric is emitted only once BOTH the
+     * matching LLM broadcast (messageReceived) AND the /sync response have arrived. The LLM broadcast
+     * confirms the client that issued the /sync received the resulting state update for its tracking
+     * id (so sync cancel, or a sync storm where the final broadcast echoed another client's tracking
+     * id, never emit); the /sync response is always waited for too, since the LLM message can arrive
+     * before the HTTP response. If either milestone is missing the record is kept so the other can
+     * still arrive; it is only consumed when the metric is actually emitted.
+     * @param meetingId meeting id
+     * @param trackingId sync tracking id used to match the pending record
+     * @returns completed sync latency metric payload, or undefined when not completed
+     */
+    completeLocusSyncLatency(meetingId: string, trackingId: string): {
+        dataSet: string;
+        syncLatency: {
+            totalTime: number;
+            syncMessageReceiveTime?: number;
+            syncResponseTime?: number;
+            randomBackoffTime: number;
+            hashtreePrepTime: number;
+            hashtreeResponseTime: number;
+            syncPrepTime: number;
+        };
+    };
+    /**
+     * Helper to calculate end - start for Locus sync milestones.
+     * @param record tracked milestone timestamps
+     * @param a start milestone
+     * @param b end milestone
+     * @returns latency
+     */
+    private getDiffBetweenLocusSyncTimestamps;
+    /**
+     * Get the timestamp that starts the sync prep segment.
+     * @param record tracked milestone timestamps
+     * @returns sync prep start milestone
+     */
+    private getLocusSyncPrepStart;
+    /**
+     * Round and clamp Locus sync latency values.
+     * @param latency latency value
+     * @returns rounded latency
+     */
+    private getClampedLocusSyncLatency;
+    /**
+     * Finds a Locus sync latency record for a meeting using a predicate run against each stored
+     * locusSync record.
+     * @param meetingId meeting id
+     * @param predicate matcher run against each locusSync record
+     * @param options.searchFromLatest when true, iterate from the most recently added record first
+     * @returns matching Locus sync latency record
+     */
+    private findLocusSyncRecord;
+    /**
+     * Get the Locus sync latency record for a meeting and tracking id.
+     * @param meetingId meeting id
+     * @param trackingId /sync response tracking id
+     * @returns matching Locus sync latency record
+     */
+    private getLocusSyncLatencyRecord;
+    /**
+     * Remove the Locus sync latency record for a meeting and tracking id.
+     * @param meetingId meeting id
+     * @param trackingId sync tracking id used to match the record
+     * @returns void
+     */
+    private removeLocusSyncLatencyRecord;
+    /**
+     * Prune stale never-completed Locus sync latency records for the same dataset as the record that
+     * just changed. Records are dropped when they have been pending longer than the TTL, or to keep
+     * the number of records per dataset under the safety cap (oldest pending candidates first).
+     * @param records current records for the meeting
+     * @param changedRecord the record that was just updated, used as the reference point
+     * @returns the records to keep
+     */
+    private pruneStaleLocusSyncLatencyRecords;
+    /**
+     * Get the most recent milestone timestamp stored on a Locus sync latency record, checking
+     * milestones from latest to earliest so the newest available one is returned.
+     * @param record tracked milestone timestamps
+     * @returns latest milestone timestamp, or undefined when none are set
+     */
+    private getLatestLocusSyncTimestamp;
+    /**
+     * Persist the Locus sync latency records for a meeting, deleting the meeting entry when no
+     * records remain. When pruneOptions is provided, stale records are pruned before saving.
+     * @param meetingId meeting id
+     * @param records records to save
+     * @param pruneOptions when provided, triggers stale record pruning relative to changedRecord
+     * @returns void
+     */
+    private setMeetingLatencyRecords;
+    /**
+     * Get the latest Locus sync latency record waiting for sync.start.
+     * @param meetingId meeting id
+     * @param dataSetName dataset name
+     * @returns latest pending Locus sync latency record
+     */
+    private getLatestPendingLocusSyncLatencyRecord;
+    /**
+     * Store random backoff latency for the current or next Locus sync latency record.
+     * @param meetingId meeting id
+     * @param dataSetName dataset name
+     * @param randomBackoffTime random backoff latency value
+     * @returns void
+     */
+    private saveLocusSyncBackoffLatency;
+    /**
+     * Checks if metric event name is a Locus sync latency milestone.
+     * @param key event name
+     * @returns whether event is Locus sync latency milestone
+     */
+    private isLocusSyncLatencyEvent;
+    /**
+     * Stores a Locus sync latency milestone timestamp.
+     * @param options options
+     */
+    private saveLocusSyncLatencyTimestamp;
     /**
      * Associate current latencies with a meeting id
      * @param meetingId
@@ -39,19 +231,20 @@ export default class CallDiagnosticLatencies extends WebexPlugin {
     saveTimestamp({ key, value, options, }: {
         key: MetricEventNames;
         value?: number;
-        options?: {
-            meetingId?: string;
-        };
+        options?: SaveTimestampOptions;
     }): void;
     /**
      * Store precomputed latency value
      * @param key - key
      * @param value - value
-     * @param accumulate - when it is true, it overwrites existing value with sum of the current value and the new measurement otherwise just store the new measurement
+     * @param options - store options (a legacy boolean `accumulate` flag is also accepted)
+     * @param options.accumulate - when it is true, it overwrites existing value with sum of the current value and the new measurement otherwise just store the new measurement
+     * @param options.meetingId - meeting id, only used for Locus sync latency records
+     * @param options.dataSetName - dataset name, only used for Locus sync latency records
      * @throws
      * @returns
      */
-    saveLatency(key: PreComputedLatencies, value: number, accumulate?: boolean): void;
+    saveLatency(key: PreComputedLatencies, value: number, options?: SaveLatencyOptions): void;
     /**
      * Measure latency for a request
      * @param callback - callback for which you would like to measure latency
@@ -267,3 +460,4 @@ export default class CallDiagnosticLatencies extends WebexPlugin {
      */
     getOtherAppApiReqResp(): number;
 }
+export {};

package/dist/types/index.d.ts

@@ -4,7 +4,7 @@
 import config from './config';
 import NewMetrics from './new-metrics';
 import * as Utils from './utils';
-import { ClientEvent, ClientEventLeaveReason, SubmitBehavioralEvent, SubmitClientEvent, SubmitInternalEvent, SubmitOperationalEvent, SubmitBusinessEvent, SubmitMQE, PreComputedLatencies, SubmitFeatureEvent } from './metrics.types';
+import { ClientEvent, ClientEventLeaveReason, SubmitBehavioralEvent, SubmitClientEvent, SubmitInternalEvent, SubmitOperationalEvent, SubmitBusinessEvent, SubmitMQE, PreComputedLatencies, SubmitFeatureEvent, LocusSyncLatencyEventName } from './metrics.types';
 import * as CALL_DIAGNOSTIC_CONFIG from './call-diagnostic/config';
 import * as CallDiagnosticUtils from './call-diagnostic/call-diagnostic-metrics.util';
 import CallDiagnosticMetrics from './call-diagnostic/call-diagnostic-metrics';
@@ -16,4 +16,4 @@ import RtcMetrics from './rtcMetrics';
 import PreLoginMetrics from './prelogin-metrics';
 export { default, getOSNameInternal } from './metrics';
 export { config, CALL_DIAGNOSTIC_CONFIG, NewMetrics, Utils, CallDiagnosticUtils, CallDiagnosticLatencies, CallDiagnosticMetrics, BehavioralMetrics, OperationalMetrics, BusinessMetrics, RtcMetrics, PreLoginMetrics, };
-export type { ClientEvent, ClientEventLeaveReason, SubmitBehavioralEvent, SubmitClientEvent, SubmitInternalEvent, SubmitMQE, SubmitOperationalEvent, SubmitBusinessEvent, PreComputedLatencies, SubmitFeatureEvent, };
+export type { ClientEvent, ClientEventLeaveReason, SubmitBehavioralEvent, SubmitClientEvent, SubmitInternalEvent, SubmitMQE, SubmitOperationalEvent, SubmitBusinessEvent, PreComputedLatencies, SubmitFeatureEvent, LocusSyncLatencyEventName, };

package/dist/types/metrics.types.d.ts

@@ -41,8 +41,10 @@ export type SubmitMQEOptions = {
     webexConferenceIdStr?: string;
     globalMeetingId?: string;
 };
+export declare const LOCUS_SYNC_LATENCY_EVENT_NAMES: readonly ["internal.client.locus.sync.start", "internal.client.locus.hashtree.request", "internal.client.locus.hashtree.response", "internal.client.locus.sync.request", "internal.client.locus.sync.response", "internal.client.locus.sync.message.received"];
+export type LocusSyncLatencyEventName = (typeof LOCUS_SYNC_LATENCY_EVENT_NAMES)[number];
 export type InternalEvent = {
-    name: 'internal.client.meetinginfo.request' | 'internal.client.meetinginfo.response' | 'internal.register.device.request' | 'internal.register.device.response' | 'internal.reset.join.latencies' | 'internal.host.meeting.participant.admitted' | 'internal.client.meeting.interstitial-window.showed' | 'internal.client.interstitial-window.click.joinbutton' | 'internal.client.add-media.turn-discovery.start' | 'internal.client.add-media.turn-discovery.end' | 'internal.client.share.initiated' | 'internal.client.share.stopped';
+    name: 'internal.client.meetinginfo.request' | 'internal.client.meetinginfo.response' | 'internal.register.device.request' | 'internal.register.device.response' | 'internal.reset.join.latencies' | 'internal.host.meeting.participant.admitted' | 'internal.client.meeting.interstitial-window.showed' | 'internal.client.interstitial-window.click.joinbutton' | 'internal.client.add-media.turn-discovery.start' | 'internal.client.add-media.turn-discovery.end' | 'internal.client.share.initiated' | 'internal.client.share.stopped' | LocusSyncLatencyEventName;
     payload?: never;
     options?: never;
 };
@@ -154,7 +156,7 @@ export type BuildClientEventFetchRequestOptions = (args: {
     payload?: RecursivePartial<ClientEvent['payload']>;
     options?: SubmitClientEventOptions;
 }) => Promise<any>;
-export type PreComputedLatencies = 'internal.client.pageJMT' | 'internal.download.time' | 'internal.get.cluster.time' | 'internal.click.to.interstitial' | 'internal.click.to.interstitial.with.user.delay' | 'internal.click.to.interstitial.for.client.jmt' | 'internal.refresh.captcha.time' | 'internal.exchange.ci.token.time' | 'internal.get.u2c.time' | 'internal.call.init.join.req' | 'internal.other.app.api.time' | 'internal.api.fetch.intelligence.models';
+export type PreComputedLatencies = 'internal.client.pageJMT' | 'internal.download.time' | 'internal.get.cluster.time' | 'internal.click.to.interstitial' | 'internal.click.to.interstitial.with.user.delay' | 'internal.click.to.interstitial.for.client.jmt' | 'internal.refresh.captcha.time' | 'internal.exchange.ci.token.time' | 'internal.get.u2c.time' | 'internal.call.init.join.req' | 'internal.other.app.api.time' | 'internal.api.fetch.intelligence.models' | 'internal.client.locus.sync.random.backoff';
 export interface IdType {
     meetingId?: string;
     callId?: string;

package/package.json

@@ -40,7 +40,7 @@
     "@webex/event-dictionary-ts": "^1.0.2215",
     "@webex/test-helper-chai": "3.12.0-next.5",
     "@webex/test-helper-mock-webex": "3.12.0-next.5",
-    "@webex/webex-core": "3.12.0-next.34",
+    "@webex/webex-core": "3.12.0-next.35",
     "ip-anonymize": "^0.1.0",
     "lodash": "^4.17.21",
     "uuid": "^3.3.2"
@@ -53,5 +53,5 @@
     "test:style": "eslint ./src/**/*.*",
     "test:unit": "webex-legacy-tools test --unit --runner mocha"
   },
-  "version": "3.12.0-next.34"
+  "version": "3.12.0-next.35"
 }