@microsoft/applicationinsights-web-basic 2.8.0-beta.2203-02 → 2.8.0-beta.2203-05

package/dist/applicationinsights-web-basic.api.json

@@ -705,6 +705,130 @@
               ],
               "name": "addNotificationListener"
             },
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@microsoft/applicationinsights-web-basic!IAppInsightsCore#addPlugin:member(1)",
+              "docComment": "/**\n * Add a new plugin to the installation\n *\n * @param plugin - The new plugin to add\n *\n * @param replaceExisting - should any existing plugin be replaced\n *\n * @param doAsync - Should the add be performed asynchronously\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "addPlugin<T extends "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "IPlugin",
+                  "canonicalReference": "@microsoft/applicationinsights-web-basic!IPlugin:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": " "
+                },
+                {
+                  "kind": "Content",
+                  "text": "= "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ITelemetryPlugin",
+                  "canonicalReference": "@microsoft/applicationinsights-web-basic!ITelemetryPlugin:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ">(plugin: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "T"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", replaceExisting: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", doAsync: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", addCb?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "(added?: boolean) => void"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": false,
+              "returnTypeTokenRange": {
+                "startIndex": 14,
+                "endIndex": 15
+              },
+              "releaseTag": "Public",
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "plugin",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 6,
+                    "endIndex": 7
+                  }
+                },
+                {
+                  "parameterName": "replaceExisting",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 8,
+                    "endIndex": 9
+                  }
+                },
+                {
+                  "parameterName": "doAsync",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 10,
+                    "endIndex": 11
+                  }
+                },
+                {
+                  "parameterName": "addCb",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 12,
+                    "endIndex": 13
+                  }
+                }
+              ],
+              "typeParameters": [
+                {
+                  "typeParameterName": "T",
+                  "constraintTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 3
+                  },
+                  "defaultTypeTokenRange": {
+                    "startIndex": 4,
+                    "endIndex": 5
+                  }
+                }
+              ],
+              "name": "addPlugin"
+            },
             {
               "kind": "MethodSignature",
               "canonicalReference": "@microsoft/applicationinsights-web-basic!IAppInsightsCore#addTelemetryInitializer:member(1)",
@@ -755,6 +879,51 @@
               ],
               "name": "addTelemetryInitializer"
             },
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@microsoft/applicationinsights-web-basic!IAppInsightsCore#addUnloadCb:member(1)",
+              "docComment": "/**\n * Add a handler that will be called when the SDK is being unloaded\n *\n * @param handler - the handler\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "addUnloadCb(handler: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "UnloadHandler",
+                  "canonicalReference": "@microsoft/applicationinsights-web-basic!UnloadHandler:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": false,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 4
+              },
+              "releaseTag": "Public",
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "handler",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  }
+                }
+              ],
+              "name": "addUnloadCb"
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@microsoft/applicationinsights-web-basic!IAppInsightsCore#config:member",
@@ -1370,6 +1539,65 @@
                 }
               ],
               "name": "track"
+            },
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@microsoft/applicationinsights-web-basic!IAppInsightsCore#unload:member(1)",
+              "docComment": "/**\n * 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.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "unload(isAsync?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", unloadComplete?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "() => void"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": false,
+              "returnTypeTokenRange": {
+                "startIndex": 5,
+                "endIndex": 6
+              },
+              "releaseTag": "Public",
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "isAsync",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  }
+                },
+                {
+                  "parameterName": "unloadComplete",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  }
+                }
+              ],
+              "name": "unload"
             }
           ],
           "extendsTokenRanges": [

package/dist/applicationinsights-web-basic.api.md

@@ -44,9 +44,13 @@ export const CoreUtils: ICoreUtils;
 export interface IAppInsightsCore extends IPerfManagerProvider {
     // Warning: (ae-forgotten-export) The symbol "INotificationListener" needs to be exported by the entry point index.d.ts
     addNotificationListener?(listener: INotificationListener): void;
+    // Warning: (ae-forgotten-export) The symbol "ITelemetryPlugin" needs to be exported by the entry point index.d.ts
+    addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting: boolean, doAsync: boolean, addCb?: (added?: boolean) => void): void;
     // Warning: (ae-forgotten-export) The symbol "TelemetryInitializerFunction" needs to be exported by the entry point index.d.ts
     // Warning: (ae-forgotten-export) The symbol "ITelemetryInitializerHandler" needs to be exported by the entry point index.d.ts
     addTelemetryInitializer(telemetryInitializer: TelemetryInitializerFunction): ITelemetryInitializerHandler | void;
+    // Warning: (ae-forgotten-export) The symbol "UnloadHandler" needs to be exported by the entry point index.d.ts
+    addUnloadCb(handler: UnloadHandler): void;
     // (undocumented)
     config: IConfiguration;
     evtNamespace(): string;
@@ -74,6 +78,7 @@ export interface IAppInsightsCore extends IPerfManagerProvider {
     stopPollingInternalLogs?(): void;
     // (undocumented)
     track(telemetryItem: ITelemetryItem): void;
+    unload(isAsync?: boolean, unloadComplete?: () => void): void;
 }
 
 // @public
@@ -112,7 +117,6 @@ export interface IConfiguration {
     extensionConfig?: {
         [key: string]: any;
     };
-    // Warning: (ae-forgotten-export) The symbol "ITelemetryPlugin" needs to be exported by the entry point index.d.ts
     extensions?: ITelemetryPlugin[];
     idLength?: number;
     instrumentationKey?: string;

package/dist/applicationinsights-web-basic.d.ts

@@ -1,5 +1,5 @@
 /*
- * Microsoft.ApplicationInsights, 2.8.0-beta.2203-02
+ * Microsoft.ApplicationInsights, 2.8.0-beta.2203-05
  * Copyright (c) Microsoft and contributors. All rights reserved.
  *
  * Microsoft Application Insights Team
@@ -100,12 +100,34 @@ declare namespace ApplicationInsights {
          * @returns - A ITelemetryInitializerHandler to enable the initializer to be removed
          */
         addTelemetryInitializer(telemetryInitializer: TelemetryInitializerFunction): ITelemetryInitializerHandler | void;
+        /**
+         * 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.
+         */
+        unload(isAsync?: boolean, unloadComplete?: (unloadState: ITelemetryUnloadState) => void, cbTimeout?: number): void;
         getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
+        addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting: boolean, doAsync: boolean, addCb?: (added?: boolean) => void): void;
         /**
          * Returns the unique event namespace that should be used
          */
         evtNamespace(): string;
+        /**
+         * Add an unload handler that will be called when the SDK is being unloaded
+         * @param handler - the handler
+         */
+        addUnloadCb(handler: UnloadHandler): void;
         protected releaseQueue(): void;
+        /**
+         * 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;
     }
 
     /**
@@ -162,6 +184,14 @@ declare namespace ApplicationInsights {
          * @returns boolean - true if the plugin has or will call asyncCallback, this allows the plugin to perform any asynchronous operations.
          */
         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();
         initialize(config: IConfiguration, core: IAppInsightsCore, extensions: IPlugin[], pluginChain?: ITelemetryPluginChain): void;
         /**
@@ -174,6 +204,18 @@ declare namespace ApplicationInsights {
          */
         teardown(unloadCtx?: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState): void | boolean;
         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.
+         */
+        update(updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState): void | boolean;
+        /**
+         * Add an unload handler that will be called when the SDK is being unloaded
+         * @param handler - the handler
+         */
+        protected _addUnloadCb(handler: UnloadHandler): void;
         /**
          * Add this hook so that it is automatically removed during unloading
          * @param hooks - The single hook or an array of IInstrumentHook objects
@@ -361,15 +403,36 @@ declare namespace ApplicationInsights {
          * Return a new instance of the IProcessTelemetryContext for processing events
          */
         getProcessTelContext(): IProcessTelemetryContext;
+        /**
+         * 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.
+         */
+        unload(isAsync?: boolean, unloadComplete?: () => void): void;
         /**
          * Find and return the (first) plugin with the specified identifier if present
          * @param pluginIdentifier
          */
         getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
+        /**
+         * Add a new plugin to the installation
+         * @param plugin - The new plugin to add
+         * @param replaceExisting - should any existing plugin be replaced
+         * @param doAsync - Should the add be performed asynchronously
+         */
+        addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting: boolean, doAsync: boolean, addCb?: (added?: boolean) => void): void;
         /**
          * Returns the unique event namespace that should be used when registering events
          */
         evtNamespace(): string;
+        /**
+         * Add a handler that will be called when the SDK is being unloaded
+         * @param handler - the handler
+         */
+        addUnloadCb(handler: UnloadHandler): void;
     }
 
     /**
@@ -1426,6 +1489,11 @@ declare namespace ApplicationInsights {
      * You must always supply the error callback
      */
     interface IInstrumentHooksCallbacks {
+        /**
+         * [Optional] Namespace details (same as the namespace used for events), useful for debugging and testing to
+         * identify the source of the instrumented hooks
+         */
+        ns?: string | string[];
         /**
          * The hook callback to call before the original function is called
          */
@@ -1460,6 +1528,7 @@ declare namespace ApplicationInsights {
          * (unless it's also been re-initialized)
          */
         setEnabled: (isEnabled: boolean) => void;
+        remove: (isAsync?: boolean, removeCb?: (removed?: boolean) => void) => void;
     }
 
     interface IMetricTelemetry extends IPartC {
@@ -1936,8 +2005,8 @@ declare namespace ApplicationInsights {
     }
 
     /**
-     * The current context for the current call to processTelemetry(), used to support sharing the same plugin instance
-     * between multiple AppInsights instances
+     * The current context for the current call to teardown() implementations, used to support when plugins are being removed
+     * or the SDK is being unloaded.
      */
     interface IProcessTelemetryUnloadContext extends IBaseProcessingContext {
         /**
@@ -1956,6 +2025,27 @@ declare namespace ApplicationInsights {
         createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IProcessTelemetryUnloadContext;
     }
 
+    /**
+     * The current context for the current call to the plugin update() implementations, used to support the notifications
+     * for when plugins are added, removed or the configuration was changed.
+     */
+    interface IProcessTelemetryUpdateContext extends IBaseProcessingContext {
+        /**
+         * This Plugin has finished unloading, so unload the next one
+         * @param updateState - The update State
+         * @returns boolean (true) if there is no more plugins to process otherwise false or undefined (void)
+         */
+        processNext: (updateState: ITelemetryUpdateState) => boolean | void;
+        /**
+         * Create a new context using the core and config from the current instance, returns a new instance of the same type
+         * @param plugins - The execution order to process the plugins, if null or not supplied
+         *                  then the current execution order will be copied.
+         * @param startAt - The plugin to start processing from, if missing from the execution
+         *                  order then the next plugin will be NOT set.
+         */
+        createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IProcessTelemetryUpdateContext;
+    }
+
     interface IRequestContext {
         status?: number;
         xhr?: XMLHttpRequest;
@@ -2191,6 +2281,15 @@ declare namespace ApplicationInsights {
          * to later plugins (vs appending items to the telemetry item)
          */
         processTelemetry: (env: ITelemetryItem, itemCtx?: IProcessTelemetryContext) => void;
+        /**
+         * The the plugin should re-evaluate configuration and update any cached configuration settings or
+         * plugins. If implemented this method will be called whenever a plugin is added or removed and if
+         * the configuration has bee updated.
+         * @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.
+         */
+        update?: (updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState) => void | boolean;
     }
 
     interface ITelemetryUnloadState {
@@ -2199,6 +2298,27 @@ declare namespace ApplicationInsights {
         flushComplete?: boolean;
     }
 
+    interface ITelemetryUpdateState {
+        /**
+         * Identifies the reason for the update notification, this is a bitwise numeric value
+         */
+        reason: TelemetryUpdateReason;
+        /**
+         * If this is a configuration update this was the previous configuration that was used
+         */
+        /**
+         * If this is a configuration update is the new configuration that is being used
+         */
+        /**
+         * This holds a collection of plugins that have been added (if the reason identifies that one or more plugins have been added)
+         */
+        added?: IPlugin[];
+        /**
+         * This holds a collection of plugins that have been removed (if the reason identifies that one or more plugins have been removed)
+         */
+        removed?: IPlugin[];
+    }
+
     interface ITraceTelemetry extends IPartC {
         /**
          * @description A message string
@@ -2342,6 +2462,10 @@ declare namespace ApplicationInsights {
          * The event(s) being sent as a retry
          */
         Retry = 5,
+        /**
+         * The SDK is unloading
+         */
+        SdkUnload = 6,
         /**
          * Maximum batch size would be exceeded
          */
@@ -2376,9 +2500,44 @@ declare namespace ApplicationInsights {
         /**
          * Teardown has been called without any context.
          */
-        ManualTeardown = 0
+        ManualTeardown = 0,
+        /**
+         * Just this plugin is being removed
+         */
+        PluginUnload = 1,
+        /**
+         * This instance of the plugin is being removed and replaced
+         */
+        PluginReplace = 2,
+        /**
+         * The entire SDK is being unloaded
+         */
+        SdkUnload = 50
+    }
+
+    /**
+     * The TelemetryUpdateReason enumeration contains a set of bit-wise values that specify the reason for update request.
+     */
+    const enum TelemetryUpdateReason {
+        /**
+         * Unknown.
+         */
+        Unknown = 0,
+        /**
+         * The configuration has ben updated or changed
+         */
+        /**
+         * One or more plugins have been added
+         */
+        PluginAdded = 16,
+        /**
+         * One or more plugins have been removed
+         */
+        PluginRemoved = 32
     }
 
+    type UnloadHandler = (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
+
     interface XDomainRequest extends XMLHttpRequestEventTarget {
         readonly responseText: string;
         send(payload: string): void;