[msal-node]: Add regional authorities telemetry

change/@azure-msal-common-3150477f-929f-4013-8176-77b1a63f8912.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: add regional authority telemetry",
+  "packageName": "@azure/msal-common",
+  "email": "samuelkamau@microsoft.com",
+  "dependentChangeType": "patch"
+}

change/@azure-msal-node-f63abd0d-4eab-4485-ba86-ca75799c6065.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: add regional authority telemetry",
+  "packageName": "@azure/msal-node",
+  "email": "samuelkamau@microsoft.com",
+  "dependentChangeType": "patch"
+}

lib/msal-common/src/authority/Authority.ts

@@ -9,7 +9,7 @@ import { UrlString } from "../url/UrlString";
 import { IUri } from "../url/IUri";
 import { ClientAuthError } from "../error/ClientAuthError";
 import { INetworkModule } from "../network/INetworkModule";
-import { AuthorityMetadataSource, Constants } from "../utils/Constants";
+import { AuthorityMetadataSource, Constants, RegionDiscoveryOutcomes } from "../utils/Constants";
 import { ClientConfigurationError } from "../error/ClientConfigurationError";
 import { ProtocolMode } from "./ProtocolMode";
 import { ICacheManager } from "../cache/interface/ICacheManager";
@@ -18,6 +18,7 @@ import { AuthorityOptions } from "./AuthorityOptions";
 import { CloudInstanceDiscoveryResponse, isCloudInstanceDiscoveryResponse } from "./CloudInstanceDiscoveryResponse";
 import { CloudDiscoveryMetadata } from "./CloudDiscoveryMetadata";
 import { RegionDiscovery } from "./RegionDiscovery";
+import { RegionDiscoveryMetadata } from "./RegionDiscoveryMetadata";
 
 /**
  * The authority class validates the authority URIs used by the user, and retrieves the OpenID Configuration Data from the
@@ -39,6 +40,8 @@ export class Authority {
     private metadata: AuthorityMetadataEntity;
     // Region discovery service
     private regionDiscovery: RegionDiscovery;
+    // Region discovery metadata
+    private regionDiscoveryMetadata: RegionDiscoveryMetadata;
 
     constructor(authority: string, networkInterface: INetworkModule, cacheManager: ICacheManager, authorityOptions: AuthorityOptions) {
         this.canonicalAuthority = authority;
@@ -47,6 +50,7 @@ export class Authority {
         this.cacheManager = cacheManager;
         this.authorityOptions = authorityOptions;
         this.regionDiscovery = new RegionDiscovery(networkInterface);
+        this.regionDiscoveryMetadata = { region_used: undefined, region_source: undefined, region_outcome: undefined };
     }
 
     // See above for AuthorityType
@@ -172,6 +176,15 @@ export class Authority {
         }
     }
 
+    /**
+     * Region used if any
+     * 
+     * @returns string
+     */
+    public getRegionDiscoveryMetadata(): RegionDiscoveryMetadata {
+        return this.regionDiscoveryMetadata;
+    }
+
     /**
      * Replaces tenant in url path with current tenant. Defaults to common.
      * @param urlString
@@ -263,13 +276,32 @@ export class Authority {
         if (metadata) {
             // If the user prefers to use an azure region replace the global endpoints with regional information.
             if (this.authorityOptions.azureRegionConfiguration?.azureRegion) {
-                const autodetectedRegionName = await this.regionDiscovery.detectRegion(this.authorityOptions.azureRegionConfiguration.environmentRegion);
+                const autodetectedRegionName = await this.regionDiscovery.detectRegion(this.authorityOptions.azureRegionConfiguration.environmentRegion, this.regionDiscoveryMetadata);
 
                 const azureRegion = this.authorityOptions.azureRegionConfiguration.azureRegion === Constants.AZURE_REGION_AUTO_DISCOVER_FLAG 
                     ? autodetectedRegionName 
                     : this.authorityOptions.azureRegionConfiguration.azureRegion;
 
+                if (this.authorityOptions.azureRegionConfiguration.azureRegion === Constants.AZURE_REGION_AUTO_DISCOVER_FLAG) {
+                    if (autodetectedRegionName) {
+                        this.regionDiscoveryMetadata.region_outcome = RegionDiscoveryOutcomes.AUTO_DETECTION_REQUESTED_SUCCESSFUL;
+                    } else {
+                        this.regionDiscoveryMetadata.region_outcome = RegionDiscoveryOutcomes.AUTO_DETECTION_REQUESTED_FAILED;
+                    }
+                } else {
+                    if (autodetectedRegionName) {
+                        if (this.authorityOptions.azureRegionConfiguration.azureRegion === autodetectedRegionName) {
+                            this.regionDiscoveryMetadata.region_outcome = RegionDiscoveryOutcomes.CONFIGURED_MATCHES_DETECTED;
+                        } else {
+                            this.regionDiscoveryMetadata.region_outcome = RegionDiscoveryOutcomes.CONFIGURED_NOT_DETECTED;
+                        }
+                    } else {
+                        this.regionDiscoveryMetadata.region_outcome = RegionDiscoveryOutcomes.CONFIGURED_NO_AUTO_DETECTION;
+                    }
+                }
+
                 if (azureRegion) {
+                    this.regionDiscoveryMetadata.region_used = azureRegion;
                     metadata = Authority.replaceWithRegionalInformation(metadata, azureRegion);
                 }
             }

lib/msal-common/src/authority/RegionDiscovery.ts

@@ -6,7 +6,8 @@
 import { INetworkModule } from "../network/INetworkModule";
 import { NetworkResponse } from "../network/NetworkManager";
 import { IMDSBadResponse } from "../response/IMDSBadResponse";
-import { Constants, ResponseCodes } from "../utils/Constants";
+import { Constants, RegionDiscoverySources, ResponseCodes } from "../utils/Constants";
+import { RegionDiscoveryMetadata } from "./RegionDiscoveryMetadata";
 
 export class RegionDiscovery {
     // Network interface to make requests with.
@@ -23,7 +24,7 @@ export class RegionDiscovery {
      * 
      * @returns Promise<string | null>
      */
-    public async detectRegion(environmentRegion: string | undefined): Promise<string | null> {
+    public async detectRegion(environmentRegion: string | undefined, regionDiscoveryMetadata: RegionDiscoveryMetadata): Promise<string | null> {
         // Initialize auto detected region with the region from the envrionment 
         let autodetectedRegionName = environmentRegion;
 
@@ -38,19 +39,27 @@ export class RegionDiscovery {
                 if (response.status === ResponseCodes.httpBadRequest) {
                     const latestIMDSVersion = await this.getCurrentVersion();
                     if (!latestIMDSVersion) {
+                        regionDiscoveryMetadata.region_source = RegionDiscoverySources.FAILED_AUTO_DETECTION;
                         return null;
                     }
 
                     const response = await this.getRegionFromIMDS(latestIMDSVersion);
                     if (response.status === ResponseCodes.httpSuccess) {
                         autodetectedRegionName = response.body;
                     }
-                } 
+                }
+
+                if (autodetectedRegionName) regionDiscoveryMetadata.region_source = RegionDiscoverySources.IMDS;
             } catch(e) {
+                regionDiscoveryMetadata.region_source = RegionDiscoverySources.FAILED_AUTO_DETECTION;
                 return null;
             } 
+        } else {
+            regionDiscoveryMetadata.region_source = RegionDiscoverySources.ENVIRONMENT_VARIABLE;
         }
 
+        if (!autodetectedRegionName) regionDiscoveryMetadata.region_source = RegionDiscoverySources.FAILED_AUTO_DETECTION;
+
         return autodetectedRegionName || null;
     }
 

lib/msal-common/src/authority/RegionDiscoveryMetadata.ts

@@ -0,0 +1,15 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    RegionDiscoveryOutcomes,
+    RegionDiscoverySources
+} from "../utils/Constants";
+
+export type RegionDiscoveryMetadata = {
+    region_used?: string;
+    region_source?: RegionDiscoverySources;
+    region_outcome?: RegionDiscoveryOutcomes;
+};

lib/msal-common/src/telemetry/server/ServerTelemetryManager.ts

@@ -3,12 +3,13 @@
  * Licensed under the MIT License.
  */
 
-import { SERVER_TELEM_CONSTANTS, Separators, Constants } from "../../utils/Constants";
+import { SERVER_TELEM_CONSTANTS, Separators, Constants, RegionDiscoverySources, RegionDiscoveryOutcomes } from "../../utils/Constants";
 import { CacheManager } from "../../cache/CacheManager";
 import { AuthError } from "../../error/AuthError";
 import { ServerTelemetryRequest } from "./ServerTelemetryRequest";
 import { ServerTelemetryEntity } from "../../cache/entities/ServerTelemetryEntity";
 import { StringUtils } from "../../utils/StringUtils";
+import { RegionDiscoveryMetadata } from "../../authority/RegionDiscoveryMetadata";
 
 export class ServerTelemetryManager {
     private cacheManager: CacheManager;
@@ -18,6 +19,9 @@ export class ServerTelemetryManager {
     private telemetryCacheKey: string;
     private wrapperSKU: String;
     private wrapperVer: String;
+    private regionUsed: string | undefined;
+    private regionSource: RegionDiscoverySources | undefined;
+    private regionOutcome: RegionDiscoveryOutcomes | undefined;
 
     constructor(telemetryRequest: ServerTelemetryRequest, cacheManager: CacheManager) {
         this.cacheManager = cacheManager;
@@ -37,8 +41,10 @@ export class ServerTelemetryManager {
         const forceRefreshInt = this.forceRefresh ? 1 : 0;
         const request = `${this.apiId}${SERVER_TELEM_CONSTANTS.VALUE_SEPARATOR}${forceRefreshInt}`;
         const platformFields = [this.wrapperSKU, this.wrapperVer].join(SERVER_TELEM_CONSTANTS.VALUE_SEPARATOR);
+        const regionDiscoveryFields = this.getRegionDiscoveryFields();
+        const requestWithRegionDiscoveryFields = [request, regionDiscoveryFields].join(SERVER_TELEM_CONSTANTS.VALUE_SEPARATOR);
 
-        return [SERVER_TELEM_CONSTANTS.SCHEMA_VERSION, request, platformFields].join(SERVER_TELEM_CONSTANTS.CATEGORY_SEPARATOR);
+        return [SERVER_TELEM_CONSTANTS.SCHEMA_VERSION, requestWithRegionDiscoveryFields, platformFields].join(SERVER_TELEM_CONSTANTS.CATEGORY_SEPARATOR);
     }
 
     /**
@@ -158,4 +164,72 @@ export class ServerTelemetryManager {
 
         return maxErrors;
     }
+
+    /**
+     * Get the region discovery fields
+     * 
+     * @returns string
+     */
+    getRegionDiscoveryFields(): string {
+        const regionDiscoveryFields: string[] = [];
+
+        regionDiscoveryFields.push(this.regionUsed ? this.regionUsed : "");
+        regionDiscoveryFields.push(this.getRegionSourceValue(this.regionSource));
+        regionDiscoveryFields.push(this.getRegionOutcomeValue(this.regionOutcome));
+
+        return regionDiscoveryFields.join(",");
+    }
+
+    /**
+     * Get the header value for the region source
+     * @param regionSource
+     * @returns string
+     */
+    getRegionSourceValue(regionSource: RegionDiscoverySources | undefined): string {
+        if (!regionSource) return "";
+
+        switch (regionSource) {
+            case RegionDiscoverySources.FAILED_AUTO_DETECTION:
+                return "1";
+            case RegionDiscoverySources.INTERNAL_CACHE:
+                return "2";
+            case RegionDiscoverySources.ENVIRONMENT_VARIABLE:
+                return "3";
+            case RegionDiscoverySources.IMDS:
+                return "4";
+            default:
+                return "0";
+        }
+    }
+
+    getRegionOutcomeValue(regionOutcome: RegionDiscoveryOutcomes | undefined): string {
+        if (!regionOutcome) return "";
+
+        switch (regionOutcome) {
+            case RegionDiscoveryOutcomes.CONFIGURED_MATCHES_DETECTED:
+                return "1";
+            case RegionDiscoveryOutcomes.CONFIGURED_NO_AUTO_DETECTION:
+                return "2";
+            case RegionDiscoveryOutcomes.CONFIGURED_NOT_DETECTED:
+                return "3";
+            case RegionDiscoveryOutcomes.AUTO_DETECTION_REQUESTED_SUCCESSFUL:
+                return "4";
+            case RegionDiscoveryOutcomes.AUTO_DETECTION_REQUESTED_FAILED:
+                return "5";
+            default:
+                return "0";
+        }
+    }  
+
+    /**
+     * Update the region discovery metadata
+     * 
+     * @param regionDiscoveryMetadata
+     * @returns void
+     */
+    updateRegionDiscoveryMetadata(regionDiscoveryMetadata: RegionDiscoveryMetadata): void {
+        this.regionUsed = regionDiscoveryMetadata.region_used;
+        this.regionSource = regionDiscoveryMetadata.region_source;
+        this.regionOutcome = regionDiscoveryMetadata.region_outcome;
+    } 
 }

lib/msal-common/src/utils/Constants.ts

@@ -349,3 +349,24 @@ export enum  ResponseCodes {
     httpSuccess = 200,
     httpBadRequest = 400
 }
+
+/**
+ * Region Discovery Sources
+ */
+export enum RegionDiscoverySources {
+    FAILED_AUTO_DETECTION = "FAILED AUTO DETECTION",
+    INTERNAL_CACHE = "INTERNAL CACHE",
+    ENVIRONMENT_VARIABLE = "ENVIRONMENT VARIABLE",
+    IMDS = "IMDS",
+}
+
+/**
+ * Region Discovery Outcomes
+ */
+export enum RegionDiscoveryOutcomes {
+    CONFIGURED_MATCHES_DETECTED = "Configured by developer and matches auto-detected",
+    CONFIGURED_NO_AUTO_DETECTION = "Configured by developer, cannot be auto-detected",
+    CONFIGURED_NOT_DETECTED = "Configured by developer, does not match auto-detected",
+    AUTO_DETECTION_REQUESTED_SUCCESSFUL = "Auto-detect requested and auto-detection worked",
+    AUTO_DETECTION_REQUESTED_FAILED = "Auto-detect requested and failed, fallback to global"
+}

lib/msal-common/test/telemetry/ServerTelemetryManager.spec.ts

@@ -111,14 +111,14 @@ describe("ServerTelemetryManager.ts", () => {
         it("Adds telemetry headers with current request", () => {
             const telemetryManager = new ServerTelemetryManager(testTelemetryPayload, testCacheManager);
             const currHeaderVal = telemetryManager.generateCurrentRequestHeaderValue();
-            expect(currHeaderVal).toBe(`2|${testApiCode},0|,`);
+            expect(currHeaderVal).toEqual(`2|${testApiCode},0,,,|,`);
         });
 
         it("Adds telemetry headers with current request with forceRefresh true", () => {
             const testPayload: ServerTelemetryRequest = {...testTelemetryPayload, forceRefresh: true };
             const telemetryManager = new ServerTelemetryManager(testPayload, testCacheManager);
             const currHeaderVal = telemetryManager.generateCurrentRequestHeaderValue();
-            expect(currHeaderVal).toBe(`2|${testApiCode},1|,`);
+            expect(currHeaderVal).toEqual(`2|${testApiCode},1,,,|,`);
         });
 
         it("Adds telemetry headers with last failed request", () => {

lib/msal-node/src/client/ClientApplication.ts

@@ -240,6 +240,8 @@ export abstract class ClientApplication {
 
         const discoveredAuthority = await this.createAuthority(authority, azureRegionConfiguration);
 
+        serverTelemetryManager?.updateRegionDiscoveryMetadata(discoveredAuthority.getRegionDiscoveryMetadata());
+
         return {
             authOptions: {
                 clientId: this.config.auth.clientId,

lib/msal-node/test/client/ConfidentialClientApplication.spec.ts

@@ -16,6 +16,9 @@ mocked(StringUtils.isEmpty).mockImplementation((str) => {
 
 describe('ConfidentialClientApplication', () => {
     const authority: Authority = {
+        getRegionDiscoveryMetadata: () => {
+            return { region_used: undefined, region_source: undefined, region_outcome: undefined };
+        },
         resolveEndpointsAsync: () => {
             return new Promise<void>(resolve => {
                 resolve();

lib/msal-node/test/client/PublicClientApplication.spec.ts

@@ -25,6 +25,9 @@ jest.mock('@azure/msal-common');
 
 describe('PublicClientApplication', () => {
     const authority: Authority = {
+        getRegionDiscoveryMetadata: () => {
+            return { region_used: undefined, region_source: undefined, region_outcome: undefined };
+        },
         resolveEndpointsAsync: () => {
             return new Promise<void>(resolve => {
                 resolve();