@microsoft/applicationinsights-common 3.0.0-beta.2210-19 → 3.0.0-beta.2210-21

package/src/Interfaces/IThrottleMgr.ts

@@ -0,0 +1,109 @@
+import { IThrottleMsgKey } from "../Enums";
+
+/**
+ * Identifies limit number/percentage of items sent per time
+ * If both are provided, minimum number between the two will be used
+ */
+export interface IThrottleLimit {
+    /**
+     * Identifies sampling percentage of items per time
+     * The percentage is set to 4 decimal places, for example: 1 means 0.0001%
+     * Default: 100 (0.01%)
+     */
+    samplingRate?: number;
+
+    /**
+     * Identifies limit number of items per time
+     * Default: 1
+     */
+    maxSendNumber?: number;
+}
+
+/**
+ * Identifies frequency of items sent
+ * Default: send data on 28th every 3 month each year
+ */
+export interface IThrottleInterval {
+    /**
+     * Identifies month interval that items can be sent
+     * For example, if it is set to 2 and start date is in Jan, items will be sent out every two months (Jan, March, May etc.)
+     * Default: 3
+     */
+    monthInterval?: number;
+
+    /**
+     * Identifies days that items can be sent within a month
+     * Default: 28
+     */
+    dayInterval?: number;
+
+    /**
+     * Identifies max times items can be sent within a month
+     * Default: 1
+     */
+    maxTimesPerMonth?: number;
+}
+
+/**
+* Identifies basic config
+*/
+export interface IThrottleMgrConfig {
+    /**
+    * Identifies message key to be used for local storage key
+    */
+    msgKey: IThrottleMsgKey;
+
+    /**
+    * Identifies if throttle is disabled
+    * Default: false
+    */
+    disabled?: boolean;
+
+    /**
+    * Identifies limit number/percentage of items sent per time
+    */
+    limit?: IThrottleLimit;
+
+    /**
+    * Identifies frequency of items sent
+    * Default: send data on 28th every 3 month each year
+    */
+    interval?: IThrottleInterval;
+}
+
+/**
+* Identifies object for local storage
+*/
+export interface IThrottleLocalStorageObj {
+    /**
+    * Identifies start date
+    */
+    date: Date;
+
+    /**
+    * Identifies current count
+    */
+
+    count: number;
+
+    /**
+     * identifies previous triggered throttle date
+     */
+    preTriggerDate?: Date;
+}
+
+/**
+* Identifies throttle result
+*/
+export interface IThrottleResult {
+    /**
+    * Identifies if items are sent
+    */
+    isThrottled: boolean;
+
+    /**
+    * Identifies numbers of items are sent
+    * if isThrottled is false, it will be set to 0
+    */
+    throttleNum: number;
+}

package/src/ThrottleMgr.ts

@@ -0,0 +1,285 @@
+import {
+    IAppInsightsCore, IDiagnosticLogger, _eInternalMessageId, _throwInternal, arrForEach, eLoggingSeverity, isNotNullOrUndefined,
+    isNullOrUndefined, randomValue, safeGetLogger, strTrim
+} from "@microsoft/applicationinsights-core-js";
+import { IThrottleMsgKey } from "./Enums";
+import { IThrottleLocalStorageObj, IThrottleMgrConfig, IThrottleResult } from "./Interfaces/IThrottleMgr";
+import { utlCanUseLocalStorage, utlGetLocalStorage, utlSetLocalStorage } from "./StorageHelperFuncs";
+
+const THROTTLE_STORAGE_PREFIX = "appInsightsThrottle";
+
+interface SendMsgParameter {
+    msgID: _eInternalMessageId,
+    message: string,
+    severity?: eLoggingSeverity
+}
+
+export class ThrottleMgr {
+    public canThrottle: () => boolean;
+    public sendMessage: (msgID: _eInternalMessageId, message: string, severity?: eLoggingSeverity) => IThrottleResult | null;
+    public getConfig: () => IThrottleMgrConfig;
+    public isTriggered: () => boolean; // this function is to get previous triggered status
+    public isReady: () => boolean
+    public onReadyState: (isReady?: boolean) => boolean;
+    public flush: () => boolean;
+
+    constructor(throttleMgr?: IThrottleMgrConfig, core?: IAppInsightsCore, namePrefix?: string) {
+        let _self = this;
+        let _canUseLocalStorage: boolean;
+        let _logger: IDiagnosticLogger | null | undefined;
+        let _config: IThrottleMgrConfig;
+        let _localStorageName: string | null;
+        let _localStorageObj: IThrottleLocalStorageObj | null | undefined;
+        let _isTriggered: boolean; //_isTriggered is to make sure that we only trigger throttle once a day
+        let _namePrefix: string;
+        let _queue: Array<SendMsgParameter>;
+        let _isReady: boolean = false;
+
+        _initConfig();
+
+        _self.getConfig = (): IThrottleMgrConfig => {
+            return _config;
+        }
+
+        /**
+         * Check if it is the correct day to send message.
+         * If _isTriggered is true, even if canThrottle returns true, message will not be sent,
+         * because we only allow triggering sendMessage() once a day.
+         * @returns if the current date is the valid date to send message
+         */
+        _self.canThrottle = (): boolean => {
+            return _canThrottle(_config, _canUseLocalStorage, _localStorageObj);
+        }
+
+        /**
+         * Check if throttle is triggered on current day(UTC)
+         * if canThrottle returns false, isTriggered will return false
+         * @returns if throttle is triggered on current day(UTC)
+         */
+        _self.isTriggered = (): boolean => {
+            return _isTriggered;
+        }
+
+        /**
+         * Before isReady set to true, all message will be stored in queue.
+         * Message will only be sent out after isReady set to true.
+         * Initial and default value: false
+         * @returns isReady state
+         */
+        _self.isReady = (): boolean => {
+            return _isReady;
+        }
+
+        /**
+         * Flush all message in queue with isReady state set to true.
+         * @returns if message queue is flushed
+         */
+        _self.flush = (): boolean => {
+            try {
+                if (_isReady && _queue.length > 0) {
+                    arrForEach(_queue, (item: SendMsgParameter) => {
+                        _self.sendMessage(item.msgID, item.message, item.severity);
+                    });
+                    return true;
+                }
+            } catch(err) {
+                // eslint-disable-next-line no-empty
+            }
+            return false;
+        }
+
+        /**
+         * Set isReady State
+         * if isReady set to true, message queue will be flushed automatically.
+         * @param isReady isReady State
+         * @returns if message queue is flushed
+         */
+        _self.onReadyState = (isReady?: boolean): boolean => {
+            _isReady  = isNullOrUndefined(isReady)? true : isReady;
+            return _self.flush();
+        }
+       
+        _self.sendMessage = (msgID: _eInternalMessageId, message: string, severity?: eLoggingSeverity): IThrottleResult | null => {
+            if (_isReady) {
+                let isSampledIn = _canSampledIn();
+                if (!isSampledIn) {
+                    return;
+                }
+                let canThrottle = _canThrottle(_config, _canUseLocalStorage, _localStorageObj);
+                let throttled = false;
+                let number = 0;
+                try {
+                    if (canThrottle && !_isTriggered) {
+                        number =  Math.min(_config.limit.maxSendNumber, _localStorageObj.count + 1);
+                        _localStorageObj.count = 0;
+                        throttled = true;
+                        _isTriggered = true;
+                        _localStorageObj.preTriggerDate = new Date();
+                    } else {
+                        _isTriggered = canThrottle;
+                        _localStorageObj.count += 1;
+                    }
+                    _resetLocalStorage(_logger, _localStorageName, _localStorageObj);
+                    for (let i = 0; i < number; i++) {
+                        _sendMessage(msgID, _logger, message, severity);
+                    }
+                } catch(e) {
+                    // eslint-disable-next-line no-empty
+                }
+                return {
+                    isThrottled: throttled,
+                    throttleNum: number
+                } as IThrottleResult;
+            } else {
+                _queue.push({
+                    msgID: msgID,
+                    message: message,
+                    severity: severity
+                } as SendMsgParameter);
+            }
+            return null;
+        }
+        
+        function _initConfig() {
+            _canUseLocalStorage = utlCanUseLocalStorage();
+            _logger = safeGetLogger(core);
+            _isTriggered = false;
+            _namePrefix = isNotNullOrUndefined(namePrefix)? namePrefix : "";
+            _queue = [];
+            let configMgr = throttleMgr;
+            _config = {} as any;
+            _config.disabled = !!configMgr.disabled;
+            _config.msgKey = configMgr.msgKey;
+            // default: send data on 28th every 3 month each year
+            let interval = {
+                // dafault: sent every three months
+                monthInterval: configMgr.interval?.monthInterval || 3,
+                dayInterval : configMgr.interval?.dayInterval || 28,
+                maxTimesPerMonth: configMgr.interval?.maxTimesPerMonth || 1
+            };
+            _config.interval = interval;
+            let limit = {
+                samplingRate: configMgr.limit?.samplingRate || 100,
+                // dafault: every time sent only 1 event
+                maxSendNumber: configMgr.limit?.maxSendNumber || 1
+            };
+            _config.limit = limit;
+            _localStorageName = _getLocalStorageName(_config.msgKey, _namePrefix);
+            
+            if (_canUseLocalStorage && _localStorageName) {
+                _localStorageObj = _getLocalStorageObj(utlGetLocalStorage(_logger, _localStorageName), _logger, _localStorageName);
+            }
+            if (_localStorageObj) {
+                _isTriggered = _isTriggeredOnCurDate(_localStorageObj.preTriggerDate);
+            }
+        }
+
+        function _canThrottle(config: IThrottleMgrConfig, canUseLocalStorage: boolean, localStorageObj: IThrottleLocalStorageObj) {
+            if (!config.disabled && canUseLocalStorage && isNotNullOrUndefined(localStorageObj)) {
+                let curDate = _getThrottleDate();
+                let date = localStorageObj.date;
+                let interval = config.interval;
+                let monthExpand = (curDate.getUTCFullYear() - date.getUTCFullYear()) * 12 + curDate.getUTCMonth() - date.getUTCMonth();
+                let monthCheck = _checkInterval(interval.monthInterval, 0, monthExpand);
+                let dayCheck = _checkInterval(interval.dayInterval, 0, curDate.getUTCDate()) -1;
+                return monthCheck >= 0 && dayCheck >= 0 && dayCheck <= config.interval.maxTimesPerMonth;
+            }
+            return false;
+        }
+
+        function _getLocalStorageName(msgKey: IThrottleMsgKey, prefix?: string) {
+            let fix = isNotNullOrUndefined(prefix)? prefix : "";
+            if (msgKey) {
+                return THROTTLE_STORAGE_PREFIX + fix + "-" + msgKey;
+            }
+            return null;
+        }
+
+        // returns if throttle is triggered on current Date
+        function _isTriggeredOnCurDate(preTriggerDate?: Date) {
+            try {
+                if(preTriggerDate) {
+                    let curDate = new Date();
+                    return preTriggerDate.getUTCFullYear() === curDate.getUTCFullYear() &&
+                    preTriggerDate.getUTCMonth() === curDate.getUTCMonth() &&
+                    preTriggerDate.getUTCDate() === curDate.getUTCDate();
+                }
+            } catch (e) {
+                // eslint-disable-next-line no-empty
+            }
+            return false;
+        }
+
+        // transfer local storage string value to object that identifies start date, current count and preTriggerDate
+        function _getLocalStorageObj(value: string, logger: IDiagnosticLogger, storageName: string) {
+            try {
+                let storageObj = {
+                    date: _getThrottleDate(),
+                    count: 0
+                } as IThrottleLocalStorageObj;
+                if (value) {
+                    let obj = JSON.parse(value);
+                    return {
+                        date: _getThrottleDate(obj.date) || storageObj.date,
+                        count: obj.count || storageObj.count,
+                        preTriggerDate: obj.preTriggerDate? _getThrottleDate(obj.preTriggerDate) : undefined
+                    } as IThrottleLocalStorageObj;
+                } else {
+                    _resetLocalStorage(logger, storageName, storageObj);
+                    return storageObj;
+
+                }
+            } catch(e) {
+                // eslint-disable-next-line no-empty
+            }
+            return null;
+        }
+
+        // if datestr is not defined, current date will be returned
+        function _getThrottleDate(dateStr?: string) {
+            // if new Date() can't be created through the provided dateStr, null will be returned.
+            try {
+                if (dateStr) {
+                    let date = new Date(dateStr);
+                    //make sure it is a valid Date Object
+                    if (!isNaN(date.getDate())) {
+                        return date;
+                    }
+                } else {
+                    return new Date();
+                }
+                
+            } catch (e) {
+                // eslint-disable-next-line no-empty
+            }
+            return null;
+        }
+
+        function _resetLocalStorage(logger: IDiagnosticLogger, storageName: string, obj: IThrottleLocalStorageObj) {
+            try {
+                return utlSetLocalStorage(logger, storageName, strTrim(JSON.stringify(obj)));
+            } catch (e) {
+            //     // eslint-disable-next-line no-empty
+            }
+            return false;
+        }
+
+        function _checkInterval(interval: number, start: number, current: number) {
+            // count from start year
+            return  (current >= start) && (current - start) % interval == 0 ? Math.floor((current - start) / interval) + 1 : -1;
+        }
+        
+        function _sendMessage(msgID: _eInternalMessageId, logger: IDiagnosticLogger, message: string, severity?: eLoggingSeverity) {
+            _throwInternal(logger,
+                severity || eLoggingSeverity.CRITICAL,
+                msgID,
+                message);
+        }
+
+        // NOTE: config.limit.samplingRate is set to 4 decimal places,
+        // so config.limit.samplingRate = 1 means 0.0001%
+        function _canSampledIn() {
+            return randomValue(1000000) <= _config.limit.samplingRate;
+        }
+    }
+}

package/src/__DynamicConstants.ts

@@ -11,12 +11,20 @@
 // ###########################################################################################################################################
 
 export const _DYN_SPLIT = "split";  // Count: 6
-export const _DYN_LENGTH = "length";  // Count: 40
+export const _DYN_LENGTH = "length";  // Count: 41
 export const _DYN_TO_LOWER_CASE = "toLowerCase";  // Count: 6
 export const _DYN_INGESTIONENDPOINT = "ingestionendpoint";  // Count: 4
 export const _DYN_TO_STRING = "toString";  // Count: 12
 export const _DYN_REMOVE_ITEM = "removeItem";  // Count: 3
 export const _DYN_NAME = "name";  // Count: 11
+export const _DYN_MESSAGE = "message";  // Count: 10
+export const _DYN_COUNT = "count";  // Count: 8
+export const _DYN_PRE_TRIGGER_DATE = "preTriggerDate";  // Count: 4
+export const _DYN_DISABLED = "disabled";  // Count: 3
+export const _DYN_DATE = "date";  // Count: 5
+export const _DYN_GET_UTCDATE = "getUTCDate";  // Count: 3
+export const _DYN_MAX_TIMES_PER_MONTH = "maxTimesPerMonth";  // Count: 2
+export const _DYN_STRINGIFY = "stringify";  // Count: 4
 export const _DYN_PATHNAME = "pathname";  // Count: 4
 export const _DYN_CORRELATION_HEADER_E0 = "correlationHeaderExcludePatterns";  // Count: 2
 export const _DYN_EXTENSION_CONFIG = "extensionConfig";  // Count: 4
@@ -24,8 +32,6 @@ export const _DYN_EXCEPTIONS = "exceptions";  // Count: 6
 export const _DYN_PARSED_STACK = "parsedStack";  // Count: 11
 export const _DYN_PROPERTIES = "properties";  // Count: 9
 export const _DYN_MEASUREMENTS = "measurements";  // Count: 9
-export const _DYN_STRINGIFY = "stringify";  // Count: 3
-export const _DYN_MESSAGE = "message";  // Count: 8
 export const _DYN_SIZE_IN_BYTES = "sizeInBytes";  // Count: 11
 export const _DYN_TYPE_NAME = "typeName";  // Count: 11
 export const _DYN_SEVERITY_LEVEL = "severityLevel";  // Count: 5

package/src/applicationinsights-common.ts

@@ -5,6 +5,7 @@ export {
     correlationIdGetCorrelationContextValue, dateTimeUtilsNow, dateTimeUtilsDuration, isInternalApplicationInsightsEndpoint,
     createDistributedTraceContextFromTrace
 } from "./Util";
+export { ThrottleMgr } from "./ThrottleMgr";
 export { parseConnectionString, ConnectionStringParser } from "./ConnectionStringParser";
 export { FieldType } from "./Enums";
 export { IRequestHeaders, RequestHeaders, eRequestHeaders } from "./RequestResponseHeaders";
@@ -57,7 +58,8 @@ export { IPropertiesPlugin } from "./Interfaces/IPropertiesPlugin";
 export { IUser, IUserContext } from "./Interfaces/Context/IUser";
 export { ITelemetryTrace, ITraceState } from "./Interfaces/Context/ITelemetryTrace";
 export { IRequestContext } from "./Interfaces/IRequestContext";
-export { eDistributedTracingModes, DistributedTracingModes } from "./Enums";
+export { IThrottleLocalStorageObj, IThrottleMgrConfig, IThrottleResult, IThrottleLimit, IThrottleInterval } from "./Interfaces/IThrottleMgr";
+export { eDistributedTracingModes, DistributedTracingModes, IThrottleMsgKey } from "./Enums";
 export { stringToBoolOrDefault, msToTimeSpan, getExtensionByName, isCrossOriginError } from "./HelperFuncs";
 export {
     isBeaconsSupported as isBeaconApiSupported,

package/types/Enums.d.ts

@@ -33,3 +33,8 @@ export declare const enum eDistributedTracingModes {
 }
 export declare const DistributedTracingModes: import("@microsoft/applicationinsights-core-js").EnumValue<typeof eDistributedTracingModes>;
 export declare type DistributedTracingModes = number | eDistributedTracingModes;
+export declare const enum IThrottleMsgKey {
+    default = 0,
+    ikeyDeprecate = 1,
+    cdnDeprecate = 2
+}

package/types/Interfaces/IThrottleMgr.d.ts

@@ -0,0 +1,94 @@
+import { IThrottleMsgKey } from "../Enums";
+/**
+ * Identifies limit number/percentage of items sent per time
+ * If both are provided, minimum number between the two will be used
+ */
+export interface IThrottleLimit {
+    /**
+     * Identifies sampling percentage of items per time
+     * The percentage is set to 4 decimal places, for example: 1 means 0.0001%
+     * Default: 100 (0.01%)
+     */
+    samplingRate?: number;
+    /**
+     * Identifies limit number of items per time
+     * Default: 1
+     */
+    maxSendNumber?: number;
+}
+/**
+ * Identifies frequency of items sent
+ * Default: send data on 28th every 3 month each year
+ */
+export interface IThrottleInterval {
+    /**
+     * Identifies month interval that items can be sent
+     * For example, if it is set to 2 and start date is in Jan, items will be sent out every two months (Jan, March, May etc.)
+     * Default: 3
+     */
+    monthInterval?: number;
+    /**
+     * Identifies days that items can be sent within a month
+     * Default: 28
+     */
+    dayInterval?: number;
+    /**
+     * Identifies max times items can be sent within a month
+     * Default: 1
+     */
+    maxTimesPerMonth?: number;
+}
+/**
+* Identifies basic config
+*/
+export interface IThrottleMgrConfig {
+    /**
+    * Identifies message key to be used for local storage key
+    */
+    msgKey: IThrottleMsgKey;
+    /**
+    * Identifies if throttle is disabled
+    * Default: false
+    */
+    disabled?: boolean;
+    /**
+    * Identifies limit number/percentage of items sent per time
+    */
+    limit?: IThrottleLimit;
+    /**
+    * Identifies frequency of items sent
+    * Default: send data on 28th every 3 month each year
+    */
+    interval?: IThrottleInterval;
+}
+/**
+* Identifies object for local storage
+*/
+export interface IThrottleLocalStorageObj {
+    /**
+    * Identifies start date
+    */
+    date: Date;
+    /**
+    * Identifies current count
+    */
+    count: number;
+    /**
+     * identifies previous triggered throttle date
+     */
+    preTriggerDate?: Date;
+}
+/**
+* Identifies throttle result
+*/
+export interface IThrottleResult {
+    /**
+    * Identifies if items are sent
+    */
+    isThrottled: boolean;
+    /**
+    * Identifies numbers of items are sent
+    * if isThrottled is false, it will be set to 0
+    */
+    throttleNum: number;
+}

package/types/ThrottleMgr.d.ts

@@ -0,0 +1,12 @@
+import { IAppInsightsCore, _eInternalMessageId, eLoggingSeverity } from "@microsoft/applicationinsights-core-js";
+import { IThrottleMgrConfig, IThrottleResult } from "./Interfaces/IThrottleMgr";
+export declare class ThrottleMgr {
+    canThrottle: () => boolean;
+    sendMessage: (msgID: _eInternalMessageId, message: string, severity?: eLoggingSeverity) => IThrottleResult | null;
+    getConfig: () => IThrottleMgrConfig;
+    isTriggered: () => boolean;
+    isReady: () => boolean;
+    onReadyState: (isReady?: boolean) => boolean;
+    flush: () => boolean;
+    constructor(throttleMgr?: IThrottleMgrConfig, core?: IAppInsightsCore, namePrefix?: string);
+}

package/types/__DynamicConstants.d.ts

@@ -5,6 +5,14 @@ export declare const _DYN_INGESTIONENDPOINT = "ingestionendpoint";
 export declare const _DYN_TO_STRING = "toString";
 export declare const _DYN_REMOVE_ITEM = "removeItem";
 export declare const _DYN_NAME = "name";
+export declare const _DYN_MESSAGE = "message";
+export declare const _DYN_COUNT = "count";
+export declare const _DYN_PRE_TRIGGER_DATE = "preTriggerDate";
+export declare const _DYN_DISABLED = "disabled";
+export declare const _DYN_DATE = "date";
+export declare const _DYN_GET_UTCDATE = "getUTCDate";
+export declare const _DYN_MAX_TIMES_PER_MONTH = "maxTimesPerMonth";
+export declare const _DYN_STRINGIFY = "stringify";
 export declare const _DYN_PATHNAME = "pathname";
 export declare const _DYN_CORRELATION_HEADER_E0 = "correlationHeaderExcludePatterns";
 export declare const _DYN_EXTENSION_CONFIG = "extensionConfig";
@@ -12,8 +20,6 @@ export declare const _DYN_EXCEPTIONS = "exceptions";
 export declare const _DYN_PARSED_STACK = "parsedStack";
 export declare const _DYN_PROPERTIES = "properties";
 export declare const _DYN_MEASUREMENTS = "measurements";
-export declare const _DYN_STRINGIFY = "stringify";
-export declare const _DYN_MESSAGE = "message";
 export declare const _DYN_SIZE_IN_BYTES = "sizeInBytes";
 export declare const _DYN_TYPE_NAME = "typeName";
 export declare const _DYN_SEVERITY_LEVEL = "severityLevel";

package/types/applicationinsights-common.d.ts

@@ -1,4 +1,5 @@
 export { correlationIdSetPrefix, correlationIdGetPrefix, correlationIdCanIncludeCorrelationHeader, correlationIdGetCorrelationContext, correlationIdGetCorrelationContextValue, dateTimeUtilsNow, dateTimeUtilsDuration, isInternalApplicationInsightsEndpoint, createDistributedTraceContextFromTrace } from "./Util";
+export { ThrottleMgr } from "./ThrottleMgr";
 export { parseConnectionString, ConnectionStringParser } from "./ConnectionStringParser";
 export { FieldType } from "./Enums";
 export { IRequestHeaders, RequestHeaders, eRequestHeaders } from "./RequestResponseHeaders";
@@ -46,7 +47,8 @@ export { IPropertiesPlugin } from "./Interfaces/IPropertiesPlugin";
 export { IUser, IUserContext } from "./Interfaces/Context/IUser";
 export { ITelemetryTrace, ITraceState } from "./Interfaces/Context/ITelemetryTrace";
 export { IRequestContext } from "./Interfaces/IRequestContext";
-export { eDistributedTracingModes, DistributedTracingModes } from "./Enums";
+export { IThrottleLocalStorageObj, IThrottleMgrConfig, IThrottleResult, IThrottleLimit, IThrottleInterval } from "./Interfaces/IThrottleMgr";
+export { eDistributedTracingModes, DistributedTracingModes, IThrottleMsgKey } from "./Enums";
 export { stringToBoolOrDefault, msToTimeSpan, getExtensionByName, isCrossOriginError } from "./HelperFuncs";
 export { isBeaconsSupported as isBeaconApiSupported, ITraceParent, createTraceParent, parseTraceParent, isValidTraceId, isValidSpanId, isValidTraceParent, isSampledFlag, formatTraceParent, findW3cTraceParent } from "@microsoft/applicationinsights-core-js";
 export { createDomEvent } from "./DomHelperFuncs";