maxAjaxCallsPerView doesn't account for filtering by TelemetryInitial…

…izer #1887

- Highlight the beta development

AISKU/src/Initialization.ts

@@ -22,7 +22,9 @@ import {
     isReactNative, isString, mergeEvtNamespace, objForEachKey, proxyAssign, proxyFunctions, removePageHideEventListener,
     removePageUnloadEventListener, throwError
 } from "@microsoft/applicationinsights-core-js";
-import { AjaxPlugin as DependenciesPlugin, IDependenciesPlugin } from "@microsoft/applicationinsights-dependencies-js";
+import {
+    AjaxPlugin as DependenciesPlugin, DependencyInitializerFunction, IDependenciesPlugin, IDependencyInitializerHandler
+} from "@microsoft/applicationinsights-dependencies-js";
 import {
     DependencyListenerFunction, IDependencyListenerHandler
 } from "@microsoft/applicationinsights-dependencies-js/types/DependencyListener";
@@ -422,7 +424,8 @@ export class Initialization implements IApplicationInsights {
 
             proxyFunctions(_self, _getCurrentDependencies, [
                 STR_TRACK_DEPENDENCY_DATA,
-                "addDependencyListener"
+                "addDependencyListener",
+                "addDependencyInitializer"
             ]);
 
             proxyFunctions(_self, _core, [
@@ -738,6 +741,18 @@ export class Initialization implements IApplicationInsights {
         return null;
     }
 
+    /**
+     * Add an dependency telemetry initializer callback function to allow populating additional properties or drop the request.
+     * It is called after the dependency call has completed and any available performance details are available. A dependency
+     * initializer is similar to the TelemetryInitializer function but it allows you to block the reporting of the dependency
+     * request so that it doesn't count against the `maxAjaxCallsPerView`.
+     * @param dependencyInitializer - The Dependency Telemetry Initializer function
+     * @returns - A IDependencyInitializerHandler to enable the initializer to be removed
+     */
+    public addDependencyInitializer(dependencyInitializer: DependencyInitializerFunction): IDependencyInitializerHandler {
+        return null;
+    }
+
     /**
      * Gets the current distributed trace context for this instance if available
      */

API-reference.md

@@ -196,6 +196,73 @@ Adds a telemetry initializer to the collection. Telemetry initializers will be c
 before the telemetry item is pushed for sending.
 If one of the telemetry initializers returns false or throws an error, then the telemetry item will not be sent.
 
+### addDependencyListener
+
+```ts
+public addDependencyListener(dependencyListener: (dependencyDetails: IDependencyListenerDetails) => void): IDependencyListenerHandler;
+
+// Example Usage
+let handler = appInsights.addDependencyListener((details) => {
+    // You have complete access to the xhr instance
+    // details.xhr: XMLHttpRequest;
+
+    // Or if a fetch request you have complete access to the input and init objects
+    // details.input: Request | string;
+    // details.init: RequestInit;
+
+    // Access or change the W3C traceId that will be added to the outbound request
+    details.traceId = "";
+
+    // Access or change the W3C spanId that will be added to the outbound request
+    details.spanId = "";
+
+    // Access or change the W3C traceflags that will be added to the outbound request
+    details.traceFlags = 1;
+
+    // Add additional context values (any) that can be used by other listeners and is
+    // also passed to any dependency initializers
+    details.context.someValue = 1234;
+});
+
+// [Optional] Remove the dependency initializer
+handler.remove();
+```
+
+A dependency listener is a callback function that allows you to perform additional manipulation of the request details before the request is performed.
+
+This includes :-
+
+- Complete access to either the XMLHttpRequest instance or the fetch API `input` and `init` arguments.
+- Ability to get/set the properties used to generate the W3C `traceparent` header (`traceId`, `spanId, `traceFlags)
+- Set values in the object context container for other listeners called after the current one, as well as this context object is also made available to all dependency initializers.
+
+### addDependencyInitializer
+
+```ts
+public addDependencyInitializer(dependencyInitializer: (item: IDependencyInitializerDetails) => boolean | void): IDependencyInitializerHandler
+
+// Example Usage
+let handler = appInsights.addDependencyInitializer((details) => {
+    details.item.xxxx = "";   // item is the telemetry event "before" it's been processed
+
+    // [Optional] To stop any event from being reported you can
+    // return false;
+});
+
+
+// [Optional] Remove the dependency initializer
+handler.remove();
+```
+
+A Dependency Initializer is very similar to a [Telemetry Initializer](https://github.com/Microsoft/ApplicationInsights-JS#telemetry-initializers) in that it allows you modify the contents of collected telemetry before being sent from the user's browser. And you can also returning `false` to cause the event to not be emitted.
+
+The differences between a telemetry initializer and a dependency initializer are :-
+- A Dependency Initializer is called "before" the event is processed by the pipeline, as such it will NOT (yet) contain the automatically populated properties that are applied later;
+- When a dependency initializer returns `false` to drop the event the event does NOT count against the `maxAjaxCallsPerView` as this blocks the event call from being tracked, and while returning `false` from a [Telemetry Initializer](https://github.com/Microsoft/ApplicationInsights-JS#telemetry-initializers) will also stop the event from being reported because this is further down the processing pipeline the dependency event IS counted against the `maxAjaxCallsPerView` limit.
+- It has access to an optional "context" `{ [key: string]: any }` object that is also available to the Dependency Listeners. This allows a listener to add additional details to the context (before the XHR/fetch request is sent), and the initializer will be called after the request has completed.
+
+The input argument to `addDependencyInitializer` is a callback that takes a [`IDependencyInitializerDetails`](./extensions/applicationinsights-dependencies-js/src/DependencyInitializer.ts) as an argument and returns a `boolean` or `void`. If returning `false`, the dependency event is not sent, else it proceeds to the next dependency initializer, if any, or is sent to processing pipeline to be sent to the telemetry collection endpoint.
+
 ### getSender
 
 ```ts

README.md

@@ -23,6 +23,19 @@
 
 > ***Note:*** The documentation for `applicationinsights-js@1.0.20` has moved [here](./legacy/README.md). If you are looking to upgrade to the new version of the SDK, please see the [Upgrade Guide](#upgrading-from-the-old-version-of-application-insights). For Node.js instrumentation reference this [repository](https://github.com/microsoft/ApplicationInsights-node.js). 
 
+## Beta (v3.x) Release Breaking changes
+
+As part of the beta development we intend to stop adding additional features (enhancements) to the v2.x releases.
+
+Development has started on the next major release which is occurring on the [beta](https://github.com/Microsoft/ApplicationInsights-JS/tree/beta) branch, this includes nightly automatic build and releases.
+
+Some of the major changes include
+
+- Removed ES3 / IE8 Support
+- Removed V1 API Backward Compatibility (Upgrading V1 -> V3)
+
+See the [beta](https://github.com/Microsoft/ApplicationInsights-JS/tree/beta) for the current documented set of breaking changes, all feedback on excessive breaks are welcome current release target is early (1st quarter) 2023.
+
 ## Getting Started
 
 1. Create an Application Insights resource in Azure by following [these instructions](https://docs.microsoft.com/en-us/azure/application-insights/app-insights-javascript?toc=/azure/azure-monitor/toc.json).
@@ -258,6 +271,25 @@ appInsights.addTelemetryInitializer(() => false); // Nothing is sent after this
 appInsights.trackTrace({message: 'this message will not be sent'}); // Not sent
 ```
 
+### Dependency Listeners
+
+A [dependency listener is a callback function](./API-reference.md#addDependencyListener) that allows you to perform additional manipulation of the request details before the request is performed.
+
+This includes :-
+
+- Complete access to either the XMLHttpRequest instance or the fetch API `input` and `init` arguments.
+- Ability to get/set the properties used to generate the W3C `traceparent` header (`traceId`, `spanId, `traceFlags)
+- Set values in the object context container for other listeners called after the current one, as well as this context object is also made available to all dependency initializers.
+
+### Dependency Initializers
+
+A [Dependency Initializer is very similar](./API-reference.md#addDependencyInitializer) to a [Telemetry Initializer](https://github.com/Microsoft/ApplicationInsights-JS#telemetry-initializers) in that it allows you modify the contents of collected telemetry before being sent from the user's browser. And you can also returning `false` to cause the event to not be emitted.
+
+The differences between a telemetry initializer and a dependency initializer are :-
+- A Dependency Initializer is called "before" the event is processed by the pipeline, as such it will NOT (yet) contain the automatically populated properties that are applied later;
+- When a dependency initializer returns `false` to drop the event the event does NOT count against the `maxAjaxCallsPerView` as this blocks the event call from being tracked, and while returning `false` from a [Telemetry Initializer](https://github.com/Microsoft/ApplicationInsights-JS#telemetry-initializers) will also stop the event from being reported because this is further down the processing pipeline the dependency event IS counted against the `maxAjaxCallsPerView` limit.
+- It has access to an optional "context" `{ [key: string]: any }` object that is also available to the Dependency Listeners. This allows a listener to add additional details to the context (before the XHR/fetch request is sent), and the initializer will be called after the request has completed.
+
 ## Configuration
 
 Most configuration fields are named such that they can be defaulted to falsey. All fields are optional except for `instrumentationKey` or a `connectionString` containing the instrumentation key.