@microsoft/applicationinsights-core-js 2.8.0-beta.2203-02 → 2.8.0-beta.2203-05

package/src/JavaScriptSDK/BaseCore.ts

@@ -12,27 +12,36 @@ import { ITelemetryItem } from "../JavaScriptSDK.Interfaces/ITelemetryItem";
 import { INotificationManager } from "../JavaScriptSDK.Interfaces/INotificationManager";
 import { INotificationListener } from "../JavaScriptSDK.Interfaces/INotificationListener";
 import { IDiagnosticLogger } from "../JavaScriptSDK.Interfaces/IDiagnosticLogger";
-import { IProcessTelemetryContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
-import { createProcessTelemetryContext, createTelemetryProxyChain } from "./ProcessTelemetryContext";
+import { IProcessTelemetryContext, IProcessTelemetryUpdateContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
+import { createProcessTelemetryContext, createProcessTelemetryUnloadContext, createProcessTelemetryUpdateContext, createTelemetryProxyChain } from "./ProcessTelemetryContext";
 import { initializePlugins, sortPlugins, _getPluginState } from "./TelemetryHelpers";
-import { eLoggingSeverity } from "../JavaScriptSDK.Enums/LoggingEnums";
+import { eLoggingSeverity, _eInternalMessageId } from "../JavaScriptSDK.Enums/LoggingEnums";
 import { IPerfManager } from "../JavaScriptSDK.Interfaces/IPerfManager";
 import { getGblPerfMgr, PerfManager } from "./PerfManager";
 import { ICookieMgr } from "../JavaScriptSDK.Interfaces/ICookieMgr";
 import { createCookieMgr } from "./CookieMgr";
-import { arrForEach, isNullOrUndefined, toISOString, getSetValue, setValue, throwError, isNotTruthy, isFunction, objFreeze, proxyFunctions } from "./HelperFuncs";
+import { arrForEach, isNullOrUndefined, toISOString, getSetValue, setValue, throwError, isNotTruthy, isFunction, objFreeze, proxyFunctionAs, proxyFunctions } from "./HelperFuncs";
 import { strExtensionConfig, strIKey } from "./Constants";
-import { DiagnosticLogger, _InternalLogMessage } from "./DiagnosticLogger";
+import { DiagnosticLogger, _InternalLogMessage, _throwInternal } from "./DiagnosticLogger";
 import { getDebugListener } from "./DbgExtensionUtils";
 import { ITelemetryPluginChain } from "../JavaScriptSDK.Interfaces/ITelemetryPluginChain";
 import { ChannelControllerPriority, createChannelControllerPlugin, createChannelQueues, IChannelController, IInternalChannelController, _IInternalChannels } from "./ChannelController";
 import { ITelemetryInitializerHandler, TelemetryInitializerFunction } from "../JavaScriptSDK.Interfaces/ITelemetryInitializers";
 import { TelemetryInitializerPlugin } from "./TelemetryInitializerPlugin";
 import { createUniqueNamespace } from "./DataCacheHelper";
+import { createUnloadHandlerContainer, IUnloadHandlerContainer, UnloadHandler } from "./UnloadHandlerContainer";
+import { TelemetryUpdateReason } from "../JavaScriptSDK.Enums/TelemetryUpdateReason";
+import { ITelemetryUpdateState } from "../JavaScriptSDK.Interfaces/ITelemetryUpdateState";
+import { ITelemetryUnloadState } from "../JavaScriptSDK.Interfaces/ITelemetryUnloadState";
+import { TelemetryUnloadReason } from "../JavaScriptSDK.Enums/TelemetryUnloadReason";
+import { SendRequestReason } from "../JavaScriptSDK.Enums/SendRequestReason";
 import { strAddNotificationListener, strDisabled, strEventsDiscarded, strEventsSendRequest, strEventsSent, strRemoveNotificationListener, strTeardown } from "./InternalConstants";
 
 const strValidationError = "Plugins must provide initialize method";
 const strNotificationManager = "_notificationManager";
+const strSdkUnloadingError = "SDK is still unloading...";
+const strSdkNotInitialized = "SDK is not initialized";
+const strPluginUnloadFailed = "Failed to unload plugin";
 
 /**
  * Helper to create the default performance manager
@@ -82,6 +91,19 @@ function _validateExtensions(logger: IDiagnosticLogger, channelPriority: number,
     };
 }
 
+function _isPluginPresent(thePlugin: IPlugin, plugins: IPlugin[]) {
+    let exists = false;
+
+    arrForEach(plugins, (plugin) => {
+        if (plugin === thePlugin) {
+            exists = true;
+            return -1;
+        }
+    });
+
+    return exists;
+}
+
 function _createDummyNotificationManager(): INotificationManager {
     return objCreateFn({
         [strAddNotificationListener]: (listener: INotificationListener) => { },
@@ -114,9 +136,11 @@ export class BaseCore implements IAppInsightsCore {
         let _channelControl: IChannelController;
         let _channelConfig: IChannelControls[][];
         let _channelQueue: _IInternalChannels[];
+        let _isUnloading: boolean;
         let _telemetryInitializerPlugin: TelemetryInitializerPlugin;
         let _internalLogsEventName: string;
         let _evtNamespace: string;
+        let _unloadHandlers: IUnloadHandlerContainer;
         let _debugListener: INotificationListener;
 
         /**
@@ -132,6 +156,10 @@ export class BaseCore implements IAppInsightsCore {
             _self.isInitialized = () => _isInitialized;
 
             _self.initialize = (config: IConfiguration, extensions: IPlugin[], logger?: IDiagnosticLogger, notificationManager?: INotificationManager): void => {
+                if (_isUnloading) {
+                    throwError(strSdkUnloadingError);
+                }
+        
                 // Make sure core is only initialized once
                 if (_self.isInitialized()) {
                     throwError("Core should not be initialized more than once");
@@ -153,8 +181,7 @@ export class BaseCore implements IAppInsightsCore {
                 config.extensions = isNullOrUndefined(config.extensions) ? [] : config.extensions;
         
                 // add notification to the extensions in the config so other plugins can access it
-                let extConfig = getSetValue(config, strExtensionConfig);
-                extConfig.NotificationManager = notificationManager;
+                _initExtConfig(config);
 
                 if (logger) {
                     _self.logger = logger;
@@ -165,7 +192,7 @@ export class BaseCore implements IAppInsightsCore {
                 _configExtensions.push(...extensions, ...config.extensions);
                 _channelConfig = (config||{}).channels;
 
-                _initPluginChain(config);
+                _initPluginChain(config, null);
 
                 if (_self.getTransmissionControls().length === 0) {
                     throwError("No channels available");
@@ -194,7 +221,7 @@ export class BaseCore implements IAppInsightsCore {
                 // Common Schema 4.0
                 setValue(telemetryItem, "ver", "4.0", null, isNullOrUndefined);
         
-                if (_self.isInitialized()) {
+                if (!_isUnloading && _self.isInitialized()) {
                     // Process the telemetry plugin chain
                     _createTelCtx().processNext(telemetryItem);
                 } else {
@@ -223,9 +250,9 @@ export class BaseCore implements IAppInsightsCore {
              * called.
              * @param {INotificationListener} listener - An INotificationListener object.
              */
-             _self.addNotificationListener = (listener: INotificationListener): void => {
+             _self[strAddNotificationListener] = (listener: INotificationListener): void => {
                  if (_notificationManager) {
-                     _notificationManager.addNotificationListener(listener);
+                     _notificationManager[strAddNotificationListener](listener);
                  }
             };
         
@@ -233,9 +260,9 @@ export class BaseCore implements IAppInsightsCore {
              * Removes all instances of the listener.
              * @param {INotificationListener} listener - INotificationListener to remove.
              */
-            _self.removeNotificationListener = (listener: INotificationListener): void => {
+            _self[strRemoveNotificationListener] = (listener: INotificationListener): void => {
                 if (_notificationManager) {
-                    _notificationManager.removeNotificationListener(listener);
+                    _notificationManager[strRemoveNotificationListener](listener);
                 }
             }
         
@@ -314,12 +341,110 @@ export class BaseCore implements IAppInsightsCore {
             // Add addTelemetryInitializer
             proxyFunctions(_self, () => _telemetryInitializerPlugin, [ "addTelemetryInitializer" ]);
 
+            _self.unload = (isAsync: boolean = true, unloadComplete?: (unloadState: ITelemetryUnloadState) => void, cbTimeout?: number): void => {
+                if (!_isInitialized) {
+                    // The SDK is not initialized
+                    throwError(strSdkNotInitialized);
+                }
+
+                // Check if the SDK still unloading so throw
+                if (_isUnloading) {
+                    // The SDK is already unloading
+                    throwError(strSdkUnloadingError);
+                }
+
+                let unloadState: ITelemetryUnloadState = {
+                    reason: TelemetryUnloadReason.SdkUnload,
+                    isAsync: isAsync,
+                    flushComplete: false
+                }
+
+                let processUnloadCtx = createProcessTelemetryUnloadContext(_getPluginChain(), _self.config, _self);
+                processUnloadCtx.onComplete(() => {
+                    _initDefaults();
+                    unloadComplete && unloadComplete(unloadState);
+                }, _self);
+
+                function _doUnload(flushComplete: boolean) {
+                    unloadState.flushComplete = flushComplete;
+                    _isUnloading = true;
+
+                    // Run all of the unload handlers first (before unloading the plugins)
+                    _unloadHandlers.run(processUnloadCtx, unloadState);
+                    
+                    // Stop polling the internal logs
+                    _self.stopPollingInternalLogs();
+
+                    // Start unloading the components, from this point onwards the SDK should be considered to be in an unstable state
+                    processUnloadCtx.processNext(unloadState);
+                }
+
+                if (_channelControl) {
+                    _channelControl.flush(isAsync, _doUnload, SendRequestReason.SdkUnload, cbTimeout);
+                } else {
+                    _doUnload(true);
+                }
+            };
+
             _self.getPlugin = _getPlugin;
 
+            _self.addPlugin = <T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting: boolean, isAsync: boolean = true, addCb?: (added?: boolean) => void): void => {
+                if (!plugin) {
+                    addCb && addCb(false);
+                    _logOrThrowError(strValidationError);
+                    return;
+                }
+
+                let existingPlugin = _getPlugin(plugin.identifier);
+                if (existingPlugin && !replaceExisting) {
+                    addCb && addCb(false);
+
+                    _logOrThrowError("Plugin [" + plugin.identifier + "] is already loaded!");
+                    return;
+                }
+
+                let updateState: ITelemetryUpdateState = {
+                    reason: TelemetryUpdateReason.PluginAdded
+                };
+
+                function _addPlugin(removed: boolean) {
+                    _configExtensions.push(plugin);
+                    updateState.added = [plugin];
+
+                    // Re-Initialize the plugin chain
+                    _initPluginChain(_self.config, updateState);
+                    addCb && addCb(true);
+                }
+
+                if (existingPlugin) {
+                    let removedPlugins: IPlugin[] = [existingPlugin.plugin];
+                    let unloadState: ITelemetryUnloadState = {
+                        reason: TelemetryUnloadReason.PluginReplace,
+                        isAsync: isAsync
+                    };
+
+                    _removePlugins(removedPlugins, unloadState, (removed) => {
+                        if (!removed) {
+                            // Previous plugin was successfully removed or was not installed
+                            addCb && addCb(false);
+                        } else {
+                            updateState.removed = removedPlugins
+                            updateState.reason |= TelemetryUpdateReason.PluginRemoved;
+                            _addPlugin(true);
+                        }
+                    });
+                } else {
+                    _addPlugin(false);
+                }
+            };
+
             _self.evtNamespace = (): string => {
                 return _evtNamespace;
             };
 
+            // Create the addUnloadCb
+            proxyFunctionAs(_self, "addUnloadCb", () => _unloadHandlers, "add");
+
             function _initDefaults() {
                 _isInitialized = false;
 
@@ -340,8 +465,10 @@ export class BaseCore implements IAppInsightsCore {
                 _channelControl = null;
                 _channelConfig = null;
                 _channelQueue = null;
+                _isUnloading = false;
                 _internalLogsEventName = null;
                 _evtNamespace = createUniqueNamespace("AIBaseCore", true);
+                _unloadHandlers = createUnloadHandlerContainer();
             }
 
             function _createTelCtx(): IProcessTelemetryContext {
@@ -349,7 +476,7 @@ export class BaseCore implements IAppInsightsCore {
             }
 
             // Initialize or Re-initialize the plugins
-            function _initPluginChain(config: IConfiguration) {
+            function _initPluginChain(config: IConfiguration, updateState: ITelemetryUpdateState) {
                 // Extension validation
                 let theExtensions = _validateExtensions(_self.logger, ChannelControllerPriority, _configExtensions);
             
@@ -395,6 +522,10 @@ export class BaseCore implements IAppInsightsCore {
 
                 // Now reset the extensions to just those being managed by Basecore
                 _self._extensions = objFreeze(sortPlugins(_coreExtensions || [])).slice();
+
+                if (updateState) {
+                    _doUpdate(updateState);
+                }
             }
 
             function _getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T> {
@@ -422,6 +553,25 @@ export class BaseCore implements IAppInsightsCore {
                         isEnabled: () => {
                             let pluginState = _getPluginState(thePlugin);
                             return !pluginState[strTeardown] && !pluginState[strDisabled];
+                        },
+                        remove: (isAsync: boolean = true, removeCb?: (removed?: boolean) => void): void => {
+                            let pluginsToRemove: IPlugin[] = [thePlugin];
+                            let unloadState: ITelemetryUnloadState = {
+                                reason: TelemetryUnloadReason.PluginUnload,
+                                isAsync: isAsync
+                            };
+
+                            _removePlugins(pluginsToRemove, unloadState, (removed) => {
+                                if (removed) {
+                                    // Re-Initialize the plugin chain
+                                    _initPluginChain(_self.config, {
+                                        reason: TelemetryUpdateReason.PluginRemoved,
+                                        removed: pluginsToRemove
+                                    });
+                                }
+
+                                removeCb && removeCb(removed);
+                            });
                         }
                     }
                 }
@@ -445,6 +595,55 @@ export class BaseCore implements IAppInsightsCore {
                 return _pluginChain;
             }
 
+            function _removePlugins(thePlugins: IPlugin[], unloadState: ITelemetryUnloadState, removeComplete: (removed: boolean) => void) {
+
+                if (thePlugins && thePlugins.length > 0) {
+                    let unloadChain = createTelemetryProxyChain(thePlugins, _self.config, _self);
+                    let unloadCtx = createProcessTelemetryUnloadContext(unloadChain, _self.config, _self);
+
+                    unloadCtx.onComplete(() => {
+                        let removed = false;
+
+                        // Remove the listed config extensions
+                        let newConfigExtensions: IPlugin[] = [];
+                        arrForEach(_configExtensions, (plugin, idx) => {
+                            if (!_isPluginPresent(plugin, thePlugins)) {
+                                newConfigExtensions.push(plugin);
+                            } else {
+                                removed = true;
+                            }
+                        });
+
+                        _configExtensions = newConfigExtensions;
+
+                        // Re-Create the channel config
+                        let newChannelConfig: IChannelControls[][] = [];
+                        if (_channelConfig) {
+                            arrForEach(_channelConfig, (queue, idx) => {
+                                let newQueue: IChannelControls[] = [];
+                                arrForEach(queue, (channel) => {
+                                    if (!_isPluginPresent(channel, thePlugins)) {
+                                        newQueue.push(channel);
+                                    } else {
+                                        removed = true;
+                                    }
+                                });
+
+                                newChannelConfig.push(newQueue);
+                            });
+
+                            _channelConfig = newChannelConfig;
+                        }
+
+                        removeComplete && removeComplete(removed);
+                    });
+
+                    unloadCtx.processNext(unloadState);
+                } else {
+                    removeComplete(false);
+                }
+            }
+
             function _flushInternalLogs() {
                 let queue: _InternalLogMessage[] = _self.logger ? _self.logger.queue : [];
                 if (queue) {
@@ -488,6 +687,29 @@ export class BaseCore implements IAppInsightsCore {
                     setValue(_self.config, "createPerfMgr", _createPerfManager);
                 }
             }
+
+            function _initExtConfig(config: IConfiguration) {
+                let extConfig = getSetValue(config, strExtensionConfig);
+                extConfig.NotificationManager = _notificationManager;
+            }
+
+            function _doUpdate(updateState: ITelemetryUpdateState): void {
+                let updateCtx = createProcessTelemetryUpdateContext(_getPluginChain(), _self.config, _self);
+
+                if (!_self._updateHook || _self._updateHook(updateCtx, updateState) !== true) {
+                    updateCtx.processNext(updateState);
+                }
+            }
+
+            function _logOrThrowError(message: string) {
+                let logger = _self.logger;
+                if (logger) {
+                    // there should always be a logger
+                    _throwInternal(logger, eLoggingSeverity.WARNING, _eInternalMessageId.PluginException, message);
+                } else {
+                    throwError(message);
+                }
+            }
         });
     }
 
@@ -586,11 +808,28 @@ export class BaseCore implements IAppInsightsCore {
         // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
     }
 
+    /**
+     * Unload and Tear down the SDK and any initialized plugins, after calling this the SDK will be considered
+     * to be un-initialized and non-operational, re-initializing the SDK should only be attempted if the previous
+     * unload call return `true` stating that all plugins reported that they also unloaded, the recommended
+     * approach is to create a new instance and initialize that instance.
+     * This is due to possible unexpected side effects caused by plugins not supporting unload / teardown, unable
+     * to successfully remove any global references or they may just be completing the unload process asynchronously.
+     */
+    public unload(isAsync?: boolean, unloadComplete?: (unloadState: ITelemetryUnloadState) => void, cbTimeout?: number): void {
+        // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
+        return null;
+    }
+
     public getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T> {
         // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
         return null;
     }
 
+    public addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting: boolean, doAsync: boolean, addCb?: (added?: boolean) => void): void {
+        // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
+    }
+
     /**
      * Returns the unique event namespace that should be used
      */
@@ -599,7 +838,26 @@ export class BaseCore implements IAppInsightsCore {
         return null;
     }
 
+    /**
+     * Add an unload handler that will be called when the SDK is being unloaded
+     * @param handler - the handler
+     */
+    public addUnloadCb(handler: UnloadHandler): void {
+        // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
+    }
+
     protected releaseQueue() {
         // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
     }
+
+    /**
+     * Hook for Core extensions to allow them to update their own configuration before updating all of the plugins.
+     * @param updateCtx - The plugin update context
+     * @param updateState - The Update State
+     * @returns boolean - True means the extension class will call updateState otherwise the Core will
+     */
+    protected _updateHook?(updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState): void | boolean {
+        // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
+        return false;
+    }
 }

package/src/JavaScriptSDK/BaseTelemetryPlugin.ts

@@ -9,14 +9,17 @@ import { IConfiguration } from "../JavaScriptSDK.Interfaces/IConfiguration";
 import { IDiagnosticLogger } from "../JavaScriptSDK.Interfaces/IDiagnosticLogger";
 import { IPlugin, ITelemetryPlugin } from "../JavaScriptSDK.Interfaces/ITelemetryPlugin";
 import { ITelemetryItem } from "../JavaScriptSDK.Interfaces/ITelemetryItem";
-import { IProcessTelemetryContext, IProcessTelemetryUnloadContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
+import { IProcessTelemetryContext, IProcessTelemetryUnloadContext, IProcessTelemetryUpdateContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
 import { ITelemetryPluginChain } from "../JavaScriptSDK.Interfaces/ITelemetryPluginChain";
-import { createProcessTelemetryContext, createProcessTelemetryUnloadContext } from "./ProcessTelemetryContext";
-import { arrForEach, isArray, isFunction, isNullOrUndefined, setValue } from "./HelperFuncs";
+import { createProcessTelemetryContext, createProcessTelemetryUnloadContext, createProcessTelemetryUpdateContext } from "./ProcessTelemetryContext";
+import { arrForEach, isArray, isFunction, isNullOrUndefined, proxyFunctionAs, setValue } from "./HelperFuncs";
 import { strExtensionConfig } from "./Constants";
+import { createUnloadHandlerContainer, IUnloadHandlerContainer, UnloadHandler } from "./UnloadHandlerContainer";
 import { IInstrumentHook } from "../JavaScriptSDK.Interfaces/IInstrumentHooks";
 import { ITelemetryUnloadState } from "../JavaScriptSDK.Interfaces/ITelemetryUnloadState";
 import { TelemetryUnloadReason } from "../JavaScriptSDK.Enums/TelemetryUnloadReason";
+import { ITelemetryUpdateState } from "../JavaScriptSDK.Interfaces/ITelemetryUpdateState";
+import { TelemetryUpdateReason } from "../JavaScriptSDK.Enums/TelemetryUpdateReason";
 import { strDoTeardown, strIsInitialized, strSetNextPlugin } from "./InternalConstants";
 
 let strGetPlugin = "getPlugin";
@@ -86,6 +89,15 @@ export abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
      */
     protected _doTeardown?: (unloadCtx?: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState, asyncCallback?: () => void) => void | boolean;
 
+    /**
+     * Extension hook to allow implementations to perform some additional update operations before the BaseTelemetryPlugin finishes it's removal
+     * @param updateCtx - This is the context that should be used during updating.
+     * @param updateState - The details / state of the update process, it holds details like the current and previous configuration.
+     * @param asyncCallback - An optional callback that the plugin must call if it returns true to inform the caller that it has completed any async update operations.
+     * @returns boolean - true if the plugin has or will call asyncCallback, this allows the plugin to perform any asynchronous operations.
+     */
+    protected _doUpdate?: (updateCtx?: IProcessTelemetryUpdateContext, updateState?: ITelemetryUpdateState, asyncCallback?: () => void) => void | boolean;
+
     constructor() {
         let _self = this;           // Setting _self here as it's used outside of the dynamicProto as well
 
@@ -93,6 +105,7 @@ export abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
         let _isinitialized: boolean;
         let _rootCtx: IProcessTelemetryContext; // Used as the root context, holding the current config and initialized core
         let _nextPlugin: ITelemetryPlugin | ITelemetryPluginChain; // Used for backward compatibility where plugins don't call the main pipeline
+        let _unloadHandlerContainer: IUnloadHandlerContainer;
         let _hooks: IInstrumentHook[];
 
         _initDefaults();
@@ -120,11 +133,12 @@ export abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
                     isAsync: false
                 };
 
-
                 function _unloadCallback() {
                     if (!unloadDone) {
                         unloadDone = true;
 
+                        _unloadHandlerContainer.run(theUnloadCtx, unloadState);
+
                         // Remove all instrumentation hooks
                         arrForEach(_hooks, (fn) => {
                             fn.rm();
@@ -148,6 +162,37 @@ export abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
 
                 return result;
             };
+
+            _self.update = (updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState) => {
+                // If this plugin has already been torn down (not operational) or is not initialized (core is not set)
+                // or the core being used for unload was not the same core used for initialization.
+                if (!_self.core || (updateCtx && _self.core !== updateCtx.core())) {
+                    // Do Nothing
+                    return;
+                }
+
+                let result: void | boolean;
+                let updateDone = false;
+                let theUpdateCtx = updateCtx || createProcessTelemetryUpdateContext(null, {}, _self.core, _nextPlugin && _nextPlugin[strGetPlugin] ? _nextPlugin[strGetPlugin]() : _nextPlugin);
+                let theUpdateState: ITelemetryUpdateState = updateState || {
+                    reason: TelemetryUpdateReason.Unknown
+                };
+
+                function _updateCallback() {
+                    if (!updateDone) {
+                        updateDone = true;
+                        _setDefaults(theUpdateCtx.getCfg(), theUpdateCtx.core(), theUpdateCtx.getNext());
+                    }
+                }
+
+                if (!_self._doUpdate || _self._doUpdate(theUpdateCtx, theUpdateState, _updateCallback) !== true) {
+                    _updateCallback();
+                } else {
+                    result = true;
+                }
+
+                return result;
+            };
         
             _self._addHook = (hooks: IInstrumentHook | IInstrumentHook[]) => {
                 if (hooks) {
@@ -158,6 +203,8 @@ export abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
                     }
                 }
             };
+
+            proxyFunctionAs(_self, "_addUnloadCb", () => _unloadHandlerContainer, "add");
         });
 
         // These are added after the dynamicProto so that are not moved to the prototype
@@ -240,6 +287,7 @@ export abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
             _rootCtx = null;
             _nextPlugin = null;
             _hooks = [];
+            _unloadHandlerContainer = createUnloadHandlerContainer();
         }
     }
 
@@ -262,6 +310,24 @@ export abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
 
     public abstract processTelemetry(env: ITelemetryItem, itemCtx?: IProcessTelemetryContext): void;
 
+    /**
+     * The the plugin should re-evaluate configuration and update any cached configuration settings.
+     * @param updateCtx - This is the context that should be used during updating.
+     * @param updateState - The details / state of the update process, it holds details like the current and previous configuration.
+     * @returns boolean - true if the plugin has or will call updateCtx.processNext(), this allows the plugin to perform any asynchronous operations.
+     */
+    public update(updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState): void | boolean{
+        // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
+    }
+
+    /**
+     * Add an unload handler that will be called when the SDK is being unloaded
+     * @param handler - the handler
+     */
+    protected _addUnloadCb(handler: UnloadHandler): void {
+        // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
+    }
+
     /**
      * Add this hook so that it is automatically removed during unloading
      * @param hooks - The single hook or an array of IInstrumentHook objects

package/src/JavaScriptSDK/ChannelController.ts

@@ -3,14 +3,16 @@
 
 import { SendRequestReason } from "../JavaScriptSDK.Enums/SendRequestReason";
 import { TelemetryUnloadReason } from "../JavaScriptSDK.Enums/TelemetryUnloadReason";
+import { TelemetryUpdateReason } from "../JavaScriptSDK.Enums/TelemetryUpdateReason";
 import { IAppInsightsCore } from "../JavaScriptSDK.Interfaces/IAppInsightsCore";
 import { IChannelControls } from "../JavaScriptSDK.Interfaces/IChannelControls";
 import { IConfiguration } from "../JavaScriptSDK.Interfaces/IConfiguration";
-import { IBaseProcessingContext, IProcessTelemetryContext, IProcessTelemetryUnloadContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
+import { IBaseProcessingContext, IProcessTelemetryContext, IProcessTelemetryUnloadContext, IProcessTelemetryUpdateContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
 import { ITelemetryItem } from "../JavaScriptSDK.Interfaces/ITelemetryItem";
 import { IPlugin } from "../JavaScriptSDK.Interfaces/ITelemetryPlugin";
 import { ITelemetryPluginChain } from "../JavaScriptSDK.Interfaces/ITelemetryPluginChain";
 import { ITelemetryUnloadState } from "../JavaScriptSDK.Interfaces/ITelemetryUnloadState";
+import { ITelemetryUpdateState } from "../JavaScriptSDK.Interfaces/ITelemetryUpdateState";
 import { arrForEach, isArray, objFreeze, throwError } from "./HelperFuncs";
 import { strPause, strProcessNext, strResume, strTeardown } from "./InternalConstants";
 import { createProcessTelemetryContext, createTelemetryProxyChain } from "./ProcessTelemetryContext";
@@ -90,6 +92,20 @@ export function createChannelControllerPlugin(channelQueue: _IInternalChannels[]
         _runChainOnComplete();
     }
 
+    function _doUpdate(updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState) {
+        let theUpdateState: ITelemetryUpdateState = updateState || {
+            reason: TelemetryUpdateReason.Unknown
+        };
+
+        _processChannelQueue(channelQueue, updateCtx, (chainCtx: IProcessTelemetryUpdateContext) => {
+            chainCtx[strProcessNext](theUpdateState);
+        }, () => {
+            updateCtx[strProcessNext](theUpdateState);
+        });
+
+        return true;
+    }
+
     function _doTeardown(unloadCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) {
         let theUnloadState: ITelemetryUnloadState = unloadState || {
             reason: TelemetryUnloadReason.ManualTeardown,
@@ -152,6 +168,7 @@ export function createChannelControllerPlugin(channelQueue: _IInternalChannels[]
                 itemCtx[strProcessNext](item);
             });
         },
+        update: _doUpdate,
         [strPause]: () => {
             _processChannelQueue(channelQueue, _getTelCtx(), (chainCtx: IProcessTelemetryContext) => {
                 chainCtx.iterate<IChannelControls>((plugin) => {

package/src/JavaScriptSDK/CookieMgr.ts

@@ -11,6 +11,7 @@ import {
 import { IConfiguration } from "../JavaScriptSDK.Interfaces/IConfiguration";
 import { IAppInsightsCore } from "../JavaScriptSDK.Interfaces/IAppInsightsCore";
 import { strEmpty } from "./InternalConstants";
+import { _throwInternal } from "./DiagnosticLogger";
 
 const strToGMTString = "toGMTString";
 const strToUTCString = "toUTCString";
@@ -252,7 +253,8 @@ export function areCookiesSupported(logger?: IDiagnosticLogger): any {
             let doc = _doc || {} as Document;
             _supportsCookies = doc[strCookie] !== undefined;
         } catch (e) {
-            logger && logger.throwInternal(
+            _throwInternal(
+                logger,
                 eLoggingSeverity.WARNING,
                 _eInternalMessageId.CannotAccessCookie,
                 "Cannot access document.cookie - " + getExceptionName(e),

package/src/JavaScriptSDK/DiagnosticLogger.ts

@@ -320,3 +320,17 @@ export class DiagnosticLogger implements IDiagnosticLogger {
         // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
     }
 }
+
+/**
+ * This is a helper method which will call throwInternal on the passed logger, will throw exceptions in
+ * debug mode or attempt to log the error as a console warning. This helper is provided mostly to better
+ * support minification as logger.throwInternal() will not compress the publish "throwInternal" used throughout
+ * the code.
+ * @param logger - The Diagnostic Logger instance to use.
+ * @param severity {LoggingSeverity} - The severity of the log message
+ * @param message {_InternalLogMessage} - The log message.
+ */
+export function _throwInternal(logger: IDiagnosticLogger, severity: LoggingSeverity, msgId: _InternalMessageId, msg: string, properties?: Object, isUserAct = false) {
+    (logger || new DiagnosticLogger()).throwInternal(severity, msgId, msg, properties, isUserAct);
+}
+