@webex/internal-plugin-metrics 3.8.1 → 3.9.0

package/src/call-diagnostic/call-diagnostic-metrics-latencies.ts

@@ -148,15 +148,27 @@ export default class CallDiagnosticLatencies extends WebexPlugin {
    * @param b end
    * @returns latency
    */
-  public getDiffBetweenTimestamps(a: MetricEventNames, b: MetricEventNames) {
+  public getDiffBetweenTimestamps(
+    a: MetricEventNames,
+    b: MetricEventNames,
+    clampValues?: {minimum?: number; maximum?: number}
+  ) {
     const start = this.latencyTimestamps.get(a);
     const end = this.latencyTimestamps.get(b);
 
-    if (typeof start === 'number' && typeof end === 'number') {
-      return end - start;
+    if (typeof start !== 'number' || typeof end !== 'number') {
+      return undefined;
     }
 
-    return undefined;
+    const diff = end - start;
+
+    if (!clampValues) {
+      return diff;
+    }
+
+    const {minimum = 0, maximum} = clampValues;
+
+    return Math.min(maximum ?? Infinity, Math.max(diff, minimum));
   }
 
   /**
@@ -172,7 +184,8 @@ export default class CallDiagnosticLatencies extends WebexPlugin {
   public getMeetingInfoReqResp() {
     return this.getDiffBetweenTimestamps(
       'internal.client.meetinginfo.request',
-      'internal.client.meetinginfo.response'
+      'internal.client.meetinginfo.response',
+      {maximum: 1200000}
     );
   }
 
@@ -215,7 +228,8 @@ export default class CallDiagnosticLatencies extends WebexPlugin {
   public getCallInitJoinReq() {
     return this.getDiffBetweenTimestamps(
       'internal.client.interstitial-window.click.joinbutton',
-      'client.locus.join.request'
+      'client.locus.join.request',
+      {maximum: 1200000}
     );
   }
 
@@ -224,7 +238,11 @@ export default class CallDiagnosticLatencies extends WebexPlugin {
    * @returns - latency
    */
   public getJoinReqResp() {
-    return this.getDiffBetweenTimestamps('client.locus.join.request', 'client.locus.join.response');
+    return this.getDiffBetweenTimestamps(
+      'client.locus.join.request',
+      'client.locus.join.response',
+      {maximum: 1200000}
+    );
   }
 
   /**
@@ -245,7 +263,8 @@ export default class CallDiagnosticLatencies extends WebexPlugin {
   public getLocalSDPGenRemoteSDPRecv() {
     return this.getDiffBetweenTimestamps(
       'client.media-engine.local-sdp-generated',
-      'client.media-engine.remote-sdp-received'
+      'client.media-engine.remote-sdp-received',
+      {maximum: 1200000}
     );
   }
 
@@ -254,7 +273,7 @@ export default class CallDiagnosticLatencies extends WebexPlugin {
    * @returns - latency
    */
   public getICESetupTime() {
-    return this.getDiffBetweenTimestamps('client.ice.start', 'client.ice.end');
+    return this.getDiffBetweenTimestamps('client.ice.start', 'client.ice.end', {maximum: 1200000});
   }
 
   /**
@@ -336,6 +355,30 @@ export default class CallDiagnosticLatencies extends WebexPlugin {
     return undefined;
   }
 
+  /**
+   * Click To Interstitial With User Delay
+   * @returns - latency
+   */
+  public getClickToInterstitialWithUserDelay() {
+    // for normal join (where green join button exists before interstitial, i.e reminder, space list etc)
+    if (this.latencyTimestamps.get('internal.client.meeting.click.joinbutton')) {
+      return this.getDiffBetweenTimestamps(
+        'internal.client.meeting.click.joinbutton',
+        'internal.client.meeting.interstitial-window.showed'
+      );
+    }
+
+    const clickToInterstitialWithUserDelayLatency = this.precomputedLatencies.get(
+      'internal.click.to.interstitial.with.user.delay'
+    );
+
+    if (typeof clickToInterstitialWithUserDelayLatency === 'number') {
+      return clickToInterstitialWithUserDelayLatency;
+    }
+
+    return undefined;
+  }
+
   /**
    * Interstitial To Join Ok
    * @returns - latency
@@ -354,7 +397,8 @@ export default class CallDiagnosticLatencies extends WebexPlugin {
   public getCallInitMediaEngineReady() {
     return this.getDiffBetweenTimestamps(
       'internal.client.interstitial-window.click.joinbutton',
-      'client.media-engine.ready'
+      'client.media-engine.ready',
+      {maximum: 1200000}
     );
   }
 
@@ -374,7 +418,9 @@ export default class CallDiagnosticLatencies extends WebexPlugin {
     const lobbyTime = typeof lobbyTimeLatency === 'number' ? lobbyTimeLatency : 0;
 
     if (interstitialJoinClickTimestamp && connectedMedia) {
-      return connectedMedia - interstitialJoinClickTimestamp - lobbyTime;
+      const interstitialToMediaOKJmt = connectedMedia - interstitialJoinClickTimestamp - lobbyTime;
+
+      return Math.max(0, interstitialToMediaOKJmt);
     }
 
     return undefined;
@@ -395,6 +441,24 @@ export default class CallDiagnosticLatencies extends WebexPlugin {
     return undefined;
   }
 
+  /**
+   * Total JMT With User Delay
+   * @returns - latency
+   */
+  public getTotalJMTWithUserDelay() {
+    const clickToInterstitialWithUserDelay = this.getClickToInterstitialWithUserDelay();
+    const interstitialToJoinOk = this.getInterstitialToJoinOK();
+
+    if (
+      typeof clickToInterstitialWithUserDelay === 'number' &&
+      typeof interstitialToJoinOk === 'number'
+    ) {
+      return clickToInterstitialWithUserDelay + interstitialToJoinOk;
+    }
+
+    return undefined;
+  }
+
   /**
    * Join Conf JMT
    * @returns - latency
@@ -421,12 +485,28 @@ export default class CallDiagnosticLatencies extends WebexPlugin {
     const lobbyTime = this.getStayLobbyTime();
 
     if (clickToInterstitial && interstitialToJoinOk && joinConfJMT) {
-      const totalMediaJMT = clickToInterstitial + interstitialToJoinOk + joinConfJMT;
+      const totalMediaJMT = Math.max(0, clickToInterstitial + interstitialToJoinOk + joinConfJMT);
       if (this.getMeeting()?.allowMediaInLobby) {
         return totalMediaJMT;
       }
 
-      return totalMediaJMT - lobbyTime;
+      return Math.max(0, totalMediaJMT - lobbyTime);
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Total Media JMT With User Delay
+   * @returns - latency
+   */
+  public getTotalMediaJMTWithUserDelay() {
+    const clickToInterstitialWithUserDelay = this.getClickToInterstitialWithUserDelay();
+    const interstitialToJoinOk = this.getInterstitialToJoinOK();
+    const joinConfJMT = this.getJoinConfJMT();
+
+    if (clickToInterstitialWithUserDelay && interstitialToJoinOk && joinConfJMT) {
+      return Math.max(0, clickToInterstitialWithUserDelay + interstitialToJoinOk + joinConfJMT);
     }
 
     return undefined;
@@ -441,7 +521,7 @@ export default class CallDiagnosticLatencies extends WebexPlugin {
     const joinConfJMT = this.getJoinConfJMT();
 
     if (typeof interstitialToJoinOk === 'number' && typeof joinConfJMT === 'number') {
-      return interstitialToJoinOk - joinConfJMT;
+      return Math.max(0, interstitialToJoinOk - joinConfJMT);
     }
 
     return undefined;
@@ -486,6 +566,16 @@ export default class CallDiagnosticLatencies extends WebexPlugin {
     return this.getDiffBetweenTimestamps('client.locus.join.response', 'client.media.tx.start');
   }
 
+  /**
+   * Time from share initiation to share stop (ms).
+   */
+  public getShareDuration() {
+    return this.getDiffBetweenTimestamps(
+      'internal.client.share.initiated',
+      'internal.client.share.stopped'
+    );
+  }
+
   /**
    * Total latency for all exchange ci token.
    */

package/src/call-diagnostic/call-diagnostic-metrics.ts

@@ -41,6 +41,9 @@ import {
   ClientSubServiceType,
   BrowserLaunchMethodType,
   DelayedClientEvent,
+  DelayedClientFeatureEvent,
+  FeatureEvent,
+  ClientFeatureEventPayload,
 } from '../metrics.types';
 import CallDiagnosticEventsBatcher from './call-diagnostic-metrics-batcher';
 import PreLoginMetricsBatcher from '../prelogin-metrics-batcher';
@@ -58,6 +61,8 @@ import {
   AUTHENTICATION_FAILED_CODE,
   WEBEX_SUB_SERVICE_TYPES,
   SDP_OFFER_CREATION_ERROR_MAP,
+  CALL_FEATURE_LOG_IDENTIFIER,
+  CALL_FEATURE_EVENT_FAILED_TO_SEND,
 } from './config';
 
 const {getOSVersion, getBrowserName, getBrowserVersion} = BrowserDetection();
@@ -97,7 +102,11 @@ export default class CallDiagnosticMetrics extends StatelessWebexPlugin {
   private hasLoggedBrowserSerial: boolean;
   private device: any;
   private delayedClientEvents: DelayedClientEvent[] = [];
+  private delayedClientFeatureEvents: DelayedClientFeatureEvent[] = [];
   private eventErrorCache: WeakMap<any, any> = new WeakMap();
+  private isMercuryConnected = false;
+  private eventLimitTracker: Map<string, number> = new Map();
+  private eventLimitWarningsLogged: Set<string> = new Set();
 
   // the default validator before piping an event to the batcher
   // this function can be overridden by the user
@@ -150,6 +159,16 @@ export default class CallDiagnosticMetrics extends StatelessWebexPlugin {
     return undefined;
   }
 
+  /**
+   * Sets mercury connected status for event data object in CA events
+   * @public
+   * @param status - boolean value indicating mercury connection status
+   * @return {void}
+   */
+  public setMercuryConnectedStatus(status: boolean): void {
+    this.isMercuryConnected = status;
+  }
+
   /**
    * Returns meeting's subServiceType
    * @param meeting
@@ -416,12 +435,97 @@ export default class CallDiagnosticMetrics extends StatelessWebexPlugin {
   }
 
   /**
-   * TODO: NOT IMPLEMENTED
+   * Create feature event
+   * @param name
+   * @param payload
+   * @param options
+   * @returns
+   */
+  private prepareClientFeatureEvent({
+    name,
+    payload,
+    options,
+  }: {
+    name: FeatureEvent['name'];
+    payload?: ClientFeatureEventPayload;
+    options?: SubmitClientEventOptions;
+  }) {
+    const {meetingId, correlationId} = options;
+    let featureEventObject: FeatureEvent['payload'];
+
+    // events that will most likely happen in join phase
+    if (meetingId) {
+      featureEventObject = this.createFeatureEventObjectInMeeting({name, options});
+    } else {
+      throw new Error('Not implemented');
+    }
+
+    // merge any new properties, or override existing ones
+    featureEventObject = merge(featureEventObject, payload);
+
+    // append client event data to the call diagnostic event
+    const featureEvent = this.prepareDiagnosticEvent(featureEventObject, options);
+
+    return featureEvent;
+  }
+
+  /**
    * Submit Feature Event
+   * submit to business_ucf
    * @returns
    */
-  public submitFeatureEvent() {
-    throw Error('Not implemented');
+  public submitFeatureEvent({
+    name,
+    payload,
+    options,
+    delaySubmitEvent,
+  }: {
+    name: FeatureEvent['name'];
+    payload?: ClientFeatureEventPayload;
+    options?: SubmitClientEventOptions;
+    delaySubmitEvent?: boolean;
+  }) {
+    if (delaySubmitEvent) {
+      // Preserve the time when the event was triggered if delaying the submission to Call Features
+      const delayedOptions = {
+        ...options,
+        triggeredTime: new Date().toISOString(),
+      };
+
+      this.delayedClientFeatureEvents.push({
+        name,
+        payload,
+        options: delayedOptions,
+      });
+
+      return Promise.resolve();
+    }
+
+    this.logger.log(
+      CALL_FEATURE_LOG_IDENTIFIER,
+      'CallFeatureMetrics: @submitFeatureEvent. Submit Client Feature Event CA event.',
+      `name: ${name}`
+    );
+    const featureEvent = this.prepareClientFeatureEvent({name, payload, options});
+
+    this.validator({type: 'ce', event: featureEvent});
+
+    return this.submitToCallFeatures(featureEvent);
+  }
+
+  /**
+   * Submit Feature Event
+   * type is business
+   * @param event
+   */
+  submitToCallFeatures(event: Event): Promise<any> {
+    // build metrics-a event type
+    const finalEvent = {
+      eventPayload: event,
+      type: ['business'],
+    };
+
+    return this.callDiagnosticEventsBatcher.request(finalEvent);
   }
 
   /**
@@ -563,6 +667,144 @@ export default class CallDiagnosticMetrics extends StatelessWebexPlugin {
     this.eventErrorCache = new WeakMap();
   }
 
+  /**
+   * Checks if an event should be limited based on criteria defined in the event dictionary.
+   * Returns true if the event should be sent, false if it has reached its limit.
+   * @param event - The diagnostic event object
+   * @returns boolean indicating whether the event should be sent
+   */
+  private shouldSendEvent({event}: Event): boolean {
+    const eventName = event?.name as string;
+    const correlationId = event?.identifiers?.correlationId;
+
+    if (!correlationId || correlationId === 'unknown') {
+      return true;
+    }
+
+    const limitKeyPrefix = `${eventName}:${correlationId}`;
+
+    switch (eventName) {
+      case 'client.media.render.start':
+      case 'client.media.render.stop':
+      case 'client.media.rx.start':
+      case 'client.media.rx.stop':
+      case 'client.media.tx.start':
+      case 'client.media.tx.stop': {
+        // Send only once per mediaType-correlationId pair (or mediaType-correlationId-shareInstanceId for share/share_audio)
+        const mediaType = event?.mediaType;
+        if (mediaType) {
+          if (mediaType === 'share' || mediaType === 'share_audio') {
+            const shareInstanceId = event?.shareInstanceId;
+            if (shareInstanceId) {
+              const limitKey = `${limitKeyPrefix}:${mediaType}:${shareInstanceId}`;
+
+              return this.checkAndIncrementEventCount(
+                limitKey,
+                1,
+                `${eventName} for ${mediaType} instance ${shareInstanceId}`
+              );
+            }
+          } else {
+            const limitKey = `${limitKeyPrefix}:${mediaType}`;
+
+            return this.checkAndIncrementEventCount(
+              limitKey,
+              1,
+              `${eventName} for mediaType ${mediaType}`
+            );
+          }
+        }
+        break;
+      }
+
+      case 'client.roap-message.received':
+      case 'client.roap-message.sent': {
+        // Send only once per correlationId and roap.messageType/roap.type
+        const roapMessageType = event?.roap?.messageType || event?.roap?.type;
+        if (roapMessageType) {
+          const limitKey = `${limitKeyPrefix}:${roapMessageType}`;
+
+          return this.checkAndIncrementEventCount(
+            limitKey,
+            1,
+            `${eventName} for ROAP type ${roapMessageType}`
+          );
+        }
+        break;
+      }
+
+      default:
+        return true;
+    }
+
+    return true;
+  }
+
+  /**
+   * Checks the current count for a limit key and increments if under limit.
+   * @param limitKey - The unique key for this limit combination
+   * @param maxCount - Maximum allowed count
+   * @param eventDescription - Description for logging
+   * @returns true if under limit and incremented, false if at/over limit
+   */
+  private checkAndIncrementEventCount(
+    limitKey: string,
+    maxCount: number,
+    eventDescription: string
+  ): boolean {
+    const currentCount = this.eventLimitTracker.get(limitKey) || 0;
+
+    if (currentCount >= maxCount) {
+      // Log warning only once per limit key
+      if (!this.eventLimitWarningsLogged.has(limitKey)) {
+        this.logger.log(
+          CALL_DIAGNOSTIC_LOG_IDENTIFIER,
+          `CallDiagnosticMetrics: Event limit reached for ${eventDescription}. ` +
+            `Max count ${maxCount} exceeded. Event will not be sent.`,
+          `limitKey: ${limitKey}`
+        );
+        this.eventLimitWarningsLogged.add(limitKey);
+      }
+
+      return false;
+    }
+
+    // Increment count and allow event
+    this.eventLimitTracker.set(limitKey, currentCount + 1);
+
+    return true;
+  }
+
+  /**
+   * Clears event limit tracking
+   */
+  public clearEventLimits(): void {
+    this.eventLimitTracker.clear();
+    this.eventLimitWarningsLogged.clear();
+  }
+
+  /**
+   * Clears event limit tracking for a specific correlationId only.
+   * Keeps limits for other meetings intact.
+   */
+  public clearEventLimitsForCorrelationId(correlationId: string): void {
+    if (!correlationId) {
+      return;
+    }
+    // Keys are formatted as "eventName:correlationId:..." across all limiters.
+    const hasCorrIdAtSecondToken = (key: string) => key.split(':')[1] === correlationId;
+    for (const key of Array.from(this.eventLimitTracker.keys())) {
+      if (hasCorrIdAtSecondToken(key)) {
+        this.eventLimitTracker.delete(key);
+      }
+    }
+    for (const key of Array.from(this.eventLimitWarningsLogged.values())) {
+      if (hasCorrIdAtSecondToken(key)) {
+        this.eventLimitWarningsLogged.delete(key);
+      }
+    }
+  }
+
   /**
    * Generate error payload for Client Event
    * @param rawError
@@ -680,20 +922,20 @@ export default class CallDiagnosticMetrics extends StatelessWebexPlugin {
   }
 
   /**
-   * Create client event object for in meeting events
-   * @param arg - create args
-   * @param arg.event - event key
-   * @param arg.options - options
+   * Create common object for in meeting events
+   * @param name
+   * @param options
+   * @param eventType - 'client' | 'feature'
    * @returns object
    */
-  private createClientEventObjectInMeeting({
+  private createCommonEventObjectInMeeting({
     name,
     options,
-    errors,
+    eventType = 'client',
   }: {
-    name: ClientEvent['name'];
+    name: string;
     options?: SubmitClientEventOptions;
-    errors?: ClientEventPayloadError;
+    eventType?: 'client' | 'feature';
   }) {
     const {
       meetingId,
@@ -708,16 +950,21 @@ export default class CallDiagnosticMetrics extends StatelessWebexPlugin {
 
     if (!meeting) {
       console.warn(
-        'Attempt to send client event but no meeting was found...',
+        'Attempt to send common event but no meeting was found...',
         `name: ${name}, meetingId: ${meetingId}`
       );
       // @ts-ignore
-      this.webex.internal.metrics.submitClientMetrics(CALL_DIAGNOSTIC_EVENT_FAILED_TO_SEND, {
-        fields: {
-          meetingId,
-          name,
-        },
-      });
+      this.webex.internal.metrics.submitClientMetrics(
+        eventType === 'feature'
+          ? CALL_FEATURE_EVENT_FAILED_TO_SEND
+          : CALL_DIAGNOSTIC_EVENT_FAILED_TO_SEND,
+        {
+          fields: {
+            meetingId,
+            name,
+          },
+        }
+      );
 
       return undefined;
     }
@@ -731,12 +978,11 @@ export default class CallDiagnosticMetrics extends StatelessWebexPlugin {
       sessionCorrelationId,
     });
 
-    // create client event object
-    const clientEventObject: ClientEvent['payload'] = {
+    // create common event object structur
+    const commonEventObject = {
       name,
       canProceed: true,
       identifiers,
-      errors,
       eventData: {
         webClientDomain: window.location.hostname,
       },
@@ -757,18 +1003,80 @@ export default class CallDiagnosticMetrics extends StatelessWebexPlugin {
 
     const joinFlowVersion = options.joinFlowVersion ?? meeting.callStateForMetrics?.joinFlowVersion;
     if (joinFlowVersion) {
-      clientEventObject.joinFlowVersion = joinFlowVersion;
+      // @ts-ignore
+      commonEventObject.joinFlowVersion = joinFlowVersion;
     }
     const meetingJoinedTime = meeting.isoLocalClientMeetingJoinTime;
     if (meetingJoinedTime) {
-      clientEventObject.meetingJoinedTime = meetingJoinedTime;
+      // @ts-ignore
+      commonEventObject.meetingJoinedTime = meetingJoinedTime;
     }
 
     if (options.meetingJoinPhase) {
-      clientEventObject.meetingJoinPhase = options.meetingJoinPhase;
+      // @ts-ignore
+      commonEventObject.meetingJoinPhase = options.meetingJoinPhase;
     }
 
-    return clientEventObject;
+    return commonEventObject;
+  }
+
+  /**
+   * Create client event object for in meeting events
+   * @param arg - create args
+   * @param arg.event - event key
+   * @param arg.options - options
+   * @returns object
+   */
+  private createClientEventObjectInMeeting({
+    name,
+    options,
+    errors,
+  }: {
+    name: ClientEvent['name'];
+    options?: SubmitClientEventOptions;
+    errors?: ClientEventPayloadError;
+  }) {
+    const commonObject = this.createCommonEventObjectInMeeting({
+      name,
+      options,
+      eventType: 'client',
+    });
+    if (!commonObject) return undefined;
+
+    return {
+      ...commonObject,
+      errors,
+      eventData: {
+        ...commonObject.eventData,
+        isMercuryConnected: this.isMercuryConnected,
+      },
+    } as ClientEvent['payload'];
+  }
+
+  /**
+   * Create feature event object for in meeting function event
+   * @param name
+   * @param options
+   * @returns object
+   */
+  private createFeatureEventObjectInMeeting({
+    name,
+    options,
+  }: {
+    name: FeatureEvent['name'];
+    options?: SubmitClientEventOptions;
+  }) {
+    const commonObject = this.createCommonEventObjectInMeeting({
+      name,
+      options,
+      eventType: 'feature',
+    });
+    if (!commonObject) return undefined;
+
+    return {
+      ...commonObject,
+      key: 'UcfFeatureUsage',
+    } as FeatureEvent['payload'];
   }
 
   /**
@@ -807,6 +1115,7 @@ export default class CallDiagnosticMetrics extends StatelessWebexPlugin {
       identifiers,
       eventData: {
         webClientDomain: window.location.hostname,
+        isMercuryConnected: this.isMercuryConnected,
       },
       loginType: this.getCurLoginType(),
       // @ts-ignore
@@ -930,6 +1239,10 @@ export default class CallDiagnosticMetrics extends StatelessWebexPlugin {
     );
     const diagnosticEvent = this.prepareClientEvent({name, payload, options});
 
+    if (!this.shouldSendEvent(diagnosticEvent)) {
+      return Promise.resolve();
+    }
+
     if (options?.preLoginId) {
       return this.submitToCallDiagnosticsPreLogin(diagnosticEvent, options?.preLoginId);
     }
@@ -964,6 +1277,31 @@ export default class CallDiagnosticMetrics extends StatelessWebexPlugin {
     return Promise.all(promises);
   }
 
+  /**
+   * Submit Delayed feature Event CA events. Clears submitDelayedClientFeatureEvents array after submission.
+   */
+  public submitDelayedClientFeatureEvents(overrides?: Partial<DelayedClientEvent['options']>) {
+    this.logger.log(
+      CALL_FEATURE_LOG_IDENTIFIER,
+      'CallDiagnosticMetrics: @submitDelayedClientFeatureEvents. Submitting delayed feature events.'
+    );
+
+    if (this.delayedClientFeatureEvents.length === 0) {
+      return Promise.resolve();
+    }
+
+    const promises = this.delayedClientFeatureEvents.map((delayedSubmitClientEventParams) => {
+      const {name, payload, options} = delayedSubmitClientEventParams;
+      const optionsWithOverrides: DelayedClientEvent['options'] = {...options, ...overrides};
+
+      return this.submitFeatureEvent({name, payload, options: optionsWithOverrides});
+    });
+
+    this.delayedClientFeatureEvents = [];
+
+    return Promise.all(promises);
+  }
+
   /**
    * Prepare the event and send the request to metrics-a service.
    * @param event