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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. package/browser/applicationinsights-core-js.integrity.json +9 -9
  2. package/browser/applicationinsights-core-js.js +319 -29
  3. package/browser/applicationinsights-core-js.js.map +1 -1
  4. package/browser/applicationinsights-core-js.min.js +2 -2
  5. package/browser/applicationinsights-core-js.min.js.map +1 -1
  6. package/dist/applicationinsights-core-js.api.json +2458 -250
  7. package/dist/applicationinsights-core-js.api.md +87 -7
  8. package/dist/applicationinsights-core-js.d.ts +192 -7
  9. package/dist/applicationinsights-core-js.js +319 -29
  10. package/dist/applicationinsights-core-js.js.map +1 -1
  11. package/dist/applicationinsights-core-js.min.js +2 -2
  12. package/dist/applicationinsights-core-js.min.js.map +1 -1
  13. package/dist/applicationinsights-core-js.rollup.d.ts +195 -10
  14. package/dist-esm/JavaScriptSDK/AppInsightsCore.js +1 -1
  15. package/dist-esm/JavaScriptSDK/BaseCore.js +205 -13
  16. package/dist-esm/JavaScriptSDK/BaseCore.js.map +1 -1
  17. package/dist-esm/JavaScriptSDK/BaseTelemetryPlugin.js +37 -3
  18. package/dist-esm/JavaScriptSDK/BaseTelemetryPlugin.js.map +1 -1
  19. package/dist-esm/JavaScriptSDK/ChannelController.js +14 -2
  20. package/dist-esm/JavaScriptSDK/ChannelController.js.map +1 -1
  21. package/dist-esm/JavaScriptSDK/Constants.js +1 -1
  22. package/dist-esm/JavaScriptSDK/CookieMgr.js +3 -2
  23. package/dist-esm/JavaScriptSDK/CookieMgr.js.map +1 -1
  24. package/dist-esm/JavaScriptSDK/CoreUtils.js +1 -1
  25. package/dist-esm/JavaScriptSDK/DataCacheHelper.js +1 -1
  26. package/dist-esm/JavaScriptSDK/DbgExtensionUtils.js +1 -1
  27. package/dist-esm/JavaScriptSDK/DiagnosticLogger.js +14 -1
  28. package/dist-esm/JavaScriptSDK/DiagnosticLogger.js.map +1 -1
  29. package/dist-esm/JavaScriptSDK/EnvUtils.js +1 -1
  30. package/dist-esm/JavaScriptSDK/EventHelpers.js +18 -13
  31. package/dist-esm/JavaScriptSDK/EventHelpers.js.map +1 -1
  32. package/dist-esm/JavaScriptSDK/HelperFuncs.js +3 -13
  33. package/dist-esm/JavaScriptSDK/HelperFuncs.js.map +1 -1
  34. package/dist-esm/JavaScriptSDK/InstrumentHooks.js +1 -1
  35. package/dist-esm/JavaScriptSDK/InternalConstants.js +1 -1
  36. package/dist-esm/JavaScriptSDK/NotificationManager.js +1 -1
  37. package/dist-esm/JavaScriptSDK/PerfManager.js +1 -1
  38. package/dist-esm/JavaScriptSDK/ProcessTelemetryContext.js +71 -6
  39. package/dist-esm/JavaScriptSDK/ProcessTelemetryContext.js.map +1 -1
  40. package/dist-esm/JavaScriptSDK/RandomHelper.js +1 -1
  41. package/dist-esm/JavaScriptSDK/TelemetryHelpers.js +1 -1
  42. package/dist-esm/JavaScriptSDK/TelemetryInitializerPlugin.js +3 -2
  43. package/dist-esm/JavaScriptSDK/TelemetryInitializerPlugin.js.map +1 -1
  44. package/dist-esm/JavaScriptSDK/UnloadHandlerContainer.js +33 -0
  45. package/dist-esm/JavaScriptSDK/UnloadHandlerContainer.js.map +1 -0
  46. package/dist-esm/JavaScriptSDK.Enums/EventsDiscardedReason.js +1 -1
  47. package/dist-esm/JavaScriptSDK.Enums/LoggingEnums.js +1 -1
  48. package/dist-esm/JavaScriptSDK.Enums/SendRequestReason.js +1 -1
  49. package/dist-esm/JavaScriptSDK.Enums/TelemetryUnloadReason.js +1 -1
  50. package/dist-esm/JavaScriptSDK.Enums/TelemetryUpdateReason.js +8 -0
  51. package/dist-esm/JavaScriptSDK.Enums/TelemetryUpdateReason.js.map +1 -0
  52. package/dist-esm/JavaScriptSDK.Interfaces/IAppInsightsCore.js +1 -1
  53. package/dist-esm/JavaScriptSDK.Interfaces/IChannelControls.js +1 -1
  54. package/dist-esm/JavaScriptSDK.Interfaces/IConfiguration.js +1 -1
  55. package/dist-esm/JavaScriptSDK.Interfaces/ICookieMgr.js +1 -1
  56. package/dist-esm/JavaScriptSDK.Interfaces/IDbgExtension.js +1 -1
  57. package/dist-esm/JavaScriptSDK.Interfaces/IDiagnosticLogger.js +1 -1
  58. package/dist-esm/JavaScriptSDK.Interfaces/IInstrumentHooks.js +1 -1
  59. package/dist-esm/JavaScriptSDK.Interfaces/INotificationListener.js +1 -1
  60. package/dist-esm/JavaScriptSDK.Interfaces/INotificationManager.js +1 -1
  61. package/dist-esm/JavaScriptSDK.Interfaces/IPerfEvent.js +1 -1
  62. package/dist-esm/JavaScriptSDK.Interfaces/IPerfManager.js +1 -1
  63. package/dist-esm/JavaScriptSDK.Interfaces/IProcessTelemetryContext.js +1 -1
  64. package/dist-esm/JavaScriptSDK.Interfaces/ITelemetryInitializers.js +1 -1
  65. package/dist-esm/JavaScriptSDK.Interfaces/ITelemetryItem.js +1 -1
  66. package/dist-esm/JavaScriptSDK.Interfaces/ITelemetryPlugin.js +1 -1
  67. package/dist-esm/JavaScriptSDK.Interfaces/ITelemetryPluginChain.js +1 -1
  68. package/dist-esm/JavaScriptSDK.Interfaces/ITelemetryUnloadState.js +1 -1
  69. package/dist-esm/JavaScriptSDK.Interfaces/ITelemetryUpdateState.js +8 -0
  70. package/dist-esm/JavaScriptSDK.Interfaces/ITelemetryUpdateState.js.map +1 -0
  71. package/dist-esm/applicationinsights-core-js.js +3 -2
  72. package/dist-esm/applicationinsights-core-js.js.map +1 -1
  73. package/package.json +1 -1
  74. package/src/JavaScriptSDK/BaseCore.ts +272 -14
  75. package/src/JavaScriptSDK/BaseTelemetryPlugin.ts +70 -4
  76. package/src/JavaScriptSDK/ChannelController.ts +18 -1
  77. package/src/JavaScriptSDK/CookieMgr.ts +3 -1
  78. package/src/JavaScriptSDK/DiagnosticLogger.ts +14 -0
  79. package/src/JavaScriptSDK/EventHelpers.ts +18 -12
  80. package/src/JavaScriptSDK/HelperFuncs.ts +4 -2
  81. package/src/JavaScriptSDK/ProcessTelemetryContext.ts +87 -10
  82. package/src/JavaScriptSDK/TelemetryInitializerPlugin.ts +3 -1
  83. package/src/JavaScriptSDK/UnloadHandlerContainer.ts +46 -0
  84. package/src/JavaScriptSDK.Enums/SendRequestReason.ts +5 -0
  85. package/src/JavaScriptSDK.Enums/TelemetryUnloadReason.ts +3 -3
  86. package/src/JavaScriptSDK.Enums/TelemetryUpdateReason.ts +27 -0
  87. package/src/JavaScriptSDK.Interfaces/IAppInsightsCore.ts +29 -2
  88. package/src/JavaScriptSDK.Interfaces/IInstrumentHooks.ts +11 -6
  89. package/src/JavaScriptSDK.Interfaces/IProcessTelemetryContext.ts +25 -2
  90. package/src/JavaScriptSDK.Interfaces/ITelemetryPlugin.ts +12 -1
  91. package/src/JavaScriptSDK.Interfaces/ITelemetryUpdateState.ts +34 -0
  92. package/types/JavaScriptSDK/BaseCore.d.ts +27 -2
  93. package/types/JavaScriptSDK/BaseTelemetryPlugin.d.ts +23 -1
  94. package/types/JavaScriptSDK/DiagnosticLogger.d.ts +10 -0
  95. package/types/JavaScriptSDK/EventHelpers.d.ts +4 -2
  96. package/types/JavaScriptSDK/HelperFuncs.d.ts +2 -1
  97. package/types/JavaScriptSDK/ProcessTelemetryContext.d.ts +11 -1
  98. package/types/JavaScriptSDK/UnloadHandlerContainer.d.ts +11 -0
  99. package/types/JavaScriptSDK.Enums/SendRequestReason.d.ts +4 -0
  100. package/types/JavaScriptSDK.Enums/TelemetryUnloadReason.d.ts +13 -1
  101. package/types/JavaScriptSDK.Enums/TelemetryUpdateReason.d.ts +20 -0
  102. package/types/JavaScriptSDK.Interfaces/IAppInsightsCore.d.ts +24 -1
  103. package/types/JavaScriptSDK.Interfaces/IInstrumentHooks.d.ts +5 -0
  104. package/types/JavaScriptSDK.Interfaces/IProcessTelemetryContext.d.ts +23 -2
  105. package/types/JavaScriptSDK.Interfaces/ITelemetryPlugin.d.ts +11 -1
  106. package/types/JavaScriptSDK.Interfaces/ITelemetryUpdateState.d.ts +22 -0
  107. package/types/applicationinsights-core-js.d.ts +6 -2
@@ -3,10 +3,12 @@ import { IConfiguration } from "../JavaScriptSDK.Interfaces/IConfiguration";
3
3
  import { IDiagnosticLogger } from "../JavaScriptSDK.Interfaces/IDiagnosticLogger";
4
4
  import { IPlugin, ITelemetryPlugin } from "../JavaScriptSDK.Interfaces/ITelemetryPlugin";
5
5
  import { ITelemetryItem } from "../JavaScriptSDK.Interfaces/ITelemetryItem";
6
- import { IProcessTelemetryContext, IProcessTelemetryUnloadContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
6
+ import { IProcessTelemetryContext, IProcessTelemetryUnloadContext, IProcessTelemetryUpdateContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
7
7
  import { ITelemetryPluginChain } from "../JavaScriptSDK.Interfaces/ITelemetryPluginChain";
8
+ import { UnloadHandler } from "./UnloadHandlerContainer";
8
9
  import { IInstrumentHook } from "../JavaScriptSDK.Interfaces/IInstrumentHooks";
9
10
  import { ITelemetryUnloadState } from "../JavaScriptSDK.Interfaces/ITelemetryUnloadState";
11
+ import { ITelemetryUpdateState } from "../JavaScriptSDK.Interfaces/ITelemetryUpdateState";
10
12
  /**
11
13
  * BaseTelemetryPlugin provides a basic implementation of the ITelemetryPlugin interface so that plugins
12
14
  * can avoid implementation the same set of boiler plate code as well as provide a base
@@ -61,6 +63,14 @@ export declare abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
61
63
  * @returns boolean - true if the plugin has or will call asyncCallback, this allows the plugin to perform any asynchronous operations.
62
64
  */
63
65
  protected _doTeardown?: (unloadCtx?: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState, asyncCallback?: () => void) => void | boolean;
66
+ /**
67
+ * Extension hook to allow implementations to perform some additional update operations before the BaseTelemetryPlugin finishes it's removal
68
+ * @param updateCtx - This is the context that should be used during updating.
69
+ * @param updateState - The details / state of the update process, it holds details like the current and previous configuration.
70
+ * @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.
71
+ * @returns boolean - true if the plugin has or will call asyncCallback, this allows the plugin to perform any asynchronous operations.
72
+ */
73
+ protected _doUpdate?: (updateCtx?: IProcessTelemetryUpdateContext, updateState?: ITelemetryUpdateState, asyncCallback?: () => void) => void | boolean;
64
74
  constructor();
65
75
  initialize(config: IConfiguration, core: IAppInsightsCore, extensions: IPlugin[], pluginChain?: ITelemetryPluginChain): void;
66
76
  /**
@@ -73,6 +83,18 @@ export declare abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
73
83
  */
74
84
  teardown(unloadCtx?: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState): void | boolean;
75
85
  abstract processTelemetry(env: ITelemetryItem, itemCtx?: IProcessTelemetryContext): void;
86
+ /**
87
+ * The the plugin should re-evaluate configuration and update any cached configuration settings.
88
+ * @param updateCtx - This is the context that should be used during updating.
89
+ * @param updateState - The details / state of the update process, it holds details like the current and previous configuration.
90
+ * @returns boolean - true if the plugin has or will call updateCtx.processNext(), this allows the plugin to perform any asynchronous operations.
91
+ */
92
+ update(updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState): void | boolean;
93
+ /**
94
+ * Add an unload handler that will be called when the SDK is being unloaded
95
+ * @param handler - the handler
96
+ */
97
+ protected _addUnloadCb(handler: UnloadHandler): void;
76
98
  /**
77
99
  * Add this hook so that it is automatically removed during unloading
78
100
  * @param hooks - The single hook or an array of IInstrumentHook objects
@@ -63,3 +63,13 @@ export declare class DiagnosticLogger implements IDiagnosticLogger {
63
63
  */
64
64
  logInternalMessage(severity: LoggingSeverity, message: _InternalLogMessage): void;
65
65
  }
66
+ /**
67
+ * This is a helper method which will call throwInternal on the passed logger, will throw exceptions in
68
+ * debug mode or attempt to log the error as a console warning. This helper is provided mostly to better
69
+ * support minification as logger.throwInternal() will not compress the publish "throwInternal" used throughout
70
+ * the code.
71
+ * @param logger - The Diagnostic Logger instance to use.
72
+ * @param severity {LoggingSeverity} - The severity of the log message
73
+ * @param message {_InternalLogMessage} - The log message.
74
+ */
75
+ export declare function _throwInternal(logger: IDiagnosticLogger, severity: LoggingSeverity, msgId: _InternalMessageId, msg: string, properties?: Object, isUserAct?: boolean): void;
@@ -6,9 +6,11 @@ export interface _IRegisteredEvents {
6
6
  * Get all of the registered events on the target object, this is primarily used for testing cleanup but may also be used by
7
7
  * applications to remove their own events
8
8
  * @param target - The EventTarget that has registered events
9
- * @param evtName - [Optional] The name of the event to return the registered handlers and full name (with namespaces)
9
+ * @param eventName - [Optional] The name of the event to return the registered handlers and full name (with namespaces)
10
+ * @param evtNamespace - [Optional] Additional namespace(s) to append to the event listeners so they can be uniquely identified and removed based on this namespace,
11
+ * if the eventName also includes a namespace the namespace(s) are merged into a single namespace
10
12
  */
11
- export declare function __getRegisteredEvents(target: any, evtName?: string): _IRegisteredEvents[];
13
+ export declare function __getRegisteredEvents(target: any, eventName?: string, evtNamespace?: string | string[]): _IRegisteredEvents[];
12
14
  export declare function mergeEvtNamespace(theNamespace: string, namespaces: string | string[]): string | string[];
13
15
  /**
14
16
  * Binds the specified function to an event, so that the function gets called whenever the event fires on the object
@@ -259,4 +259,5 @@ export declare function optimizeObject<T>(theObject: T): T;
259
259
  * @param obj5 - object to merge.
260
260
  * @returns The extended first object.
261
261
  */
262
- export declare function objExtend<T1, T2, T3, T4, T5, T6>(obj?: boolean | T1, obj2?: T2, obj3?: T3, obj4?: T4, obj5?: T5, obj6?: T6): T1 & T2 & T3 & T4 & T5 & T6;
262
+ export declare function objExtend<T2, T3, T4, T5, T6>(deepExtend?: boolean, obj2?: T2, obj3?: T3, obj4?: T4, obj5?: T5, obj6?: T6): T2 & T3 & T4 & T5 & T6;
263
+ export declare function objExtend<T1, T2, T3, T4, T5, T6>(obj1?: T1, obj2?: T2, obj3?: T3, obj4?: T4, obj5?: T5, obj6?: T6): T1 & T2 & T3 & T4 & T5 & T6;
@@ -2,7 +2,7 @@ import { IAppInsightsCore } from "../JavaScriptSDK.Interfaces/IAppInsightsCore";
2
2
  import { IConfiguration } from "../JavaScriptSDK.Interfaces/IConfiguration";
3
3
  import { ITelemetryItem } from "../JavaScriptSDK.Interfaces/ITelemetryItem";
4
4
  import { IPlugin, ITelemetryPlugin } from "../JavaScriptSDK.Interfaces/ITelemetryPlugin";
5
- import { IProcessTelemetryContext, IProcessTelemetryUnloadContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
5
+ import { IProcessTelemetryContext, IProcessTelemetryUnloadContext, IProcessTelemetryUpdateContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
6
6
  import { ITelemetryPluginChain } from "../JavaScriptSDK.Interfaces/ITelemetryPluginChain";
7
7
  import { IDiagnosticLogger } from "../JavaScriptSDK.Interfaces/IDiagnosticLogger";
8
8
  /**
@@ -10,6 +10,7 @@ import { IDiagnosticLogger } from "../JavaScriptSDK.Interfaces/IDiagnosticLogger
10
10
  * @param plugins - The plugin instances that will be executed
11
11
  * @param config - The current config
12
12
  * @param core - The current core instance
13
+ * @param startAt - Identifies the next plugin to execute, if null there is no "next" plugin and if undefined it should assume the start of the chain
13
14
  */
14
15
  export declare function createProcessTelemetryContext(telemetryChain: ITelemetryPluginChain, config: IConfiguration, core: IAppInsightsCore, startAt?: IPlugin): IProcessTelemetryContext;
15
16
  /**
@@ -17,8 +18,17 @@ export declare function createProcessTelemetryContext(telemetryChain: ITelemetry
17
18
  * @param plugins - The plugin instances that will be executed
18
19
  * @param config - The current config
19
20
  * @param core - The current core instance
21
+ * @param startAt - Identifies the next plugin to execute, if null there is no "next" plugin and if undefined it should assume the start of the chain
20
22
  */
21
23
  export declare function createProcessTelemetryUnloadContext(telemetryChain: ITelemetryPluginChain, config: IConfiguration, core: IAppInsightsCore, startAt?: IPlugin): IProcessTelemetryUnloadContext;
24
+ /**
25
+ * Creates a new Telemetry Item context with the current config, core and plugin execution chain for updating the configuration
26
+ * @param plugins - The plugin instances that will be executed
27
+ * @param config - The current config
28
+ * @param core - The current core instance
29
+ * @param startAt - Identifies the next plugin to execute, if null there is no "next" plugin and if undefined it should assume the start of the chain
30
+ */
31
+ export declare function createProcessTelemetryUpdateContext(telemetryChain: ITelemetryPluginChain, config: IConfiguration, core: IAppInsightsCore, startAt?: IPlugin): IProcessTelemetryUpdateContext;
22
32
  /**
23
33
  * Creates an execution chain from the array of plugins
24
34
  * @param plugins - The array of plugins that will be executed in this order
@@ -0,0 +1,11 @@
1
+ import { IProcessTelemetryUnloadContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
2
+ import { ITelemetryUnloadState } from "../JavaScriptSDK.Interfaces/ITelemetryUnloadState";
3
+ export declare type UnloadHandler = (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
4
+ export interface IUnloadHandlerContainer {
5
+ add: (handler: UnloadHandler) => void;
6
+ run: (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
7
+ }
8
+ export declare function createUnloadHandlerContainer(): {
9
+ add: (handler: UnloadHandler) => void;
10
+ run: (unloadCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
11
+ };
@@ -30,6 +30,10 @@ export declare const enum SendRequestReason {
30
30
  * The event(s) being sent as a retry
31
31
  */
32
32
  Retry = 5,
33
+ /**
34
+ * The SDK is unloading
35
+ */
36
+ SdkUnload = 6,
33
37
  /**
34
38
  * Maximum batch size would be exceeded
35
39
  */
@@ -5,5 +5,17 @@ export declare const enum TelemetryUnloadReason {
5
5
  /**
6
6
  * Teardown has been called without any context.
7
7
  */
8
- ManualTeardown = 0
8
+ ManualTeardown = 0,
9
+ /**
10
+ * Just this plugin is being removed
11
+ */
12
+ PluginUnload = 1,
13
+ /**
14
+ * This instance of the plugin is being removed and replaced
15
+ */
16
+ PluginReplace = 2,
17
+ /**
18
+ * The entire SDK is being unloaded
19
+ */
20
+ SdkUnload = 50
9
21
  }
@@ -0,0 +1,20 @@
1
+ /**
2
+ * The TelemetryUpdateReason enumeration contains a set of bit-wise values that specify the reason for update request.
3
+ */
4
+ export declare const enum TelemetryUpdateReason {
5
+ /**
6
+ * Unknown.
7
+ */
8
+ Unknown = 0,
9
+ /**
10
+ * The configuration has ben updated or changed
11
+ */
12
+ /**
13
+ * One or more plugins have been added
14
+ */
15
+ PluginAdded = 16,
16
+ /**
17
+ * One or more plugins have been removed
18
+ */
19
+ PluginRemoved = 32
20
+ }
@@ -1,6 +1,6 @@
1
1
  import { ITelemetryItem } from "./ITelemetryItem";
2
2
  import { IChannelControls } from "./IChannelControls";
3
- import { IPlugin } from "./ITelemetryPlugin";
3
+ import { IPlugin, ITelemetryPlugin } from "./ITelemetryPlugin";
4
4
  import { IConfiguration } from "./IConfiguration";
5
5
  import { INotificationManager } from "./INotificationManager";
6
6
  import { INotificationListener } from "./INotificationListener";
@@ -9,6 +9,7 @@ import { IProcessTelemetryContext } from "./IProcessTelemetryContext";
9
9
  import { IPerfManagerProvider } from "./IPerfManager";
10
10
  import { ICookieMgr } from "./ICookieMgr";
11
11
  import { ITelemetryInitializerHandler, TelemetryInitializerFunction } from "./ITelemetryInitializers";
12
+ import { UnloadHandler } from "../applicationinsights-core-js";
12
13
  export interface ILoadedPlugin<T extends IPlugin> {
13
14
  plugin: T;
14
15
  /**
@@ -24,6 +25,7 @@ export interface ILoadedPlugin<T extends IPlugin> {
24
25
  * (unless it's also been re-initialized)
25
26
  */
26
27
  setEnabled: (isEnabled: boolean) => void;
28
+ remove: (isAsync?: boolean, removeCb?: (removed?: boolean) => void) => void;
27
29
  }
28
30
  export interface IAppInsightsCore extends IPerfManagerProvider {
29
31
  config: IConfiguration;
@@ -72,13 +74,34 @@ export interface IAppInsightsCore extends IPerfManagerProvider {
72
74
  * Return a new instance of the IProcessTelemetryContext for processing events
73
75
  */
74
76
  getProcessTelContext(): IProcessTelemetryContext;
77
+ /**
78
+ * Unload and Tear down the SDK and any initialized plugins, after calling this the SDK will be considered
79
+ * to be un-initialized and non-operational, re-initializing the SDK should only be attempted if the previous
80
+ * unload call return `true` stating that all plugins reported that they also unloaded, the recommended
81
+ * approach is to create a new instance and initialize that instance.
82
+ * This is due to possible unexpected side effects caused by plugins not supporting unload / teardown, unable
83
+ * to successfully remove any global references or they may just be completing the unload process asynchronously.
84
+ */
85
+ unload(isAsync?: boolean, unloadComplete?: () => void): void;
75
86
  /**
76
87
  * Find and return the (first) plugin with the specified identifier if present
77
88
  * @param pluginIdentifier
78
89
  */
79
90
  getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
91
+ /**
92
+ * Add a new plugin to the installation
93
+ * @param plugin - The new plugin to add
94
+ * @param replaceExisting - should any existing plugin be replaced
95
+ * @param doAsync - Should the add be performed asynchronously
96
+ */
97
+ addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting: boolean, doAsync: boolean, addCb?: (added?: boolean) => void): void;
80
98
  /**
81
99
  * Returns the unique event namespace that should be used when registering events
82
100
  */
83
101
  evtNamespace(): string;
102
+ /**
103
+ * Add a handler that will be called when the SDK is being unloaded
104
+ * @param handler - the handler
105
+ */
106
+ addUnloadCb(handler: UnloadHandler): void;
84
107
  }
@@ -8,6 +8,11 @@ export declare type InstrumentorHooksCallback = (funcArgs: IInstrumentCallDetail
8
8
  * You must always supply the error callback
9
9
  */
10
10
  export interface IInstrumentHooksCallbacks {
11
+ /**
12
+ * [Optional] Namespace details (same as the namespace used for events), useful for debugging and testing to
13
+ * identify the source of the instrumented hooks
14
+ */
15
+ ns?: string | string[];
11
16
  /**
12
17
  * The hook callback to call before the original function is called
13
18
  */
@@ -5,6 +5,7 @@ import { ITelemetryItem } from "./ITelemetryItem";
5
5
  import { IPlugin, ITelemetryPlugin } from "./ITelemetryPlugin";
6
6
  import { ITelemetryPluginChain } from "./ITelemetryPluginChain";
7
7
  import { ITelemetryUnloadState } from "./ITelemetryUnloadState";
8
+ import { ITelemetryUpdateState } from "./ITelemetryUpdateState";
8
9
  export declare const enum GetExtCfgMergeType {
9
10
  None = 0,
10
11
  MergeDefaultOnly = 1,
@@ -91,8 +92,8 @@ export interface IProcessTelemetryContext extends IBaseProcessingContext {
91
92
  createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IProcessTelemetryContext;
92
93
  }
93
94
  /**
94
- * The current context for the current call to processTelemetry(), used to support sharing the same plugin instance
95
- * between multiple AppInsights instances
95
+ * The current context for the current call to teardown() implementations, used to support when plugins are being removed
96
+ * or the SDK is being unloaded.
96
97
  */
97
98
  export interface IProcessTelemetryUnloadContext extends IBaseProcessingContext {
98
99
  /**
@@ -110,3 +111,23 @@ export interface IProcessTelemetryUnloadContext extends IBaseProcessingContext {
110
111
  */
111
112
  createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IProcessTelemetryUnloadContext;
112
113
  }
114
+ /**
115
+ * The current context for the current call to the plugin update() implementations, used to support the notifications
116
+ * for when plugins are added, removed or the configuration was changed.
117
+ */
118
+ export interface IProcessTelemetryUpdateContext extends IBaseProcessingContext {
119
+ /**
120
+ * This Plugin has finished unloading, so unload the next one
121
+ * @param updateState - The update State
122
+ * @returns boolean (true) if there is no more plugins to process otherwise false or undefined (void)
123
+ */
124
+ processNext: (updateState: ITelemetryUpdateState) => boolean | void;
125
+ /**
126
+ * Create a new context using the core and config from the current instance, returns a new instance of the same type
127
+ * @param plugins - The execution order to process the plugins, if null or not supplied
128
+ * then the current execution order will be copied.
129
+ * @param startAt - The plugin to start processing from, if missing from the execution
130
+ * order then the next plugin will be NOT set.
131
+ */
132
+ createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IProcessTelemetryUpdateContext;
133
+ }
@@ -1,9 +1,10 @@
1
1
  import { ITelemetryItem } from "./ITelemetryItem";
2
2
  import { IConfiguration } from "./IConfiguration";
3
3
  import { IAppInsightsCore } from "./IAppInsightsCore";
4
- import { IProcessTelemetryContext, IProcessTelemetryUnloadContext } from "./IProcessTelemetryContext";
4
+ import { IProcessTelemetryContext, IProcessTelemetryUnloadContext, IProcessTelemetryUpdateContext } from "./IProcessTelemetryContext";
5
5
  import { ITelemetryPluginChain } from "./ITelemetryPluginChain";
6
6
  import { ITelemetryUnloadState } from "./ITelemetryUnloadState";
7
+ import { ITelemetryUpdateState } from "./ITelemetryUpdateState";
7
8
  export interface ITelemetryProcessor {
8
9
  /**
9
10
  * Call back for telemetry processing before it it is sent
@@ -13,6 +14,15 @@ export interface ITelemetryProcessor {
13
14
  * to later plugins (vs appending items to the telemetry item)
14
15
  */
15
16
  processTelemetry: (env: ITelemetryItem, itemCtx?: IProcessTelemetryContext) => void;
17
+ /**
18
+ * The the plugin should re-evaluate configuration and update any cached configuration settings or
19
+ * plugins. If implemented this method will be called whenever a plugin is added or removed and if
20
+ * the configuration has bee updated.
21
+ * @param updateCtx - This is the context that should be used during updating.
22
+ * @param updateState - The details / state of the update process, it holds details like the current and previous configuration.
23
+ * @returns boolean - true if the plugin has or will call updateCtx.processNext(), this allows the plugin to perform any asynchronous operations.
24
+ */
25
+ update?: (updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState) => void | boolean;
16
26
  }
17
27
  /**
18
28
  * Configuration provided to SDK core
@@ -0,0 +1,22 @@
1
+ import { TelemetryUpdateReason } from "../JavaScriptSDK.Enums/TelemetryUpdateReason";
2
+ import { IPlugin } from "./ITelemetryPlugin";
3
+ export interface ITelemetryUpdateState {
4
+ /**
5
+ * Identifies the reason for the update notification, this is a bitwise numeric value
6
+ */
7
+ reason: TelemetryUpdateReason;
8
+ /**
9
+ * If this is a configuration update this was the previous configuration that was used
10
+ */
11
+ /**
12
+ * If this is a configuration update is the new configuration that is being used
13
+ */
14
+ /**
15
+ * This holds a collection of plugins that have been added (if the reason identifies that one or more plugins have been added)
16
+ */
17
+ added?: IPlugin[];
18
+ /**
19
+ * This holds a collection of plugins that have been removed (if the reason identifies that one or more plugins have been removed)
20
+ */
21
+ removed?: IPlugin[];
22
+ }
@@ -3,13 +3,15 @@ export { IChannelControls, MinChannelPriorty } from "./JavaScriptSDK.Interfaces/
3
3
  export { ITelemetryPlugin, IPlugin } from "./JavaScriptSDK.Interfaces/ITelemetryPlugin";
4
4
  export { IAppInsightsCore } from "./JavaScriptSDK.Interfaces/IAppInsightsCore";
5
5
  export { ITelemetryItem, ICustomProperties, Tags } from "./JavaScriptSDK.Interfaces/ITelemetryItem";
6
- export { IProcessTelemetryContext, GetExtCfgMergeType } from "./JavaScriptSDK.Interfaces/IProcessTelemetryContext";
6
+ export { IBaseProcessingContext, IProcessTelemetryContext, IProcessTelemetryUnloadContext, IProcessTelemetryUpdateContext, GetExtCfgMergeType } from "./JavaScriptSDK.Interfaces/IProcessTelemetryContext";
7
7
  export { INotificationListener } from "./JavaScriptSDK.Interfaces/INotificationListener";
8
8
  export { ITelemetryPluginChain } from "./JavaScriptSDK.Interfaces/ITelemetryPluginChain";
9
9
  export { IDiagnosticLogger } from "./JavaScriptSDK.Interfaces/IDiagnosticLogger";
10
10
  export { InstrumentorHooksCallback, IInstrumentHooksCallbacks, IInstrumentHooks, IInstrumentHook, IInstrumentCallDetails } from "./JavaScriptSDK.Interfaces/IInstrumentHooks";
11
11
  export { EventsDiscardedReason } from "./JavaScriptSDK.Enums/EventsDiscardedReason";
12
12
  export { SendRequestReason } from "./JavaScriptSDK.Enums/SendRequestReason";
13
+ export { TelemetryUpdateReason } from "./JavaScriptSDK.Enums/TelemetryUpdateReason";
14
+ export { TelemetryUnloadReason } from "./JavaScriptSDK.Enums/TelemetryUnloadReason";
13
15
  export { AppInsightsCore } from "./JavaScriptSDK/AppInsightsCore";
14
16
  export { BaseCore } from "./JavaScriptSDK/BaseCore";
15
17
  export { BaseTelemetryPlugin } from "./JavaScriptSDK/BaseTelemetryPlugin";
@@ -24,7 +26,7 @@ export { INotificationManager } from "./JavaScriptSDK.Interfaces/INotificationMa
24
26
  export { IPerfEvent } from "./JavaScriptSDK.Interfaces/IPerfEvent";
25
27
  export { IPerfManager, IPerfManagerProvider } from "./JavaScriptSDK.Interfaces/IPerfManager";
26
28
  export { PerfEvent, PerfManager, doPerf, getGblPerfMgr, setGblPerfMgr } from "./JavaScriptSDK/PerfManager";
27
- export { safeGetLogger, DiagnosticLogger, _InternalLogMessage } from "./JavaScriptSDK/DiagnosticLogger";
29
+ export { safeGetLogger, DiagnosticLogger, _InternalLogMessage, _throwInternal } from "./JavaScriptSDK/DiagnosticLogger";
28
30
  export { ProcessTelemetryContext, createProcessTelemetryContext } from "./JavaScriptSDK/ProcessTelemetryContext";
29
31
  export { initializePlugins, sortPlugins } from "./JavaScriptSDK/TelemetryHelpers";
30
32
  export { _InternalMessageId, _eInternalMessageId, LoggingSeverity, eLoggingSeverity } from "./JavaScriptSDK.Enums/LoggingEnums";
@@ -36,4 +38,6 @@ export { IDbgExtension } from "./JavaScriptSDK.Interfaces/IDbgExtension";
36
38
  export { getDebugListener, getDebugExt } from "./JavaScriptSDK/DbgExtensionUtils";
37
39
  export { TelemetryInitializerFunction, ITelemetryInitializerHandler, ITelemetryInitializerContainer } from "./JavaScriptSDK.Interfaces/ITelemetryInitializers";
38
40
  export { createUniqueNamespace } from "./JavaScriptSDK/DataCacheHelper";
41
+ export { UnloadHandler, IUnloadHandlerContainer, createUnloadHandlerContainer } from "./JavaScriptSDK/UnloadHandlerContainer";
42
+ export { ITelemetryUpdateState } from "./JavaScriptSDK.Interfaces/ITelemetryUpdateState";
39
43
  export { ITelemetryUnloadState } from "./JavaScriptSDK.Interfaces/ITelemetryUnloadState";