@microsoft/applicationinsights-dependencies-js 2.8.4-nightly.2205-09 → 2.8.5-nightly.2206-02

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@microsoft/applicationinsights-dependencies-js",
-    "version": "2.8.4-nightly.2205-09",
+    "version": "2.8.5-nightly.2206-02",
     "description": "Microsoft Application Insights XHR dependencies plugin",
     "homepage": "https://github.com/microsoft/ApplicationInsights-JS#readme",
     "author": "Microsoft Application Insights Team",
@@ -50,8 +50,8 @@
     "dependencies": {
         "@microsoft/dynamicproto-js": "^1.1.6",
         "@microsoft/applicationinsights-shims": "2.0.1",
-        "@microsoft/applicationinsights-core-js": "2.8.4-nightly.2205-09",
-        "@microsoft/applicationinsights-common": "2.8.4-nightly.2205-09"
+        "@microsoft/applicationinsights-core-js": "2.8.5-nightly.2206-02",
+        "@microsoft/applicationinsights-common": "2.8.5-nightly.2206-02"
     },
     "license": "MIT",
     "publishConfig": {

package/src/DependencyListener.ts

@@ -0,0 +1,65 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { IAppInsightsCore } from "@microsoft/applicationinsights-core-js";
+
+export interface IDependencyListenerDetails {
+    /**
+     * The current core instance
+     */
+    core: IAppInsightsCore;
+
+    /**
+     * Provided only if the dependency request is an XHR call
+     */
+    xhr?: XMLHttpRequest;
+
+    /**
+     * Provided only if the dependency request is a fetch call, this is the input argument being used,
+     * re-assigning this value has not affect on the value used for the request, however, when this is a Request
+     * object changing the value of the Request will be used for the outbound request.
+     */
+    input?: Request | string;
+
+    /**
+     * Provided only if the dependency request is a fetch call, this is the init argument being used,
+     * re-assigning this value does not change the value used for the request, however, changing properties
+     * of this object will be used.
+     */
+    init?: RequestInit;
+
+    /**
+     * Returns the unique identifier for a trace. All requests / spans from the same trace share the same traceId.
+     * Must be read from incoming headers or generated according to the W3C TraceContext specification,
+     * in a hex representation of 16-byte array. A.k.a. trace-id, TraceID or Distributed TraceID
+     */
+    traceId?: string;
+
+    /**
+     * Self-generated 8-bytes identifier of the incoming request. Must be a hex representation of 8-byte array.
+     * Also know as the parentId, used to link requests together
+     */
+    spanId?: string;
+
+    /**
+     * An integer representation of the W3C TraceContext trace-flags.
+    * https://www.w3.org/TR/trace-context/#trace-flags
+    */
+    traceFlags?: number;
+}
+
+export declare type DependencyListenerFunction = (dependencyDetails: IDependencyListenerDetails) => void;
+
+export interface IDependencyListenerHandler {
+    remove(): void;
+}
+
+export interface IDependencyListenerContainer {
+    /**
+     * 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
+     */
+    addDependencyListener(dependencyListener: DependencyListenerFunction): IDependencyListenerHandler;
+}

package/src/ajax.ts

@@ -5,17 +5,18 @@ import {
     RequestHeaders, CorrelationIdHelper, createTelemetryItem, ICorrelationConfig,
     RemoteDependencyData, dateTimeUtilsNow, DisabledPropertyName, IDependencyTelemetry,
     IConfig, ITelemetryContext, PropertiesPluginIdentifier, eDistributedTracingModes, IRequestContext, isInternalApplicationInsightsEndpoint,
-    eRequestHeaders, formatTraceParent, createTraceParent
+    eRequestHeaders, formatTraceParent, createTraceParent, createDistributedTraceContextFromTrace
 } from "@microsoft/applicationinsights-common";
 import {
     isNullOrUndefined, arrForEach, isString, strTrim, isFunction, eLoggingSeverity, _eInternalMessageId,
     IAppInsightsCore, BaseTelemetryPlugin, ITelemetryPluginChain, IConfiguration, IPlugin, ITelemetryItem, IProcessTelemetryContext,
     getLocation, getGlobal, strPrototype, IInstrumentCallDetails, InstrumentFunc, InstrumentProto, getPerformance,
     IInstrumentHooksCallbacks, objForEachKey, generateW3CId, getIEVersion, dumpObj, ICustomProperties, isXhrSupported, eventOn,
-    mergeEvtNamespace, createUniqueNamespace, createProcessTelemetryContext, _throwInternal
+    mergeEvtNamespace, createUniqueNamespace, createProcessTelemetryContext, _throwInternal, IDistributedTraceContext, getExceptionName
 } from "@microsoft/applicationinsights-core-js";
 import { ajaxRecord, IAjaxRecordResponse } from "./ajaxRecord";
 import dynamicProto from "@microsoft/dynamicproto-js";
+import { DependencyListenerFunction, IDependencyListenerContainer, IDependencyListenerDetails, IDependencyListenerHandler } from "./DependencyListener";
 
 const AJAX_MONITOR_PREFIX = "ai.ajxmn.";
 const strDiagLog = "diagLog";
@@ -26,6 +27,11 @@ const strTrackDependencyDataInternal = "trackDependencyDataInternal"; // Using s
 // Using a global value so that to handle same iKey with multiple app insights instances (mostly for testing)
 let _markCount: number = 0;
 
+interface _IInternalDependencyListenerHandler {
+    id: number;
+    fn: DependencyListenerFunction;
+}
+
 /** @Ignore */
 function _supportsFetch(): (input: RequestInfo, init?: RequestInit) => Promise<Response> {
     let _global = getGlobal();
@@ -132,11 +138,47 @@ function _indexOf(value:string, match:string):number {
     return -1;
 }
 
+function _processDependencyListeners(listeners: _IInternalDependencyListenerHandler[], core: IAppInsightsCore, ajaxData: ajaxRecord, xhr: XMLHttpRequest, input?: Request | string, init?: RequestInit): void {
+    var initializersCount = listeners.length;
+    if (initializersCount > 0) {
+        let details: IDependencyListenerDetails = {
+            core: core,
+            xhr: xhr,
+            input: input,
+            init: init,
+            traceId: ajaxData.traceID,
+            spanId: ajaxData.spanID,
+            traceFlags: ajaxData.traceFlags
+        };
+    
+        for (var i = 0; i < initializersCount; ++i) {
+            var dependencyListener = listeners[i];
+            if (dependencyListener && dependencyListener.fn) {
+                try {
+                    dependencyListener.fn.call(null, details);
+                } catch (e) {
+                    let core = details.core;
+                    _throwInternal(
+                        core && core.logger,
+                        eLoggingSeverity.CRITICAL,
+                        _eInternalMessageId.TelemetryInitializerFailed,
+                        "Dependency listener [#" + i + "] failed: " + getExceptionName(e),
+                        { exception: dumpObj(e) }, true);
+                }
+            }
+        }
+
+        ajaxData.traceID = details.traceId;
+        ajaxData.spanID = details.spanId;
+        ajaxData.traceFlags = details.traceFlags;
+    }
+}
+
 export interface XMLHttpRequestInstrumented extends XMLHttpRequest {
     ajaxData: ajaxRecord;
 }
 
-export interface IDependenciesPlugin {
+export interface IDependenciesPlugin extends IDependencyListenerContainer {
     /**
      * Logs dependency call
      * @param dependencyData dependency data object
@@ -219,6 +261,8 @@ export class AjaxMonitor extends BaseTelemetryPlugin implements IDependenciesPlu
         let _excludeRequestFromAutoTrackingPatterns: string[] | RegExp[];
         let _addRequestContext: (requestContext?: IRequestContext) => ICustomProperties;
         let _evtNamespace: string | string[];
+        let _dependencyListenerId: number;
+        let _dependencyListeners: _IInternalDependencyListenerHandler[];
 
         dynamicProto(AjaxMonitor, this, (_self, _base) => {
             let _addHook = _base._addHook;
@@ -250,6 +294,9 @@ export class AjaxMonitor extends BaseTelemetryPlugin implements IDependenciesPlu
             _self.includeCorrelationHeaders = (ajaxData: ajaxRecord, input?: Request | string, init?: RequestInit, xhr?: XMLHttpRequestInstrumented): any => {
                 // Test Hook to allow the overriding of the location host
                 let currentWindowHost = _self["_currentWindowHost"] || _currentWindowHost;
+
+                _processDependencyListeners(_dependencyListeners, _self.core, ajaxData, xhr, input, init);
+
                 if (input) { // Fetch
                     if (CorrelationIdHelper.canIncludeCorrelationHeader(_config, ajaxData.getAbsoluteUrl(), currentWindowHost)) {
                         if (!init) {
@@ -274,7 +321,12 @@ export class AjaxMonitor extends BaseTelemetryPlugin implements IDependenciesPlu
                             }
                         }
                         if (_isUsingW3CHeaders) {
-                            const traceParent = formatTraceParent(createTraceParent(ajaxData.traceID, ajaxData.spanID, 0x01));
+                            let traceFlags = ajaxData.traceFlags;
+                            if (isNullOrUndefined(traceFlags)) {
+                                traceFlags = 0x01;
+                            }
+
+                            const traceParent = formatTraceParent(createTraceParent(ajaxData.traceID, ajaxData.spanID, traceFlags));
                             init.headers.set(RequestHeaders[eRequestHeaders.traceParentHeader], traceParent);
                             if (_enableRequestHeaderTracking) {
                                 ajaxData.requestHeaders[RequestHeaders[eRequestHeaders.traceParentHeader]] = traceParent;
@@ -300,7 +352,12 @@ export class AjaxMonitor extends BaseTelemetryPlugin implements IDependenciesPlu
                             }
                         }
                         if (_isUsingW3CHeaders) {
-                            const traceParent = formatTraceParent(createTraceParent(ajaxData.traceID, ajaxData.spanID, 0x01));
+                            let traceFlags = ajaxData.traceFlags;
+                            if (isNullOrUndefined(traceFlags)) {
+                                traceFlags = 0x01;
+                            }
+
+                            const traceParent = formatTraceParent(createTraceParent(ajaxData.traceID, ajaxData.spanID, traceFlags));
                             xhr.setRequestHeader(RequestHeaders[eRequestHeaders.traceParentHeader], traceParent);
                             if (_enableRequestHeaderTracking) {
                                 ajaxData.requestHeaders[RequestHeaders[eRequestHeaders.traceParentHeader]] = traceParent;
@@ -347,6 +404,28 @@ export class AjaxMonitor extends BaseTelemetryPlugin implements IDependenciesPlu
                 ++_trackAjaxAttempts;
             }
 
+            _self.addDependencyListener = (dependencyListener: DependencyListenerFunction): IDependencyListenerHandler => {
+                let theInitializer = {
+                    id: _dependencyListenerId++,
+                    fn: dependencyListener
+                };
+
+                _dependencyListeners.push(theInitializer);
+
+                let handler: IDependencyListenerHandler = {
+                    remove: () => {
+                        arrForEach(_dependencyListeners, (initializer, idx) => {
+                            if (initializer.id === theInitializer.id) {
+                                _dependencyListeners.splice(idx, 1);
+                                return -1;
+                            }
+                        });
+                    }
+                }
+    
+                return handler;
+            };
+        
             function _initDefaults() {
                 let location = getLocation();
                 _fetchInitialized = false;      // fetch monitoring initialized
@@ -367,9 +446,11 @@ export class AjaxMonitor extends BaseTelemetryPlugin implements IDependenciesPlu
                 _disableAjaxTracking = false;
                 _disableFetchTracking = false;
         
-                _excludeRequestFromAutoTrackingPatterns = null
+                _excludeRequestFromAutoTrackingPatterns = null;
                 _addRequestContext = null;
                 _evtNamespace = null;
+                _dependencyListenerId = 0;
+                _dependencyListeners = [];
             }
 
             function _populateDefaults(config: IConfiguration) {
@@ -681,11 +762,28 @@ export class AjaxMonitor extends BaseTelemetryPlugin implements IDependenciesPlu
                     && ajaxValidation;
             }
 
+            function _getDistributedTraceCtx(): IDistributedTraceContext {
+                let distributedTraceCtx: IDistributedTraceContext = null;
+                if (_self.core && _self.core.getTraceCtx) {
+                    distributedTraceCtx = _self.core.getTraceCtx(false);
+                }
+
+                // Fall back
+                if (!distributedTraceCtx && _context && _context.telemetryTrace) {
+                    distributedTraceCtx = createDistributedTraceContextFromTrace(_context.telemetryTrace);
+                }
+
+                return distributedTraceCtx;
+            }
+
             function _openHandler(xhr: XMLHttpRequestInstrumented, method: string, url: string, async: boolean) {
-                const traceID = (_context && _context.telemetryTrace && _context.telemetryTrace.traceID) || generateW3CId();
+                let distributedTraceCtx: IDistributedTraceContext = _getDistributedTraceCtx();
+
+                const traceID = (distributedTraceCtx && distributedTraceCtx.getTraceId()) || generateW3CId();
                 const spanID = generateW3CId().substr(0, 16);
 
                 const ajaxData = new ajaxRecord(traceID, spanID, _self[strDiagLog]());
+                ajaxData.traceFlags = distributedTraceCtx && distributedTraceCtx.getTraceFlags();
                 ajaxData.method = method;
                 ajaxData.requestUrl = url;
                 ajaxData.xhrMonitoringState.openDone = true;
@@ -921,10 +1019,13 @@ export class AjaxMonitor extends BaseTelemetryPlugin implements IDependenciesPlu
             }
 
             function _createFetchRecord(input?: Request | string, init?: RequestInit): ajaxRecord {
-                const traceID = (_context && _context.telemetryTrace && _context.telemetryTrace.traceID) || generateW3CId();
+                let distributedTraceCtx: IDistributedTraceContext = _getDistributedTraceCtx();
+
+                const traceID = (distributedTraceCtx && distributedTraceCtx.getTraceId()) || generateW3CId();
                 const spanID = generateW3CId().substr(0, 16);
 
-                const ajaxData = new ajaxRecord(traceID, spanID, _self[strDiagLog]());
+                let ajaxData = new ajaxRecord(traceID, spanID, _self[strDiagLog]());
+                ajaxData.traceFlags = distributedTraceCtx && distributedTraceCtx.getTraceFlags();
                 ajaxData.requestSentTime = dateTimeUtilsNow();
                 ajaxData.errorStatusText = _enableAjaxErrorStatusText;
 
@@ -1070,6 +1171,17 @@ export class AjaxMonitor extends BaseTelemetryPlugin implements IDependenciesPlu
         // @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.
+     * @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;
+    }
+
     /**
      * Protected function to allow sub classes the chance to add additional properties to the dependency event
      * before it's sent. This function calls track, so sub-classes must call this function after they have

package/src/ajaxRecord.ts

@@ -237,6 +237,7 @@ export class ajaxRecord {
 
     public traceID: string;
     public spanID: string;
+    public traceFlags?: number;
 
     constructor(traceID: string, spanID: string, logger: IDiagnosticLogger) {
         let self = this;

package/types/DependencyListener.d.ts

@@ -0,0 +1,52 @@
+import { IAppInsightsCore } from "@microsoft/applicationinsights-core-js";
+export interface IDependencyListenerDetails {
+    /**
+     * The current core instance
+     */
+    core: IAppInsightsCore;
+    /**
+     * Provided only if the dependency request is an XHR call
+     */
+    xhr?: XMLHttpRequest;
+    /**
+     * Provided only if the dependency request is a fetch call, this is the input argument being used,
+     * re-assigning this value has not affect on the value used for the request, however, when this is a Request
+     * object changing the value of the Request will be used for the outbound request.
+     */
+    input?: Request | string;
+    /**
+     * Provided only if the dependency request is a fetch call, this is the init argument being used,
+     * re-assigning this value does not change the value used for the request, however, changing properties
+     * of this object will be used.
+     */
+    init?: RequestInit;
+    /**
+     * Returns the unique identifier for a trace. All requests / spans from the same trace share the same traceId.
+     * Must be read from incoming headers or generated according to the W3C TraceContext specification,
+     * in a hex representation of 16-byte array. A.k.a. trace-id, TraceID or Distributed TraceID
+     */
+    traceId?: string;
+    /**
+     * Self-generated 8-bytes identifier of the incoming request. Must be a hex representation of 8-byte array.
+     * Also know as the parentId, used to link requests together
+     */
+    spanId?: string;
+    /**
+     * An integer representation of the W3C TraceContext trace-flags.
+    * https://www.w3.org/TR/trace-context/#trace-flags
+    */
+    traceFlags?: number;
+}
+export declare type DependencyListenerFunction = (dependencyDetails: IDependencyListenerDetails) => void;
+export interface IDependencyListenerHandler {
+    remove(): void;
+}
+export interface IDependencyListenerContainer {
+    /**
+     * 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
+     */
+    addDependencyListener(dependencyListener: DependencyListenerFunction): IDependencyListenerHandler;
+}

package/types/ajax.d.ts

@@ -1,10 +1,11 @@
 import { ICorrelationConfig, IDependencyTelemetry, IConfig } from "@microsoft/applicationinsights-common";
 import { IAppInsightsCore, BaseTelemetryPlugin, ITelemetryPluginChain, IConfiguration, IPlugin, ITelemetryItem, IProcessTelemetryContext } from "@microsoft/applicationinsights-core-js";
 import { ajaxRecord } from "./ajaxRecord";
+import { DependencyListenerFunction, IDependencyListenerContainer, IDependencyListenerHandler } from "./DependencyListener";
 export interface XMLHttpRequestInstrumented extends XMLHttpRequest {
     ajaxData: ajaxRecord;
 }
-export interface IDependenciesPlugin {
+export interface IDependenciesPlugin extends IDependencyListenerContainer {
     /**
      * Logs dependency call
      * @param dependencyData dependency data object
@@ -31,6 +32,13 @@ export declare class AjaxMonitor extends BaseTelemetryPlugin implements IDepende
         [key: string]: any;
     }): void;
     includeCorrelationHeaders(ajaxData: ajaxRecord, input?: Request | string, init?: RequestInit, xhr?: XMLHttpRequestInstrumented): any;
+    /**
+     * 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.
+     * @param dependencyListener - The Telemetry Initializer function
+     * @returns - A IDependencyListenerHandler to enable the initializer to be removed
+     */
+    addDependencyListener(dependencyListener: DependencyListenerFunction): IDependencyListenerHandler;
     /**
      * Protected function to allow sub classes the chance to add additional properties to the dependency event
      * before it's sent. This function calls track, so sub-classes must call this function after they have

package/types/ajaxRecord.d.ts

@@ -43,6 +43,7 @@ export declare class ajaxRecord {
     clientFailure: number;
     traceID: string;
     spanID: string;
+    traceFlags?: number;
     constructor(traceID: string, spanID: string, logger: IDiagnosticLogger);
     getAbsoluteUrl(): string;
     getPathName(): string;

package/types/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.24.0"
+      "packageVersion": "7.24.2"
     }
   ]
 }