@webex/internal-plugin-metrics 3.0.0-bnr.5 → 3.0.0-next.2

package/src/index.ts

@@ -0,0 +1,54 @@
+/*!
+ * Copyright (c) 2015-2020 Cisco Systems, Inc. See LICENSE file.
+ */
+
+import '@webex/internal-plugin-device';
+
+import {registerInternalPlugin} from '@webex/webex-core';
+
+import Metrics from './metrics';
+import config from './config';
+import NewMetrics from './new-metrics';
+import * as Utils from './utils';
+import {
+  ClientEvent,
+  ClientEventLeaveReason,
+  SubmitBehavioralEvent,
+  SubmitClientEvent,
+  SubmitInternalEvent,
+  SubmitOperationalEvent,
+  SubmitMQE,
+} 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';
+import CallDiagnosticLatencies from './call-diagnostic/call-diagnostic-metrics-latencies';
+
+registerInternalPlugin('metrics', Metrics, {
+  config,
+});
+
+registerInternalPlugin('newMetrics', NewMetrics, {
+  config,
+});
+
+export {default, getOSNameInternal} from './metrics';
+
+export {
+  config,
+  CALL_DIAGNOSTIC_CONFIG,
+  NewMetrics,
+  Utils,
+  CallDiagnosticUtils,
+  CallDiagnosticLatencies,
+  CallDiagnosticMetrics,
+};
+export type {
+  ClientEvent,
+  ClientEventLeaveReason,
+  SubmitBehavioralEvent,
+  SubmitClientEvent,
+  SubmitInternalEvent,
+  SubmitMQE,
+  SubmitOperationalEvent,
+};

package/src/metrics.js

@@ -10,7 +10,6 @@ import {OS_NAME, OSMap, CLIENT_NAME} from './config';
 
 import Batcher from './batcher';
 import ClientMetricsBatcher from './client-metrics-batcher';
-import CallDiagnosticEventsBatcher from './call-diagnostic-events-batcher';
 
 const {getOSName, getOSVersion, getBrowserName, getBrowserVersion} = BrowserDetection();
 
@@ -38,7 +37,6 @@ const Metrics = WebexPlugin.extend({
   children: {
     batcher: Batcher,
     clientMetricsBatcher: ClientMetricsBatcher,
-    callDiagnosticEventsBatcher: CallDiagnosticEventsBatcher,
   },
 
   namespace: 'Metrics',
@@ -48,22 +46,24 @@ const Metrics = WebexPlugin.extend({
   },
 
   /**
-   * This corresponds to #sendSemiStructured() in the deprecated metrics handler
+   * Returns the payload for submitting client metrics.
    * @param {string} eventName
-   * @param {Object} props
-   * @param {string} preLoginId
-   * @returns {Object} HttpResponse object
+   * @param {any} props
+   * @returns {any} - the payload
    */
-  submitClientMetrics(eventName, props = {}, preLoginId) {
+  getClientMetricsPayload(eventName, props) {
     if (!eventName) {
       throw Error('Missing behavioral metric name. Please provide one');
     }
     const payload = {metricName: eventName};
+    // @ts-ignore
+    const providedClientVersion = this.webex.meetings?.config?.metrics?.clientVersion;
 
     payload.tags = {
       ...props.tags,
       browser: getBrowserName(),
       os: getOSNameInternal(),
+      appVersion: providedClientVersion,
 
       // Node does not like this so we need to check if it exists or not
       // eslint-disable-next-line no-undef
@@ -103,6 +103,19 @@ const Metrics = WebexPlugin.extend({
     // is impossible so unable to use Date.now()
     payload.timestamp = new Date().valueOf();
 
+    return payload;
+  },
+
+  /**
+   * This corresponds to #sendSemiStructured() in the deprecated metrics handler
+   * @param {string} eventName
+   * @param {Object} props
+   * @param {string} preLoginId
+   * @returns {Object} HttpResponse object
+   */
+  submitClientMetrics(eventName, props = {}, preLoginId) {
+    const payload = this.getClientMetricsPayload(eventName, props);
+
     if (preLoginId) {
       const _payload = {
         metrics: [payload],
@@ -151,15 +164,6 @@ const Metrics = WebexPlugin.extend({
       })
     );
   },
-
-  submitCallDiagnosticEvents(payload) {
-    const event = {
-      type: 'diagnostic-event',
-      eventPayload: payload,
-    };
-
-    return this.callDiagnosticEventsBatcher.request(event);
-  },
 });
 
 export default Metrics;

package/src/metrics.types.ts

@@ -0,0 +1,168 @@
+import {
+  ClientEvent as RawClientEvent,
+  Event as RawEvent,
+  MediaQualityEvent as RawMediaQualityEvent,
+} from '@webex/event-dictionary-ts';
+
+export type Event = Omit<RawEvent, 'event'> & {event: RawClientEvent | RawMediaQualityEvent};
+
+export type ClientEventError = NonNullable<RawClientEvent['errors']>[0];
+
+export type EnvironmentType = NonNullable<RawEvent['origin']['environment']>;
+
+export type NewEnvironmentType = NonNullable<RawEvent['origin']['newEnvironment']>;
+
+export type ClientLaunchMethodType = NonNullable<
+  RawEvent['origin']['clientInfo']
+>['clientLaunchMethod'];
+
+export type SubmitClientEventOptions = {
+  meetingId?: string;
+  mediaConnections?: any[];
+  rawError?: any;
+  correlationId?: string;
+  preLoginId?: string;
+  environment?: EnvironmentType;
+  newEnvironmentType?: NewEnvironmentType;
+  clientLaunchMethod?: ClientLaunchMethodType;
+  webexConferenceIdStr?: string;
+  globalMeetingId?: string;
+};
+
+export type SubmitMQEOptions = {
+  meetingId: string;
+  mediaConnections?: any[];
+  networkType?: Event['origin']['networkType'];
+  webexConferenceIdStr?: string;
+  globalMeetingId?: string;
+};
+
+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.client.meeting.click.joinbutton'
+    | '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';
+
+  payload?: never;
+  options?: never;
+};
+
+export interface ClientEvent {
+  name: RawClientEvent['name'];
+  payload?: RawClientEvent;
+  options?: SubmitClientEventOptions;
+}
+
+export interface BehavioralEvent {
+  // TODO: not implemented
+  name: 'host.meeting.participant.admitted' | 'sdk.media-flow.started';
+  payload?: never;
+  options?: never;
+}
+
+export interface OperationalEvent {
+  // TODO: not implemented
+  name: never;
+  payload?: never;
+  options?: never;
+}
+
+export interface FeatureEvent {
+  // TODO: not implemented
+  name: never;
+  payload?: never;
+  options?: never;
+}
+
+export interface MediaQualityEvent {
+  name: RawMediaQualityEvent['name'];
+  payload?: RawMediaQualityEvent;
+  options: SubmitMQEOptions;
+}
+
+export type RecursivePartial<T> = {
+  [P in keyof T]?: T[P] extends (infer U)[]
+    ? RecursivePartial<U>[]
+    : T[P] extends object
+    ? RecursivePartial<T[P]>
+    : T[P];
+};
+
+export type MetricEventNames =
+  | InternalEvent['name']
+  | ClientEvent['name']
+  | BehavioralEvent['name']
+  | OperationalEvent['name']
+  | FeatureEvent['name']
+  | MediaQualityEvent['name'];
+
+export type ClientInfo = NonNullable<RawEvent['origin']['clientInfo']>;
+export type ClientType = NonNullable<RawEvent['origin']['clientInfo']>['clientType'];
+export type SubClientType = NonNullable<RawEvent['origin']['clientInfo']>['subClientType'];
+export type NetworkType = NonNullable<RawEvent['origin']>['networkType'];
+
+export type ClientSubServiceType = ClientEvent['payload']['webexSubServiceType'];
+export type ClientEventPayload = RecursivePartial<ClientEvent['payload']>;
+export type ClientEventLeaveReason = ClientEvent['payload']['leaveReason'];
+export type ClientEventPayloadError = ClientEvent['payload']['errors'];
+
+export type MediaQualityEventAudioSetupDelayPayload = NonNullable<
+  MediaQualityEvent['payload']
+>['audioSetupDelay'];
+export type MediaQualityEventVideoSetupDelayPayload = NonNullable<
+  MediaQualityEvent['payload']
+>['videoSetupDelay'];
+
+export type SubmitMQEPayload = RecursivePartial<MediaQualityEvent['payload']> & {
+  intervals: NonNullable<MediaQualityEvent['payload']>['intervals'];
+};
+
+export type SubmitInternalEvent = (args: {
+  name: InternalEvent['name'];
+  payload?: RecursivePartial<InternalEvent['payload']>;
+  options?: any;
+}) => void;
+
+export type SubmitBehavioralEvent = (args: {
+  name: BehavioralEvent['name'];
+  payload?: RecursivePartial<BehavioralEvent['payload']>;
+  options?: any;
+}) => void;
+
+export type SubmitClientEvent = (args: {
+  name: ClientEvent['name'];
+  payload?: RecursivePartial<ClientEvent['payload']>;
+  options?: SubmitClientEventOptions;
+}) => Promise<any>;
+
+export type SubmitOperationalEvent = (args: {
+  name: OperationalEvent['name'];
+  payload?: RecursivePartial<OperationalEvent['payload']>;
+  options?: any;
+}) => void;
+
+export type SubmitMQE = (args: {
+  name: MediaQualityEvent['name'];
+  payload: SubmitMQEPayload;
+  options: any;
+}) => void;
+
+export type BuildClientEventFetchRequestOptions = (args: {
+  name: ClientEvent['name'];
+  payload?: RecursivePartial<ClientEvent['payload']>;
+  options?: SubmitClientEventOptions;
+}) => Promise<any>;
+
+export type PreComputedLatencies =
+  | 'internal.client.pageJMT'
+  | 'internal.download.time'
+  | 'internal.click.to.interstitial'
+  | 'internal.call.init.join.req';

package/src/new-metrics.ts

@@ -0,0 +1,278 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/* eslint-disable class-methods-use-this */
+/* eslint-disable valid-jsdoc */
+
+// @ts-ignore
+import {WebexPlugin} from '@webex/webex-core';
+
+import CallDiagnosticMetrics from './call-diagnostic/call-diagnostic-metrics';
+import {
+  RecursivePartial,
+  ClientEvent,
+  FeatureEvent,
+  BehavioralEvent,
+  OperationalEvent,
+  MediaQualityEvent,
+  InternalEvent,
+  SubmitClientEventOptions,
+} from './metrics.types';
+import CallDiagnosticLatencies from './call-diagnostic/call-diagnostic-metrics-latencies';
+import {setMetricTimings} from './call-diagnostic/call-diagnostic-metrics.util';
+import {generateCommonErrorMetadata} from './utils';
+
+/**
+ * Metrics plugin to centralize all types of metrics.
+ * @class
+ */
+class Metrics extends WebexPlugin {
+  // eslint-disable-next-line no-use-before-define
+  static instance: Metrics;
+
+  // Call Diagnostic latencies
+  callDiagnosticLatencies: CallDiagnosticLatencies;
+  // Helper classes to handle the different types of metrics
+  callDiagnosticMetrics: CallDiagnosticMetrics;
+
+  /**
+   * Constructor
+   * @param args
+   * @constructor
+   * @private
+   * @returns
+   */
+  constructor(...args) {
+    super(...args);
+
+    this.onReady();
+  }
+
+  /**
+   * On Ready
+   */
+  private onReady() {
+    // @ts-ignore
+    this.webex.once('ready', () => {
+      // @ts-ignore
+      this.callDiagnosticMetrics = new CallDiagnosticMetrics({}, {parent: this.webex});
+      // @ts-ignore
+      this.callDiagnosticLatencies = new CallDiagnosticLatencies({}, {parent: this.webex});
+    });
+  }
+
+  /**
+   * Used for internal purposes only
+   * @param args
+   */
+  submitInternalEvent({
+    name,
+    payload,
+    options,
+  }: {
+    name: InternalEvent['name'];
+    payload?: RecursivePartial<InternalEvent['payload']>;
+    options?: any;
+  }) {
+    if (name === 'internal.reset.join.latencies') {
+      this.callDiagnosticLatencies.clearTimestamps();
+    } else {
+      this.callDiagnosticLatencies.saveTimestamp({key: name});
+    }
+  }
+
+  /**
+   * Behavioral event
+   * @param args
+   */
+  submitBehavioralEvent({
+    name,
+    payload,
+    options,
+  }: {
+    name: BehavioralEvent['name'];
+    payload?: RecursivePartial<BehavioralEvent['payload']>;
+    options?: any;
+  }) {
+    this.callDiagnosticLatencies.saveTimestamp({key: name});
+    throw new Error('Not implemented.');
+  }
+
+  /**
+   * Operational event
+   * @param args
+   */
+  submitOperationalEvent({
+    name,
+    payload,
+    options,
+  }: {
+    name: OperationalEvent['name'];
+    payload?: RecursivePartial<OperationalEvent['payload']>;
+    options?: any;
+  }) {
+    throw new Error('Not implemented.');
+  }
+
+  /**
+   * Call Analyzer: Media Quality Event
+   * @param args
+   */
+  submitMQE({
+    name,
+    payload,
+    options,
+  }: {
+    name: MediaQualityEvent['name'];
+    payload: RecursivePartial<MediaQualityEvent['payload']> & {
+      intervals: MediaQualityEvent['payload']['intervals'];
+    };
+    options: any;
+  }) {
+    this.callDiagnosticLatencies.saveTimestamp({key: name});
+    this.callDiagnosticMetrics.submitMQE({name, payload, options});
+  }
+
+  /**
+   * Call Analyzer: Feature Usage Event
+   * @param args
+   */
+  submitFeatureEvent({
+    name,
+    payload,
+    options,
+  }: {
+    name: FeatureEvent['name'];
+    payload?: RecursivePartial<FeatureEvent['payload']>;
+    options: any;
+  }) {
+    throw new Error('Not implemented.');
+  }
+
+  /**
+   * Call Analyzer: Client Event
+   * @public
+   * @param args
+   */
+  public submitClientEvent({
+    name,
+    payload,
+    options,
+  }: {
+    name: ClientEvent['name'];
+    payload?: RecursivePartial<ClientEvent['payload']>;
+    options?: SubmitClientEventOptions;
+  }): Promise<any> {
+    if (!this.callDiagnosticLatencies || !this.callDiagnosticMetrics) {
+      // @ts-ignore
+      this.webex.logger.log(
+        `NewMetrics: @submitClientEvent. Attempted to submit before webex.ready. Event name: ${name}`
+      );
+
+      return Promise.resolve();
+    }
+    this.callDiagnosticLatencies.saveTimestamp({
+      key: name,
+      options: {meetingId: options?.meetingId},
+    });
+
+    return this.callDiagnosticMetrics.submitClientEvent({name, payload, options});
+  }
+
+  /**
+   * Issue request to alias a user's pre-login ID with their CI UUID
+   * @param {string} preLoginId
+   * @returns {Object} HttpResponse object
+   */
+  public clientMetricsAliasUser(preLoginId: string) {
+    // @ts-ignore
+    return this.webex
+      .request({
+        method: 'POST',
+        api: 'metrics',
+        resource: 'clientmetrics',
+        headers: {
+          'x-prelogin-userid': preLoginId,
+        },
+        body: {},
+        qs: {
+          alias: true,
+        },
+      })
+      .then((res) => {
+        // @ts-ignore
+        this.webex.logger.log(`NewMetrics: @clientMetricsAliasUser. Request successful.`);
+
+        return res;
+      })
+      .catch((err) => {
+        // @ts-ignore
+        this.logger.error(
+          `NewMetrics: @clientMetricsAliasUser. Request failed:`,
+          `err: ${generateCommonErrorMetadata(err)}`
+        );
+
+        return Promise.reject(err);
+      });
+  }
+
+  /**
+   * Returns a promise that will resolve to fetch options for submitting a metric.
+   *
+   * This is to support quickly submitting metrics when the browser/tab is closing.
+   * Calling submitClientEvent will not work because there some async steps that will
+   * not complete before the browser is closed.  Instead, we pre-gather all the
+   * information/options needed for the request(s), and then simply and quickly
+   * fire the fetch(es) when beforeUnload is triggered.
+   *
+   * We must use fetch instead of request because fetch has a keepalive option that
+   * allows the request it to outlive the page.
+   *
+   * Note: the timings values will be wrong, but setMetricTimingsAndFetch() will
+   * properly adjust them before submitting.
+   *
+   * @public
+   * @param {Object} arg
+   * @param {String} arg.name - event name
+   * @param {Object} arg.payload - event payload
+   * @param {Object} arg.options - other options
+   * @returns {Promise} promise that resolves to options to be used with fetch
+   */
+  public async buildClientEventFetchRequestOptions({
+    name,
+    payload,
+    options,
+  }: {
+    name: ClientEvent['name'];
+    payload?: RecursivePartial<ClientEvent['payload']>;
+    options?: SubmitClientEventOptions;
+  }): Promise<any> {
+    return this.callDiagnosticMetrics.buildClientEventFetchRequestOptions({
+      name,
+      payload,
+      options,
+    });
+  }
+
+  /**
+   * Submits a metric from pre-built request options via the fetch API. Updates
+   * the "$timings" and "originTime" values to Date.now() since the existing times
+   * were set when the options were built (not submitted).
+
+   * @param {any} options - the pre-built request options for submitting a metric
+   * @returns {Promise} promise that resolves to the response object
+   */
+  public setMetricTimingsAndFetch(options: any): Promise<any> {
+    // @ts-ignore
+    return this.webex.setTimingsAndFetch(setMetricTimings(options));
+  }
+
+  /**
+   * Returns true if the specified serviceErrorCode maps to an expected error.
+   * @param {number} serviceErrorCode the service error code
+   * @returns {boolean}
+   */
+  public isServiceErrorExpected(serviceErrorCode: number): boolean {
+    return this.callDiagnosticMetrics.isServiceErrorExpected(serviceErrorCode);
+  }
+}
+
+export default Metrics;

package/src/prelogin-metrics-batcher.ts

@@ -0,0 +1,95 @@
+import {uniqueId} from 'lodash';
+import Batcher from './batcher';
+import {prepareDiagnosticMetricItem} from './call-diagnostic/call-diagnostic-metrics.util';
+import {generateCommonErrorMetadata} from './utils';
+
+const PRE_LOGIN_METRICS_IDENTIFIER = 'Pre Login Metrics -->';
+
+const PreLoginMetricsBatcher = Batcher.extend({
+  namespace: 'Metrics',
+  preLoginId: undefined,
+
+  /**
+   * Save the pre-login ID.
+   * @param {string} preLoginId The pre-login ID to be saved.
+   * @returns {void}
+   */
+  savePreLoginId(preLoginId) {
+    this.preLoginId = preLoginId;
+  },
+
+  /**
+   * Prepare item
+   * @param {any} item
+   * @returns {Promise<any>}
+   */
+  prepareItem(item) {
+    return Promise.resolve(prepareDiagnosticMetricItem(this.webex, item));
+  },
+
+  /**
+   * Prepare request, add time sensitive date etc.
+   * @param {any[]} queue
+   * @returns {Promise<any[]>}
+   */
+  prepareRequest(queue) {
+    // Add sent timestamp
+    queue.forEach((item) => {
+      item.eventPayload.originTime = item.eventPayload.originTime || {};
+      item.eventPayload.originTime.sent = new Date().toISOString();
+    });
+
+    return Promise.resolve(queue);
+  },
+
+  /**
+   *
+   * @param {any} payload
+   * @returns {Promise<any>}
+   */
+  submitHttpRequest(payload: any) {
+    const batchId = uniqueId('prelogin-ca-batch-');
+    if (this.preLoginId === undefined) {
+      this.webex.logger.error(
+        PRE_LOGIN_METRICS_IDENTIFIER,
+        `PreLoginMetricsBatcher: @submitHttpRequest#${batchId}. PreLoginId is not set.`
+      );
+
+      return Promise.reject(new Error('PreLoginId is not set.'));
+    }
+
+    return this.webex
+      .request({
+        method: 'POST',
+        service: 'metrics',
+        resource: 'clientmetrics-prelogin',
+        headers: {
+          authorization: false,
+          'x-prelogin-userid': this.preLoginId,
+        },
+        body: {
+          metrics: payload,
+        },
+        waitForServiceTimeout: this.webex.config.metrics.waitForServiceTimeout,
+      })
+      .then((res) => {
+        this.webex.logger.log(
+          PRE_LOGIN_METRICS_IDENTIFIER,
+          `PreLoginMetricsBatcher: @submitHttpRequest#${batchId}. Request successful.`
+        );
+
+        return res;
+      })
+      .catch((err) => {
+        this.webex.logger.error(
+          PRE_LOGIN_METRICS_IDENTIFIER,
+          `PreLoginMetricsBatcher: @submitHttpRequest#${batchId}. Request failed:`,
+          `error: ${generateCommonErrorMetadata(err)}`
+        );
+
+        return Promise.reject(err);
+      });
+  },
+});
+
+export default PreLoginMetricsBatcher;

package/src/utils.ts

@@ -0,0 +1,17 @@
+/* eslint-disable import/prefer-default-export */
+/**
+ * Generates common metadata for errors
+ * @param {any} error
+ * @returns {object}
+ */
+export const generateCommonErrorMetadata = (error) => {
+  if (error instanceof Error) {
+    return JSON.stringify({
+      message: error?.message,
+      name: error?.name,
+      stack: error?.stack,
+    });
+  }
+
+  return error;
+};

package/test/unit/spec/batcher.js

@@ -37,6 +37,7 @@ describe('plugin-metrics', () => {
         return Promise.resolve({
           statusCode: 204,
           body: undefined,
+          waitForServiceTimeout: 30,
           options,
         });
       };
@@ -97,6 +98,7 @@ describe('plugin-metrics', () => {
             return Promise.resolve({
               statusCode: 204,
               body: undefined,
+              waitForServiceTimeout: 30,
               options,
             });
           });