Task 6268904: [JS] Provide options for populating the SDK operation i…

…d during initialization

- Single Page Application Page View Tracking #176
- Run-time Telemetry initializers for Ajax requests #198
- How to modify traceflag in traceparent header? #1776

AISKU/src/Initialization.ts

@@ -7,7 +7,7 @@ import {
     IChannelControls, hasWindow, hasDocument, isReactNative, doPerf, IDiagnosticLogger, INotificationManager, objForEachKey, proxyAssign, proxyFunctions,
     arrForEach, isString, isFunction, isNullOrUndefined, isArray, throwError, ICookieMgr, addPageUnloadEventListener, addPageHideEventListener,
     createUniqueNamespace, ITelemetryPlugin, IPlugin, ILoadedPlugin, UnloadHandler, removePageUnloadEventListener, removePageHideEventListener,
-    ITelemetryInitializerHandler, ITelemetryUnloadState, mergeEvtNamespace, _throwInternal, arrIndexOf
+    ITelemetryInitializerHandler, ITelemetryUnloadState, mergeEvtNamespace, _throwInternal, arrIndexOf, IDistributedTraceContext
 } from "@microsoft/applicationinsights-core-js";
 import { AnalyticsPlugin, ApplicationInsights } from "@microsoft/applicationinsights-analytics-js";
 import { Sender } from "@microsoft/applicationinsights-channel-js";
@@ -23,6 +23,7 @@ import {
     IPropertiesPlugin, DistributedTracingModes, PropertiesPluginIdentifier, BreezeChannelIdentifier, AnalyticsPluginIdentifier,
     ITelemetryContext as Common_ITelemetryContext, parseConnectionString
 } from "@microsoft/applicationinsights-common"
+import { DependencyListenerFunction, IDependencyListenerHandler } from "@microsoft/applicationinsights-dependencies-js/types/DependencyListener";
 
 export { IUtil, ICorrelationIdHelper, IUrlHelper, IDateTimeUtils, IRequestHeaders };
 
@@ -413,7 +414,8 @@ export class Initialization implements IApplicationInsights {
             ]);
 
             proxyFunctions(_self, _getCurrentDependencies, [
-                "trackDependencyData"
+                "trackDependencyData",
+                "addDependencyListener"
             ]);
 
             proxyFunctions(_self, _core, [
@@ -423,7 +425,8 @@ export class Initialization implements IApplicationInsights {
                 "getPlugin",
                 "addPlugin",
                 "evtNamespace",
-                "addUnloadCb"
+                "addUnloadCb",
+                "getTraceCtx"
             ]);
 
             proxyFunctions(_self, () => {
@@ -440,6 +443,7 @@ export class Initialization implements IApplicationInsights {
                     _self.config.diagnosticLogInterval && _self.config.diagnosticLogInterval > 0 ? _self.config.diagnosticLogInterval : 10000;
             }
 
+            // Using a function to support the dynamic adding / removal of plugins, so this will always return the current value
             function _getCurrentDependencies() {
                 return dependencies;
             }
@@ -715,6 +719,25 @@ export class Initialization implements IApplicationInsights {
     public addUnloadCb(handler: UnloadHandler): void {
         // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
     }
+
+    /**
+     * Add an ajax listener which is called just prior to the request being sent and before the correlation headers are added, to allow you
+     * to access the headers and modify the values used to generate the distributed tracing correlation headers. (added in v2.8.4)
+     * @param dependencyListener - The Telemetry Initializer function
+     * @returns - A IDependencyListenerHandler to enable the initializer to be removed
+     */
+    public addDependencyListener(dependencyListener: DependencyListenerFunction): IDependencyListenerHandler {
+        // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
+        return null;
+    }
+
+    /**
+     * Gets the current distributed trace context for this instance if available
+     */
+    public getTraceCtx(): IDistributedTraceContext | null | undefined {
+        // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
+        return null;
+    }
 }
 
 // tslint:disable-next-line

README.md

@@ -258,6 +258,10 @@ appInsights.addTelemetryInitializer(() => false); // Nothing is sent after this
 appInsights.trackTrace({message: 'this message will not be sent'}); // Not sent
 ```
 
+### Distributed Tracing support
+
+To support Server-Side Correlation see the [Distributed Tracing](docs/DistributedTracing.md) page.
+
 ## Configuration
 
 Most configuration fields are named such that they can be defaulted to falsey. All fields are optional except for `instrumentationKey`.
@@ -317,6 +321,7 @@ Most configuration fields are named such that they can be defaulted to falsey. A
 | maxAjaxPerfLookupAttempts | numeric | 3 | Defaults to 3. The maximum number of times to look for the window.performance timings (if available), this is required as not all browsers populate the window.performance before reporting the end of the XHR request and for fetch requests this is added after its complete.
 | ajaxPerfLookupDelay | numeric | 25 | Defaults to 25ms. The amount of time to wait before re-attempting to find the windows.performance timings for an ajax request, time is in milliseconds and is passed directly to setTimeout().
 | distributedTracingMode | numeric or `DistributedTracingModes` | `DistributedTracingModes.AI_AND_W3C` | Sets the distributed tracing mode. If AI_AND_W3C mode or W3C mode is set, W3C trace context headers (traceparent/tracestate) will be generated and included in all outgoing requests. AI_AND_W3C is provided for back-compatibility with any legacy Application Insights instrumented services.
+| disableTraceParent<br /> (Since 2.8.4) | boolean | true (Since 2.8.4) | [Optional] A flag to control the automatic detection of any passed "traceparent" header from the server, to enable set this value to false, by default the Sdk will look for a meta-tag on the DOM or a Server-Timing header with a name of "traceparent". In all cases the value is validated before it is used. This flag disables the `<meta />` tag and `Server-Timing` header support added in v2.8.4 as described on the [Distributed Tracing](docs/DistributedTracing.md) page.
 | enableUnhandledPromiseRejectionTracking | boolean | false | If true, unhandled promise rejections will be autocollected and reported as a javascript error. When disableExceptionTracking is true (dont track exceptions) the config value will be ignored and unhandled promise rejections will not be reported.
 | disableInstrumentationKeyValidation | boolean | false | If true, instrumentation key validation check is bypassed. Default value is false.
 | enablePerfMgr | boolean | false | [Optional] When enabled (true) this will create local perfEvents for code that has been instrumented to emit perfEvents (via the doPerf() helper). This can be used to identify performance issues within the SDK based on your usage or optionally within your own instrumented code. [More details are available by the basic documentation](./docs/PerformanceMonitoring.md). Since v2.5.7